Skip to content

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

doc:sw: mixed improvement 

Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>
parent a0257014
Hide whitespace changes
Inline Side-by-side
Showing with 64 additions and 36 deletions
doc/software/firmware-library.rst
View file @ cc017e8d
...@@ -104,8 +104,8 @@ All these functions are based on the generic :c:func:`readl()` and ...@@ -104,8 +104,8 @@ All these functions are based on the generic :c:func:`readl()` and
.. doxygenfunction:: writel .. doxygenfunction:: writel
Message Queue Utilities Message Queue
======================= ================
Mock Turtle cores' main communication mechanism is the message queues. Mock Turtle cores' main communication mechanism is the message queues.
The API is almost identical for both remote and host because most of these The API is almost identical for both remote and host because most of these
...@@ -354,8 +354,8 @@ Mock Turtle will deliver a notification to the host when the firmware calls ...@@ -354,8 +354,8 @@ Mock Turtle will deliver a notification to the host when the firmware calls
.. doxygenfunction:: trtl_notify_user .. doxygenfunction:: trtl_notify_user
Miscellaneous Utilities Miscellaneous
======================= ==============
At the end, this chapter is a collection of helpers At the end, this chapter is a collection of helpers
......
doc/software/index.rst
View file @ cc017e8d
...@@ -204,3 +204,21 @@ one from Mock Turtle.:: ...@@ -204,3 +204,21 @@ one from Mock Turtle.::
Configuration options are not documented here. For more details Configuration options are not documented here. For more details
use the help messages from Kconfig: run ``make menuconfig`` use the help messages from Kconfig: run ``make menuconfig``
from your firmware directory. 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
``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
the case you have to overwrite this variable.::
export CROSS_COMPILE_TARGET=/path/to/toolchain/bin/riscv32-elf-
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
`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
doc/software/linux-driver.rst
View file @ cc017e8d
...@@ -99,8 +99,8 @@ notification IRQ ...@@ -99,8 +99,8 @@ notification IRQ
The Linux IRQ number to use for Mock Turtle cores notifications. The Linux IRQ number to use for Mock Turtle cores notifications.
Since not all developer knows how to write such module, you can use the Since not all developer knows how to write such module, you can use the
*platform-device-loader*. This application is part of the CERN BE-CO-HT tools *platform-device-loader* [2]_. This application is part of the CERN BE-CO-HT tools
collection. collection, you may need special permission to access the repository.
If you are not sure about how to write the Linux module to load your If you are not sure about how to write the Linux module to load your
platform device, consider to have a look at the source code templates platform device, consider to have a look at the source code templates
...@@ -262,14 +262,20 @@ You can find the HMQ *sysfs* attributes at:: ...@@ -262,14 +262,20 @@ You can find the HMQ *sysfs* attributes at::
- RO - RO
- Total number of messages sent through the HMQ channel - Total number of messages sent through the HMQ channel
.. [1] https://www.kernel.org/doc/Documentation/driver-model/platform.txt
Debugging Interface Debugging Interface
------------------- -------------------
The driver exports on debugfs a file in YAML format which contains status The driver exports on debugfs a file in YAML format which contains internal
information: variable values, register values. This file is named as information about the driver: variable values, register values. This file is named as
the Mock Turtle instance that represents "trtl-%04x".:: the Mock Turtle instance that represents "trtl-%04x".::
mount -t debugfs none /sys/kernel/debug
cat /sys/kernel/debug/trtl-0001/info 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.
.. [1] https://www.kernel.org/doc/Documentation/driver-model/platform.txt
.. [2] https://gitlab.cern.ch/cohtdrivers/coht-tools/tree/master/drivers/platform-device-loader
doc/software/linux-library.rst
View file @ cc017e8d
...@@ -45,34 +45,24 @@ visible to your programs/libraries:: ...@@ -45,34 +45,24 @@ visible to your programs/libraries::
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/mockturtle/software/lib $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/mockturtle/software/lib
The CPU Management In order to include this library in your project you must include in your
================== source code:::
The Mock Turtle Linux library has a set of functions dedicated to #include <libmockturtle.h>
CPU management. This means to be able to:
- load a binary into the memory of a soft-CPU While in the compilation command you have to provide the following options
(e.g. GCC):::
- dump the memory of a soft-CPU CC = /path/to/your/compiler
CFLAGS += -I/path/to/mockturtle/software/lib
- start/stop a soft-CPU CFLAGS += -I/path/to/mockturtle/software/include
CFLAGS += -L/path/to/mockturtle/software/lib
- reset/unreset a soft-CPU LDLIBS += -lmockturtle
$(CC) $(CFLAGS) $(LDLIBS)
The typical use of these functions is to load an executable file into
the soft-CPU. The following listing shows an example
.. highlight:: c
.. code:: c
void progr_cpu(struct trtl_dev *trtl, unsigned int cpu_idx, char *file_name)
{
trtl_cpu_load_application_file(trtl, cpu_idx, file_name);
trtl_cpu_enable(trtl, cpu_idx);
}
.. highlight:: none
The example above assumes that you are compiling from the Mock Turtle
git repository or a copy of it; if on your environment libraries and header
files are in different location, then fix the above code accordingly.
Initialization Initialization
============== ==============
...@@ -111,6 +101,20 @@ Mock Turtle Cores Management ...@@ -111,6 +101,20 @@ Mock Turtle Cores Management
Library support for cores' management is limited to the firmware loading Library support for cores' management is limited to the firmware loading
(dumping) and core enable/disable. (dumping) and core enable/disable.
The typical use of these functions is to load an executable file into
the soft-CPU. The following listing shows an example
.. highlight:: c
.. code:: c
void progr_cpu(struct trtl_dev *trtl, unsigned int cpu_idx, char *file_name)
{
trtl_cpu_load_application_file(trtl, cpu_idx, file_name);
trtl_cpu_enable(trtl, cpu_idx);
}
.. highlight:: none
.. doxygenfunction:: trtl_cpu_load_application_raw .. doxygenfunction:: trtl_cpu_load_application_raw
.. doxygenfunction:: trtl_cpu_dump_application_raw .. doxygenfunction:: trtl_cpu_dump_application_raw
......
doc/tools/index.rst
View file @ cc017e8d
...@@ -6,7 +6,7 @@ The Mock Turtle Tools ...@@ -6,7 +6,7 @@ The Mock Turtle Tools
This section describes the Mock Turtle tools. The description is limited This section describes the Mock Turtle tools. The description is limited
to the main purpose of the tool, for more details use the tool’s help to the main purpose of the tool, for more details use the tool’s help
message. message. All tools are available in the directory *software/tools*.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
......
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