Skip to content

M
Mock Turtle
Commit 9e9329d7 authored by Federico Vaga's avatar Federico Vaga
Browse files
Options

Merge branch 'release/v4.0.0.rc1'

parents 7bc491de 3e47f5d3
Hide whitespace changes
Inline Side-by-side
Showing with 1105 additions and 787 deletions
LICENSES/BSD-3-Clause.txt
View file @ 9e9329d7
Copyright (c) 2018, CERN (www.cern.ch), All rights reserved.
Copyright (c) 2014-2019, CERN (home.cern), All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
......
README.rst
View file @ 9e9329d7
.. _introduction:description:
===========
Mock Turtle
===========
============
Introduction
============
Mock Turtle is a framework to develop embedded systems on FPGA.
For more information, please read the documentation in ``doc/``.
The Mock Turtle is a framework to develop embedded systems on FPGA.
Documentation Build Instructions
================================
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.
This project uses `Sphinx <http://www.sphinx-doc.org/en/master/>`_ to generate
documentation from `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
and `CommonMark <https://commonmark.org/>`_ (Markdown) files under ``doc/``.
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
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.
To build the documentation, it is highly recommended to setup a
`Python virtual environment <https://virtualenv.pypa.io/en/stable/>`_ where
the necessary packages (docuilts, sphinx, etc.) can be installed via
`pip <https://pypi.org/project/pip/>`_ and be kept at a specific version.
The Mock Turtle framework focuses mainly on the determinism of the
firmware running in it. Indeed, Mock Turtle does not support any kind of
interrupt or scheduling which might compromise the determinism.
The following steps illustrate how to do this on a Debian/Ubuntu Linux box,
with the virtual environment placed inside the ``doc/`` folder of the project
itself:::
The Mock Turtle framework includes the following components:
sudo apt install virtualenv
cd doc
virtualenv build_env
. build_env/bin/activate
pip install -r requirements.txt
deactivate
- Gateware
**Note:** If you use the same folder name and location (``doc/build_env``) for
the virtual environment as in the above example, there is already a gitignore
rule in place that will not track any auto-generated files within that folder.
- The Mock Turtle core
Once the environment is installed, you can (re)build the documentation by
doing:::
- Shared Memory among soft-CPUs and host system
cd doc
. build_env/bin/activate
make html
deactivate
- Up to 8 soft-CPUs
The generated documentation can be accessed by opening
``doc/_build/html/index.html`` in your browser.
- communication with the host system (input, output)
Alternatively, if you have `LaTeX <https://www.latex-project.org/>`_ installed,
you can produce a PDF by doing:::
- communication with remote systems (input, output)
cd doc
. build_env/bin/activate
make latexpdf
deactivate
- Software
The generated documentation can be accessed by opening the PDF found under
``doc/_build/latex/``.
- the Mock Turtle firmware library to access gateware cores from the
firmware
- the Mock Turtle firmware framework to develop firmware
If the 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:
- the Mock Turtle Linux device driver
- the Mock Turtle library that provides uniform access to the driver
- the Mock Turtle Python module to access the library using Python
.. _introduction:use-cases:
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).
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.
The following figures show the control system architecture with and
without Mock Turtle.
.. list-table::
:header-rows: 0
:widths: 1 1
* - .. figure:: img/mock-turtle-use-case-1.svg
:align: center
Control system **without** Mock-Turtle
- .. figure:: img/mock-turtle-use-case-2.svg
:align: center
Control system **with** 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
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
--------------------------------
The Mock Turtle soft-CPUs have limited computation power, this precludes
some applications like: 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.
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
**Note:** Only HTML and PDF outputs from Sphinx are supported and tested.
demos/alarm_clock/firmware/fw-01/fw-ac.c
View file @ 9e9329d7
/*
* Copyright (C) CERN 2016
* Copyright (c) 2016-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
* License: GPLv3
*/
......
demos/data_generator/firmware/fw-01/fw-dg.c
View file @ 9e9329d7
/*
* Copyright (C) CERN 2016
* Copyright (c) 2016-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
* License: GPLv3
*/
......
demos/fmc-spec-carrier/software/firmware/common/fw-spec-common.h
View file @ 9e9329d7
/*
* Copyright (C) 2018 CERN (www.cern.ch)
* Copyright (c) 2016-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......
demos/fmc-spec-carrier/software/firmware/common/fw-spec-smem-code.c
View file @ 9e9329d7
/*
* Copyright (C) 2018 CERN (www.cern.ch)
* Copyright (c) 2018-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......
demos/fmc-spec-carrier/software/firmware/fw-01/fw-spec.c
View file @ 9e9329d7
/*
* Copyright (C) 2018 CERN (www.cern.ch)
* Copyright (c) 2018-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......
demos/fmc-spec-carrier/software/firmware/fw-02/fw-spec.c
View file @ 9e9329d7
/*
* Copyright (C) 2018 CERN (www.cern.ch)
* Copyright (c) 2018-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......
demos/fmc-spec-carrier/software/include/spec-common.h
View file @ 9e9329d7
/*
* Copyright (C) 2015 CERN (www.cern.ch)
* Copyright (c) 2015-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*/
......
demos/fmc-spec-carrier/software/lib/libspec-internal.h
View file @ 9e9329d7
/*
* Copyright (C) 2018 CERN (www.cern.ch)
* Copyright (c) 2018-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......@@ -19,7 +19,7 @@
* Description of a fmc-spec-carrier device
*/
struct spec_desc {
struct trtl_dev *trtl; /**< WRNC device associated */
struct trtl_dev *trtl; /**< TRTL device associated */
uint32_t dev_id; /**< fmc device id */
uint32_t app_id; /**< Application id */
uint32_t n_cpu; /**< Number of CPUs */
......
demos/fmc-spec-carrier/software/lib/libspec.c
View file @ 9e9329d7
/*
* Copyright (C) 2018 CERN (www.cern.ch)
* Copyright (c) 2018-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......@@ -31,7 +31,7 @@ const char *spec_btn_to_name(enum spec_btn_mode mode)
}
/**
* It returns a string messages corresponding to a given error code. If
* Return a string messages corresponding to a given error code. If
* it is not a libwrtd error code, it will run trtl_strerror()
* @param[in] err error code
* @return a message error
......@@ -46,10 +46,10 @@ const char *spec_strerror(unsigned int err)
/**
* It initializes the SPEC library. It must be called before doing
* Initialize the SPEC library. It must be called before doing
* anything else.
* This library is based on the libmockturtle, so internally, this function also
* run spec_init() in order to initialize the WRNC library.
* run spec_init() in order to initialize the TRTL library.
* @return 0 on success, otherwise -1 and errno is appropriately set
*/
int spec_init()
......@@ -65,7 +65,7 @@ int spec_init()
/**
* It releases the resources allocated by spec_init(). It must be called when
* Release the resources allocated by spec_init(). It must be called when
* you stop to use this library. Then, you cannot use functions from this
* library.
*/
......@@ -103,7 +103,7 @@ out:
/**
* It closes a SPEC device opened with one of the following function:
* Close a SPEC device opened with one of the following function:
* spec_open_by_id()
* @param[in] dev device token
*/
......@@ -118,10 +118,10 @@ void spec_close(struct spec_node *dev)
/**
* It returns the WRNC token in order to allows users to run
* functions from the WRNC library
* Return the TRTL token in order to allows users to run
* functions from the TRTL library
* @param[in] dev device token
* @return the WRNC token
* @return the TRTL token
*/
struct trtl_dev *spec_get_trtl_dev(struct spec_node *dev)
{
......
demos/fmc-spec-carrier/software/lib/libspec.h
View file @ 9e9329d7
/*
* Copyright (C) 2018 CERN (www.cern.ch)
* Copyright (c) 2018-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......
demos/fmc-spec-carrier/software/tools/mockturtle-spec.c
View file @ 9e9329d7
/*
* Copyright (C) 2018 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......
demos/fmc-svec-carrier/software/firmware/common/fw-svec-common.h
View file @ 9e9329d7
/**
* Copyright (C) 2015 CERN (www.cern.ch)
* Copyright (c) 2015-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......
demos/fmc-svec-carrier/software/firmware/common/fw-svec-smem-code.c
View file @ 9e9329d7
/**
* Copyright (C) 2015 CERN (www.cern.ch)
* Copyright (c) 2015-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......
demos/fmc-svec-carrier/software/firmware/common/svec-smem-code.c
View file @ 9e9329d7
/**
* Copyright (C) 2015 CERN (www.cern.ch)
* Copyright (c) 2015-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......
demos/fmc-svec-carrier/software/firmware/fw-01/fw-svec.c
View file @ 9e9329d7
/**
* Copyright (C) 2015 CERN (www.cern.ch)
* Copyright (c) 2015-2019 CERN (home.cern)
* Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
* Author: Federico Vaga <federico.vaga@cern.ch>
*
......
demos/fmc-svec-carrier/software/firmware/fw-02/fw-svec.c
View file @ 9e9329d7
/**
* Copyright (C) 2015 CERN (www.cern.ch)
* Copyright (c) 2015-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......@@ -69,7 +69,7 @@ struct trtl_fw_variable svec_variables[] = {
/**
* It sends messages over the debug interface
* Send messages over the debug interface
*/
static int svec_debug_interface(void)
{
......
demos/fmc-svec-carrier/software/include/svec-common.h
View file @ 9e9329d7
/*
* Copyright (C) 2014 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
* SPDX-License-Identifier: BSD-3-Clause
*/
......
demos/fmc-svec-carrier/software/lib/libsvec-internal.h
View file @ 9e9329d7
/*
* Copyright (C) 2014 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......@@ -20,7 +20,7 @@
* Description of a fmc-svec-carrier device
*/
struct svec_desc {
struct trtl_dev *trtl; /**< WRNC device associated */
struct trtl_dev *trtl; /**< TRTL device associated */
uint32_t dev_id; /**< fmc device id */
uint32_t app_id; /**< Application id */
uint32_t n_cpu; /**< Number of CPUs */
......
demos/fmc-svec-carrier/software/lib/libsvec.c
View file @ 9e9329d7
/*
* Copyright (C) 2014 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......@@ -21,7 +21,7 @@ const char *svec_errors[] = {
/**
* It returns a string messages corresponding to a given error code. If
* Return a string messages corresponding to a given error code. If
* it is not a libwrtd error code, it will run trtl_strerror()
* @param[in] err error code
* @return a message error
......@@ -36,10 +36,10 @@ const char *svec_strerror(unsigned int err)
/**
* It initializes the SVEC library. It must be called before doing
* Initialize the SVEC library. It must be called before doing
* anything else.
* This library is based on the libmockturtle, so internally, this function also
* run svec_init() in order to initialize the WRNC library.
* run svec_init() in order to initialize the TRTL library.
* @return 0 on success, otherwise -1 and errno is appropriately set
*/
int svec_init()
......@@ -55,7 +55,7 @@ int svec_init()
/**
* It releases the resources allocated by svec_init(). It must be called when
* Release the resources allocated by svec_init(). It must be called when
* you stop to use this library. Then, you cannot use functions from this
* library.
*/
......@@ -93,7 +93,7 @@ out:
/**
* It closes a SVEC device opened with one of the following function:
* Close a SVEC device opened with one of the following function:
* svec_open_by_id()
* @param[in] dev device token
*/
......@@ -108,10 +108,10 @@ void svec_close(struct svec_node *dev)
/**
* It returns the WRNC token in order to allows users to run
* functions from the WRNC library
* Return the TRTL token in order to allows users to run
* functions from the TRTL library
* @param[in] dev device token
* @return the WRNC token
* @return the TRTL token
*/
struct trtl_dev *svec_get_trtl_dev(struct svec_node *dev)
{
......@@ -185,7 +185,7 @@ int svec_led_set(struct svec_node *dev, uint32_t value, enum svec_color color)
/**
* It gets the status of the SVEC program
* Get the status of the SVEC program
*/
int svec_status_get(struct svec_node *dev, struct svec_status *status)
{
......
demos/fmc-svec-carrier/software/lib/libsvec.h
View file @ 9e9329d7
/*
* Copyright (C) 2014 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......
demos/fmc-svec-carrier/software/tools/mockturtle-svec.c
View file @ 9e9329d7
/*
* Copyright (C) 2014 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: GPL-3.0-or-later
......
doc/.gitignore
View file @ 9e9329d7
......@@ -2,3 +2,4 @@ _*
doxygen-trtl-output/
registers/wbgen/
.doxystamp
build_env
doc/README deleted 100644 → 0
View file @ 7bc491de
This documentation is based on sphinx. Here a random list of known
dependencies:
- doxygen (to extract a database of symbols from the C libraries)
- GraphViz (to include images)
- ImageMagick (to include images)
- Python (to run sphinx)
- docutils
- sphinx
- sphinx_rtd_theme
If you want to generate HTML (suggested), probably the list above it enough.
make -C doc html
In order to generate the PDF version you need texlive and some extrapackages.
This really depends on your distribution and how latex packages are packed.
For this reason we suggest you to download the PDF provided by the Mock Turtle
team on the official web site, or to adjust your texlive installation according
to needs.
make -C doc latexpdf
Here good tips about how to install sphinx:
https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html
HTML and PDF are supported and tested, any other format is not directly
supported.
\ No newline at end of file
doc/architecture.rst
View file @ 9e9329d7
......@@ -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 over the Mock Turtle architecture.
The following figure shows an overview of 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
---------
......@@ -43,10 +42,10 @@ runs. Any kind of bus controller, or device must be connected externally as a
The memory size for code and data is :ref:`configurable at synthesis time <hdl:cfg>`.
.. _uRV processor: https://www.ohwr.org/projects/urv-core
.. _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,29 @@ 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 and how to read it on host side, please read:
- :ref:`Firmware Library - Serial Interface<sw:fw:lib:uart>`
- :ref:`Linux Driver - Read Serial Console<sw:drv:serial>`
Message Queue
----------------
Mock Turtle firmware can communicate with external agents using
*message queues*; as the name suggests, this is a message queue with
Firmware running on Mock Turtle can communicate with external agents using
*message queues*; as the name suggests, these 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 +117,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 +166,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 +183,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 +219,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/conf.py
View file @ 9e9329d7
......@@ -54,7 +54,7 @@ master_doc = 'index'
# General information about the project.
project = 'Mock Turtle'
copyright = 'CERN 2018'
copyright = "Copyright (c) 2014-2019 CERN (home.cern)"
author = 'Federico Vaga <federico.vaga@cern.ch>, Tomasz Wlostowski <Tomasz.Wlostowski@cern.ch>'
# The version info for the project you're documenting, acts as replacement for
......
doc/demos/fmc-spec-carrier.rst
View file @ 9e9329d7
.. _`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' status can be read.
can be turned *on* and *off* and the status of the buttons can be read.
HDL Code
==========
......@@ -74,31 +76,10 @@ inputs are copies of the same signals. The mapping of these 8 signals is the fol
All mentioned peripherals (WB crossbar, VIC, WB GPIO) are available as part of `OHWR
general-cores`_. The SPEC demo also uses the Gennum `GN4124 core`_ to provide the host interface.
Simulation
----------
.. note:: read :ref:`hdl:sim` chapter in order to run a simulation.
The spec_mt_demo testbench uses the top-level module as the Device Under Test (DUT).
It loads and executes a simple "Hello World" in the first CPU.
The aim of this testbench is to simply verify that the SPEC Demo design is working.
The expected output from the simulation is::
App ID: 0xd331d331
Core count: 2
UART MSG from core 0: Hello World!
UART MSG from core 0:
.. note::
The spec_mt_demo testbench expects an already compiled software binary under
*demos/hello_world/firmware/fw-01*. Please compile the software prior to running the simulation.
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,14 +97,13 @@ 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
.. _`FMC SPEC carrier`: https://www.ohwr.org/projects/spec/
.. _GN4124 core: https://www.ohwr.org/projects/gn4124-core/wiki
.. _Hdlmake: https://www.ohwr.org/projects/hdl-make/wiki
.. _OHWR general-cores: https://www.ohwr.org/projects/general-cores/wiki
.. _`FMC SPEC carrier`: https://www.ohwr.org/project/spec/
.. _GN4124 core: https://www.ohwr.org/project/gn4124-core/wiki
.. _Hdlmake: https://www.ohwr.org/project/hdl-make/wiki
.. _OHWR general-cores: https://www.ohwr.org/project/general-cores/wiki
doc/demos/fmc-svec-carrier.rst
View file @ 9e9329d7
.. _`demo:svec`:
====================
The *FMC SVEC* Demo
====================
......@@ -79,33 +81,10 @@ signals. The mapping of these 24 signals is the following:
All mentioned peripherals (WB crossbar, VIC, WB GPIO) are available as part of `OHWR
general-cores`_. This demo also uses the `VME64x core`_ to provide the host interface.
Simulation
----------
.. note:: read :ref:`hdl:sim` chapter in order to run a simulation.
The spec_mt_demo testbench uses the top-level module as the Device Under Test
(DUT). It loads and executes a simple "Hello World" in the first CPU.
The aim of this testbench is to simply verify that the SVEC demo design is
working.
The expected output from the simulation is::
App ID: 0xd330d330
Core count: 2
UART MSG from core 0: Hello World!
UART MSG from core 0:
.. note::
The svec_mt_demo testbench expects an already compiled software binary under
*demos/hello_world/firmware/fw-01*. Please compile the software prior to
running the simulation.
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 +93,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 reproduces 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,43 +105,43 @@ 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 exportes as :ref:`sw:fw:frm:var` the device peripheral registers
- it exports 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::
Rembember 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 uses 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
make 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
making 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 status.
the possibility to play with the status of the LEDs and LEMOs.
.. highlight:: c
.. literalinclude:: ../../demos/fmc-svec-carrier/software/tools/mockturtle-svec.c
.. _`FMC SVEC carrier`: https://www.ohwr.org/projects/svec/
.. _Hdlmake: https://www.ohwr.org/projects/hdl-make/wiki
.. _VME64x core: https://www.ohwr.org/projects/vme64x-core/wiki
.. _OHWR general-cores: https://www.ohwr.org/projects/general-cores/wiki
.. _`FMC SVEC carrier`: https://www.ohwr.org/project/svec/
.. _Hdlmake: https://www.ohwr.org/project/hdl-make/wiki
.. _VME64x core: https://www.ohwr.org/project/vme64x-core/wiki
.. _OHWR general-cores: https://www.ohwr.org/project/general-cores/wiki
doc/demos/hello-world.rst
View file @ 9e9329d7
......@@ -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 exits.
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 informations
about the firmware application.
This demo will print on the serial interface general information regarding
the firmware application.
::
......
doc/demos/index.rst
View file @ 9e9329d7
......@@ -4,15 +4,15 @@
The Demos
============
This is a collection of demo applications which main purpose is to
This is a collection of demo applications whose 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
You will notice the usage of environment variables; these variables, of
course, depend on 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 @ 9e9329d7
......@@ -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 an autonomus system made of software, hardware (and gateware),
An 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 an HDL component part of a more complex gateware design.
An 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 directions: 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/hdl/index.rst
View file @ 9e9329d7
......@@ -181,6 +181,14 @@ A VHDL component declaration for the MT top-level entity is included in the **mo
generic (
g_CONFIG : t_mt_config := c_DEFAULT_MT_CONFIG;
g_SYSTEM_CLOCK_FREQ : integer := 62500000;
g_CPU0_IRAM_INITF : string := "none";
g_CPU1_IRAM_INITF : string := "none";
g_CPU2_IRAM_INITF : string := "none";
g_CPU3_IRAM_INITF : string := "none";
g_CPU4_IRAM_INITF : string := "none";
g_CPU5_IRAM_INITF : string := "none";
g_CPU6_IRAM_INITF : string := "none";
g_CPU7_IRAM_INITF : string := "none";
g_WITH_WHITE_RABBIT : boolean := FALSE);
port (
clk_i : in std_logic;
......@@ -191,10 +199,8 @@ A VHDL component declaration for the MT top-level entity is included in the **mo
dp_master_i : in t_wishbone_master_in_array(0 to g_CONFIG.cpu_count-1) := (others => c_DUMMY_WB_MASTER_IN);
host_slave_i : in t_wishbone_slave_in;
host_slave_o : out t_wishbone_slave_out;
rmq_src_o : out t_mt_stream_source_out_array2d;
rmq_src_i : in t_mt_stream_source_in_array2d := (others => (others => c_MT_DUMMY_SOURCE_IN));
rmq_snk_o : out t_mt_stream_sink_out_array2d;
rmq_snk_i : in t_mt_stream_sink_in_array2d := (others => (others => c_MT_DUMMY_SINK_IN));
rmq_endpoint_o : out t_mt_rmq_endpoint_iface_out;
rmq_endpoint_i : in t_mt_rmq_endpoint_iface_in := c_MT_RMQ_ENDPOINT_IFACE_IN_DEFAULT_VALUE;
clk_ref_i : in std_logic := '0';
tm_i : in t_mt_timing_if := c_DUMMY_MT_TIMING;
gpio_o : out std_logic_vector(31 downto 0);
......@@ -219,6 +225,9 @@ g_SYSTEM_CLOCK_FREQ
keeping track of time when `White Rabbit Support`_ is not enabled and it is also used by
software to calculate delays.
g_CPUx_IRAM_INITF
Memory initialization file for CPUx, to be included in the FPGA bitstream, if any.
g_WITH_WHITE_RABBIT
Controls enabling of `White Rabbit Support`_.
......@@ -293,14 +302,36 @@ host_slave_i, host_slave_o
('1', '0', '0', '0', c_DUMMY_WB_DATA);
constant c_DUMMY_WB_MASTER_IN : t_wishbone_master_in := c_DUMMY_WB_SLAVE_OUT;
rmq_src_o, rmq_src_i, rmq_snk_o, rmq_snk_i
rmq_endpoint_o, rmq_endpoint_i
These ports provide the bidirectional interface from each of the configured soft CPUs to their
repspective remote message queue(s).
repspective end-points.
**t_mt_rmq_endpoint_iface_out** and **t_mt_rmq_endpoint_iface_in** are VHDL record types defined in
the **mock_turtle_pkg**::
type t_mt_rmq_endpoint_iface_out is record
src_out : t_mt_stream_source_out_array2d;
snk_out : t_mt_stream_sink_out_array2d;
src_config_out : t_mt_stream_config_out_array2d;
snk_config_out : t_mt_stream_config_out_array2d;
end record;
type t_mt_rmq_endpoint_iface_in is record
src_in : t_mt_stream_source_in_array2d;
snk_in : t_mt_stream_sink_in_array2d;
src_config_in : t_mt_stream_config_in_array2d;
snk_config_in : t_mt_stream_config_in_array2d;
end record;
*src_out*, *src_in*, *snk_out* and *snk_in* are used to transfer data to/from the end-point, while
the *config* signals are used to configure the end-points (e.g. to set the network destination for
the data).
**t_mt_stream_source_out_array2d**, **t_mt_stream_source_in_array2d**,
**t_mt_stream_sink_out_array2d** and **t_mt_stream_sink_in_array2d** are two-dimensional arrays of
**t_mt_stream_sink_out_array2d**, **t_mt_stream_sink_in_array2d**,
**t_mt_stream_config_out_array2d** and **t_mt_stream_config_in_array2d** are two-dimensional arrays of
VHDL records, defined in **mock_turtle_pkg** (for the first array dimension) and **mt_mqueue_pkg**
(for the second array dimension and for the records)::
(for the second array dimension and for the records themselves)::
subtype t_maxcpu_range is natural range 0 to 7;
subtype t_maxslot_range is natural range 0 to 7;
......@@ -314,6 +345,11 @@ VHDL records, defined in **mock_turtle_pkg** (for the first array dimension) and
subtype t_mt_stream_source_in_array2d is t_mt_stream_sink_out_array2d;
subtype t_mt_stream_source_out_array2d is t_mt_stream_sink_in_array2d;
type t_mt_stream_config_in_array2d is
array(t_maxcpu_range) of t_mt_stream_config_in_array(t_maxslot_range);
type t_mt_stream_config_out_array2d is
array(t_maxcpu_range) of t_mt_stream_config_out_array(t_maxslot_range);
-- defined in mt_mqueue_pkg
type t_mt_stream_sink_in_array is array(integer range<>) of t_mt_stream_sink_in;
type t_mt_stream_sink_out_array is array(integer range<>) of t_mt_stream_sink_out;
......@@ -334,16 +370,21 @@ VHDL records, defined in **mock_turtle_pkg** (for the first array dimension) and
pkt_ready : std_logic;
end record t_mt_stream_sink_out;
type t_mt_stream_config_out is record
adr : std_logic_vector(10 downto 0);
dat : std_logic_vector(31 downto 0);
we : std_logic;
end record t_mt_stream_config_out;
type t_mt_stream_config_in is record
dat : std_logic_vector(31 downto 0);
end record t_mt_stream_config_in;
subtype t_mt_stream_source_in is t_mt_stream_sink_out;
subtype t_mt_stream_source_out is t_mt_stream_sink_in;
constant c_MT_DUMMY_SOURCE_IN : t_mt_stream_sink_out :=
('0', '0');
constant c_MT_DUMMY_SINK_IN : t_mt_stream_sink_in :=
(x"00000000", '0', '0', '0', '0');
.. todo::
Describe how the RMQ interface works and update after Tom's endpoint work if necessary.
For an example of an end-point, please have a look at the provided Ethernet end-point, available
under *hdl/rtl/endpoint/mt_ep_ethernet_single.vhd*.
clk_ref_i
When `White Rabbit Support`_ is enabled (via the **g_WITH_WHITE_RABBIT** generic), the White
......@@ -448,8 +489,8 @@ the signals, store them for future reference, display them as waveforms, etc.
mock_turtle_core
----------------
The mock_turtle_core uses the top-level module of the MT as the Device Under Test (DUT). It loads
and executes a dedicated simulation verification program on the first CPU.
The mock_turtle_core testbench uses the top-level module of the MT as the Device Under Test
(DUT). It loads and executes a dedicated simulation verification program on the first CPU.
This program tests the following subsystems of the MT:
......@@ -467,15 +508,91 @@ The expected output from the simulation is::
UART MSG from core 0: #3 hmq
UART MSG from core 0: #4 rmq
UART MSG from core 0: Done
Simulation PASSED
.. note::
The mock_turtle_core testbench expects an already compiled software binary under
*tests/firmware/sim-verif*. Please compile the software prior to running the simulation.
.. _OHWR general-cores: https://www.ohwr.org/projects/general-cores/wiki
.. _White Rabbit PTP Core: https://www.ohwr.org/projects/wr-cores/wiki/Wrpc_core/wiki
.. _Hdlmake: https://www.ohwr.org/projects/hdl-make/wiki
.. _uRV processor: https://www.ohwr.org/projects/urv-core/wiki
mt_eth_ep
---------
The mt_eth_ep testbench uses the top-level module of the MT as the Device Under Test (DUT) and it
attaches an *mt_ep_ethernet_single* end-point to it. It loads and executes a dedicated simulation
verification program on the first CPU.
This program tests in particular the remote message queues and the mechanism to configure and control
end-points.
The expected output from the simulation is::
App ID: 0x115790de
Core count: 2
UART MSG from core 0: RMQ UDP EP test
802.1 DST [ff:ff:ff:ff:ff:ff] SRC: [00:00:00:00:00:00] Type = 0x0800 size = 50 F:( )
+000: 45 00 00 24 00 00 40 00-3c 11 83 ca c0 a8 5a 11
+010: c0 a8 5a ff 1e 61 30 39-00 10 00 00 de ad be ef
+020: 00 00 01 23
UART MSG from core 0: Recv id=21524110, val=fffffedc
UART MSG from core 0: rx(1): fffffedc
802.1 DST [ff:ff:ff:ff:ff:ff] SRC: [00:00:00:00:00:00] Type = 0x0800 size = 50 F:( )
+000: 45 00 00 24 00 00 40 00-3c 11 83 ca c0 a8 5a 11
+010: c0 a8 5a ff 1e 61 30 39-00 10 00 00 de ad be ef
+020: ff ff fe dc
UART MSG from core 0: Recv id=21524110, val=123
UART MSG from core 0: rx(2): 123
Simulation PASSED
.. note::
The mt_eth_ep testbench expects an already compiled software binary under
*tests/firmware/rmq-udp-send*. Please compile the software prior to running the simulation.
spec_mt_demo
------------
The spec_mt_demo testbench uses the top-level module of the :ref:`demo:spec` as the Device Under
Test (DUT). It loads and executes a simple "hello world" demo program on the first CPU.
The purpose of this testbench is mainly to verify that the :ref:`demo:spec` HDL design is
working. To this end, the testbench simply instantiates the top-level and waits for the
firmware to print the "hello world" message on the serial console.
The expected output from the simulation is::
App ID: 0xd331d331
Core count: 2
UART MSG from core 0: Hello World!
UART MSG from core 0:
.. note::
The spec_mt_demo testbench expects an already compiled software binary under
*demos/hello_world*. Please compile the software prior to running the simulation.
svec_mt_demo
------------
The svec_mt_demo testbench uses the top-level module of the :ref:`demo:svec` as the Device Under
Test (DUT). It loads and executes a simple "hello world" demo program on the first CPU.
The purpose of this testbench is mainly to verify that the :ref:`demo:svec` HDL design is
working. To this end, the testbench simply instantiates the top-level and waits for the
firmware to print the "hello world" message on the serial console.
The expected output from the simulation is::
App ID: 0xd330d330
Core count: 2
UART MSG from core 0: Hello World!
UART MSG from core 0:
.. note::
The svec_mt_demo testbench expects an already compiled software binary under
*demos/hello_world*. Please compile the software prior to running the simulation.
.. _OHWR general-cores: https://www.ohwr.org/project/general-cores/wiki
.. _White Rabbit PTP Core: https://www.ohwr.org/project/wr-cores/wiki/Wrpc_core/wiki
.. _Hdlmake: https://www.ohwr.org/project/hdl-make/wiki
.. _uRV processor: https://www.ohwr.org/project/urv-core/wiki
.. _Git submodules: https://git-scm.com/book/en/Git-Tools-Submodules
.. highlight:: none
doc/index.rst
View file @ 9e9329d7
......@@ -8,7 +8,7 @@ Welcome to Mock Turtle's documentation!
.. toctree::
:maxdepth: 1
:caption: Contents:
:caption: Contents
introduction
architecture
......
doc/introduction.rst deleted 120000 → 0
View file @ 7bc491de
../README.rst
\ No newline at end of file
doc/introduction.rst 0 → 100644
View file @ 9e9329d7
.. _introduction:description:
============
Introduction
============
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. 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
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.
The Mock Turtle framework focuses mainly on the determinism of the
firmware running in it. Indeed, Mock Turtle does not support any kind of
interrupt or scheduling which might compromise the determinism.
The Mock Turtle framework includes the following components:
- Gateware
- The Mock Turtle core
- Shared Memory among soft-CPUs and host system
- Up to 8 soft-CPUs
- communication with the host system (input, output)
- communication with remote systems (input, output)
- Software
- the Mock Turtle firmware library to access gateware cores from the
firmware
- the Mock Turtle firmware framework to develop firmware
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:
- the Mock Turtle Linux device driver
- the Mock Turtle library that provides uniform access to the driver
- the Mock Turtle Python module to access the library using Python
.. _introduction:use-cases:
Use Cases
==========
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 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.
.. list-table::
:header-rows: 0
:widths: 1 1
* - .. figure:: img/mock-turtle-use-case-1.svg
:align: center
Control system **without** Mock-Turtle
- .. figure:: img/mock-turtle-use-case-2.svg
:align: center
Control system **with** Mock-Turtle
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 Not To Consider Mock Turtle
--------------------------------
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 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/project/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/project/mock-turtle
doc/registers/index.rst
View file @ 9e9329d7
......@@ -4,6 +4,16 @@
Register Tables
===============
.. toctree::
:maxdepth: 1
:caption: Contents
wbgen_csr
wbgen_lr
Mock Turtle Top Level Layout
----------------------------
Memory map from the host point of view:
.. list-table::
......
doc/requirements.txt 0 → 100644
View file @ 9e9329d7
docutils==0.14
Sphinx==1.8.3
sphinx_rtd_theme
breathe==4.10.0
recommonmark==0.5.0
doc/software/firmware-framework.rst
View file @ 9e9329d7
......@@ -6,17 +6,17 @@
The Mock Turtle Firmware Framework
==================================
Mock Turtle firmware framework guides users development by
keeping them focused only 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
the performances are not enough for your application.
consider alternatives if you see that it is consuming too much memory or
that the performance is not enough for your application.
.. note::
......@@ -26,13 +26,13 @@ the performances are not enough for your application.
Application
===========
Firmwares developed with this framework need to be described by
:c:type:`trtl_fw_application`. Firmware applications develop with this
framework does 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 developed with this
framework do not have a ``main()``. The ``main()`` is implemented within the
framework itself. What you should do instead is 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
correspondent function get executed.
corresponding function gets executed.
This framework support up to :c:macro:`__TRTL_MSG_ID_MAX` actions.
This framework supports 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 meaning 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 correspondent 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 corresponding 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 correspondent 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 corresponding 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
Utilities
=========
Miscellaneous
=============
This is a collection of miscellaneous functions that can be of some helpers.
The following is a list of miscellaneous, helper functions.
.. doxygenfunction:: trtl_fw_time
......
doc/software/firmware-library.rst
View file @ 9e9329d7
......@@ -17,7 +17,7 @@ Turtle firmware.
.. warning::
Any firmware develop without this library will not receive any kind
Any firmware developed 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 Queues
================
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 commands 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 when we 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,13 +142,13 @@ 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;
uint32_t status;
while ((mq_poll_out(TRTL_HMQ) & (1 << HMQ_NUM)) == 0)
while ((mq_poll_out(TRTL_HMQ, 1 << HMQ_NUM)) == 0)
; /* wait until queue not full */
mq_claim(TRTL_HMQ, HMQ_NUM);
......@@ -168,13 +170,13 @@ 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;
uint32_t status;
while ((mq_poll_in(TRTL_HMQ) & (1 << HMQ_NUM)) == 0)
while ((mq_poll_in(TRTL_HMQ, 1 << HMQ_NUM)) == 0)
; /* wait until queue not empty */
mq_map_in_message(TRTL_HMQ, HMQ_NUM, &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 which purposes are:
This is a collection of functions and macros whose 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 example::
Here is an example on how to print over the serial interface::
#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 custum notifications to their support layer.
deliver custom 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 @ 9e9329d7
......@@ -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 only 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 performances: 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 means 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,16 +154,16 @@ 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/
.. _`soft-cpu toolchain`: https://www.ohwr.org/projects/soft-cpu-toolchains/wiki/wiki
.. _`soft-cpu toolchain`: https://www.ohwr.org/project/soft-cpu-toolchains/wiki/wiki
.. toctree::
:maxdepth: 2
:caption: Contents:
:caption: Contents
firmware-library
firmware-framework
doc/software/index-lnx.rst
View file @ 9e9329d7
......@@ -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 Pyhton module, a C library and
a Linux kernel interface. Mock Turtle users are not supposed to use
the driver interface directly.
Mock Turtle offers 3 interfaces: a Python module, a C library and a
Linux kernel interface. Users are expected to use either the Python
module or the C library.
.. graphviz::
:align: center
......
doc/software/index.rst
View file @ 9e9329d7
......@@ -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 custumized control/monitor
On the other hand, :ref:`sw:lnx` on the
host depends on your needs. If you need a customized 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 @ 9e9329d7
......@@ -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 exports 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 custumize
The following table lists the module parameters that can be used to customize
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 able
to drive it. Loading the gateware bitstream depends on the FPGA carrier in use.
Just keep in mind that you must load the bitstream **before** adding a
Mock Turtle device instance in the Linux kernel. If you do not do so, you will
get crashes because the device driver will try to access something that does
not exist yet.
A Mock Turtle instance must already exist on the FPGA in order to be
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 access
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 DeviceTree.
[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 Structure.
This driver handles all platform_device instances which name is one of
This driver handles all platform_device instances whose 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,17 +151,19 @@ 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
.. _`sw:drv:serial`:
Mock Turtle uses the standard TTY layer from the Linux kernel. Each
core has a dedicated serial interface which is used for communications
from soft-CPU to host.
......@@ -178,7 +183,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 +209,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 childred 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,16 +260,23 @@ 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
following format "trtl-%0x4x-dbg". These files can be accessed only with
``mmap(2)`` and typically the user does not need to use it directly, instead
the user should use the :ref:`Mock Turtle GDB Server <tools:mockturtle-gdbserver>`.
.. [1] https://www.kernel.org/doc/Documentation/driver-model/platform.txt
doc/software/linux-library.rst
View file @ 9e9329d7
......@@ -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 Turtle
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 the
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 code accordingly.
files are in different locations, please adjust the above example 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,
it processes the header but the payload is transfered as is.
Any processing on 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.
It processes the header but the payload is transfered as is.
Any processing of 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 operations 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 functions
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 @ 9e9329d7
......@@ -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 PyMockTurlte Basic Usage
PyMockTurtle 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 instanciated automaticaly.::
(:py:class:`PyMockTurtle.TrtlHmq`) will be instantiated automaticaly::
import PyMockTurtle
......
doc/software/protocol.rst
View file @ 9e9329d7
......@@ -32,9 +32,9 @@ with different APIs, by both host system and firmware.
Host Message Queue Protocol
==============================
A protocol in necessary in order to exchange messages between two entities.
A protocol is 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
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/index.rst
View file @ 9e9329d7
......@@ -22,3 +22,4 @@ message. All tools are available in the directory *software/tools*.
mockturtle-variable
mockturtle-buffer
mockturtle-debug
mockturtle-gdbserver
doc/tools/mockturtle-buffer.rst
View file @ 9e9329d7
......@@ -3,6 +3,9 @@
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`.
You can get the list of available Mock Turtle devices that you can access
with the command ``lsmockturtle``.
doc/tools/mockturtle-cpu-restart.rst
View file @ 9e9329d7
......@@ -5,5 +5,8 @@ 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.
You can get the list of available Mock Turtle devices that you can access
with the command ``lsmockturtle``.
doc/tools/mockturtle-firmware-loader.rst
View file @ 9e9329d7
.. _`tools:mockturtle-firmware-loader`:
==============================
===========================
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.
You can get the list of available Mock Turtle devices that you can access
with the command ``lsmockturtle``.
doc/tools/mockturtle-gdbserver.rst 0 → 100644
View file @ 9e9329d7
.. _tools:mockturtle-gdbserver:
======================
Mock Turtle GDB Server
======================
The Mock Turtle GDB Server application (*mockturtle-gdbserver*) provides
access to the Mock Turtle CPU debug interface. The user can start the server
against a Mock Turtle instance and start debugging remotly using ``gdb(1)``.
This debug interface is accessible only if the Linux debugfs file-system is
mounted at ``/sys/kernel/debug``; be sure to run the following command before
starting the *mockturtle-gdbserver*:::
mount -t debugfs none /sys/kernel/debug
Please refer to the application help message for more information.
You can get the list of available Mock Turtle devices that you can access
with the command ``lsmockturtle``.
doc/tools/mockturtle-messages.rst
View file @ 9e9329d7
.. _`tools:mockturtle-messages`:
======================
====================
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.
You can get the list of available Mock Turtle devices that you can access
with the command ``lsmockturtle``.
doc/tools/mockturtle-ping.rst
View file @ 9e9329d7
.. _tools:mockturtle-ping:
=================
================
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`.
You can get the list of available Mock Turtle devices that you can access
with the command ``lsmockturtle``.
doc/tools/mockturtle-project-creator.rst
View file @ 9e9329d7
......@@ -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.
Fortunatelly, 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 @ 9e9329d7
.. _tools:mockturtle-smem:
=============================
=========================
Mock Turtle Shared Memory
=============================
=========================
The Mock Turtle Shared Memory application (*mockturtle-smem*) provides
access to the Mock Turtle shm. The user can read/write any location of
the shm using different access modes.
access to the Mock Turtle shared memory. The user can read/write any location
of the shared memory using different access modes.
You can get the list of available Mock Turtle devices that you can access
with the command ``lsmockturtle``.
doc/tools/mockturtle-variable.rst
View file @ 9e9329d7
.. _`tools:mockturtle-variable`:
=====================
====================
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`.
You can get the list of available Mock Turtle devices that you can access
with the command ``lsmockturtle``.
hdl/rtl/cpu/mt_cpu_cb.vhd
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
-- program/data memory and control registers.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/cpu/mt_cpu_csr.wb
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: MT CPU Control/Status Registers block layout (wbgen2)
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/cpu/mt_cpu_lr.wb
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: MT CPU Per-Core Local Registers block layout (wbgen2)
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/cpu/mt_per_cpu_csr_pkg.vhd
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
-- file that describes the whole CSR interface.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2018
-- Copyright (c) 2018-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/cpu/mt_urv_wrapper.vhd
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
-- access to the RAM through CPU CSR register block.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/endpoint/mt_endpoint_pkg.vhd
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: Global package for the UDP/Ethernet RMQ endpoint.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/endpoint/mt_ep_ethernet_single.vhd
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
--
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/endpoint/mt_ethernet_tx_framer.vhd
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: Remote MQ Ethernet framer.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/endpoint/mt_rmq_endpoint_rx.vhd
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
-- single RMQ slot.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/endpoint/mt_rmq_endpoint_tx.vhd
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
-- Decode configuration registers.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/endpoint/mt_rmq_ethernet_endpoint.vhd
View file @ 9e9329d7
......@@ -11,7 +11,7 @@
--
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/endpoint/mt_rmq_packet_output.vhd
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: Packet assembler for the TX path of the RMQ.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/endpoint/mt_rmq_rx_deframer.vhd
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: Remote MQ ethernet/UDP packet deframer.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/endpoint/mt_rmq_rx_path.vhd
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: Remote MQ RX path. Deframe (extract header).
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/endpoint/mt_rmq_stream_register.vhd
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
-- nodes.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/endpoint/mt_rmq_tx_path.vhd
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: Remote MQ TX packet assembler: add eth, ip, udp headers.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/endpoint/mt_udp_tx_framer.vhd
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: Remote MQ UDP framer
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/endpoint/mt_wr_sink.vhd
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: Mock Turtle White Rabbit sink: WR fabric to MT stream.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/endpoint/mt_wr_source.vhd
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
-- MT stream to WR fabric.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/mock_turtle_core.vhd
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
-- interface and the Shared Memory.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/mock_turtle_pkg.vhd
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: top level package with public types, definitions and components.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......@@ -160,10 +160,10 @@ package mock_turtle_pkg is
sp_master_i : in t_wishbone_master_in := c_DUMMY_WB_MASTER_IN;
dp_master_o : out t_wishbone_master_out_array(0 to g_CONFIG.cpu_count-1);
dp_master_i : in t_wishbone_master_in_array(0 to g_CONFIG.cpu_count-1) := (others => c_DUMMY_WB_MASTER_IN);
rmq_endpoint_o : out t_mt_rmq_endpoint_iface_out;
rmq_endpoint_i : in t_mt_rmq_endpoint_iface_in := c_MT_RMQ_ENDPOINT_IFACE_IN_DEFAULT_VALUE;
host_slave_i : in t_wishbone_slave_in;
host_slave_o : out t_wishbone_slave_out;
rmq_endpoint_o : out t_mt_rmq_endpoint_iface_out;
rmq_endpoint_i : in t_mt_rmq_endpoint_iface_in := c_MT_RMQ_ENDPOINT_IFACE_IN_DEFAULT_VALUE;
clk_ref_i : in std_logic := '0';
tm_i : in t_mt_timing_if := c_DUMMY_MT_TIMING;
gpio_o : out std_logic_vector(31 downto 0);
......
hdl/rtl/mqueue/mt_mqueue_host.vhd
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
-- the CPU CBs and the host system.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/mqueue/mt_mqueue_pkg.vhd
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: Global package for the Message Queues
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/mqueue/mt_mqueue_remote.vhd
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
-- remote nodes.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/mqueue/mt_mqueue_slot.vhd
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: Single slot (FIFO) of a Message Queue.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/mqueue/mt_mqueue_wishbone_slave.vhd
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: Wishbone slave for MQ's Slots.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/mqueue/mt_rmq_rx.vhd
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: Remote message rx adapter
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/mqueue/mt_rmq_tx.vhd
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: Single outgoing (MT->world) slot of the Remote Message Queue.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/rtl/mt_config_rom.vhd
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
-- MockTurtle implementation.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2018
-- Copyright (c) 2018-2019 CERN (home.cern)
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
......
hdl/rtl/smem/mt_shared_mem.vhd
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
-- description: Mock Turtle CPU Shared Memory block.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2014-2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/testbench/include/mock_turtle_driver.svh
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
// MockTurtle core.
//
//------------------------------------------------------------------------------
// Copyright CERN 2018
// Copyright (c) 2018-2019 CERN (home.cern)
//------------------------------------------------------------------------------
// Copyright and related rights are licensed under the Solderpad Hardware
// License, Version 2.0 (the "License"); you may not use this file except
......
hdl/testbench/include/mt_config_rom_driver.svh
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
// MockTurtle implementation.
//
//------------------------------------------------------------------------------
// Copyright CERN 2018
// Copyright (c) 2014-2019 CERN (home.cern)
//------------------------------------------------------------------------------
// Copyright and related rights are licensed under the Solderpad Hardware
// License, Version 2.0 (the "License"); you may not use this file except
......
hdl/testbench/include/mt_cpu_csr_driver.svh
View file @ 9e9329d7
......@@ -11,7 +11,7 @@
// loading, debug UART monitoring, etc.
//
//------------------------------------------------------------------------------
// Copyright CERN 2018
// Copyright (c) 2018-2019 CERN (home.cern)
//------------------------------------------------------------------------------
// Copyright and related rights are licensed under the Solderpad Hardware
// License, Version 2.0 (the "License"); you may not use this file except
......
hdl/testbench/include/mt_debug_driver.svh
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
// MockTurtle core's debug interface.
//
//------------------------------------------------------------------------------
// Copyright CERN 2018
// Copyright (c) 2018-2019 CERN (home.cern)
//------------------------------------------------------------------------------
// Copyright and related rights are licensed under the Solderpad Hardware
// License, Version 2.0 (the "License"); you may not use this file except
......
hdl/testbench/include/mt_hmq_driver.svh
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
// MockTurtle core's host message queue.
//
//------------------------------------------------------------------------------
// Copyright CERN 2018
// Copyright (c) 2018-2019 CERN (home.cern)
//------------------------------------------------------------------------------
// Copyright and related rights are licensed under the Solderpad Hardware
// License, Version 2.0 (the "License"); you may not use this file except
......
hdl/testbench/include/mt_queue_message.svh
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
// MockTurtle core's queue message.
//
//------------------------------------------------------------------------------
// Copyright CERN 2018
// Copyright (c) 2018-2019 CERN (home.cern)
//------------------------------------------------------------------------------
// Copyright and related rights are licensed under the Solderpad Hardware
// License, Version 2.0 (the "License"); you may not use this file except
......
hdl/testbench/mock_turtle_core/main.sv
View file @ 9e9329d7
......@@ -10,7 +10,7 @@
// Mock Turtle core.
//
//------------------------------------------------------------------------------
// Copyright CERN 2018
// Copyright (c) 2018-2019 CERN (home.cern)
//------------------------------------------------------------------------------
// Copyright and related rights are licensed under the Solderpad Hardware
// License, Version 2.0 (the "License"); you may not use this file except
......
hdl/testbench/mt_eth_ep/main.sv
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
// description: A SystemVerilog testbench to test the ethernet endpoint of MT
//
//------------------------------------------------------------------------------
// Copyright CERN 2018
// Copyright (c) 2014-2019 CERN (home.cern)
//------------------------------------------------------------------------------
// Copyright and related rights are licensed under the Solderpad Hardware
// License, Version 2.0 (the "License"); you may not use this file except
......
hdl/testbench/spec_mt_demo/main.sv
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
// description: A SystemVerilog testbench for the supplied SPEC MT demo.
//
//------------------------------------------------------------------------------
// Copyright CERN 2018
// Copyright (c) 2018-2019 CERN (home.cern)
//------------------------------------------------------------------------------
// Copyright and related rights are licensed under the Solderpad Hardware
// License, Version 2.0 (the "License"); you may not use this file except
......
hdl/testbench/spec_mt_demo/synthesis_descriptor.vhd
View file @ 9e9329d7
......@@ -5,10 +5,10 @@
-- Tuesday, March 13 2018
--
-- ../../ip_cores/general-cores/tools/sdb_desc_gen.tcl is part of OHWR general-cores:
-- https://www.ohwr.org/projects/general-cores/wiki
-- https://www.ohwr.org/project/general-cores/wiki
--
-- For more information on SDB meta information, see also:
-- https://www.ohwr.org/projects/sdb/wiki
-- https://www.ohwr.org/project/sdb/wiki
--------------------------------------------------------------------------------
library ieee;
......
hdl/testbench/svec_mt_demo/main.sv
View file @ 9e9329d7
......@@ -9,7 +9,7 @@
// description: A SystemVerilog testbench for the supplied SVEC MT demo.
//
//------------------------------------------------------------------------------
// Copyright CERN 2018
// Copyright (c) 2018-2019 CERN (home.cern)
//------------------------------------------------------------------------------
// Copyright and related rights are licensed under the Solderpad Hardware
// License, Version 2.0 (the "License"); you may not use this file except
......
hdl/testbench/svec_mt_demo/synthesis_descriptor.vhd
View file @ 9e9329d7
......@@ -5,10 +5,10 @@
-- Tuesday, March 13 2018
--
-- ../../ip_cores/general-cores/tools/sdb_desc_gen.tcl is part of OHWR general-cores:
-- https://www.ohwr.org/projects/general-cores/wiki
-- https://www.ohwr.org/project/general-cores/wiki
--
-- For more information on SDB meta information, see also:
-- https://www.ohwr.org/projects/sdb/wiki
-- https://www.ohwr.org/project/sdb/wiki
--------------------------------------------------------------------------------
library ieee;
......
hdl/top/spec_mt_demo/spec_mt_demo.vhd
View file @ 9e9329d7
......@@ -13,7 +13,7 @@
-- and buttons of the SPEC.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2018
-- Copyright (c) 2018-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/top/svec_mt_demo/svec_mt_demo.vhd
View file @ 9e9329d7
......@@ -13,7 +13,7 @@
-- and LEMO I/O on the front panel of the SVEC.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2018
-- Copyright (c) 2018-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
hdl/top/svec_mt_demo_wr/svec_mt_demo_wr.vhd
View file @ 9e9329d7
......@@ -13,7 +13,7 @@
-- and LEMO I/O on the front panel of the SVEC.
--
--------------------------------------------------------------------------------
-- Copyright CERN 2018
-- Copyright (c) 2014-2019 CERN (home.cern)
--------------------------------------------------------------------------------
-- Copyright and related rights are licensed under the Solderpad Hardware
-- License, Version 2.0 (the "License"); you may not use this file except
......
software/firmware/framework/mockturtle-framework.c
View file @ 9e9329d7
/**
* Copyright (C) 2015-2016 CERN (www.cern.ch)
* Copyright (c) 2015-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......@@ -29,7 +29,7 @@ int pr_frm_debug(const char *fmt, ...)
uint32_t msg_seq = 0;
/**
* It makes the given message an error message
* Make the given message an error message
*/
void trtl_fw_message_error(struct trtl_fw_msg *msg, int err)
{
......@@ -264,7 +264,7 @@ static inline trtl_fw_action_t *rt_action_get(unsigned int msg_id)
}
/**
* It runs the action associated with the given identifier
* Run the action associated with the given identifier
* @param[in] type MQ type
* @param[in] idx_mq MQ index
* @param[out] msg the incoming message
......@@ -320,7 +320,7 @@ static inline int rt_action_run(enum trtl_mq_type type,
/**
* It dispatch messages coming from a given message queue.
* Dipatch messages coming from a given message queue.
* @param[in] type MQ type
* @param[in] idx_mq MQ index
* @return 0 on success. -1 on error
......@@ -375,7 +375,7 @@ out:
/**
* It builds and it sends a message over MQ.
* Build and send a message over MQ.
* The vargs will be copied into the payload message.
* @param[in] type MQ type
* @param[in] idx_mq MQ index within the declaration
......@@ -420,7 +420,7 @@ int trtl_fw_mq_send_uint32(enum trtl_mq_type type,
/**
* It builds and it sends a message over MQ.
* Build and send a message over MQ.
* The buffer will be copied into the payload message.
* Beware that, internally, it uses trtl_fw_mq_send().
* @param[in] type MQ type
......@@ -462,7 +462,7 @@ int trtl_fw_mq_send_buf(enum trtl_mq_type type,
/**
* It gets the current time from the internal TRTL timer
* Get the current time from the internal TRTL timer
* @param[out] seconds
* @param[out] cycles
*/
......@@ -474,7 +474,7 @@ void trtl_fw_time(uint32_t *seconds, uint32_t *cycles)
/**
* It validates the user application actions
* Validate the user application actions
* @param[in] app the user application
* @return 0 on success. -EINVAL on error
*/
......@@ -499,7 +499,7 @@ static inline int trtl_fw_init_action(struct trtl_fw_application *app)
/**
* It validates the FPGA
* Validate the FPGA
* @param[in] app the user application
* @return 0 on success. -EINVAL on error
*/
......@@ -537,7 +537,7 @@ static inline int trtl_fw_init_fpga(struct trtl_fw_application *app)
/**
* It initializes the RMQ and the HMQ
* Initialize the RMQ and the HMQ
* @param[in] app the user application
* @return 0 on success. -EINVAL on error
*/
......@@ -549,7 +549,7 @@ static inline int trtl_fw_init_mq(struct trtl_fw_application *app)
/**
* It validates the RMQ and the HMQ
* Validate the RMQ and the HMQ
* @param[in] app the user application
* @return 0 on success. -EINVAL on error
*/
......@@ -570,7 +570,7 @@ static inline int trtl_fw_init_variables(struct trtl_fw_application *app)
/**
* It validates the RMQ and the HMQ
* Validate the RMQ and the HMQ
* @param[in] app the user application
* @return 0 on success. -EINVAL on error
*/
......@@ -589,7 +589,7 @@ static inline int trtl_fw_init_buffers(struct trtl_fw_application *app)
/**
* It initializes the application and it does some compatibility check.
* Initialize the application and some compatibility check.
*
* - check bitstream FPGA ID if compatibile with the application.
* - purge remote message queue
......
software/firmware/framework/mockturtle-framework.h
View file @ 9e9329d7
/**
* @defgroup framework Mock Turtle Firmware Framework
* @{
* @copyright (C) 2015-2016 CERN (www.cern.ch)
* @copyright: Copyright (c) 2015-2019 CERN (home.cern)
* @author Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......@@ -68,7 +68,7 @@ struct trtl_fw_buffer {
/**
* Firmware Application Descriptor.
* It provides a set of useful information used by the framework to
* Provide a set of useful information used by the framework to
* provide services to users.
*/
struct trtl_fw_application {
......@@ -103,7 +103,7 @@ struct trtl_fw_application {
extern struct trtl_fw_application app;
/**
* It returns the application descriptor
* Return the application descriptor
* @return application descriptor
*/
static inline struct trtl_fw_application *trtl_fw_application_get(void)
......
software/firmware/lib/mockturtle-rt-common.c
View file @ 9e9329d7
/*
* Copyright (C) 2013-2016 CERN (www.cern.ch)
* Copyright (c) 2013-2019 CERN (home.cern)
* Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
* Author: Federico Vaga <federico.vaga@cern.ch>
*
......@@ -14,7 +14,7 @@
/**
* It sends a character to the UART interface
* Send a character to the UART interface
* @param[in] c the character to sent
* @return 0 on success (for the time being it does not fail)
*/
......@@ -27,7 +27,7 @@ int putchar(int c)
/**
* It sends a string over the serial interface
* Send a string over the serial interface
* @param[in] p string to send
* @return number of sent characters
*
......@@ -48,7 +48,7 @@ int puts(const char *p)
/**
* It prints on the serial console the given message
* Print on the serial console the given message
* @param[in] msg a mock turtle message
*/
void pr_message(struct trtl_fw_msg *msg)
......
software/firmware/lib/mockturtle-rt.h
View file @ 9e9329d7
/**
* @defgroup library Mock Turtle Firmware Library
* @{
* @copyright (C) 2013-2016 CERN (www.cern.ch)
* @copyright: Copyright (c) 2013-2019 CERN (home.cern)
* @author Federico Vaga <federico.vaga@cern.ch>
* @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
*
......@@ -44,7 +44,7 @@ struct trtl_fw_msg {
/**
* It prints a string on the serial interface.
* Print a string on the serial interface.
* Internally, it uses the puts() function.
* @param[in] fmt string format
* @param[in] ... argument according to the string format
......@@ -62,7 +62,7 @@ static inline int pp_printf(const char *fmt, ...)
/**
* It creates a new string according to the given format
* Create a new string according to the given format
* @param[out] s output string
* @param[in] fmt string format
* @param[in] ... argument according to the string format
......@@ -80,7 +80,7 @@ static inline int pp_sprintf(char *s, const char *fmt, ...)
/**
* It prints a string on the serial interface.
* Print a string on the serial interface.
* Internally, it uses the puts() function.
* @param[in] fmt string format
* @param[in] args list of arguments according to the string format
......@@ -97,7 +97,7 @@ static inline int pp_vprintf(const char *fmt, va_list args)
/**
* It creates a new string according to the given format
* Create a new string according to the given format
* @param[out] buf output string
* @param[in] fmt string format
* @param[in] args list of arguments according to the string format
......@@ -115,7 +115,7 @@ static inline int pp_vsprintf(char *buf, const char *fmt, va_list args)
/**
* It prints a string on the serial interface only when the support
* Print a string on the serial interface only when the support
* for error messages is enable.
*
* Kconfig ->CONFIG_MOCKTURTLE_LIBRARY_PRINT_DEBUG_ENABLE
......@@ -136,7 +136,7 @@ static inline int pr_debug(const char *fmt, ...)
#endif
/**
* It prints a string on the serial interface only when the support
* Print a string on the serial interface only when the support
* for error messages is enable.
*
* Kconfig -> CONFIG_MOCKTURTLE_LIBRARY_PRINT_ERROR_ENABLE
......@@ -246,7 +246,7 @@ static inline void gpio_clear(int pin)
/**
* It gets the GPIO status
* Get the GPIO status
* @param[in] pin GPIO pin to query
* @return the GPIO status
*/
......@@ -256,8 +256,8 @@ static inline unsigned int gpio_status(int pin)
}
/**
* Wait n cycles. This means that the wait can be different on
* different core with different clock.
* Wait n CPU cycles. This means that the absolute wait time can be different
* on different cores with different clock frequencies.
* @todo: use Timing Unit, compute it accoring to CPU frequency
* @param[in] n number of cycles to wait
*/
......@@ -270,7 +270,7 @@ static inline void delay(int n)
/**
* It returns a pointer to the config ROM
* Return a pointer to the config ROM
* @return pointer to the configuration ROM
*/
static inline const struct trtl_config_rom *trtl_config_rom_get(void)
......@@ -280,7 +280,7 @@ static inline const struct trtl_config_rom *trtl_config_rom_get(void)
/**
* It waits for n milli-seconds (more or less). Be carefull to not overflow
* Wait for n milli-seconds (more or less). Be carefull to not overflow
* the 32bits with big delays (in principle you should never use big delays)
* @param[in] n number of milli-seconds to wait
*/
......@@ -293,7 +293,7 @@ static inline void mdelay(unsigned int n)
/**
* It waits for n micro-seconds (more or less). Be carefull to not overflow
* Wait for n micro-seconds (more or less). Be carefull to not overflow
* the 32bits with big delays (in principle you should never use big delays)
* @param[in] n number of micro-seconds to wait
*/
......@@ -306,7 +306,7 @@ static inline void udelay(unsigned int n)
/**
* It generates a notification signal (IRQ) to ask the HOST CPU
* Generate a notification signal (IRQ) to ask the HOST CPU
* to take some action.
* @param[in] id CPU notification identifier
*/
......@@ -317,7 +317,7 @@ static inline void trtl_notify(uint8_t id)
/**
* It generates a notification signal (IRQ) to ask the HOST CPU
* Generate a notification signal (IRQ) to ask the HOST CPU
* to take some action.
* @param[in] id CPU notification identifier
*/
......@@ -333,7 +333,7 @@ static inline void trtl_notify_user(uint8_t id)
/**
* It returns the core ID on which the firmware is running
* Return the core ID on which the firmware is running
* @return the core ID
*/
static inline uint32_t trtl_get_core_id(void)
......@@ -367,7 +367,7 @@ enum trtl_mq_type {
/**
* It gets the Message Queue base address
* Get the Message Queue base address
* @param[in] type MQ type
* @return message queue base address
*/
......@@ -378,7 +378,7 @@ static inline void *trtl_mq_base_address(enum trtl_mq_type type)
/**
* It writes on a Message Queue register
* Write on a Message Queue register
* @param[in] type MQ type to use
* @param[in] val value to write
* @param[in] reg register offset
......@@ -396,7 +396,7 @@ static inline uint32_t mq_readl(enum trtl_mq_type type, uint32_t reg)
/**
* It gets the output slot data field pointer
* Get the output slot data field pointer
* @param[in] type MQ type to use
* @param[in] slot slot number
* @return pointer to the input buffer
......@@ -411,7 +411,7 @@ static inline void *mq_map_out_buffer(enum trtl_mq_type type, int slot)
/**
* It gets the input slot data field pointer
* Get the input slot data field pointer
* @param[in] type MQ type to use
* @param[in] slot slot number
* @return pointer to the input buffer
......@@ -424,7 +424,7 @@ static inline void *mq_map_in_buffer(enum trtl_mq_type type, int slot)
/**
* It gets the output slot header field pointer
* Get the output slot header field pointer
* @param[in] type MQ type to use
* @param[in] slot slot number
* @return pointer to the output header
......@@ -439,7 +439,7 @@ static inline void *mq_map_out_header(enum trtl_mq_type type, int slot)
/**
* It gets the input slot header field pointer
* Get the input slot header field pointer
* @param[in] type MQ type to use
* @param[in] slot slot number
* @return pointer to the input header
......@@ -523,7 +523,7 @@ static inline void mq_discard(enum trtl_mq_type type, int slot)
/**
* It maps a given MQ for outcoming messages
* Map a given MQ for outcoming messages
* @param[in] type MQ type to use
* @param[in] idx_mq MQ index
* @param[out] msg where to map the message
......@@ -538,7 +538,7 @@ static inline void mq_map_out_message(enum trtl_mq_type type,
/**
* It maps a given MQ for incoming messages
* Map a given MQ for incoming messages
* @param[in] type MQ type to use
* @param[in] idx_mq MQ index
* @param[out] msg where to map the message
......@@ -552,9 +552,10 @@ static inline void mq_map_in_message(enum trtl_mq_type type,
}
/**
* It gets the current MQ input status
* Get the current MQ input status
* @param[in] type MQ type to use
* @param[in] mask bitmask to set the bit of interest
* @param[in] mask bitmask to set the bit of interest that corresponds
* to a MQ number
* @return message queues input status bitmask
*/
static inline uint32_t mq_poll_in(enum trtl_mq_type type, uint32_t mask)
......@@ -570,9 +571,10 @@ static inline uint32_t mq_poll_in(enum trtl_mq_type type, uint32_t mask)
}
/**
* It gets the current MQ output status
* Get the current MQ output status
* @param[in] type MQ type to use
* @param[in] mask bitmask to set the bit of interest
* @param[in] mask bitmask to set the bit of interest that corresponds
* to a MQ number
* @return message queues output status bitmask
*/
static inline uint32_t mq_poll_out(enum trtl_mq_type type, uint32_t mask)
......@@ -589,9 +591,10 @@ static inline uint32_t mq_poll_out(enum trtl_mq_type type, uint32_t mask)
/**
* It gets the current MQ input status
* Get the current MQ input status
* @param[in] type MQ type to use
* @param[in] mask bitmask to set the bit of interest
* @param[in] mask bitmask to set the bit of interest that corresponds
* to a MQ number
* @param[in] us_timeout timeout in micro-seconds
* @return message queues input status bitmask, 0 on timeout
*/
......@@ -613,9 +616,10 @@ static inline uint32_t mq_poll_in_wait(enum trtl_mq_type type, uint32_t mask,
/**
* It gets the current MQ input status
* Get the current MQ input status
* @param[in] type MQ type to use
* @param[in] mask bitmask to set the bit of interest
* @param[in] mask bitmask to set the bit of interest that corresponds
* to a MQ number
* @param[in] us_timeout timeout in micro-seconds
* @return message queues input status bitmask, 0 on timeout
*/
......@@ -659,7 +663,7 @@ static inline uint32_t trtl_get_runtime_cycles()
#define TRTL_SMEM_RANGE_BASE 0x00000
/**
* It generates the SHM address range for a given SHM type
* Generate the SHM address range for a given SHM type
*/
#define TRTL_SMEM_TYPE_TO_RANGE(_type) \
(TRTL_SMEM_RANGE_BASE + (_type) * TRTL_SMEM_SIZE)
......@@ -722,7 +726,7 @@ static inline uint32_t trtl_get_runtime_cycles()
/**
* It performs an operations on the shared memory. What the function
* Perform an operations on the shared memory. What the function
* performs can be summerized as:
*
* (*p) = (*p) <operation-type> x
......@@ -743,7 +747,7 @@ static inline void __smem_atomic_op(volatile int *p, int x,
/**
* It performs an
* Perform an
* @copydoc TRTL_SMEM_TYPE_ADD
*
* (*p) = (*p) + x
......@@ -758,7 +762,7 @@ static inline void smem_atomic_add(volatile int *p, int x)
/**
* It performs an
* Perform an
* @copydoc TRTL_SMEM_TYPE_SUB
*
* (*p) = (*p) - x
......@@ -773,7 +777,7 @@ static inline void smem_atomic_sub(volatile int *p, int x)
/**
* It performs an
* Perform an
* @copydoc TRTL_SMEM_TYPE_SET
*
* (*p) = (*p) | x
......@@ -788,7 +792,7 @@ static inline void smem_atomic_or(volatile int *p, int x)
/**
* It performs an
* Perform an
* @copydoc TRTL_SMEM_TYPE_CLR
*
* (*p) = (*p) & (~x)
......@@ -803,7 +807,7 @@ static inline void smem_atomic_and_not(volatile int *p, int x)
/**
* It performs an
* Perform an
* @copydoc TRTL_SMEM_TYPE_FLP
*
* (*p) = (*p) ^ x
......@@ -818,7 +822,7 @@ static inline void smem_atomic_xor(int *p, int x)
/**
* It performs an:
* Perform an:
* @copydoc TRTL_SMEM_TYPE_TST_SET
*
* val = (*p);
......
software/include/mockturtle/hw/mockturtle_addresses.h
View file @ 9e9329d7
......@@ -37,12 +37,12 @@
/**
* It gives a nice pointer to the given register in the dedicated peripheral
* Give a nice pointer to the given register in the dedicated peripheral
*/
#define TRTL_ADDR_DP(_offset) ((void *)(TRTL_ADDR_DP_BASE + (_offset)))
/**
* It gives a nice pointer to the given register in the local register area
* Give a nice pointer to the given register in the local register area
*/
#define TRTL_ADDR_LR(_offset) ((void *)(TRTL_ADDR_LR_BASE + (_offset)))
......
software/include/mockturtle/hw/mockturtle_endpoint.h
View file @ 9e9329d7
/*
* Copyright (C) 2018 CERN (www.cern.ch)
* Copyright (c) 2018-2019 CERN (home.cern)
* Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......
software/include/mockturtle/hw/mockturtle_queue.h
View file @ 9e9329d7
/*
* This work is part of the Mock Turtle project.
*
* Copyright (C) 2013-2014 CERN (www.cern.ch)
* Copyright (c) 2013-2019 CERN (home.cern)
* Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
*
* Released according to the GNU GPL, version 2 or any later version.
......
software/include/mockturtle/libmockturtle.h
View file @ 9e9329d7
/*
* Copyright (C) 2014-2016 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
* inspired by a draft of Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
*
......@@ -25,7 +25,7 @@ extern const unsigned int trtl_default_timeout_ms;
/**
* @struct trtl_dev
* It is obfuscated structure type. This becasue the user should not
* An obfuscated structure type. This is done because the user should not
* modify it but just use it as a token to access the library API.
*/
struct trtl_dev;
......@@ -132,7 +132,7 @@ extern int trtl_cpu_is_enable(struct trtl_dev *trtl, unsigned int index,
unsigned int *enable);
/**
* It disable and re-enable the CPU to perform a restart
* Diable and re-enable the CPU to perform a restart
*/
static inline int trtl_cpu_restart(struct trtl_dev *trtl, unsigned int index)
{
......
software/include/mockturtle/mockturtle.h
View file @ 9e9329d7
/*
* Copyright (C) 2014 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
* SPDX-License-Identifier: BSD-3-Clause
*/
......@@ -38,7 +38,7 @@
/**
* @enum trtl_cpu_notification
* It lists all Mock Turtle notification's code.
* List all Mock Turtle notification's code.
*/
enum trtl_cpu_notification {
TRTL_CPU_NOTIFY_APPLICATION = __TRTL_CPU_NOTIFY_APPLICATION_MAX, /**< anonymous application
......@@ -53,7 +53,7 @@ enum trtl_cpu_notification {
/**
* It enumerates the Mock Turtle message ID.
* Enumerate the Mock Turtle message ID.
* These IDs starts after the user defined ones
*/
enum trtl_msg_id {
......@@ -114,7 +114,7 @@ struct trtl_hmq_header {
#define RT_VERSION(_a, _b) (((_a & 0xFFFF) << 16) | (_b & 0xFFFF))
/**
* It describes the version running on the embedded CPU
* Describe the version running on the embedded CPU
*/
struct trtl_fw_version {
uint16_t rt_id; /**< RT application identifier */
......@@ -238,19 +238,19 @@ struct trtl_msg {
#define TRTL_CONFIG_ROM_MQ_HEADER_MASK 0x000000FF
/**
* It extracts the number of message queue entries from the sizes value
* Extract the number of message queue entries from the sizes value
* in the configuration ROM
*/
#define TRTL_CONFIG_ROM_MQ_SIZE_ENTRIES(_size) (1 << ((_size & TRTL_CONFIG_ROM_MQ_ENTRIES_MASK) >> TRTL_CONFIG_ROM_MQ_ENTRIES_SHIFT))
/**
* It extracts the maximum payload size (32bit words) from the sizes value
* Extract the maximum payload size (32bit words) from the sizes value
* in the configuration ROM
*/
#define TRTL_CONFIG_ROM_MQ_SIZE_PAYLOAD(_size) (1 << ((_size & TRTL_CONFIG_ROM_MQ_PAYLOAD_MASK) >> TRTL_CONFIG_ROM_MQ_PAYLOAD_SHIFT))
/**
* It extracts the maximum header size (32bit words) from the sizes value in
* Extract the maximum header size (32bit words) from the sizes value in
* in the configuration ROM
*/
#define TRTL_CONFIG_ROM_MQ_SIZE_HEADER(_size) (1 << ((_size & TRTL_CONFIG_ROM_MQ_HEADER_MASK) >> TRTL_CONFIG_ROM_MQ_HEADER_SHIFT))
......
software/kernel/mockturtle-compat.c
View file @ 9e9329d7
// SPDX-License-Identifier: GPL-2.0-or-later
/*
* Copyright (C) 2014-2019 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*/
#include <linux/version.h>
......
software/kernel/mockturtle-compat.h
View file @ 9e9329d7
// SPDX-License-Identifier: GPL-2.0-or-later
/*
* Copyright (C) 2014-2016 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*/
......
software/kernel/mockturtle-core.c
View file @ 9e9329d7
/*
* Copyright (C) 2014-2016 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: GPL-2.0-or-later
......@@ -99,7 +99,7 @@ int trtl_minor_get(struct device *dev, enum trtl_dev_type type)
/**
* It releases the char device minor is use by a given device
* Release the char device minor is use by a given device
*/
void trtl_minor_put(struct device *dev)
{
......@@ -115,7 +115,7 @@ void trtl_minor_put(struct device *dev)
/**
* It returns the application ID
* Return the application ID
*/
static ssize_t application_id_show(struct device *dev,
struct device_attribute *attr,
......@@ -127,7 +127,7 @@ static ssize_t application_id_show(struct device *dev,
}
/**
* It returns the number of CPU in the FPGA
* Return the number of CPU in the FPGA
*/
static ssize_t n_cpu_show(struct device *dev,
struct device_attribute *attr,
......@@ -140,7 +140,7 @@ static ssize_t n_cpu_show(struct device *dev,
/**
* It returns the reset status of all CPUs as bitmask
* Return the reset status of all CPUs as bitmask
*/
static ssize_t reset_mask_show(struct device *dev,
struct device_attribute *attr,
......@@ -155,7 +155,7 @@ static ssize_t reset_mask_show(struct device *dev,
}
/**
* It sets the reset status of all CPUs as bitmask
* Set the reset status of all CPUs as bitmask
*/
static ssize_t reset_mask_store(struct device *dev,
struct device_attribute *attr,
......
software/kernel/mockturtle-cpu.c
View file @ 9e9329d7
/*
* Copyright (C) 2014-2016 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: GPL-2.0-or-later
......@@ -86,7 +86,7 @@ static ssize_t notification_history_show(struct device *dev,
{
struct trtl_cpu *cpu = to_trtl_cpu(dev);
ssize_t len;
unsigned int i; /* it must be unsigned for the circ-buffer */
unsigned int i; /* Mut be unsigned for the circ-buffer */
int idx, id;
len = 0;
......@@ -103,7 +103,7 @@ DEVICE_ATTR(notification_history, 0444,
/**
* It returns the CPU reset status
* Return the CPU reset status
*/
static ssize_t reset_show(struct device *dev,
struct device_attribute *attr,
......@@ -119,7 +119,7 @@ static ssize_t reset_show(struct device *dev,
}
/**
* It assert or de-assert the CPU reset line
* Asert or de-assert the CPU reset line
*/
static ssize_t reset_store(struct device *dev,
struct device_attribute *attr,
......@@ -158,7 +158,7 @@ const struct attribute_group *trtl_cpu_groups[] = {
/**
* It loads a given application into the CPU memory
* Load a given application into the CPU memory
*/
static int trtl_cpu_firmware_load(struct trtl_cpu *cpu, void *fw_buf,
size_t count, loff_t off)
......@@ -287,7 +287,7 @@ static int trtl_cpu_simple_open(struct inode *inode, struct file *file)
}
/**
* It writes a given firmware into a CPU
* Write a given firmware into a CPU
*/
static ssize_t trtl_cpu_write(struct file *f, const char __user *buf,
size_t count, loff_t *offp)
......@@ -320,7 +320,7 @@ out_cpy:
}
/**
* It reads the firmware from a CPU
* Read the firmware from a CPU
*/
static ssize_t trtl_cpu_read(struct file *f, char __user *buf,
size_t count, loff_t *offp)
......
software/kernel/mockturtle-dbg.c
View file @ 9e9329d7
/*
* Copyright (C) 2014-2016 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: GPL-2.0-or-later
......@@ -132,7 +132,7 @@ static const struct file_operations trtl_dbg_debugger_ops = {
};
/**
* It creates the debug info file
* Create the debug info file
* @trtl: the mock turtle device instance
*/
void trtl_debugfs_init(struct trtl_dev *trtl)
......@@ -169,7 +169,7 @@ void trtl_debugfs_init(struct trtl_dev *trtl)
/**
* It removes the debug info file
* Remove the debug info file
* @trtl: the mock turtle device instance
*/
void trtl_debugfs_exit(struct trtl_dev *trtl)
......
software/kernel/mockturtle-drv.h
View file @ 9e9329d7
/*
* Copyright (C) 2014-2016 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: GPL-2.0-or-later
......@@ -52,7 +52,7 @@ extern struct class trtl_cdev_class;
/**
* It enumerates the IRQ sources
* Enumerate the IRQ sources
* @TRTL_IRQ_HMQ_IN: incoming messages from soft-CPUs
* @TRTL_IRQ_HMQ_OUT: outgoing messages to soft-CPUs
* @TRTL_IRQ_HMQ_CON: messages in the console
......@@ -132,7 +132,7 @@ struct trtl_hmq_slot {
/**
* It describe the status of a HMQ slot
* Decribe the status of a HMQ slot
* @dev:
* @index: instance number
* @flags: describe the status of the HMQ slot from the driver point of view
......@@ -185,7 +185,7 @@ struct trtl_hmq {
#define TRTL_HMQ_USER_FLAG_SYNC_WAIT BIT(1)
/**
* It describes the consumer of the output slot
* Describe the consumer of the output slot
* @list: to keep it in our local queue
* @hmq: reference to opened HMQ
* @lock: to protect flags, wait_id
......@@ -206,7 +206,7 @@ struct trtl_hmq_user {
/**
* It describes a single instance of a CPU of the TRTL
* Describe a single instance of a CPU of the TRTL
* @index: instance number
* @dev: device representing a single CPU
* @cbuf: debug circular buffer
......@@ -236,7 +236,7 @@ struct trtl_cpu {
#define TRTL_DEV_FLAGS_BIGENDIAN BIT(0)
/**
* It describes the generic instance of a TRTL
* Describe the generic instance of a TRTL
* @
* @dev;
* @cpu: CPU instances
......
software/kernel/mockturtle-hmq.c
View file @ 9e9329d7
/*
* Copyright (C) 2014-2016 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: GPL-2.0-or-later
......@@ -91,7 +91,7 @@ static int trtl_msg_seq_get(struct trtl_dev *trtl)
}
/**
* It is an opaque type. It is used to avoid mistakes when using features
* An opaque type. It is used to avoid mistakes when using features
* that requires the HMQ selection. If you do not provide this type (which is
* provided by the selection function) you will get at least a warning from
* the compiler
......@@ -265,7 +265,7 @@ void trtl_hmq_purge(struct trtl_hmq *hmq)
/**
* It gets the bit number of a HMQ within CSR HMQ registers
* Get the bit number of a HMQ within CSR HMQ registers
* Return: a bit number
*/
static inline uint32_t trtl_hmq_csr_bit(struct trtl_hmq *hmq)
......@@ -283,7 +283,7 @@ static inline uint32_t trtl_hmq_csr_bit(struct trtl_hmq *hmq)
/**
* It enables IRQ for HMQ
* Enable IRQ for HMQ
*
* Internally it locks the HMQ selection spinlock
*/
......@@ -309,7 +309,7 @@ static void trtl_hmq_irq_enable(struct trtl_hmq *hmq, unsigned int is_output)
/**
* It disables IRQ for HMQ
* Disable IRQ for HMQ
*
* Internally it locks the HMQ selection spinlock
*/
......@@ -335,7 +335,7 @@ static void trtl_hmq_irq_disable(struct trtl_hmq *hmq, unsigned int is_output)
/**
* It removes all the data from local buffers and HW slots
* Remove all the data from local buffers and HW slots
* @hmq: the HMQ to flush
*
* Do not use it in interrupt context
......@@ -390,7 +390,7 @@ static bool trtl_hmq_user_filter_one(struct trtl_hmq_user *user,
}
/**
* It clears the content of the HMQ
* Clear the content of the HMQ
*/
static ssize_t discard_all_store(struct device *dev,
struct device_attribute *attr,
......@@ -598,7 +598,7 @@ static int trtl_hmq_release(struct inode *inode, struct file *f)
/**
* It writes a single message from a buffer
* Write a single message from a buffer
* @hmq: HMQ instance destination
* @buf: source buffer
* Return: 0 on success, otherwise a negative error number
......@@ -658,7 +658,7 @@ static int trtl_hmq_write_one(struct trtl_hmq_user *user,
}
/**
* It writes message in the drive message queue. The messages will be sent on
* Write message in the drive message queue. The messages will be sent on
* IRQ signal
*/
static ssize_t trtl_hmq_write(struct file *f, const char __user *buf,
......@@ -759,7 +759,7 @@ static long trtl_hmq_ioctl(struct file *f, unsigned int cmd, unsigned long arg)
/**
* It returns a message to user space messages from an output HMQ
* Return a message to user space messages from an output HMQ
*/
static ssize_t trtl_hmq_read(struct file *f, char __user *ubuf,
size_t count, loff_t *offp)
......@@ -818,7 +818,7 @@ static ssize_t trtl_hmq_read(struct file *f, char __user *ubuf,
/**
* It filters out messages until a valid one
* Filter out messages until a valid one
* @usr: pointer to a user HMQ instance
*/
static void trtl_hmq_user_filter(struct trtl_hmq_user *usr)
......@@ -840,7 +840,7 @@ static void trtl_hmq_user_filter(struct trtl_hmq_user *usr)
}
/**
* It looks into the input and output buffer to see if the user cna take
* Look into the input and output buffer to see if the user cna take
* any action. If the user can write 'POLLOUT', if the user can read 'POLLOUT'
*/
static unsigned int trtl_hmq_poll(struct file *f, struct poll_table_struct *w)
......@@ -874,7 +874,7 @@ const struct file_operations trtl_hmq_fops = {
/**
* It extracts a message from the given HMQ
* Extract a message from the given HMQ
* @hmq: where to get the message from
* @msg: where to store the message
*
......@@ -906,7 +906,7 @@ static void trtl_message_pop(struct trtl_hmq *hmq, struct trtl_msg *msg)
/**
* It extracts a message from the given HMQ and store it in the local buffer
* Extract a message from the given HMQ and store it in the local buffer
* @hmq: where to get the message from
*
* Internally this function locks the local input buffer (spinlock)
......@@ -928,7 +928,7 @@ static void trtl_message_pop_to_buf(struct trtl_hmq *hmq)
}
/**
* It handles an incoming interrupt, messages coming from the soft-CPU
* Handle an incoming interrupt, messages coming from the soft-CPU
*/
static void trtl_irq_handler_input(struct trtl_hmq *hmq)
{
......@@ -956,7 +956,7 @@ static void trtl_irq_handler_input(struct trtl_hmq *hmq)
/**
* It gets the IRQ status for the output HMQ
* Get the IRQ status for the output HMQ
* @trtl: Mock Turtle device instance
*/
static uint64_t trtl_hmq_irq_status_in(struct trtl_dev *trtl)
......@@ -972,7 +972,7 @@ static uint64_t trtl_hmq_irq_status_in(struct trtl_dev *trtl)
/**
* It handles the HMQ interrupts incoming messages from the soft-CPU
* Handle the HMQ interrupts incoming messages from the soft-CPU
*/
irqreturn_t trtl_irq_handler_in(int irq_core_base, void *arg)
{
......@@ -1004,7 +1004,7 @@ dispatch_irq:
/**
* It writes a message to a FPGA HMQ. Note that you have to take
* Write a message to a FPGA HMQ. Note that you have to take
* the HMQ spinlock before call this function
* @hmq: where to send the message
* @msg: the message to send
......@@ -1041,7 +1041,7 @@ static void trtl_message_push(struct trtl_hmq *hmq, struct trtl_msg *msg)
/**
* It injects a message to the given HMQ from the local buffer
* Inject a message to the given HMQ from the local buffer
* @hmq: where to get the message from
*
* Internally this function locks the local output buffer (spinlock)
......@@ -1070,7 +1070,7 @@ static void trtl_message_push_from_buf(struct trtl_hmq *hmq)
/**
* It gets the IRQ status for the input HMQ
* Get the IRQ status for the input HMQ
* @trtl: Mock Turtle device instance
*/
static uint64_t trtl_hmq_irq_status_out(struct trtl_dev *trtl)
......@@ -1086,7 +1086,7 @@ static uint64_t trtl_hmq_irq_status_out(struct trtl_dev *trtl)
/**
* It handles the HMQ interrupts for outgoing messages to the soft-CPU
* Handle the HMQ interrupts for outgoing messages to the soft-CPU
*/
irqreturn_t trtl_irq_handler_out(int irq_core_base, void *arg)
{
......@@ -1146,7 +1146,7 @@ static int trtl_hmq_buf_init(struct mturtle_hmq_buffer *buf)
}
/**
* It initializes and registers a HMQ device
* Initialize and registers a HMQ device
*/
int trtl_probe_hmq(struct trtl_cpu *cpu, unsigned int hmq_idx)
{
......
software/kernel/mockturtle-tty.c
View file @ 9e9329d7
/*
* Copyright (C) 2017 CERN (www.cern.ch)
* Copyright (c) 2017-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: GPL-2.0-or-later
......@@ -41,7 +41,7 @@ static inline void trtl_tty_flip_buffer_push(struct trtl_cpu *cpu)
/**
* trtl_tty_handler_getchar - Get Character From soft-CPU
* It retrieves a character from the soft-CPU serial interface
* Retrieve a character from the soft-CPU serial interface
* and it adds the character to the TTY buffer
* @cpu: the soft-CPU to use
*/
......
software/lib/PyMockTurtle/PyMockTurtle/PyMockTurtle.py
View file @ 9e9329d7
"""
@package docstring
Copyright (c) 201 of the shared memory value with
the given one. In other words it flips the bit in the given value5 CERN
Author: Federico Vaga <federico.vaga@cern.ch>
@copyright: Copyright (c) 2016-2019 CERN (home.cern)
@author: Federico Vaga <federico.vaga@cern.ch>
SPDX-License-Identifier: LGPL-3.0-or-later
"""
......
software/lib/PyMockTurtle/PyMockTurtle/__init__.py
View file @ 9e9329d7
"""
@package docstring
@author: Federico Vaga <federico.vaga@cern.ch>
@copyright: Copyright (c) 2015 CERN
@copyright: Copyright (c) 2016-2019 CERN (home.cern)
@license: GNU Library General Public License version 2 or later
SPDX-License-Identifier: LGPL-3.0-or-later
......
software/lib/libmockturtle-internal.h
View file @ 9e9329d7
/*
* Copyright (C) 2014-2016 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......
software/lib/libmockturtle-rt-msg.c
View file @ 9e9329d7
/*
* Copyright (C) 2014-2016 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: LGPL-3.0-or-later
......@@ -51,7 +51,7 @@ int trtl_fw_version(struct trtl_dev *trtl,
/**
* It checks if firmware core is running and answering to messages
* Check if firmware core is running and answering to messages
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -86,7 +86,7 @@ int trtl_fw_ping_timeout(struct trtl_dev *trtl,
}
/**
* It checks if firmware core is running and answering to messages
* Check if firmware core is running and answering to messages
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -136,7 +136,7 @@ static int __trtl_fw_variable(struct trtl_dev *trtl,
}
/**
* It sends/receive a set of variables to/from the Real-Time application.
* Send/receive a set of variables to/from the Real-Time application.
*
* The 'variables' field data format is the following
*
......@@ -149,7 +149,7 @@ 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 asynchronous. When synchronous the 'variables' field will be
* I 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 synchronous messages to verify that you
......@@ -282,7 +282,7 @@ static int __trtl_fw_buffer(struct trtl_dev *trtl,
}
/**
* It sends/receives a set of structures within TLV records.
* Send/receives a set of structures within TLV records.
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -301,7 +301,7 @@ int trtl_fw_buffer_set(struct trtl_dev *trtl,
/**
* It receives a set of structures within TLV records.
* Receive a set of structures within TLV records.
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -321,7 +321,7 @@ int trtl_fw_buffer_get(struct trtl_dev *trtl,
/**
* It prints the message header in a human readable format
* Print the message header in a human readable format
* @param[in] msg message
*/
void trtl_print_header(struct trtl_msg *msg)
......@@ -341,7 +341,7 @@ void trtl_print_header(struct trtl_msg *msg)
/**
* It prints the payload in a human readable format according
* Print the payload in a human readable format according
* to the message type
* @param[in] msg message
*/
......@@ -400,7 +400,7 @@ void trtl_print_payload(struct trtl_msg *msg)
/**
* It prints a message in a human readable format. This function assumes
* Print a message in a human readable format. This function assumes
* that the message contains a Mock Turtle message header.
* According to the message ID the format may change
* @param[in] msg message
......
software/lib/libmockturtle.c
View file @ 9e9329d7
/*
* Copyright (C) 2014-2016 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
* inspired by a draft of Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
*
......@@ -59,7 +59,7 @@ static int trtl_sysfs_write(char *path, void *buf, size_t len);
/**
* It returns a string messages corresponding to a given error code. If
* Return a string messages corresponding to a given error code. If
* it is not a libtrtl error code, it will run strerror(3)
* @param[in] err error code. Typically 'errno' variable
* @return a message error. No need to free the string.
......@@ -73,7 +73,7 @@ const char *trtl_strerror(int err)
/**
* It initializes the TRTL library. It must be called before doing
* Initialize the TRTL library. It must be called before doing
* anything else. If you are going to load/unload TRTL devices, then
* you have to un-load (trtl_exit()) e reload (trtl_init()) the library.
* @return 0 on success, otherwise -1 and errno is appropriately set
......@@ -95,7 +95,7 @@ int trtl_init(void)
/**
* It releases the resources allocated by trtl_init(). It must be called when
* Release the resources allocated by trtl_init(). It must be called when
* you stop to use this library. Then, you cannot use functions from this
* library anymore.
*/
......@@ -106,8 +106,8 @@ void trtl_exit(void)
/**
* It returns the number of available TRTLs. This is not calculated on demand.
* It depends on library initialization.
* Return the number of available TRTLs. This is not calculated on demand.
* Depend on library initialization.
* @return the number of TRTL available
*/
uint32_t trtl_count()
......@@ -132,7 +132,7 @@ uint32_t trtl_count()
/**
* It allocates and returns the list of available TRTL devices. The user is
* Allocate and return the list of available TRTL devices. The user is
* in charge to free the allocated memory wit trtl_list_free(). The list
* contains trtl_count() + 1 elements. The last element is a NULL pointer.
* @return a list of TRTL device's names. NULL on error
......@@ -167,7 +167,7 @@ char **trtl_list()
/**
* It release the list allocated memory
* Release the list allocated memory
* @param[in] list device list to release
*/
void trtl_list_free(char **list)
......@@ -180,7 +180,7 @@ void trtl_list_free(char **list)
}
/**
* It opens a TRTL device using a string descriptor. The descriptor correspond
* Open a TRTL device using a string descriptor. The descriptor correspond
* to the main char device name of the Mock-Turtle.
* @param[in] device name of the device to open
* @return the TRTL token, NULL on error and errno is appropriately set
......@@ -270,7 +270,7 @@ out_stat:
/**
* It opens a TRTL device using its device_id. The Mock-Turtle
* Open a TRTL device using its device_id. The Mock-Turtle
* driver is based upon the platform bus infrastructure, so all trtl devices are
* identified with their platform id.
* @param[in] device_id device id of the device to use
......@@ -296,7 +296,7 @@ struct trtl_dev *trtl_open_by_id(uint32_t device_id)
/**
* It opens a TRTL device using its Logical Unit Number. The Logical Unit Number
* Open a TRTL device using its Logical Unit Number. The Logical Unit Number
* is an instance number of a particular hardware. The LUN to use is the carrier
* one, and not the mezzanine one (if any).
* The driver is not aware of LUNs but only of device-id. So, if this function does
......@@ -329,7 +329,7 @@ struct trtl_dev *trtl_open_by_lun(unsigned int lun)
/**
* It closes a TRTL device opened with one of the following functions:
* Close a TRTL device opened with one of the following functions:
* trtl_open(), wrcn_open_by_lun(), trtl_open_by_id()
* @param[in] trtl device token
*/
......@@ -458,7 +458,7 @@ static int trtl_sysfs_printf(char *path, const char *fmt, ...)
/**
* It returns the current status of the TRTL CPUs' reset line
* Return the current status of the TRTL CPUs' reset line
* @param[in] trtl device token
* @param[out] mask bit mask of the reset-lines
* @return 0 on success, -1 otherwise and errno is set appropriately
......@@ -497,7 +497,7 @@ int trtl_cpu_reset_set(struct trtl_dev *trtl, uint32_t mask)
/**
* It loads a trtl CPU firmware from a given buffer
* Load a trtl CPU firmware from a given buffer
* @param[in] trtl device token
* @param[in] index CPU index
* @param[in] code buffer containing the CPU firmware binary code
......@@ -544,7 +544,7 @@ int trtl_cpu_load_application_raw(struct trtl_dev *trtl,
/**
* It dumps a TRTL CPU firmware into a given buffer
* Dump a TRTL CPU firmware into a given buffer
* @param[in] trtl device token
* @param[in] index CPU index
* @param[out] code buffer containing the CPU firmware binary code
......@@ -585,7 +585,7 @@ int trtl_cpu_dump_application_raw(struct trtl_dev *trtl,
/**
* It loads a TRTL CPU firmware from a given file
* Load a TRTL CPU firmware from a given file
* @param[in] trtl device token
* @param[in] index CPU index
* @param[in] path path to the firmware file
......@@ -639,7 +639,7 @@ out:
/**
* It dumps a TRTL CPU firmware into a given file
* Dump a TRTL CPU firmware into a given file
* @param[in] trtl device token
* @param[in] index CPU index
* @param[in] path path to the firmware file
......@@ -674,7 +674,7 @@ int trtl_cpu_dump_application_file(struct trtl_dev *trtl,
/**
* It opens a TRTL device
* Open a TRTL device
* @param[in] wdesc device descriptor
* @return 0 on success, -1 on error and errno is set appropriately
*/
......@@ -729,7 +729,7 @@ static int trtl_smem_io(struct trtl_desc *wdesc,
}
/**
* It does a direct acces to the shared memory to read a set of cells
* Direct acces to the shared memory to read a set of cells
* @param[in] trtl device token
* @param[in] addr memory address where start the operations
* @param[out] data values read from in the shared memory. The function will
......@@ -748,7 +748,7 @@ int trtl_smem_read(struct trtl_dev *trtl, uint32_t addr, uint32_t *data,
/**
* It writes on the shared memory of the TRTL
* Write on the shared memory of the TRTL
* @param[in] trtl device to use
* @param[in] addr memory address
* @param[in, out] data values to write in the shared memory. The function will
......@@ -767,7 +767,7 @@ int trtl_smem_write(struct trtl_dev *trtl, uint32_t addr, uint32_t *data,
/**
* It enables a CPU; in other words, it clears the reset line of a CPU.
* Enable 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
......@@ -784,7 +784,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.
* Disable a CPU; in other words, it sets the reset line of a CPU.
* This function is a wrapper of trtl_cpu_reset_set() that allows you to safely
* disable a single CPU.
* @param[in] trtl device token
......@@ -801,7 +801,7 @@ int trtl_cpu_disable(struct trtl_dev *trtl, unsigned int index)
/**
* It checks if the CPU is enabled (or not)
* Check if the CPU is enabled (or not)
* @param[in] trtl device token
* @param[in] index CPU index
* @param[out] enable 1 if the CPU is enable
......@@ -822,7 +822,7 @@ int trtl_cpu_is_enable(struct trtl_dev *trtl, unsigned int index,
/**
* It returns the device name
* Return the device name
* @param[in] trtl device token
* @return the string representing the name of the device
*/
......@@ -835,7 +835,7 @@ char *trtl_name_get(struct trtl_dev *trtl)
/**
* It returns information about the synthesis configuration
* Return information about the synthesis configuration
* @param[in] trtl device token
* @return a pointer to a config structure
*
......@@ -850,7 +850,7 @@ const struct trtl_config_rom *trtl_config_get(struct trtl_dev *trtl)
/**
* It returns the HMQ File Descriptor
* Return the HMQ File Descriptor
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -866,7 +866,7 @@ int trtl_hmq_fd(struct trtl_dev *trtl,
}
/**
* It returns the HMQ File Descriptor
* Return the HMQ File Descriptor
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -899,7 +899,7 @@ static int trtl_msg_read(int fd, struct trtl_msg *msg, unsigned int n)
}
/**
* It reads messages from a given HMQ
* Read messages from a given HMQ
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -942,7 +942,7 @@ static int trtl_msg_write(int fd, struct trtl_msg *msg, unsigned int n)
return (ret / size);
}
/**
* It writes messages to a given HMQ
* Write messages to a given HMQ
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -968,7 +968,7 @@ int trtl_msg_async_send(struct trtl_dev *trtl,
}
/**
* It adds a new filter to the given hmq descriptor
* Add a new filter to the given hmq descriptor
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -985,7 +985,7 @@ int trtl_msg_sync_abort(struct trtl_dev *trtl,
}
/**
* It sends and receives a synchronous message. It is up to the user to set the
* Send and receive a synchronous message. It is up to the user to set the
* "sync_id" in the message that it would like to send.
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
......@@ -1058,7 +1058,7 @@ err:
/**
* It waits for one of a set of Mock Turtle HMQ to become ready to perform I/O
* Wait for one of a set of Mock Turtle HMQ to become ready to perform I/O
* @param[in,out] trtlp specific Mock Turtle poll descriptor
* @param[in] npolls like in poll(2)
* @param[in] timeout like in poll(2)
......@@ -1106,7 +1106,7 @@ int trtl_msg_poll(struct polltrtl *trtlp,
/**
* It flushes the content of an HMQ for both input and output channel
* Flush the content of an HMQ for both input and output channel
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......
software/tools/lsmockturtle.c
View file @ 9e9329d7
/*
* Copyright (C) 2014-2016 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: GPL-3.0-or-later
......@@ -15,14 +15,14 @@
/**
* It prints the help message
* Print the help message
* @param[in] name the program name
*/
static void help(char *name)
{
fprintf(stderr, "\n");
fprintf(stderr, "%s [options]\n\n", name);
fprintf(stderr, "It shows the Mock Turtle devices available on the system.\n\n");
fprintf(stderr, "Show the Mock Turtle devices available on the system.\n\n");
fprintf(stderr, "-v show more information\n");
fprintf(stderr, "-h show this help\n");
fprintf(stderr, "\n");
......@@ -31,7 +31,7 @@ static void help(char *name)
/**
* It shows information about a given Mock Turtle device
* Show information about a given Mock Turtle device
* @param[in] trtl Mock Turtle device instance
*/
static void trtl_list_device_info(struct trtl_dev *trtl)
......
software/tools/mockturtle-buffer.c
View file @ 9e9329d7
/*
* Copyright (C) 2016 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* This program is free software: you can redistribute it and/or modify
......@@ -27,7 +27,7 @@ static void help(char *name)
fprintf(stderr,
"%s -D 0x<hex-number> -i <number> -c <number> -q <number> [read <idx> <size> <idx> <size> ...] [write <idx> <size> <value> ... <value>]\n\n",
name);
fprintf(stderr, "It reads/writes variables on a HMQ\n\n");
fprintf(stderr, "Read/write buffers on a HMQ\n\n");
fprintf(stderr, "-D device identificator in hexadecimal format\n");
fprintf(stderr, "-c CPU core index\n");
fprintf(stderr, "-q HMQ index\n");
......
software/tools/mockturtle-count.c
View file @ 9e9329d7
/*
* Copyright (C) 2014-2016 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: GPL-3.0-or-later
......
software/tools/mockturtle-cpu-restart.c
View file @ 9e9329d7
/*
* Copyright (C) 2014-2016 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: GPL-3.0-or-later
......@@ -16,7 +16,7 @@ static void help()
{
fprintf(stderr, "\n");
fprintf(stderr, "mockturtle-cpu-restart -D 0x<hex-number> -i <number> [options]\n\n");
fprintf(stderr, "It restarts a set of given CPUs");
fprintf(stderr, "Restart a set of given CPUs\n");
fprintf(stderr, "-D device identificator in hexadecimal format\n");
fprintf(stderr, "-i cpu index\n");
fprintf(stderr, "-h show this help\n");
......
software/tools/mockturtle-gdbserver.c
View file @ 9e9329d7
// SPDX-License-Identifier: GPL-3.0-or-later
/*
* Copyright (C) 2019 CERN (www.cern.ch)
* Copyright (c) 2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*/
......
software/tools/mockturtle-loader.c
View file @ 9e9329d7
/*
* Copyright (C) 2015-2016 CERN (www.cern.ch)
* Copyright (c) 2015-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: GPL-3.0-or-later
......@@ -17,7 +17,7 @@ static void help()
{
fprintf(stderr, "\n");
fprintf(stderr, "mockturtle-loader -D 0x<hex-number> -i <number> -f <path> [options]\n\n");
fprintf(stderr, "It loads (or dumps) an application to a Mock-Turtle internal CPU\n\n");
fprintf(stderr, "Load (or dump) an application to a Mock-Turtle internal CPU\n\n");
fprintf(stderr, "-D device identificator\n");
fprintf(stderr, "-i CPU index\n");
fprintf(stderr, "-f path to the binary to load. If the option '-d' is set, then\n");
......
software/tools/mockturtle-messages.c
View file @ 9e9329d7
/*
* Copyright (C) 2015-2016 CERN (www.cern.ch)
* Copyright (c) 2015-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: GPL-3.0-or-later
......@@ -41,7 +41,7 @@ static void help()
{
fprintf(stderr, "\n");
fprintf(stderr, "mockturtle-messages [options]\n\n");
fprintf(stderr, "It dumps all messages from a given set of Mock-Turtle slots\n\n");
fprintf(stderr, "Dump all messages from a given set of Mock-Turtle slots\n\n");
fprintf(stderr, "-q message queue selection string\n\t0x<devid>,<cpu>,<hmq>,<n>\n");
fprintf(stderr, "-t print message timestamp\n");
fprintf(stderr, "-p parse protocol\n");
......@@ -56,7 +56,7 @@ static void help()
/**
* It retreives a message from a given slots and it prints its content
* Retreive a message from a given slots and it prints its content
* @param[in] trtl device to use
* @param[in] hmq slot to read
*/
......
software/tools/mockturtle-ping.c
View file @ 9e9329d7
/*
* Copyright (C) 2014-2016 CERN (www.cern.ch)
* Copyright (c) 2014-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* This program is free software: you can redistribute it and/or modify
......@@ -24,7 +24,7 @@
/**
* It prints the help message
* Print the help message
* @param[in] name the program name
*/
static void help(char *name)
......@@ -41,7 +41,7 @@ static void help(char *name)
/**
* It prints the given Mock Turtle firmware version
* Print the given Mock Turtle firmware version
* @param[in] v version to print
*/
static void trtl_ping_version_print(struct trtl_fw_version *v)
......
software/tools/mockturtle-smem.c
View file @ 9e9329d7
/*
* Copyright (C) 2015-2016 CERN (www.cern.ch)
* Copyright (c) 2015-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* SPDX-License-Identifier: GPL-3.0-or-later
......
software/tools/mockturtle-variable.c
View file @ 9e9329d7
/*
* Copyright (C) 2016 CERN (www.cern.ch)
* Copyright (c) 2016-2019 CERN (home.cern)
* Author: Federico Vaga <federico.vaga@cern.ch>
*
* This program is free software: you can redistribute it and/or modify
......@@ -27,7 +27,7 @@ static void help(char *name)
fprintf(stderr,
"%s -D 0x<hex-number> -c <number> -q <number> [write <idx> <value> <idx> <value> ...] [read <idx> <idx> ...]\n\n",
name);
fprintf(stderr, "It reads/writes variables on a HMQ\n\n");
fprintf(stderr, "Read/write variables on a HMQ\n\n");
fprintf(stderr, "-D device identificator in hexadecimal format\n");
fprintf(stderr, "-c CPU core index\n");
fprintf(stderr, "-q HMQ index\n");
......
software/tools/trtl-project-creator/templates/software/lib/libproject.c
View file @ 9e9329d7
......@@ -19,7 +19,7 @@ static const char *{{short_name}}_errors[] = {
/**
* It returns a string messages corresponding to a given error code. If
* Return a string messages corresponding to a given error code. If
* it is not a libwrtd error code, it will run trtl_strerror()
* @param[in] err error code
* @return a message error
......@@ -35,7 +35,7 @@ const char *{{short_name}}_strerror(unsigned int err)
/**
* It initializes the {{name}} library. It must be called before doing
* Initialize the {{name}} library. It must be called before doing
* anything else.
* This library is based on the libmockturtle, so internally, this function also
* run trtl_init() in order to initialize the Mock Turtle library.
......@@ -54,7 +54,7 @@ int {{short_name}}_init()
/**
* It releases the resources allocated by {{short_name}}_init(). It must be called when
* Release the resources allocated by {{short_name}}_init(). It must be called when
* you stop to use this library. Then, you cannot use functions from this
* library.
*/
......@@ -92,7 +92,7 @@ out:
/**
* It closes a {{name}} device opened with one of the following function:
* Close a {{name}} device opened with one of the following function:
* {{short_name}}_open_by_id()
* @param[in] dev device token
*/
......@@ -107,7 +107,7 @@ void {{short_name}}_close(struct {{short_name}}_node *dev)
/**
* It returns the Mock Turtle token in order to allows users to run
* Return the Mock Turtle token in order to allows users to run
* functions from the Mock Turtle library
* @param[in] dev device token
* @return the Mock Turtle token
......
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