Skip to content

M
mock-turtle
Commit 262ab999 authored by Federico Vaga's avatar Federico Vaga
Browse files
Options

doc: re-order chapters 

It includes also some minor modifications
Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>
parent b91f6964
Hide whitespace changes
Inline Side-by-side
Showing with 169 additions and 177 deletions
doc/hdl/index.rst
View file @ 262ab999
......@@ -69,7 +69,7 @@ configuration of the MT. Configurable aspects of the MT include:
- Number and dimensions of host and remote message queues per CPU
Details about the meaning of the fields of this VHDL record can also be found in
:ref:`the-mock-turtle-architecture`.
:ref:`arch`.
VHDL Configuration Record
-------------------------
......
doc/index.rst
View file @ 262ab999
......@@ -10,14 +10,13 @@ Welcome to Mock Turtle's documentation!
:maxdepth: 1
:caption: Contents:
glossary
introduction
architecture
software/index
hdl/index
software/index
tools/index
demos/index
glossary
Indices and tables
==================
......
doc/software/index-fw.rst 0 → 100644
View file @ 262ab999
.. _`sw:fw`:
======================
Firmware Development
======================
This section explains how to write firmwares using the Mock Turtle API.
The Mock Turtle offers 2 API for the firmware development:
:ref:`sw:fw:lib` and :ref:`sw:fw:frm`.
.. graphviz::
:align: center
:caption: Mock Turtle Firmware Interfaces.
digraph layers {
concentrate=true;
node [shape=rectangle, style=filled, penwidth=2];
edge [dir=both]
mt [shape=record, label="<f> framework | <l> library", fillcolor=lightblue, color=blue];
usr [label="user firmware", fillcolor=lightgrey, color=gray];
mt:f -> usr;
mt:l -> usr;
}
It is strongly recommended to use the library because it offers a set of
macros and functions that simplifies the access to Mock Turtle
resources and to external gateware cores. This will help mainly in
firmware development.
It is recommended to use the framework because it guides you in the
development by keeping you focused only on your core logic without the
need to deal with Mock Turtle architecture details.
The framework usage, rather than precluding the user to use library
functions, is complementary to the library.
Of course, this framework provides more features and features cost space
and computation time. If you need more space (and you can't allocate more
memory) or you need much better performances: don't use this framework.
All the Mock Turtle firmware source code can be found in the directory
``/path/to/mockturtle/software/firmware/``.
Building
========
Mock Turtle has a generic ``Makefile`` that you should include in your
``Makefile`` in order to import all the Mock Turtle building rules.::
TRTL ?= /path/to/mcokturtle/
TRTL_SW = $(TRTL)/software
# Mandatory
OBJS = source1.o
OBJS += source2.o
OBJDIR += some/local/directory
OUTPUT = firmware-name
# Optional (prefer default when possible)
CFLAGS_OPT := -O1
CFLAGS_DBG := -ggdb
EXTRA_CFLGAS :=
MOCKTURTLE_LDSCRIPT := myfirmware.ld
# INCLUDE GENERIC Makefile
include $(TRTL_SW)/firmware/Makefile
Here the list of supported Makefile environment 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
will not compile any source file.
OUTPUT
(Mandatory) Final binary name (the firmware).
MOCKTURTLE_LDSCRIPT
(Optional ) Local path to the linker script.
The default is the standard Mock Turtle linker script.
Memory resources on Mock Turtle are very limited and the full framework
may take more space than needed. For this reason Mock Turtle has
*Kconfig* support which allows you to interactivly enable/disable both
library and framework. You should create a local ``Kconfig`` file in
your firmware directory; in this file you must include the generic
one from Mock Turtle.::
mainmenu "Project Firmware Name"
comment "Project specific configuration"
# INCLUDE GENERIC Kconfig
source "Kconfig.mt"
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
``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
.. toctree::
:maxdepth: 2
:caption: Contents:
firmware-library
firmware-framework
doc/software/index-lnx.rst 0 → 100644
View file @ 262ab999
.. _`sw:lnx`:
====================
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
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.
.. graphviz::
:align: center
:caption: Mock Turtle Linux Interfaces.
digraph layers {
concentrate=true;
node [shape=rectangle, style=filled, penwidth=2];
edge [dir=both]
mt [shape=record, label="<d> driver | <l> library | <p> python", fillcolor=lightblue, color=blue];
usr [label="programs", fillcolor=lightgrey, color=gray];
usr -> mt:d [style=dotted, color=dimgrey];
usr -> mt:l;
usr->mt:p;
}
.. toctree::
:maxdepth: 2
:caption: Contents:
linux-driver
linux-library
linux-python
doc/software/index.rst
View file @ 262ab999
......@@ -49,176 +49,5 @@ development of firmware development.
:caption: Contents:
protocol
.. _`sw:lnx`:
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
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.
.. graphviz::
:align: center
:caption: Mock Turtle Linux Interfaces.
digraph layers {
concentrate=true;
node [shape=rectangle, style=filled, penwidth=2];
edge [dir=both]
mt [shape=record, label="<d> driver | <l> library | <p> python", fillcolor=lightblue, color=blue];
usr [label="programs", fillcolor=lightgrey, color=gray];
usr -> mt:d [style=dotted, color=dimgrey];
usr -> mt:l;
usr->mt:p;
}
.. toctree::
:maxdepth: 2
:caption: Contents:
linux-driver
linux-library
linux-python
.. _`sw:fw`:
Firmware Development
====================
This section explains how to write firmwares using the Mock Turtle API.
The Mock Turtle offers 2 API for the firmware development:
:ref:`sw:fw:lib` and :ref:`sw:fw:frm`.
.. graphviz::
:align: center
:caption: Mock Turtle Firmware Interfaces.
digraph layers {
concentrate=true;
node [shape=rectangle, style=filled, penwidth=2];
edge [dir=both]
mt [shape=record, label="<f> framework | <l> library", fillcolor=lightblue, color=blue];
usr [label="user firmware", fillcolor=lightgrey, color=gray];
mt:f -> usr;
mt:l -> usr;
}
It is strongly recommended to use the library because it offers a set of
macros and functions that simplifies the access to Mock Turtle
resources and to external gateware cores. This will help mainly in
firmware development.
It is recommended to use the framework because it guides you in the
development by keeping you focused only on your core logic without the
need to deal with Mock Turtle architecture details.
The framework usage, rather than precluding the user to use library
functions, is complementary to the library.
Of course, this framework provides more features and features cost space
and computation time. If you need more space (and you can't allocate more
memory) or you need much better performances: don't use this framework.
All the Mock Turtle firmware source code can be found in the directory
``/path/to/mockturtle/software/firmware/``.
.. toctree::
:maxdepth: 2
:caption: Contents:
firmware-library
firmware-framework
Building
--------
Mock Turtle has a generic ``Makefile`` that you should include in your
``Makefile`` in order to import all the Mock Turtle building rules.::
TRTL ?= /path/to/mcokturtle/
TRTL_SW = $(TRTL)/software
# Mandatory
OBJS = source1.o
OBJS += source2.o
OBJDIR += some/local/directory
OUTPUT = firmware-name
# Optional (prefer default when possible)
CFLAGS_OPT := -O1
CFLAGS_DBG := -ggdb
EXTRA_CFLGAS :=
MOCKTURTLE_LDSCRIPT := myfirmware.ld
# INCLUDE GENERIC Makefile
include $(TRTL_SW)/firmware/Makefile
Here the list of supported Makefile environment 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
will not compile any source file.
OUTPUT
(Mandatory) Final binary name (the firmware).
CFLAGS_OPT
(Optional) Optimization level. The default is ``-Os``.
CFLAGS_DBG
(Optional). Debug information. The default is ``-ggdb``.
EXTRA_CFLAGS
(Optional) Extra compiler flags. The default is an empty string,
so no extra flags.
MOCKTURTLE_LDSCRIPT
(Optional ) Local path to the linker script.
The default is the standard Mock Turtle linker script.
Memory resources on Mock Turtle are very limited and the full framework
may take more space than needed. For this reason Mock Turtle has
*Kconfig* support which allows you to interactivly enable/disable both
library and framework. You should create a local ``Kconfig`` file in
your firmware directory; in this file you must include the generic
one from Mock Turtle.::
mainmenu "Project Firmware Name"
comment "Project specific configuration"
# INCLUDE GENERIC Kconfig
source "Kconfig.mt"
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
``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
index-lnx
index-fw
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