Commit b91f6964 authored by Federico Vaga's avatar Federico Vaga

doc: add architecture

Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>
parent 371d60c8
......@@ -4,7 +4,7 @@
Introduction
============
The Mock Turtle is a framework to develop embedded systems.
The Mock Turtle is a framework to develop embedded systems on FPGA.
The need for this framework comes from the fact that in some contexts
the development of a gateware core is more complex than writing a
......@@ -60,19 +60,6 @@ support Mock Turtle:
- the Mock Turtle Python module to access the library using Python.
The following figure shows the Mock Turtle architecture.
.. figure:: img/mock-turtle-overview.svg
:align: center
Mock Turtle Architecture Overview.
Mock Turtle Architecture Overview. The blue and orange blocks are
Mock Turtle components (respectively software and gateware cores).
Gray blocks are external components (gateware cores or software)
developed by the user. In purple any external world communication
over the network.
.. _introduction:use-cases:
Use Cases
......
.. _the-mock-turtle-architecture:
.. _arch:
===============================
The Mock Turtle Architecture
===============================
The Mock Turtle is a framework to develop embedded systems on FPGA. This
framework offers a complete and integrated stack from the HDL core to
the software application.
The following figure shows an overview over the Mock Turtle architecture.
.. figure:: img/mock-turtle-overview.svg
:align: center
Mock Turtle Architecture Overview.
Mock Turtle Architecture Overview. The blue and orange blocks are
Mock Turtle components (respectively software and gateware cores).
Gray blocks are external components (gateware cores or software)
developed by the user. In purple any external world communication
over the network.
This document tries to provide a big overview of what Mock Turtle offers
and what is important to know when designing a Mock Turtle application.
For more information read the dedicated chapts for the different parts
Mock Turtle Core
==================
Mock Turtle can have one or more core. A single cor eis made of the following
components: soft-CPU, Serial console and message queues.
Soft-CPU
---------
Mock Turtle uses the `uRV processor`_, a `RISC-V`_ ISA implementation. This is
just a CPU without any sort of integrated peripheral. This is where the firmware
runs. Any kind of bus controller, or device must be connected externally as a
:ref:`device peripheral<arch:dp>` and driven from the firmware.
Memory size for code and data is :ref:`configurable at synthesis time <hdl:cfg>`
.. _uRV processor: https://www.ohwr.org/projects/urv-core
.. _`RISC-V`: https://riscv.org/
For more information about how to handle cores from software read:
- :ref:`Linux Library - Cores Management<sw:lnx:lib:cpu>`
Serial Console
--------------
Each core has a serial console connected to the host system. This link is
unidirectional from core to host. Whenever there is a pending character in
a serial buffer, Mock Turtle raises an interrupt for the host.
.. graphviz::
:align: center
:caption: Example of Mock Turtle Serial Connection.
digraph layers {
concentrate=true;
node [shape=rectangle, style=filled, penwidth=2, fillcolor="#e3b68b", color="#ee6103"];
host [label="Host", fillcolor=lightblue, color=blue];
fw1 [label="Firmware 1", fillcolor=lightblue, color=blue]
fw2 [label="Firmware 2", fillcolor=lightblue, color=blue]
fw3 [label="Firmware 3", fillcolor=lightblue, color=blue]
fw1 -> "Serial 1" -> host;
fw2 -> "Serial 2" -> host;
fw3 -> "Serial 3" -> host;
}
This is used to send string messages from the running firmware to the host system:
- :ref:`Firmware Library - Serial Interface<sw:fw:lib:uart>`
Message Queue
----------------
Mock Turtle firmwares can communicate with external agents using
*message queues*; as the name suggests, this is a message queue with
FIFO priority. Each soft-CPU has two sets of private message queues:
one set is for host communication (*host message queue*), the other one is
for external communication (*remote message queue*). Each message queue
is bidirectional (one queue per direction).
A message queue entry is split in two fixed size buffers: header and payload.
Header should be used to store a protocol header, while payload should be
used to store the message content to be exchanged.
.. figure:: img/mock-turtle-mq.svg
:align: center
:scale: 70%
Mock Turtle Message Queue Overview.
.. note::
Header and payload are conventions, nothing prevents users from using them
otherwise. But remember that this convention is used in the Mock Turtle
software APIs as described above.
All Message queue dimensions are fixed and
:ref:`configured at synthesis time <hdl:cfg>`. These dimensions apply to both
input and output queues:
- maximum entries number
- maximum header size
- maximum payload size
Host message queues are connected to the host system. The host receives an
interrupt whenever an input queue contains at least one message; while
for output it receives an interrupt when a queue has at least one free entry.
Remote message queues do not have interrupt. They must be connected to an
*end-point* that provides connection to the external world. Their task is
to pack and unpack messages according to the type of network on which are
connected. End-point implementation is application specific and outside
the Mock Turtle scope.
For more information about how to access it from software read:
- :ref:`Firmware Library - Message Queue<sw:fw:lib:mq>`
- :ref:`Linux Library - Message Queue<sw:lnx:lib:hmq>`
Shared Memory
================
Mock Turtle offers a *shared memory* block accessible from the host system as
well as from soft-CPU cores. This can be used to share data among all actors.
Access to the shared memory is serialized, this means that an intensive use of it
can affect the determinism.
.. graphviz::
:align: center
:caption: Mock Turtle Shared Memory.
graph layers {
concentrate=true;
node [shape=rectangle, style=filled, penwidth=2, fillcolor=lightblue, color=blue];
edge [dir=both]
shm [label="Shared Memory", fillcolor="#e3b68b", color="#ee6103"];
"Host" -- shm;
shm -- "Firmware 1";
shm -- "Firmware 2";
shm -- "Firmware 3";
}
The shared memory size can be :ref:`configured at synthesis time <hdl:cfg>`
but it cannot exceed 64KiB.
Its address space is mirrored into multiple address ranges (contiguous),
each responsible for a single atomic operation; for more information about
how to access it from software read:
- :ref:`Firmware Library - Shared Memory<sw:fw:lib:shm>`
- :ref:`Linux Library - Shared Memory<sw:lnx:lib:shm>`
.. _`arch:dp`:
Device Peripheral
==================
Device peripherals are external components connected to a Mock Turtle core.
What they do, how many they are and how they are connected is application
specific: Mock Turtle just offers connections to cores.
From the core on which the device is connected, the firmware must be able
to address the device.
.. graphviz::
:align: center
:caption: Example of Mock Turtle Device Peripheral Connection.
graph layers {
concentrate=true;
node [shape=rectangle, style=filled, penwidth=2, fillcolor=lightgray, color=gray];
c1 [label="soft-CPU 1", fillcolor="#e3b68b", color="#ee6103"];
c2 [label="soft-CPU 2", fillcolor="#e3b68b", color="#ee6103"];
subgraph core2 {
c2 -- "Custom Logic";
}
subgraph core1 {
graph [nodesep=1];
c1 -- corssbar -- "I2C master";
c1 -- corssbar -- "SPI master";
}
{rank=same; c1; c2}
{rank=same; "Custom Logic"; "I2C master"; "SPI master"}
}
For more information about how to access it from software read:
- :ref:`Firmware Library - Memory Location<sw:fw:lib:mem>`
......@@ -55,6 +55,8 @@ Even if you do not intend to follow the same approach in your project, you shoul
submodule`` command above to get a list of working/compatible versions for the various HDL
dependencies.
.. _`hdl:cfg`:
Mock Turtle Configuration
=========================
......
......@@ -20,6 +20,7 @@ Turtle firmware.
Any firmware develop without this library will not receive any kind
of support.
.. _`sw:fw:lib:mem`:
Read And Write Memory Locations
===============================
......@@ -104,6 +105,8 @@ All these functions are based on the generic :c:func:`readl()` and
.. doxygenfunction:: writel
.. _`sw:fw:lib:mq`:
Message Queue
================
......@@ -224,6 +227,9 @@ the ones above.
.. doxygenfunction:: mq_map_in_buffer
.. _`sw:fw:lib:shm`:
Shared Memory
=============
......@@ -288,6 +294,8 @@ Here an example that uses all operations.::
.. doxygenfunction:: smem_atomic_test_and_set
.. _`sw:fw:lib:uart`:
Serial Interface
=================
......
......@@ -9,7 +9,7 @@ the necessary steps to develop software layers on top of the Mock Turtle
ones.
The software integration discussion will assume that you have a general
understanding of :ref:`the-mock-turtle-architecture`
understanding of :ref:`arch`
The Mock Turtle software stack consists in two main development domains:
the :ref:`sw:fw` and the :ref:`sw:lnx`
......
......@@ -95,6 +95,8 @@ close it with :c:func:`trtl_close`.
.. doxygenfunction:: trtl_close
.. _`sw:lnx:lib:cpu`:
Mock Turtle Cores Management
============================
......@@ -195,6 +197,9 @@ build on top of them your high level API.
.. doxygenfunction:: trtl_fw_buffer_get
.. _`sw:lnx:lib:shm`:
Shared Memory
=============
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment