Skip to content

M
Mock Turtle
Commit 7d4ee06e authored by Federico Vaga's avatar Federico Vaga
Browse files
Options

doc: update software documentation 

Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>
parent d38e348c
Hide whitespace changes
Inline Side-by-side
Showing with 59 additions and 35 deletions
doc/software/index.rst
View file @ 7d4ee06e
.. hightlight:: none
==============
The Software
==============
This section explains the Mock Turtle software architecture as wall as
This section explains the Mock Turtle software architecture as well as
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`
The Mock Turtle software consists in two main development domains: the
:ref:`sw:fw` and the :ref:`sw:lnx`
The Mock Turtle software stack consists in two main development domains:
the :ref:`sw:fw` and the :ref:`sw:lnx`
(libraries or applications).
The Mock Turtle software stack is made of different layers which main
......@@ -18,7 +20,7 @@ objectives are:
- to manage the Mock Turtle cores from the host;
- to allow the firmware to access the Mock Turtle resources;
- to allow firmwares to access Mock Turtle resources;
- to provide a communication infrastructure between firmware and host
......@@ -26,11 +28,11 @@ objectives are:
The development of a firmware is necessary to make the system work. In
the section :ref:`sw:fw` you will learn how to write a firmware using
the Mock Turtle API.
Mock Turtle API.
On the other hand, the development of a software support layer on the
host depends on your needs. If you need a custumized control/monitor
infrastructure for the firmware, then it is recommended to develop
infrastructure for firmwares, then it is recommended to develop
your software support layer(s) on top of the Mock Turtle ones.
Keep in mind that :ref:`tools` can be used for basic control/monitor
operations. This means that for basic requirements you can directly use
......@@ -112,17 +114,21 @@ The Mock Turtle offers 2 API for the firmware development:
}
It is strongly recommended to use the library because it offers a set of
macros and functions that simplifies the access to the Mock Turtle
resources and to the external gateware cores. This will help mainly in
the development of the firmware core logic.
macros and functions that simplifies the access to Mock Turtle
resources and to external gateware cores. This will help mainly in
firmware development.
It is recommended to use the framework because it guides you in the
development by keeping you focused only on your core logic without the
need to deal with the Mock Turtle architecture details.
need to deal with Mock Turtle architecture details.
The framework usage, rather than precluding the user to use library
functions, is complementary to the library.
Of course, this framework provides more features and features cost space
and computation time. If you need more space (and you can't allocate more
memory) or you need much better performances: don't use this framework.
All the Mock Turtle firmware source code can be found in the directory
``/path/to/mockturtle/software/firmware/``.
......@@ -186,7 +192,7 @@ may take more space than needed. For this reason Mock Turtle has
*Kconfig* support which allows you to interactivly enable/disable both
library and framework. You should create a local ``Kconfig`` file in
your firmware directory; in this file you must include the generic
one offerd by Mock Turtle.::
one from Mock Turtle.::
mainmenu "Project Firmware Name"
......@@ -195,6 +201,6 @@ one offerd by Mock Turtle.::
# INCLUDE GENERIC Kconfig
source "Kconfig.mt"
The configuration options are not documented here. For more details
use the help messages provided by Kconfig: run ``make menuconfig``
Configuration options are not documented here. For more details
use the help messages from Kconfig: run ``make menuconfig``
from your firmware directory.
doc/software/linux-driver.rst
View file @ 7d4ee06e
.. hightlight:: none
.. _`sw:lnx:drv`:
=========================
......@@ -24,7 +26,7 @@ Compile And Install
====================
The Mock Turtle device driver compilation and installation requires only
to execute ``make``.::
to execute ``make``.
$ cd /path/to/mockturtle/software/kernel
$ export LINUX=/path/to/linux/sources
......@@ -60,10 +62,10 @@ Load Gateware
Of course, a Mock Turtle instance must exist on your FPGA in order to be able
to drive it. Loading the gateware bitstream depends on the FPGA carrier in use.
Just keep in mind that you must load the bitstream before adding a Mock Turtle
device instance in the Linux kernel. If you do not do so, you will get crashes
because the device driver will try to access something that has not been
loaded yet.
Just keep in mind that you must load the bitstream **before** adding a
Mock Turtle device instance in the Linux kernel. If you do not do so, you will
get crashes because the device driver will try to access something that does
not exist yet.
.. _integration:software:host:linux:platform:
......@@ -72,7 +74,7 @@ Load Device
The Mock Turtle device driver is based on the platform Linux subsystem
[1]_ . This means that you need a mechanism to load a platform device that
describes the Mock Turtle device. Typically, this mechanism involves the
describes a Mock Turtle device. Typically, this mechanism involves the
development of a Linux module or the DeviceTree.
This driver handles all platform_device instances which name is one of
......@@ -114,7 +116,9 @@ Mock Turtle Device
The Mock Turtle driver exports a *char device* for each Mock Turtle.
In */dev/mockturtle* you will have devices named ``trtl-%04x``
(trtl-<device-id>).
(trtl-<device-id>). This exports a set of ``ioctl(2)`` commands:
.. doxygendefine:: TRTL_IOCTL_SMEM_IO
You can find the cores *sysfs* attributes at::
......@@ -143,15 +147,15 @@ Mock Turtle Cores
The Mock Turtle driver exports a *char device* for each Mock Turtle core.
All core instances will appear as child of a :ref:`sw:drv:dev`; in
*/dev/mockturtle* you will have devices named ``trtl-%04x-%02d``
*/dev/mockturtle* you will have devices named *trtl-%04x-%02d``*
(trtl-<device-id>-<cpu-index>). The main purpose of this interface is to
program (or rarely useful dump) firmwares into cores. These devices are
bidirectional, so you can: ``write(2)`` to program a firmware, ``read(2)``
to dump a firmware; ``lseek(2)`` to move to different locations.
to dump a firmware; ``lseek(2)`` to move to different memory locations.
Mock Turtle uses the standard TTY layer form the Linux kernel. Each
core has a dedicated serial interface which is used for communications
from the soft-CPU to the host system.
from soft-CPU to host.
Linux TTY devices appear in the */dev* directory and they are named
*ttytrtl-%04x-%d*.
......@@ -199,11 +203,10 @@ All HMQ instances will appear as child of a :ref:`sw:drv:core`; in
(trtl-<device-id>-<cpu-index>-<hmq-index>). The main purposes of this
interface is to exchange messages and configure filters. These devices
are bidirectional, so you can: ``write(2)`` to send messaged;
``read(2)`` to receive messages; ``poll(2)`` or ``select(2)`` to wait.
``read(2)`` to receive messages; ``poll(2)`` or ``select(2)`` to wait
for the interface to become accessible.
This *char device* has also a little set of ``ioctl(2)`` commands to configure
filters: :c:macro:`TRTL_IOCTL_MSG_FILTER_ADD`,
:c:macro:`TRTL_IOCTL_MSG_FILTER_CLEAN`.
This *char device* provides a set of ``ioctl(2)`` commands:
.. doxygendefine:: TRTL_IOCTL_MSG_FILTER_ADD
......@@ -224,10 +227,15 @@ You can find the HMQ *sysfs* attributes at::
- Description
* - empty
- RO
- 1 when the HMQ channel buffer is empty, 0 otherwise (hardware)
- It shows the input and output empty status:
1 when the HMQ channel buffer is empty, 0 otherwise (hardware)
* - full
- RO
- 1 when the HMQ channel buffer is full, 0 otherwise (hardware)
- It shows the input and output full status:
1 when the HMQ channel buffer is full, 0 otherwise (hardware)
* - occupied
- RO
- The number of entries in the queue for input and output
* - discard_all
- WO
- When written it flushes the HMQ from all pending messages
......
doc/software/linux-library.rst
View file @ 7d4ee06e
.. highlight:: none
.. _`sw:lnx:library`:
==============================
......@@ -58,7 +60,10 @@ CPU management. This means to be able to:
- reset/unreset a soft-CPU
The typical use of these functions is to load an executable file into
the soft-CPU. The following listing shows an example::
the soft-CPU. The following listing shows an example
.. highlight:: c
.. code:: c
void progr_cpu(struct trtl_dev *trtl, unsigned int cpu_idx, char *file_name)
{
......@@ -69,6 +74,7 @@ the soft-CPU. The following listing shows an example::
trtl_cpu_start(trtl, cpu_idx);
}
.. highlight:: none
Initialization
......
doc/software/protocol.rst
View file @ 7d4ee06e
......@@ -5,11 +5,6 @@
Common Data Structures
===========================
When exchanging messages between two entities it is always handy
to have a protocol. Any Mock Turtle message queue has an header part and
a payload part. It is within the header part that users put the information
to handle the choosen protocol.
.. _`sw:cfg`:
Configuration ROM
......@@ -37,6 +32,11 @@ with different APIs, by both host system and firmwares.
Host Message Queue Protocol
==============================
When exchanging messages between two entities it is always handy
to have a protocol. Any Mock Turtle message queue has an header part and
a payload part. It is within the header part that users put the information
to handle the choosen protocol.
In order to standardize the message exchange between host and firmwares
a message header has been defined. This header is expected to be in the
message queue header buffer.
......@@ -71,3 +71,7 @@ Remote Message Queue Protocol
Within this project we have defined a protocol for the communication with
the host system. How to handle the communication with remote nodes is left
to the user who can chose among dozen of existing protocols (for example UDP).
Also for remote queues a message is made of header and payload; whatever is
your choosen protocol, its header will lay in the header part and the payload
the payload part. End-points can use the header part to configure them selves
with user parameters.
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