Commit cadcc242 authored by Federico Vaga's avatar Federico Vaga

doc: applies reviewer comments

Mainly style and grammar comments

Remove any reference to platform-device-loader. It is not open-source,
it should not be used by anyone, nobody should see it. This tool is
used by us to compensate the lack of infrastructure at CERN. Other
people should go for DeviceTree.
Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>
Reported-by: 's avatarErik Van Der Bij <Erik.van.der.Bij@cern.ch>
parent 4f92e90e
......@@ -102,7 +102,7 @@ external world because it’s already part of the Mock Turtle framework.
.. _introduction:when-do-not-consider-mock-turtle:
When Do Not Consider Mock Turtle
When To Not Consider Mock Turtle
--------------------------------
The Mock Turtle soft-CPUs have limited computation power, this precludes
......@@ -112,3 +112,18 @@ 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.
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::
git clone https://@ohwr.org/gitolite/hdl-core-lib/mock-turtle.git
In it you can find all sources: HDL, software, demos, tests and this
documentation.
.. _`Open Hardware Repository`: https://www.ohwr.org/
.. _`Mock Turtle`: https://www.ohwr.org/projects/mock-turtle/repository
......@@ -17,20 +17,20 @@ The following figure shows an overview over the Mock Turtle architecture.
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)
Grey 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
For more information read the dedicated chapters for the different parts.
Mock Turtle Core
==================
Mock Turtle can have one or more core. A single cor eis made of the following
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
......@@ -41,12 +41,12 @@ 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>`
The 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:
For more information about how to handle cores from software, please read:
- :ref:`Linux Library - Cores Management<sw:lnx:lib:cpu>`
......@@ -82,7 +82,7 @@ This is used to send string messages from the running firmware to the host syste
Message Queue
----------------
Mock Turtle firmwares can communicate with external agents using
Mock Turtle firmware 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
......@@ -116,13 +116,14 @@ 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.
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.
For more information about how to access it from software read:
For more information about how to access it from software, please read:
- :ref:`Firmware Library - Message Queue<sw:fw:lib:mq>`
......@@ -166,7 +167,7 @@ how to access it from software read:
.. _`arch:dp`:
Device Peripheral
Device Peripherals
==================
Device peripherals are external components connected to a Mock Turtle core.
......@@ -191,14 +192,14 @@ to address the device.
}
subgraph core1 {
graph [nodesep=1];
c1 -- corssbar -- "I2C master";
c1 -- corssbar -- "SPI master";
c1 -- crossbar -- "I2C master";
c1 -- crossbar -- "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:
For more information about how to access it from software, please read:
- :ref:`Firmware Library - Memory Location<sw:fw:lib:mem>`
......@@ -98,7 +98,7 @@ The expected output from the simulation is::
Software
=========
This demo has two firmwares. One is named *blinker* (fw-01), the other
This demo has two firmware. One is named *blinker* (fw-01), the other
*controller* (fw-02).
The *blinker* firmware runs autonomously without any communication with the host
......
......@@ -105,7 +105,7 @@ The expected output from the simulation is::
Software
=========
This demo has two firmwares. One is named *autosvec* (fw-01), the other
This demo has two firmware. One is named *autosvec* (fw-01), the other
*manualsvec* (fw-02).
The *autosvec* firmware runs autonomously without any communication with the host
......
......@@ -7,6 +7,9 @@ The Demos
This is a collection of demo applications which 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 of your environment. Here a list of used variable
......
......@@ -40,7 +40,7 @@ Glossary
It is the system that hosts the hardware in use.
Host Application
It is an user space program running on the host system.
It is a user space program running on the host system.
HMQ
Host Message Queue
......
......@@ -146,7 +146,7 @@ If a **t_mt_config** is not provided, a default one will be used::
shared_mem_size => 2048
);
The default configuration instantiates two soft CPUs, each with 32KB of memory, plus 8KB of shared
The default configuration instantiates two soft CPUs, each with 32KiB of memory, plus 8KiB of shared
memory. Each CPU will have default host and remote message queue configurations defined as::
constant c_MT_DEFAULT_MQUEUE_CONFIG : t_mt_mqueue_config :=
......@@ -230,7 +230,7 @@ clk_i
is the system clock.
rst_n_i
is an active-low reset input, which is expected to be syncrhonous to the system clock.
is an active-low reset input, which is expected to be synchronous to the system clock.
sp_master_i, sp_master_o
they form the *Shared Peripheral (SP)* Wishbone bus. Wishbone peripherals attached to these ports
......@@ -253,7 +253,7 @@ host_slave_i, host_slave_o
.. important::
When mapping the MT address area to the host, users should keep in mind that the
whole MT address space is 128KB (0x20000).
whole MT address space is 128KiB (0x20000).
**t_wishbone_master_out**, **t_wishbone_master_in** and their respective arrays, as well as
**t_wishbone_slave_out** and **t_wishbone_slave_in** are VHDL record types declared in the
......@@ -374,7 +374,7 @@ default/dummy constant as::
cycles => (others => '0'),
aux_locked => (others => '0'));
For an explanation of these fields, please refer to `White Rabbit PTP core`_ manual.
For an explanation of these fields, please refer to the `White Rabbit PTP core`_ manual.
gpio_o, gpio_i
These are the 32-bit inputs and outputs to the GPIO registers of each configured MT soft
......
......@@ -14,7 +14,7 @@ This API is available by including ``mockturtle-framework.h`` in your source fil
#include <mockturtle-framework.h>
We recommend this framework to develop Mock Turtle firmwares. You should
We recommend this framework to develop Mock Turtle firmware. You should
consider alternatives if you see that it’s consuming too much memory or
the performances are not enough for your application.
......@@ -83,7 +83,7 @@ Here an example.::
};
The Mock Turtle is FPGA based, this means that the firmwares are
The Mock Turtle is FPGA based, this means that the firmware are
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
......@@ -273,7 +273,7 @@ In chapter :ref:`sw:lnx:lib:hmq` you can find the correspondent host API,
which in few words consists in two function: :c:func:`trtl_fw_variable_set`
and :c:func:`trtl_fw_variable_get`.
What we have seen till now it is handled automatically by this framework.
What we have seen until now it is handled automatically by this framework.
The user can send, asynchronously, variables of choice using the function
:c:func:`trtl_fw_mq_send_buf`.
......@@ -289,7 +289,7 @@ the host system. The buffers must be declared using the
:c:type:`trtl_fw_buffer` and then exported in your
:c:type:`trtl_fw_application`.
The mean of buffer in this context is extended to any contiguous memory
The meaning of buffer in this context is extended to any contiguous memory
location.
The framework handles the buffer exchange as a special action.
......@@ -357,11 +357,11 @@ 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 correspondent host API,
which in few words consists in two function: :c:func:`trtl_fw_buffer_set`
In chapter :ref:`sw:lnx:lib:hmq` you can find the correspondent host API;
in a few words consists of two function: :c:func:`trtl_fw_buffer_set`
and :c:func:`trtl_fw_buffer_get`.
What we have seen till now it is handled automatically by this framework.
What we have seen until now it is handled automatically by this framework.
The user can send, asynchronously, buffer of choice using the function
:c:func:`trtl_fw_mq_send_buf`.
......@@ -370,7 +370,7 @@ The user can send, asynchronously, buffer of choice using the function
Utilities
=========
This is a collection of miscellaneous function that can be of some helpers.
This is a collection of miscellaneous functions that can be of some helpers.
.. doxygenfunction:: trtl_fw_time
......
......@@ -343,7 +343,7 @@ function :c:func:`puts()` to send the strings over the serial interface.
Host Notification
=================
Mock Turtle has a mechanism that allows firmwares to send arbitrary interrupts
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 custum notifications to their support layer.
......
......@@ -4,7 +4,7 @@
Firmware Development
======================
This section explains how to write firmwares using the Mock Turtle API.
This section explains how to write firmware using the Mock Turtle API.
The Mock Turtle offers 2 API for the firmware development:
:ref:`sw:fw:lib` and :ref:`sw:fw:frm`.
......
......@@ -18,9 +18,9 @@ the :ref:`sw:fw` and the :ref:`sw:lnx`
The Mock Turtle software stack is made of different layers which main
objectives are:
- to manage the Mock Turtle cores from the host;
- to manage the Mock Turtle cores from the host
- to allow firmwares to access Mock Turtle resources;
- to allow firmware to access Mock Turtle resources
- to provide a communication infrastructure between firmware and host
......@@ -32,7 +32,7 @@ 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 firmwares, then it is recommended to develop
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
......@@ -41,8 +41,8 @@ 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
development of firmware development.
Following a list of generic topics which are not specific to Linux or firmware
development.
.. toctree::
:maxdepth: 1
......
......@@ -8,7 +8,7 @@ The Linux Device Driver
The Mock Turtle device driver is a software component that exposes the
Mock Turtle gateware core to the host. Any interaction with the Mock
Turtle gateware core pass trought the device driver. This implies that
Turtle gateware core passes trought the device driver. This implies that
if the driver does not support a Mock Turtle feature, neither the other
layers (the library or the Python module) will do.
......@@ -80,31 +80,20 @@ development of a Linux module or the DeviceTree.
This driver handles all platform_device instances which name is one of
the following: "mock-turtle", "mockturtle".
The Mock Turtle device driver expects 5 ``resources`` from the platform
The Mock Turtle device driver expects five ``resources`` from the platform
device.
memory address
The gateware core base address within the virtual addres space.
- memory address: The gateware core base address within the virtual address
space.
hmq IRQ input
The Linux IRQ number to use for the hmq input.
- hmq IRQ input: The Linux IRQ number to use for the hmq input.
hmq IRQ output
The Linux IRQ number to use for the hmq output.
- hmq IRQ output: The Linux IRQ number to use for the hmq output.
console IRQ
The Linux IRQ number to use for the serial interface.
- console IRQ: The Linux IRQ number to use for the serial interface.
notification IRQ
The Linux IRQ number to use for Mock Turtle cores notifications.
Since not all developer knows how to write such module, you can use the
*platform-device-loader* [2]_. This application is part of the CERN BE-CO-HT tools
collection, you may need special permission to access the repository.
If you are not sure about how to write the Linux module to load your
platform device, consider to have a look at the source code templates
from the *platform-device-loader* tool.
- notification IRQ: The Linux IRQ number to use for Mock Turtle cores
notifications.
Interfaces
==========
......@@ -150,7 +139,7 @@ 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) firmwares into cores. These devices are
program (or rarely useful dump) firmware 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 memory locations.
......@@ -163,8 +152,9 @@ The same command can be used also to dump the memory content.::
dd if=/dev/mockturtle/trtl-0001-00 of=firmwaredump.bin
In both cases (loading and dumping) the driver automatically put in *reset*
the core. This means that after your operation you need to *unreset* the
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.::
echo 0 > /sys/class/mockturtle/trtl-0001-00/reset
......@@ -216,7 +206,7 @@ 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
*/dev/mockturtle/* you will have devices named ``trtl-%04x-%02d-%02d``
(trtl-<device-id>-<cpu-index>-<hmq-index>). The main purposes of this
(trtl-<device-id>-<cpu-index>-<hmq-index>). The main purpose 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
......@@ -278,4 +268,3 @@ This is typically used by driver developers for debugging purposes.
Do not consider this as a stable interface.
.. [1] https://www.kernel.org/doc/Documentation/driver-model/platform.txt
.. [2] https://gitlab.cern.ch/cohtdrivers/coht-tools/tree/master/drivers/platform-device-loader
......@@ -62,7 +62,7 @@ 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 location, then fix the above code accordingly.
files are in different locations, then fix the above code accordingly.
Initialization
==============
......@@ -147,16 +147,16 @@ messages to/from them.
Whenever you need to remove all the messages from the HMQ you can use
the function :c:func:`trtl_hmq_flush()`. The host system does not have
access to the RMQ. If what you want to achive is a complete flush of
access to the RMQ. If what you want to achieve is a complete flush of
all the message queues (host and remote) you should do it on firmware
side so that the complete flush happens synchronously.
.. doxygenfunction:: trtl_hmq_flush
The Mock Turtle driver has a basic message filtering mechanism. Each
user can add a set of filter on any host message queue. Mock Turtle
user can add a set of filters on any host message queue. Mock Turtle
will deliver to the user only those messages which pass the filter.
Rembember that this is user filter, this means that on the same
Rembember that this is a user filter, this means that on the same
host message queue, different users can have different filters.
.. doxygenfunction:: trtl_hmq_filter_add
......@@ -168,7 +168,7 @@ host message queue, different users can have different filters.
.. doxygenstruct:: trtl_msg_filter
:members:
Then, there are the functions to exchange messages with firmwares
Then, there are the functions to exchange messages with firmware
running on Mock Turtle. This API offers a minimum set of function
to allow users to send/receive synchronous/asynchronous messages.
This library does not have any knowledge about the message content,
......
......@@ -103,7 +103,7 @@ Then, it exports a set of *ctype* data structures used to exchange
information with the Mock Turtle layers.
.. note::
Since this Pyhton module is nothing more than a wrapper on top of
Since this Python module is nothing more than a wrapper on top of
a C library, we suggest you to have a look at :ref:`sw:lnx:library`
for a better understanding of this API
......
......@@ -13,7 +13,7 @@ Configuration ROM
The *configuration ROM* is, indeed, a ROM where at synthesis time we put
information about the synthesis configuration. This configuration is the one
used to tailor Mock Turtle to fit users needs. The configuration can be read,
with different APIs, by both host system and firmwares.
with different APIs, by both host system and firmware.
.. doxygenstruct:: trtl_config_rom
:members:
......@@ -32,20 +32,20 @@ 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.
A protocol in 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 choosen
protocol.
In order to standardize the message exchange between host and firmwares
In order to standardize the message exchange between host and firmware
a message header has been defined. This header is expected to be in the
message queue header buffer.
Different Mock Turtle layers make a different use of this message header.
Different Mock Turtle layers make different use of this message header.
The HDL code does not process the header, while the driver uses the
:c:member:`trtl_hmq_header.len` to optimize the amount of data copied.
This protocol is mostly used by libraries and firmwares, which are the
This protocol is mostly used by libraries and firmware, which are the
two end-points of Host Message Queue communication channel.
......
......@@ -5,4 +5,4 @@ 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 firmwares developed using :ref:`sw:fw:frm`.
only with those firmware developed using :ref:`sw:fw:frm`.
......@@ -8,4 +8,4 @@ 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 firmwares developed using :ref:`sw:fw:frm`.
those firmware developed using :ref:`sw:fw:frm`.
......@@ -6,4 +6,4 @@ 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 firmwares developed using :ref:`sw:fw:frm`.
only with those firmware developed using :ref:`sw:fw:frm`.
......@@ -33,7 +33,7 @@ config MOCKTURTLE_FRAMEWORK_ENABLE
default y
help
It enables the Mock Turtle firmware framework. This framework
provides a well structured way to develop Mock turtle firmwares
provides a well structured way to develop Mock turtle firmware
as wall as helpers for the most common operations.
config MOCKTURTLE_FRAMEWORK_DEBUG_ENABLE
......@@ -72,14 +72,14 @@ config MOCKTURTLE_FRAMEWORK_PING_ENABLE
depends on MOCKTURTLE_FRAMEWORK_ACTION_ENABLE
default y
help
It enables the API to send ping message to firmwares.
It enables the API to send ping message to firmware.
config MOCKTURTLE_FRAMEWORK_VERSION_ENABLE
bool "Enable version message in Mock Turtle framework"
depends on MOCKTURTLE_FRAMEWORK_ACTION_ENABLE
default y
help
It enables the API to send version message to firmwares.
It enables the API to send version message to firmware.
config MOCKTURTLE_FRAMEWORK_VALUE_SEND_ENABLE
bool "Enable value message send in Mock Turtle framework"
......
......@@ -465,7 +465,7 @@ int trtl_fw_mq_send_buf(enum trtl_mq_type type,
/**
* It get the current time from the internal TRTL timer
* It gets the current time from the internal TRTL timer
* @param[out] seconds
* @param[out] cycles
*/
......
......@@ -166,7 +166,7 @@ struct trtl_tlv {
/**
* @enum trtl_smem_modifier
* Shared memory operation modifier. This is a list of operation modifier
* Shared memory operation modifier. This is a list of operation modifiers
* that you can use to access the shared memory.
*/
enum trtl_smem_modifier {
......
......@@ -839,7 +839,7 @@ static ssize_t trtl_hmq_read(struct file *f, char __user *ubuf,
/**
* It filters out messages until a valid one
* @usr: pointer to an user HMQ instance
* @usr: pointer to a user HMQ instance
*/
static void trtl_hmq_user_filter(struct trtl_hmq_user *usr)
{
......
......@@ -132,10 +132,10 @@ static int __trtl_fw_variable(struct trtl_dev *trtl,
* VAL is the associated value
*
* By setting the flag 'sync' you will send a synchronous message, otherwise
* it is asyncrhonous. When synchronous the 'variables' field will be
* overwritten by the syncrhonous answer; the answer contains the read back
* it is asynchronous. When synchronous the 'variables' field will be
* overwritten by the synchronous answer; the answer contains the read back
* values for the requested variable after the set operation. You can use
* this to verify. You can use synchrounous messages to verify that you
* this to verify. You can use synchronous messages to verify that you
* variable are properly set.
* This function will change the header content, in particular it will change
* the following fields: msg_id, len
......@@ -174,7 +174,7 @@ int trtl_fw_variable_set(struct trtl_dev *trtl,
* VAL is the associated value
*
* This kind of message is always synchronous. The 'variables' field will be
* overwritten by the syncrhonous answer; the answer contains the read back
* overwritten by the synchronous answer; the answer contains the read back
* values for the requested variables.
* This function will change the header content, in particular it will change
* the following fields: msg_id, flags, len
......
......@@ -822,7 +822,7 @@ int trtl_smem_write(struct trtl_dev *trtl, uint32_t addr, uint32_t *data,
/**
* It enables a CPU; in other words, it clear the reset line of a CPU.
* It enables a CPU; in other words, it clears the reset line of a CPU.
* This function is a wrapper of trtl_cpu_reset_set() that allow you to safely
* enable a single CPU.
* @param[in] trtl device token
......@@ -840,7 +840,7 @@ int trtl_cpu_enable(struct trtl_dev *trtl, unsigned int index)
/**
* It disables a CPU; in other words, it sets the reset line of a CPU.
* This function is a wrapper of trtl_cpu_reset_set() that allow you to safely
* This function is a wrapper of trtl_cpu_reset_set() that allows you to safely
* disable a single CPU.
* @param[in] trtl device token
* @param[in] index CPU index
......@@ -1050,8 +1050,8 @@ int trtl_msg_async_send(struct trtl_dev *trtl,
* @param[in] timeout like poll(2)
* @return 0 on success, otherwise -1 and errno is set appropriately
*
* This function configure some filters, so it does some bit magic which have been
* tested on a little-endian host.
* This function configures some filters, so it does some bit magic which have
* been tested on a little-endian host.
*/
int trtl_msg_sync(struct trtl_dev *trtl,
unsigned int idx_cpu,
......
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