Skip to content
Projects
Groups
Snippets
Help
Loading...
Sign in
Toggle navigation
M
Mock Turtle
Project
Project
Details
Activity
Cycle Analytics
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Charts
Issues
1
Issues
1
List
Board
Labels
Milestones
Merge Requests
0
Merge Requests
0
Wiki
Wiki
image/svg+xml
Discourse
Discourse
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Charts
Create a new issue
Commits
Issue Boards
Open sidebar
Projects
Mock Turtle
Commits
a4c7b3ed
Commit
a4c7b3ed
authored
May 09, 2019
by
Dimitris Lampridis
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
doc: documentation proofreading
parent
e5ee2536
Hide whitespace changes
Inline
Side-by-side
Showing
25 changed files
with
323 additions
and
299 deletions
+323
-299
README.rst
README.rst
+30
-33
architecture.rst
doc/architecture.rst
+66
-47
fmc-spec-carrier.rst
doc/demos/fmc-spec-carrier.rst
+6
-5
fmc-svec-carrier.rst
doc/demos/fmc-svec-carrier.rst
+15
-13
hello-world.rst
doc/demos/hello-world.rst
+3
-3
index.rst
doc/demos/index.rst
+7
-7
glossary.rst
doc/glossary.rst
+16
-24
index.rst
doc/index.rst
+1
-1
firmware-framework.rst
doc/software/firmware-framework.rst
+38
-35
firmware-library.rst
doc/software/firmware-library.rst
+26
-22
index-fw.rst
doc/software/index-fw.rst
+9
-9
index-lnx.rst
doc/software/index-lnx.rst
+6
-6
index.rst
doc/software/index.rst
+14
-17
linux-driver.rst
doc/software/linux-driver.rst
+40
-34
linux-library.rst
doc/software/linux-library.rst
+17
-17
linux-python.rst
doc/software/linux-python.rst
+4
-3
protocol.rst
doc/software/protocol.rst
+9
-7
mockturtle-buffer.rst
doc/tools/mockturtle-buffer.rst
+3
-3
mockturtle-cpu-restart.rst
doc/tools/mockturtle-cpu-restart.rst
+1
-1
mockturtle-firmware-loader.rst
doc/tools/mockturtle-firmware-loader.rst
+2
-2
mockturtle-messages.rst
doc/tools/mockturtle-messages.rst
+2
-2
mockturtle-ping.rst
doc/tools/mockturtle-ping.rst
+2
-2
mockturtle-project-creator.rst
doc/tools/mockturtle-project-creator.rst
+1
-1
mockturtle-smem.rst
doc/tools/mockturtle-smem.rst
+2
-2
mockturtle-variable.rst
doc/tools/mockturtle-variable.rst
+3
-3
No files found.
README.rst
View file @
a4c7b3ed
...
...
@@ -4,26 +4,24 @@
Introduction
============
The
Mock Turtle is a framework to develop embedded systems on FPGA.
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
software application. Software takes more computation time than a
custom-designed gateware core; but on the other hand, the development
and support efforts are significantly reduced. Mock Turtle is a solution
for such problem. The gateware core complexity is moved to the software
domain within the Mock Turtle boundaries, without sacrificing
determinism.
software application. Typically, software takes more computation time
than a custom-designed gateware core; but on the other hand, the
development and support efforts are significantly reduced. By using Mock
Turtle, the gateware core complexity is moved to the software domain
within the Mock Turtle boundaries, without sacrificing determinism.
The Mock Turtle framework provides an infrastructure on which you can
build an FPGA-based embedded system. The basic ingredient of this
framework is a soft-
cpu
multi-core environment that can be used to write
framework is a soft-
CPU
multi-core environment that can be used to write
firmware to control/monitor gateware cores. In other words, you can
connect Mock Turtle to your gateware cores and control them with the
firmware running on the soft-cpu. In addition, the Mock Turtle framework
provides a communication channel between the firmware and the
host applications which can be used to configure or control the
firmware.
firmware running on the soft-CPU. In addition, the Mock Turtle framework
provides a communication channel between the firmware and the host
applications which can be used to configure or control the firmware.
The Mock Turtle framework focuses mainly on the determinism of the
firmware running in it. Indeed, Mock Turtle does not support any kind of
...
...
@@ -50,7 +48,7 @@ The Mock Turtle framework includes the following components:
- the Mock Turtle firmware framework to develop firmware
If
the
Mock Turtle is used within a Linux host system, the user can take
If Mock Turtle is used within a Linux host system, the user can take
advantage of a number of software components which run on the host and
support Mock Turtle:
...
...
@@ -65,13 +63,13 @@ support Mock Turtle:
Use Cases
==========
The focus on the high determinism of the soft-cpus makes the Mock Turtle
a very good candidate to implement rtc systems and control
systems (which are, typically, rtc applications).
The focus on the high determinism of its soft-CPUs makes Mock Turtle
a very good candidate to implement (typically real-time) control systems.
To make clear the system architecture differences let’s take the
classical control system from the control theory: the heating system. We
have a thermometer sensor, and an actuator to adjust the temperature.
To demonstrate the system architecture and benefits of Mock Turtle,
let’s take the classical control system example from control theory: the
heating system. We have a thermometer sensor, and an actuator to adjust
the temperature.
The following figures show the control system architecture with and
without Mock Turtle.
...
...
@@ -92,33 +90,32 @@ without Mock Turtle.
In the scenario without Mock-Turtle in figure the
user is responsible for the entire development. On the other hands, with
Mock Turtle, the user will be responsible of the development only of
your business logic. This will limit your gateware development to the
essential blocks, and move the control logic to the software domain. You
do not have to care about the communication with the host system or the
In the scenario without Mock-Turtle, the user is responsible for the
entire development. On the other hand, with Mock Turtle, the user will
be responsible only for the development of the application-specific
control logic, which is moved to the software domain. The user does not
have to care about the communication with the host system or the
external world because it’s already part of the Mock Turtle framework.
.. _introduction:when-do-not-consider-mock-turtle:
When
To Not
Consider Mock Turtle
When
Not To
Consider Mock Turtle
--------------------------------
The Mock Turtle soft-CPUs have limited computation power, this precludes
some applications like: dsp.
Since the Mock Turtle soft-CPUs have limited computation power, this
precludes using it for applications like Digital Signal Processing
(DSP).
If you really want to use Mock Turtle for dsp analysis, please consider
the development of a dedicated gateware core to perform the dsp analysis
and to use the Mock Turtle as a control system for the dsp gateware
core.
the development of a dedicated gateware core to perform the DSP analysis
and to use Mock Turtle as a control system for the DSP gateware core.
Where To Get Mock Turtle
========================
Mock Turtle is officially hosted on the `Open Hardware Repository`_:
`Mock Turtle`_. This project is distributed as a git repository which
can
be cloned using the following command::
`Mock Turtle`_. This project is distributed as a git repository which
can
be cloned using the following command::
git clone https://ohwr.org/project/mock-turtle.git
...
...
doc/architecture.rst
View file @
a4c7b3ed
...
...
@@ -4,34 +4,33 @@
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 Mock Turtle framework offers a complete and integrated stack from
the HDL core to the software application.
The following figure shows an overview o
ver
the Mock Turtle architecture.
The following figure shows an overview o
f
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).
Grey blocks are external components (gateware cores or software)
developed by the user. In purple any external world communication
over the network.
The blue and orange blocks are Mock Turtle components (respectively
software and gateware cores). Grey blocks are external components
(gateware cores or software) developed by the user. Purple represents
any communication to the external world 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.
This
chapter tries to provide an overview of what Mock Turtle offers and
what is important to know when designing a Mock Turtle application.
For more information read the dedicated chapters for the different parts.
For more information, please read the dedicated chapters for the
different parts.
Mock Turtle Core
==================
Mock Turtle can have one or more cores. A single core is made of the
following
components: soft-CPU, Serial console and message queues.
Mock Turtle can have one or more cores. A single core is made of the
following
components: soft-CPU, Serial console and message queues.
Soft-CPU
---------
...
...
@@ -46,7 +45,7 @@ The memory size for code and data is :ref:`configurable at synthesis time <hdl:c
.. _uRV processor: https://www.ohwr.org/project/urv-core
.. _`RISC-V`: https://riscv.org/
For more information
about
how to handle cores from software, please read:
For more information
on
how to handle cores from software, please read:
- :ref:`Linux Library - Cores Management<sw:lnx:lib:cpu>`
...
...
@@ -55,7 +54,7 @@ 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.
a serial buffer, Mock Turtle raises an interrupt
to
the host.
.. graphviz::
:align: center
...
...
@@ -75,23 +74,28 @@ a serial buffer, Mock Turtle raises an interrupt for the host.
fw3 -> "Serial 3" -> host;
}
This is used to send string messages from the running firmware to the host system:
This is used to send string messages from the running firmware to the
host system.
For more information on how to access the serial console from the
firmware, please read:
- :ref:`Firmware Library - Serial Interface<sw:fw:lib:uart>`
Message Queue
----------------
Mock Turtle firmwar
e can communicate with external agents using
*message queues*; as the name suggests, th
is is a message queue
with
Firmware running on Mock Turtl
e can communicate with external agents using
*message queues*; as the name suggests, th
ese are message queues
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).
for external communication (*remote message queue*).
All message queues
are
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.
A message queue entry is split in two fixed size buffers: header and
payload. The header buffer should be used to store a protocol header,
while the payload buffer should be used to store the message content to
be exchanged.
.. figure:: img/mock-turtle-mq.svg
:align: center
...
...
@@ -112,30 +116,35 @@ input and output queues:
- 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.
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 are not handled by the host system. They must be
connected to an *end-point* that provides a connection to the external
world.
Their task is to pack and unpack messages according to the type of network to
which are connected. The end-point implementation is application specific and
outside the Mock Turtle scope. Mock Turtle offers a set of generic end-points
that you can use.
connected to an *end-point* that provides a connection to the external
world. Their task is to pack and unpack messages according to the type
of network they are connected to. The end-point implementation is
application specific and outside the scope of Mock Turtle. Mock Turtle
offers a set of generic end-points
that you can use.
For more information about how to access it from software, please read:
For more information on how to access message queues from the firmware,
please read:
- :ref:`Firmware Library - Message Queue<sw:fw:lib:mq>`
For more information on how to access message queues from user space,
please read:
- :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.
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. Since access to the shared memory is serialized, an
intensive use of it
can affect the determinism.
.. graphviz::
:align: center
...
...
@@ -156,13 +165,16 @@ can affect the determinism.
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:
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 on how to access the shared memory from the firmware, please read:
- :ref:`Firmware Library - Shared Memory<sw:fw:lib:shm>`
For more information on how to access the shared memory from user space, please read:
- :ref:`Linux Library - Shared Memory<sw:lnx:lib:shm>`
.. _`arch:dp`:
...
...
@@ -170,11 +182,17 @@ how to access it from software read:
Device Peripherals
==================
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.
Device peripherals are external components connected to a Mock Turtle
core over a Wishbone interface. What they do, how many they are and how
they are connected is application specific: Mock Turtle just offers
connections to cores.
Once a device peripheral is connected to a Mock Turtle core, firmware
running on that core can access the peripheral by performing
reads/writes over Wishbone.
Note that device peripherals are not directly accessible from user
space. Only the firmware can access them.
.. graphviz::
:align: center
...
...
@@ -200,6 +218,7 @@ to address the device.
{rank=same; "Custom Logic"; "I2C master"; "SPI master"}
}
For more information about how to access it from software, please read:
For more information about how to access device peripherals from the
firmware, please read:
- :ref:`Firmware Library - Memory Location<sw:fw:lib:mem>`
doc/demos/fmc-spec-carrier.rst
View file @
a4c7b3ed
.. _`demo:spec`:
===================
The *FMC SPEC* Demo
===================
...
...
@@ -9,7 +11,7 @@ application. Apart from the board itself, no other hardware is necessary to
run the demo.
The main aim of this demo is to handle the SPEC LEDs and buttons. The LEDs
can be turned *on* and *off*
. Buttuns' statu
s can be read.
can be turned *on* and *off*
and the status of the button
s can be read.
HDL Code
==========
...
...
@@ -98,7 +100,7 @@ The expected output from the simulation is::
Software
=========
This demo
has two firmware
. One is named *blinker* (fw-01), the other
This demo
uses two firmware programs
. One is named *blinker* (fw-01), the other
*controller* (fw-02).
The *blinker* firmware runs autonomously without any communication with the host
...
...
@@ -116,9 +118,8 @@ the following things:
The *controller* firmware gives you the possibility to control the *blinker*.
This firmware does the following things:
- it exportes as :ref:`sw:fw:frm:var` the blinking mode (it's on the shared
memory);
- it exportes as :ref:`sw:fw:frm:var` the buttons actions (it's on the shared memory);
- it exports as a shared memory :ref:`variable <sw:fw:frm:var>` the blinking mode;
- it exports as a shared memory :ref:`variable <sw:fw:frm:var>` the buttons' actions;
.. highlight:: c
.. literalinclude:: ../../demos/fmc-spec-carrier/software/firmware/fw-02/fw-spec.c
...
...
doc/demos/fmc-svec-carrier.rst
View file @
a4c7b3ed
.. _`demo:svec`:
====================
The *FMC SVEC* Demo
====================
...
...
@@ -105,7 +107,7 @@ The expected output from the simulation is::
Software
=========
This demo
has two firmware
. One is named *autosvec* (fw-01), the other
This demo
uses two firmware programs
. One is named *autosvec* (fw-01), the other
*manualsvec* (fw-02).
The *autosvec* firmware runs autonomously without any communication with the host
...
...
@@ -114,7 +116,7 @@ It does not use :ref:`sw:fw:frm` but only :ref:`sw:fw:lib`. This firmware does
the following things:
- it turns *on* and *off* all the LEDs one after the other;
- it reproduce on LEMO connector 2 whatever state is on LEMO connector 1
- it reproduce
s
on LEMO connector 2 whatever state is on LEMO connector 1
- it generates square signals on LEMO connectors 3
- it generates square signals on LEMO connectors 4
- it periodically prints messages on the console with the GPIO status (LEDs
...
...
@@ -126,37 +128,37 @@ the following things:
The *manualsvec* firmware offers a manual control of all LEDs and LEMOs.
It does use :ref:`sw:fw:frm`. This firmware does the following things:
- it export
es as :ref:`sw:fw:frm:var
` the device peripheral registers
- it export
s as :ref:`variables <sw:fw:frm:var>
` the device peripheral registers
to configure LEDs and LEMOs
-
to exports a local :ref:`sw:fw:frm:buf
` where the user can read and write
-
it exports a local :ref:`buffer <sw:fw:frm:buf>
` where the user can read and write
(it is not used)
- it exports a local :ref:`variable <sw:fw:frm:var>` that can be used to
stop/start an *autosvec* firmware running on a different core.
.. note::
Rem
b
ember that the SVEC connects LEMO 3 and LEMO 4 to the same GPIO port.
Remember that the SVEC connects LEMO 3 and LEMO 4 to the same GPIO port.
This means that they must have the same direction (both input, or both
output)
.. highlight:: c
.. literalinclude:: ../../demos/fmc-svec-carrier/software/firmware/fw-02/fw-svec.c
This firmware
has also a support layer on
the host side. This is not really
necessary because you can always use
s
the generic Mock Turtle tools
This firmware
also provides a support layer to
the host side. This is not really
necessary because you can always use the generic Mock Turtle tools
to :ref:`read/write variables <tools:mockturtle-variable>` and
to :ref:`read/write buffers <tools:mockturtle-buffer>`; but for the sake of
mak
e this demos as complete as possible we added an
host support layer which is
made of a C library and a C program. A
part from the standard operations to open
and close a device, the library exports an API to handle the LEDs and LEMOs
status and functions
to set/get a dummy data structure. This library is mainly a
mak
ing this demo as complete as possible we added a
host support layer which is
made of a C library and a C program. Apart from the standard operations to open
and close a device, the library exports an API to handle the
status of the
LEDs and LEMOs
and
to set/get a dummy data structure. This library is mainly a
wrapper around the Mock Turtle one.
.. highlight:: c
.. literalinclude:: ../../demos/fmc-svec-carrier/software/lib/libsvec.c
At the end,
the host program. This program is a command line tool that uses the
Last but not least, there is
the host program. This program is a command line tool that uses the
svec library described above to handle the SVEC board. Again, it gives users
the possibility to play with
LEDs and LEMOs statu
s.
the possibility to play with
the status of the LEDs and LEMO
s.
.. highlight:: c
.. literalinclude:: ../../demos/fmc-svec-carrier/software/tools/mockturtle-svec.c
...
...
doc/demos/hello-world.rst
View file @
a4c7b3ed
...
...
@@ -3,7 +3,7 @@ The *Hello World* Demo
==========================
The *Hello World* demo is a firmware program that prints
over the serial interface the string ``"Hello World"`` and exit.
over the serial interface the string ``"Hello World"`` and exit
s
.
This program makes use of the :ref:`sw:fw:lib`.
...
...
@@ -16,8 +16,8 @@ This program makes use of the :ref:`sw:fw:lib`.
.. literalinclude:: ../../demos/hello_world/firmware/fw-01/fw-hello.c
There is also the *Hello World* demo based on the :ref:`sw:fw:frm`.
This demo will print on the serial interface general information
s
about
the firmware application.
This demo will print on the serial interface general information
regarding
the firmware application.
::
...
...
doc/demos/index.rst
View file @
a4c7b3ed
...
...
@@ -4,15 +4,15 @@
The Demos
============
This is a collection of demo applications wh
ich
main purpose is to
This is a collection of demo applications wh
ose
main purpose is to
introduce the users to the Mock Turtle development. In the following
demos you will find some example code to run and test the applications.
Unless it is explicitly specified, these demos can run on **any** Mock Turtle
instance, in other words they do not depends on a specific HDL or hardware
design.
You will notice the usage of environment variable; these variables, of
course, depend o
f your environment. Here a list of used variable
You will notice the usage of environment variable
s
; these variables, of
course, depend o
n your environment. Here is a list of used variables:
TRTL
This is the path to the root directory of the Mock Turtle project.
...
...
@@ -35,9 +35,9 @@ DEMO
``software/demos`` main directory.
In principle you can compile all the demos by running *make* in the main
directory. Then you can load the firmware using
:ref:`tools:mockturtle-firmware-loader`
and restart the CPU with
:ref:`tools:mockturtle-cpu-restart`::
directory. Then you can load the firmware using
the
:ref:`tools:mockturtle-firmware-loader`
tool and restart the CPU with the
:ref:`tools:mockturtle-cpu-restart`
tool
::
# Compile
make -C $DEMO
...
...
@@ -48,7 +48,7 @@ directory. Then you can load the firmware using
.. toctree::
:maxdepth: 2
:caption: Contents
:
:caption: Contents
hello-world
data-generator
...
...
doc/glossary.rst
View file @
a4c7b3ed
...
...
@@ -5,73 +5,65 @@ Glossary
.. glossary::
Control System
It is a system that manage
, commands, regulates the behaviour of a set
A system that manages
, commands, regulates the behaviour of a set
of devices.
Digital Signal Processing
The use of digital processing to perform a wide variety of signal
processing operations.
CPU-Core
It is a soft-CPU in Mock Turtle
Embedded System
It is a
n autonomus system made of software, hardware (and gateware),
A
n autonomus system made of software, hardware (and gateware),
implementing dedicated functions
End-Point
It is a
gateware core connected to a Mock Turtle RMQ that provides
A
gateware core connected to a Mock Turtle RMQ that provides
connection to an external network.
Firmware
It is an embedded software system running on the Mock Turtle cpu-core
.
An embedded software system running on a Mock Turtle soft-CPU
.
Gateware
It is a
bitstream which configures an FPGA, or the HDL sources
A
bitstream which configures an FPGA, or the HDL sources
from which it was generated.
Gateware Core
It is a
n HDL component part of a more complex gateware design.
A
n HDL component part of a more complex gateware design.
Hardware
It is a
physical component.
A
physical component.
Host
It is the system that hosts the hardware in use.
Host Application
It is a
user space program running on the host system.
A
user space program running on the host system.
HMQ
Host Message Queue
It is a
message queue that connects Mock Turtle to the host system.
A
message queue that connects Mock Turtle to the host system.
MQ
Message Queue
It is a
communication system based on queues with FIFO policy. Messages are
A
communication system based on queues with FIFO policy. Messages are
put on the queue and they are sent to the programmed destination. Each
message queue has two direction: input and output.
message queue has two direction
s
: input and output.
Mock Turtle supports two message queues: host and remote.
RTC
Real-Time Computing
It is an hardware and software system subject to time constraints.
RMQ
Remote Message Queue
It is a
message queue that connects the Mock Turtle to a network.
A
message queue that connects the Mock Turtle to a network.
SHM
Shared Memory
It is a
memory shared among soft-CPUs and the host system.
A
memory shared among soft-CPUs and the host system.
Soft CPU
soft-cpu
It is an HDL implementation of a CPU running on an FPGA.
An HDL implementation of a CPU running on an FPGA.
MQ Entry
It is a
single element in the MQ.
A
single element in the MQ.
User Space
It is a software running on the host and it is
not in kernel mode.
A software running on the host, but
not in kernel mode.
This includes libraries and programs.
doc/index.rst
View file @
a4c7b3ed
...
...
@@ -8,7 +8,7 @@ Welcome to Mock Turtle's documentation!
.. toctree::
:maxdepth: 1
:caption: Contents
:
:caption: Contents
introduction
architecture
...
...
doc/software/firmware-framework.rst
View file @
a4c7b3ed
...
...
@@ -6,17 +6,17 @@
The Mock Turtle Firmware Framework
==================================
Mock Turtle firmware framework guides users
development by
keeping them focused on
ly on
the core logic without the need to deal
The Mock Turtle firmware framework guides users'
development by
keeping them focused on the core logic without the need to deal
with Mock Turtle architectural details.
This API is available by including ``mockturtle-framework.h`` in your source file
.
::
This API is available by including ``mockturtle-framework.h`` in your source file::
#include <mockturtle-framework.h>
We recommend this framework to develop Mock Turtle firmware. You should
consider alternatives if you see that it
’
s consuming too much memory or
th
e performances are
not enough for your application.
consider alternatives if you see that it
i
s consuming too much memory or
th
at the performance is
not enough for your application.
.. note::
...
...
@@ -26,13 +26,13 @@ the performances are not enough for your application.
Application
===========
Firmware
s developed with this framework need
to be described by
:c:type:`trtl_fw_application`. Firmware applications develop with this
framework do
es
not have a ``main()``. The ``main()`` is implemented within the
framework itself. What you should do is to declare a new
Firmware
developed with this framework needs
to be described by
:c:type:`trtl_fw_application`. Firmware applications develop
ed
with this
framework do not have a ``main()``. The ``main()`` is implemented within the
framework itself. What you should do i
nstead i
s to declare a new
:c:type:`trtl_fw_application` named **app** and implement the operations
*init*, *main* and *exit*. These operations are all optional, it means that if
you do not implement them nothing will be executed.
you do not implement them
,
nothing will be executed.
.. graphviz::
:align: center
...
...
@@ -45,7 +45,7 @@ you do not implement them nothing will be executed.
Here
an example.
::
Here
is a minimal example of a firmware using the framework
::
#include <mockturtle-framework.h>
...
...
@@ -83,7 +83,7 @@ Here an example.::
};
The Mock Turtle is FPGA based, this means that the firmware are
Since the Mock Turtle is FPGA-based, the firmware is
typically loaded by the host. The procedure is error prone, so it may
happen to load the wrong firmware with unpredictable consequences. To
limit the damage, the ``fpga_id_compat`` can be used to declare a
...
...
@@ -102,23 +102,24 @@ not provide a compatibility list (like in the example above).
Actions
========
The *action* is s function that get executed when a special message
arrives through a mq slot. In order words, an action is similar to an RPC.
The *action* is a function that gets executed when a special message
arrives through a message queue. In order words, an action is similar to a
remote procedure call (RPC).
The firmware framework relies on the :ref:`sw:proto:hmq` to make this work.
The mechanism is quite simple. The Mock Turtle message header has a
dedicated flag to mark a message as an RPC call
:c:macro:`TRTL_HMQ_HEADER_FLAG_RPC`. When this flag is set, the firmware
framework interprets the header’s message-id as action-id. Thus, the
correspond
ent function get
executed.
correspond
ing function gets
executed.
This framework support up to :c:macro:`__TRTL_MSG_ID_MAX` actions.
This framework support
s
up to :c:macro:`__TRTL_MSG_ID_MAX` actions.
Part of it (:c:macro:`__TRTL_MSG_ID_MAX_TRTL`) is reserved for internal use,
the rest (:c:macro:`__TRTL_MSG_ID_MAX_USER`) can be used to implement new
actions. The reserved IDs are at the end of the number space and they are
defined in :c:type:`trtl_msg_id`.
The declaration of a new user action consists
in
4 steps:
The declaration of a new user action consists
of
4 steps:
#. enumerate the action IDs, share it with host;
...
...
@@ -133,7 +134,9 @@ The declaration of a new user action consists in 4 steps:
The framework does not execute actions automatically. Once the actions
are declared, the user must ask the framework to dispatch incoming actions.
This is performed by :c:func:`trtl_fw_mq_action_dispatch`, which listens for
RPC messages on a given mq. Here an example.::
RPC messages on a given mq.
Here is an example of declaring and using an action::
#include <mockturtle-framework.h>
...
...
@@ -192,10 +195,10 @@ Variables
The firmware framework offers the possibility to export local variables
to the host system. Variables must be declared using the
:c:type:`trtl_fw_variable` and then exported
in
your
:c:type:`trtl_fw_variable` and then exported
by
your
:c:type:`trtl_fw_application`.
The mean
of
variable in this context is extended to any memory location:
The mean
ing of a
variable in this context is extended to any memory location:
local variable, Mock Turtle registers, device peripheral registers
and so on.
...
...
@@ -269,12 +272,12 @@ From the host you can read/write the variable by using the
.. highlight:: c
In chapter :ref:`sw:lnx:lib:hmq` you can find the correspond
ent
host API,
which
in few words consists in two function
: :c:func:`trtl_fw_variable_set`
In chapter :ref:`sw:lnx:lib:hmq` you can find the correspond
ing
host API,
which
consists of two functions
: :c:func:`trtl_fw_variable_set`
and :c:func:`trtl_fw_variable_get`.
What we have seen until now it is handled automatically by this
framework.
The user can send, asynchronously, variables of choice using the function
All of the above is handled automatically by the
framework.
The user can
also
send, asynchronously, variables of choice using the function
:c:func:`trtl_fw_mq_send_buf`.
.. doxygenfunction:: trtl_fw_mq_send_uint32
...
...
@@ -286,11 +289,11 @@ Buffers
The firmware framework offers the possibility to export local buffers to
the host system. The buffers must be declared using the
:c:type:`trtl_fw_buffer` and then exported
in
your
:c:type:`trtl_fw_buffer` and then exported
by
your
:c:type:`trtl_fw_application`.
The meaning of
buffer in this context is extended to any contiguous memory
location.
The meaning of
a buffer in this context is extended to any contiguous
memory
location.
The framework handles the buffer exchange as a special action.
Internally, the framework defines actions to write and to read buffers.
...
...
@@ -357,20 +360,20 @@ From the host you can read/write the buffer by using the
.. highlight:: c
In chapter :ref:`sw:lnx:lib:hmq` you can find the correspond
ent host API;
in a few words consists of two function: :c:func:`trtl_fw_buffer_set`
and
:c:func:`trtl_fw_buffer_get`.
In chapter :ref:`sw:lnx:lib:hmq` you can find the correspond
ing host
API, which consists of two functions: :c:func:`trtl_fw_buffer_set` and
:c:func:`trtl_fw_buffer_get`.
What we have seen until now it is handled automatically by this framework.
The user can send, asynchronously, buffer
of choice using the function
All of the above is handled automatically by the framework. The user
can also send, asynchronously, buffers
of choice using the function
:c:func:`trtl_fw_mq_send_buf`.
.. doxygenfunction:: trtl_fw_mq_send_buf
Utilitie
s
=========
Miscellaneou
s
=========
====
Th
is is a collection of miscellaneous functions that can be of some helper
s.
Th
e following is a list of miscellaneous, helper function
s.
.. doxygenfunction:: trtl_fw_time
...
...
doc/software/firmware-library.rst
View file @
a4c7b3ed
...
...
@@ -17,7 +17,7 @@ Turtle firmware.
.. warning::
Any firmware develop without this library will not receive any kind
Any firmware develop
ed
without this library will not receive any kind
of support.
.. _`sw:fw:lib:mem`:
...
...
@@ -25,11 +25,13 @@ Turtle firmware.
Read And Write Memory Locations
===============================
This firmware library offers a set of function to read/write memory locations.
You can access local register with :c:func:`lr_readl()` and
This firmware library offers a set of functions to read/write memory locations.
You can access local registers with :c:func:`lr_readl()` and
:c:func:`lr_writel()`.
You can access device peripherals with :c:func:`dp_readl()` and
:c:func:`dp_writel()`
.
::
:c:func:`dp_writel()`::
#include <mockturtle-rt.h>
...
...
@@ -107,7 +109,7 @@ All these functions are based on the generic :c:func:`readl()` and
.. _`sw:fw:lib:mq`:
Message Queue
Message Queue
s
================
Mock Turtle cores' main communication mechanism is the message queues.
...
...
@@ -115,18 +117,18 @@ The API is almost identical for both remote and host because most of these
functions have the *message queue type* argument to distinguish them.
You can handle the message queue with the commands: *claim*, *send*,
*discard*, *purge*. For each of these command there is a function that
*discard*, *purge*. For each of these command
s
there is a function that
you can call to execute that command: :c:func:`mq_claim`, :c:func:`mq_send`,
:c:func:`mq_discard`, :c:func:`mq_purge`. A
part from performing active
:c:func:`mq_discard`, :c:func:`mq_purge`. Apart from performing active
actions on the message queue, sometimes we are interested only in their
status, expecialy we want to know if the message queue input channel is
status, expecialy w
hen w
e want to know if the message queue input channel is
*not empty* (it means that there is something to read) or the output channel
is *not full* (it means that there space for writing). You can check the queue
status with :c:func:`mq_poll_in` and :c:func:`mq_poll_out`.
The API usage is different for input and for output.
The typical procedure to send (output) messages
over
is the following.
The typical procedure to send (output) messages is the following.
#. *poll* the mq to see if there is at least an empty entry;
...
...
@@ -140,7 +142,7 @@ The typical procedure to send (output) messages over is the following.
#. *send* the data, which will also release the mq slot;
Here
the output example.
::
Here
is an example of how to send a message
::
#define HMQ_NUM 0
struct trtl_fw_msg msg;
...
...
@@ -168,7 +170,7 @@ The typical procedure to receive (input) messages is the following.
#. *discard* the slot, which will erase the data and point to the next
one;
Here
the input example.
::
Here
is an example on how to receive a message
::
#define HMQ_NUM 0
struct trtl_fw_msg msg;
...
...
@@ -184,8 +186,10 @@ Here the input example.::
mq_discard(TRTL_HMQ, HMQ_NUM);
The library does not perform any validation on the data you write in
the message. Any kind of overflow control is up to the user who can take
the payload size from the configuration rom using :c:func:`trtl_config_rom_get`.
the message. Any kind of overflow control is up to the user.
The size of the payload can be retrieved from the configuration rom using
:c:func:`trtl_config_rom_get`.
On the host you can read the messages using the tool :ref:`tools:mockturtle-messages`
...
...
@@ -212,7 +216,7 @@ On the host you can read the messages using the tool :ref:`tools:mockturtle-mess
These functions are enough to send and receive messages with both HMQ and RMQ.
Following a list of lower level functions which actually are
used to implement
The remaining functions listed below are actually
used to implement
the ones above.
.. note::
...
...
@@ -235,7 +239,7 @@ the ones above.
Shared Memory
=============
This is a collection of functions and macros wh
ich purposes are
:
This is a collection of functions and macros wh
ose purpose is
:
- to read/write the Mock Turtle shared memory
...
...
@@ -265,7 +269,7 @@ Then you can use a shared memory variable as a normal variable::
The shared memory provides a set of atomic operations, to avoid race conditions
while different cores are writing. There is a dedicated API for such operations.
Here
an example that uses all operations.
::
Here
is an example that uses all of the available operations
::
#include <mockturtle-rt.h>
...
...
@@ -301,7 +305,7 @@ Here an example that uses all operations.::
Serial Interface
=================
Over the serial interface you can
print formatted string messages.
You can user the serial interface to
print formatted string messages.
.. note::
Even if it is potentially possible to use the serial interface to
...
...
@@ -311,7 +315,7 @@ Over the serial interface you can print formatted string messages.
This API is based on :c:func:`pp_printf` and its different flavors:
:c:func:`pr_error`, :c:func:`pr_debug`.
Here
an exampl
e::
Here
is an example on how to print over the serial interfac
e::
#include <mockturtle-rt.h>
...
...
@@ -348,7 +352,7 @@ Host Notification
Mock Turtle has a mechanism that allows firmware to send arbitrary interrupts
to the host system. This mechanism is used by Mock Turtle software to deliver
special notifications; but this mechanism can be used as well by the user to
deliver cust
u
m notifications to their support layer.
deliver cust
o
m notifications to their support layer.
The Mock Turtle notifications are enumerated
by :c:type:`trtl_cpu_notification`. The user must start their enumeration
...
...
@@ -357,8 +361,8 @@ after the value *__TRTL_CPU_NOTIFY_MAX*.
.. doxygenenum:: trtl_cpu_notification
Mock Turtle will deliver a notification to the host when the firmware calls
:c:func:`trtl_notify()` or
, suggested for user's notification,
:c:func:`trtl_notify_user()`
.
:c:func:`trtl_notify()` or
:c:func:`trtl_notify_user()`. The latter is
suggested for users' notifications
.
.. doxygenfunction:: trtl_notify
...
...
@@ -367,7 +371,7 @@ Mock Turtle will deliver a notification to the host when the firmware calls
Miscellaneous
==============
At the end, this chapter is a collection of helpers
The following is a list of miscellaneous, helper functions.
.. doxygenfunction:: delay
...
...
doc/software/index-fw.rst
View file @
a4c7b3ed
...
...
@@ -30,15 +30,15 @@ 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 on
ly on
your core logic without the
development by keeping you focused on your core logic without the
need to deal with Mock Turtle architecture details.
The framework usage, rather than precluding the user
to use
library
The framework usage, rather than precluding the user
from using
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 performance
s
: don't use this framework.
memory) or you need much better performance: don't use this framework.
All the Mock Turtle firmware source code can be found in the directory
``/path/to/mockturtle/software/firmware/``.
...
...
@@ -63,7 +63,7 @@ Here the list of supported TBuild variables
OBJS
(Mandatory) List of object files to generate from sources with
the same name. The default is an empty variable, this mean that it
the same name. The default is an empty variable, this mean
s
that it
will not compile any source file.
OUTPUT
...
...
@@ -104,7 +104,7 @@ configuration of the target Mock Turtle instance.
please write your own linker script file and pass it to the build system
by using ``TRTL_LD_SCRIPT``.
You can build such firmware application by calling ``make`` from the
You can build such
a
firmware application by calling ``make`` from the
application directory (where the ``TBuild`` file is) like this::
make -C <path-to-mockturtle-project>/software/firmware M=$PWD
...
...
@@ -142,8 +142,8 @@ Configuration options are not documented here. For more details
use the help messages from Kconfig: run ``make menuconfig``
from your firmware directory.
Mock Turtle is using the *RISC-V* ISA,
this
means that your code must be
compiled for this instruction
-
set. Mock Turtle uses the environment variable
Mock Turtle is using the *RISC-V* ISA,
which
means that your code must be
compiled for this instruction
set. Mock Turtle uses the environment variable
``CROSS_COMPILE_TARGET`` to provide the path to the cross-compilation
toolchain. By default, Mock Turtle expects the cross-compilation toolchain
to be installed on your system and visible in ``PATH``. If this is not
...
...
@@ -154,7 +154,7 @@ the case you have to overwrite this variable.::
At this point you can call ``make(1)`` to build your firmware.
.. note:: If you do not know how to get the cross-compilation toolchain
or you need to build your own
one
, please have a look at the
or you need to build your own, please have a look at the
`soft-cpu toolchain`_ project on the `OHWR`_.
.. _`OHWR`: https://www.ohwr.org/
...
...
@@ -163,7 +163,7 @@ At this point you can call ``make(1)`` to build your firmware.
.. toctree::
:maxdepth: 2
:caption: Contents
:
:caption: Contents
firmware-library
firmware-framework
doc/software/index-lnx.rst
View file @
a4c7b3ed
...
...
@@ -4,14 +4,14 @@
Linux Development
====================
It includes an explaination about the
host development (libraries or
applications) and the Mock Turtle API on a Linux host.
Any future reference
to host
in this section will assume a Linux host because it is the only
This section provides details regarding
host development (libraries or
applications) and the Mock Turtle API on a Linux host.
References to a
"host"
in this section will assume a Linux host because it is the only
supported platform for the time being.
Mock Turtle offers 3 interfaces: a Py
hton module, a C library and
a Linux kernel interface. Mock Turtle users are not supposed to use
the driver interface directl
y.
Mock Turtle offers 3 interfaces: a Py
thon module, a C library and a
Linux kernel interface. Users are expected to use either the Python
module or the C librar
y.
.. graphviz::
:align: center
...
...
doc/software/index.rst
View file @
a4c7b3ed
...
...
@@ -4,36 +4,36 @@
The Software
==============
This
section
explains the Mock Turtle software architecture as well as
This
chapter
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
The
following discussion assumes that the reader already has
a general
understanding of :ref:`arch`
The Mock Turtle software stack consists
in
two main development domains:
the :ref:`sw:fw` and the
:ref:`sw:lnx`
The Mock Turtle software stack consists
of
two main development domains:
:ref:`sw:fw` and
:ref:`sw:lnx`
(libraries or applications).
The Mock Turtle software stack is made of different layers which main
objectives are:
The main objectives of the Mock Turtle software stack are:
- to
manage
the Mock Turtle cores from the host
- to
allow managing of
the Mock Turtle cores from the host
- to allow firmware to access Mock Turtle resources
- to provide a communication infrastructure between firmware and host
- to provide a communication infrastructure
with
remote nodes
- to provide a communication infrastructure
between
remote nodes
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
Mock Turtle API.
:ref:`sw:fw` is necessary to make any Mock Turtle based system to
work. In
the
:ref:`sw:fw` section
you will learn how to write a firmware using
the provided
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 cust
u
mized control/monitor
On the other hand,
:ref:`sw:lnx`
on the
host depends on your needs. If you need a cust
o
mized control/monitor
infrastructure for firmware, 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
the tools without developing any support layer.
...
...
@@ -41,12 +41,9 @@ the tools without developing any support layer.
We strongly recommend you to start the develpment of a new Mock Turtle
project by using the :ref:`tools:mockturtle-project-creator`.
Following a list of generic topics which are not specific to Linux or firmware
development.
.. toctree::
:maxdepth: 1
:caption: Contents
:
:caption: Contents
protocol
index-lnx
...
...
doc/software/linux-driver.rst
View file @
a4c7b3ed
...
...
@@ -16,17 +16,17 @@ Requirements
==============
The Mock Turtle device driver has been developed and tested on Linux
3.6. Other Linux versions might work as well but it is not guaranteed.
3.6, 3.10 and 4.14. Other Linux versions might work as well but it is
not guaranteed.
The FPGA address space must be visible on the host system. This requires
a driver for the FPGA carrier that export the FPGA address space to the
a driver for the FPGA carrier that export
s
the FPGA address space to the
host.
Compile And Install
====================
The Mock Turtle device driver compilation and installation requires only
to execute ``make``.::
The compile and install the Mock Turtle device driver simply execute ``make``::
$ cd /path/to/mockturtle/software/kernel
$ export LINUX=/path/to/linux/sources
...
...
@@ -36,13 +36,13 @@ to execute ``make``.::
Load Driver
=============
The Mock Turtle device driver module needs to be loaded in order to be
used
.
::
The Mock Turtle device driver module needs to be loaded in order
for it
to be
used::
$ cd /path/to/mockturtle/software/kernel
$ sudo insmod mock-turtle.ko
Following the list of module parameters that can be used to custu
mize
The following table lists the module parameters that can be used to custo
mize
the driver instance.
.. list-table::
...
...
@@ -60,12 +60,12 @@ the driver instance.
Load Gateware
================
Of course, a Mock Turtle instance must exist on your FPGA in order to be abl
e
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 doe
s
not exist yet.
A Mock Turtle instance must already exist on the FPGA in order to b
e
able to drive it. Loading the gateware bitstream depends on the FPGA
carrier in use. Therefore, the bitstream must be loaded to the FPGA
**before** adding a Mock Turtle device instance in the Linux kernel. If
not, the host will crash because the device driver will try to acces
s
something that does
not exist yet.
.. _integration:software:host:linux:platform:
...
...
@@ -73,11 +73,11 @@ 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 a Mock Turtle device. Typically, this mechanism involves the
development of a Linux module or the DeviceTre
e.
[1]_ . This means that you need a mechanism to load a platform device
that describes a Mock Turtle device. Typically, this mechanism involves
the development of a Linux module or a Device Tree Structur
e.
This driver handles all platform_device instances wh
ich
name is one of
This driver handles all platform_device instances wh
ose
name is one of
the following: "mock-turtle", "mockturtle".
The Mock Turtle device driver expects five ``resources`` from the platform
...
...
@@ -110,7 +110,7 @@ In */dev/mockturtle* you will have devices named *trtl-%04x*
.. doxygendefine:: TRTL_IOCTL_SMEM_IO
:outline:
You can find the
cores *sysfs* attributes
at::
You can find the
*sysfs* attributes for each instance of Mock Turtle
at::
/sys/class/mockturtle/trtl-%04x/
...
...
@@ -135,11 +135,14 @@ You can find the cores *sysfs* attributes at::
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``*
(trtl-<device-id>-<cpu-index>). The main purpose of this interface is to
program (or rarely useful dump) firmware into cores. These devices are
The Mock Turtle driver exports a *char device* for each Mock Turtle
core. All core instances will appear as children of a
:ref:`sw:drv:dev`; in */dev/mockturtle* you will have devices named
*trtl-%04x-%02d``* (trtl-<device-id>-<cpu-index>). The main purpose of
this interface is to program firmware into cores, or, dump the firmware
that is already loaded.
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 memory locations.
...
...
@@ -148,14 +151,14 @@ tools.::
dd if=firmware.bin of=/dev/mockturtle/trtl-0001-00
The same command can
be used also to dump the memory content.
::
The same command can
also be used to dump the memory contents
::
dd if=/dev/mockturtle/trtl-0001-00 of=firmwaredump.bin
In both cases (loading and dumping) the driver automatically puts the core
in *reset* state.
This means that after your operation you need to *unreset* the
core in order to make it running again
.
::
core in order to make it running again::
echo 0 > /sys/class/mockturtle/trtl-0001-00/reset
...
...
@@ -178,7 +181,7 @@ For example::
words whatever the firmware application writes is replicated on this
interface.
You can find the
cores *sysfs* attributes
at::
You can find the
*sysfs* attributes for each core
at::
/sys/class/mockturtle/trtl-%04x/trtl-%04x-%02d-%02d
...
...
@@ -204,11 +207,13 @@ Host Message Queue
--------------------
The Mock Turtle driver exports a *char device* for each Mock Turtle HMQ.
All HMQ instances will appear as child of a :ref:`sw:drv:core`; in
All HMQ instances will appear as child
red
of a :ref:`sw:drv:core`; in
*/dev/mockturtle/* you will have devices named ``trtl-%04x-%02d-%02d``
(trtl-<device-id>-<cpu-index>-<hmq-index>). The main purpose of this
interface is to exchange messages. These devices are bidirectional,
so you can: ``write(2)`` to send messaged; ``read(2)`` to receive messages;
interface is to exchange messages.
These devices are bidirectional,
so you can: ``write(2)`` to send messages; ``read(2)`` to receive messages;
``poll(2)`` or ``select(2)`` to wait for the interface to become accessible.
This *char device* provides a set of ``ioctl(2)`` commands:
...
...
@@ -253,17 +258,18 @@ You can find the HMQ *sysfs* attributes at::
Debugging Interface
-------------------
The driver exports on debugfs a file in YAML format which contains internal
information about the driver: variable values, register values. This file is named as
the Mock Turtle instance that represents "trtl-%04x".::
The driver exports on debugfs a file in YAML format which contains
internal information about the driver: variable values, register
values. This file is named as the Mock Turtle instance that it
represents ("trtl-%04x")::
mount -t debugfs none /sys/kernel/debug
cat /sys/kernel/debug/trtl-0001/info
This is typically used by driver developers for debugging purposes.
.. warning::
Its content it is not stable and it may change at anytime.
Do not consider this as a stable interface.
.. warning::
The contents of the YAML file are not stable and may
change at any time.
Do not consider this as a stable interface.
Then, there is a debugfs file for each Mock Turtle instance that can be
used to access the CPU debug registers. These files are named using the
...
...
doc/software/linux-library.rst
View file @
a4c7b3ed
...
...
@@ -7,13 +7,13 @@ The Mock Turtle Linux Library
==============================
The Mock Turtle Library for host system development handles all the Mock
Turtle features and it makes them available to
any user. The Mock Turtl
e
library mandate
is to export all the Mock Turtle driver features to
Turtle features and it makes them available to
the user. The aim of th
e
Mock Turtle library
is to export all the Mock Turtle driver features to
user-space programs in a more user-friendly way without paying much in
terms of the flexibility that the driver offers.
The library layer covers all the driver features; for this reason, the
user should
use only
the library or the Python module. The user can
user should
only use
the library or the Python module. The user can
still access the Mock Turtle driver directly but it is strongly
discouraged.
...
...
@@ -62,12 +62,12 @@ While in the compilation command you have to provide the following options
The example above assumes that you are compiling from the Mock Turtle
git repository or a copy of it; if on your environment libraries and header
files are in different locations,
then fix the above cod
e accordingly.
files are in different locations,
please adjust the above exampl
e accordingly.
Initialization
==============
The library initialization is done with function :c:func:`trtl_init()`.
The library initialization is done with
the
function :c:func:`trtl_init()`.
You must initialize the library before calling any library function.
.. doxygenfunction:: trtl_init
...
...
@@ -103,7 +103,7 @@ Mock Turtle Cores Management
============================
Library support for cores' management is limited to the firmware loading
(
dumping) and core enable/disable
.
(
and dumping) and enabling/disabling of the cores
.
The typical use of these functions is to load an executable file into
the soft-CPU. The following listing shows an example
...
...
@@ -153,14 +153,14 @@ side so that the complete flush happens synchronously.
.. doxygenfunction:: trtl_hmq_flush
Then
, there are the functions to exchange messages with firmware
running on Mock Turtle. This API offers a
minimum set of function
Furthermore
, there are the functions to exchange messages with firmware
running on Mock Turtle. This API offers a
set of functions
to allow users to send/receive synchronous/asynchronous messages.
This library does not have any knowledge about the message content
,
i
t processes the header but the payload is transfered as is.
Any processing o
n
the payload is left to the user. This is the rule
for most messages,
anyway Mock Turtle
offers a set of special messages
which are completely handled
by Mock Turtle
.
This library does not have any knowledge about the message content
.
I
t processes the header but the payload is transfered as is.
Any processing o
f
the payload is left to the user. This is the rule
for most messages,
but Mock Turtle also
offers a set of special messages
which are completely handled
internally by Mock Turtle, including their payload
.
.. doxygenstruct:: polltrtl
:members:
...
...
@@ -176,7 +176,7 @@ which are completely handled by Mock Turtle.
Mock Turtle offers a set of special messages which can be used in
combination with the firmware framework to ease the development.
The idea behind these special messages is to offer an API for the most
common operation that you will perform with Mock Turtle. Of course,
common operation
s
that you will perform with Mock Turtle. Of course,
you are always free to use the basic message exchange mechanism and
build on top of them your high level API.
...
...
@@ -200,9 +200,9 @@ Shared Memory
The Mock Turtle shared memory is accessible also from the host.
In some cases accessing the shared memory from host is necessary, but
this is not really encouraged
as *normal usage*
because it may affect
the Mock Turtle determinism. This API is limited to the basic function
Even though In some cases it is necessary to access the shared memory from the host,
this is not really encouraged because it may affect
the Mock Turtle determinism. This API is limited to the basic function
s
to read and write: :c:func:`trtl_smem_write()`, :c:func:`trtl_smem_write()`.
.. doxygenfunction:: trtl_smem_read
...
...
doc/software/linux-python.rst
View file @
a4c7b3ed
...
...
@@ -39,7 +39,8 @@ You can use the Makefile to install PyMockTurtle module::
cd /path/to/mockturtle/software/lib/PyMockTurtle
make install
Alternatively, you can use the *distutil* script that takes care of the module installation in your Python environment::
Alternatively, you can use the *distutil* script that takes care of the
module installation in your Python environment::
cd /path/to/mockturtle/software/lib/PyMockTurtle
python setup.py install
...
...
@@ -74,7 +75,7 @@ corresponding to the version declared in the setup.py script.
.. _`sw:lnx:py:use`:
The PyMockTurlt
e Basic Usage
PyMockTurtl
e Basic Usage
============================
The usage of this module is quite straight forward. The first thing
...
...
@@ -83,7 +84,7 @@ you have to to do is to create an instance for
The instantiation process will autoconfigure the new object using the
information from the configuration ROM. This means that all the cores
(:py:class:`PyMockTurtle.TrtlCpu`) and the respective host message queues
(:py:class:`PyMockTurtle.TrtlHmq`) will be instan
ciated automaticaly.
::
(:py:class:`PyMockTurtle.TrtlHmq`) will be instan
tiated automaticaly
::
import PyMockTurtle
...
...
doc/software/protocol.rst
View file @
a4c7b3ed
...
...
@@ -32,9 +32,9 @@ with different APIs, by both host system and firmware.
Host Message Queue Protocol
==============================
A protocol i
n
necessary in order to exchange messages between two entities.
A protocol i
s
necessary in order to exchange messages between two entities.
Any Mock Turtle message queue has a header part and a payload part. It is
within the header part that users put the information to handle the cho
o
sen
within the header part that users put the information to handle the chosen
protocol.
In order to standardize the message exchange between host and firmware
...
...
@@ -68,10 +68,12 @@ two end-points of Host Message Queue communication channel.
Remote Message Queue Protocol
-------------------------------
Within this project we have defined a protocol for the communication with
Mock Turtle only defines a protocol for the communication of the cores 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
to the user who can choose among existing protocols (for example UDP).
A remote queue message is also made of a header and a payload; whatever is
the chosen protocol, its header will lay in the header part and the payload
the payload part. End-points can use the header part to configure themselves
with user parameters.
doc/tools/mockturtle-buffer.rst
View file @
a4c7b3ed
...
...
@@ -3,6 +3,6 @@
Mock Turtle Buffer
------------------
The Mock Turtle buffer application
(\
*mockturtle-buffer*) allows the
user to read/write the buffers that a firmware exports. The tool
works
only with those
firmware developed using :ref:`sw:fw:frm`.
The Mock Turtle buffer application
(
*mockturtle-buffer*) allows the
user to read/write the buffers that a firmware exports. The tool
only
works with
firmware developed using :ref:`sw:fw:frm`.
doc/tools/mockturtle-cpu-restart.rst
View file @
a4c7b3ed
...
...
@@ -5,5 +5,5 @@ Mock Turtle CPU Restart
=========================
The Mock Turtle CPU Restart application (*mockturtle-cpu-restart*) is
used to restart a soft-
cpu
. This will stop the firmware execution and
used to restart a soft-
CPU
. This will stop the firmware execution and
start it again from the ``main()`` function.
doc/tools/mockturtle-firmware-loader.rst
View file @
a4c7b3ed
...
...
@@ -5,5 +5,5 @@ Mock Turtle Firmware Loader
==============================
The Mock Turtle Loader application (*mockturtle-firmware-loader*) allows
the user to load a firmware in a soft-
cpu
. It gives also the possibility
to dump the RAM content from a soft-
cpu
.
the user to load a firmware in a soft-
CPU
. It gives also the possibility
to dump the RAM content from a soft-
CPU
.
doc/tools/mockturtle-messages.rst
View file @
a4c7b3ed
...
...
@@ -5,5 +5,5 @@ Mock Turtle Messages
======================
The Mock Turtle Messages application (*mockturtle-messages*) can be used
to sniff the traffic over a
hmq
or to access the serial console of a
soft-
cpu
.
to sniff the traffic over a
HMQ
or to access the serial console of a
soft-
CPU
.
doc/tools/mockturtle-ping.rst
View file @
a4c7b3ed
...
...
@@ -7,5 +7,5 @@ Mock Turtle Ping
The purpose of the Mock Turtle Ping application (*mockturtle-ping*) is
to be able to verify that a firmware is running. In addition, the
mockturtle-ping application provides information about the firmware
version running on a Mock Turtle soft-
cpu. The tool works only
with
those
firmware developed using :ref:`sw:fw:frm`.
version running on a Mock Turtle soft-
CPU. The tool only works
with
firmware developed using :ref:`sw:fw:frm`.
doc/tools/mockturtle-project-creator.rst
View file @
a4c7b3ed
...
...
@@ -6,7 +6,7 @@ Mock Turtle Project Creator
The process of setting up a new Mock Turtle project can takes hours the
first time if you do not know already what it is expected from the user.
Fortunatel
l
y, this process can be automated and there is not much
Fortunately, this process can be automated and there is not much
knowledge in it.
The Mock Turtle Project Creator (*mockturtle-project-creator*) is a
...
...
doc/tools/mockturtle-smem.rst
View file @
a4c7b3ed
...
...
@@ -5,5 +5,5 @@ Mock Turtle Shared Memory
=============================
The Mock Turtle Shared Memory application (*mockturtle-smem*) provides
access to the Mock Turtle sh
m
. The user can read/write any location of
the sh
m
using different access modes.
access to the Mock Turtle sh
ared memory
. The user can read/write any location of
the sh
ared memory
using different access modes.
doc/tools/mockturtle-variable.rst
View file @
a4c7b3ed
...
...
@@ -4,6 +4,6 @@
Mock Turtle Variable
=====================
The Mock Turtle variable application
(\
*mockturtle-variable*) allows the
user to read/write the variables that a firmware exports. The tool
works
only with those
firmware developed using :ref:`sw:fw:frm`.
The Mock Turtle variable application
(
*mockturtle-variable*) allows the
user to read/write the variables that a firmware exports. The tool
only
works with
firmware developed using :ref:`sw:fw:frm`.
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment