Commit 7def053c authored by Oliver Horst's avatar Oliver Horst
Browse files

[chg] Started to update and improve the documentation

parent 00a2911c
## Introduction to toki
toki, Japanese for "when an action occurs", is a build- and test-environment constructed around the real-time operating system FreeRTOS. toki's main goal is to compose an easy to use rapid prototyping platform to develop and evaluate new operating system and inter-task communication concepts for embedded and cyber-physical systems on commodity micro controller hardware. Therefore, toki combines the following open-source projects into a unified build system:
* [FreeRTOS v10.x](https://www.freertos.org/)
* [newlib vX.Y](https://sourceware.org/newlib/)
* [FreeRTOS v10.0.0](https://www.freertos.org/)
* [newlib v3.0.0](https://sourceware.org/newlib/)
* [libXil v2019.1](https://github.com/Xilinx/embeddedsw/tree/release-2019.1)
* [libXilPm v2019.1](https://github.com/Xilinx/embeddedsw/tree/release-2019.1)
* [lwIP v2.x](https://savannah.nongnu.org/projects/lwip/)
* [lwIP v2.1.2](https://savannah.nongnu.org/projects/lwip/)
* [ESFree Scheduling Library](https://github.com/RobinK2/ESFree)
* [HST User Mode Scheduler](https://github.com/fepz/hst)
* [TACLe Benchmarks](https://github.com/tacle/tacle-bench)
* [PTPd - Precision Time Protocol Daemon](https://github.com/ptpd/ptpd)
All components of the toki platform were chosen under the aspect of simplicity and easiness of modifications and extensions to the code base. A special attention was put on the fact that the utilized components, on the one hand, closely mimic the software stacks found in comparable industrial systems, and on the other hand still do not impede the prototypical realization of ideas with conceptional obstacles. Hence, the operating system of choice is FreeRTOS, a widely supported, well documented, and industry ready real-time operating system, which is also available in a safety certified version SafeRTOS.
All components of the toki platform were chosen under the aspect of simplicity and easiness of modifications and extensions to the code base. A special attention was put on the fact that the utilized components, on the one hand, closely mimic the software stacks found in comparable industrial systems, and on the other hand still do not impede the prototypical realization of ideas with conceptional obstacles. Hence, the operating system of choice is FreeRTOS, a widely supported, well documented, and industry ready real-time operating system, which is also available in the safety certified version SafeRTOS.
At the overall platform level, the toki build-system is utilizing Yocto to provide a self contained build environment that not only produces the final image that can be used to flash the actual hardware platform, but also all of its dependencies, such as a GCC cross-compiler. At the project level, the source code of the contained open-source projects was restructured and extended with a CMake based build-system to support include prefixes, where needed. This reconstruction is conducted in an automatic fashion by a dedicated restructuring script, to allow fetches of upstream changes. More details on the restructuring process and the script behind it are discussed in the section ['The toki helper scripts'](#toki-scripts). In addition, the generated cross-compiler together with a CMakeToolchain file, both provided by Yocto, and an additional top-level CMake file allow you to enable full code insight and debugging capabilities within the IDE of your choice.
......@@ -25,143 +26,114 @@ Besides the changes made to support an integrated build environment for the soft
The aforementioned toki build-environment is seamlessly integrated with a test-environment based on QEMU. All images built with Yocto in the toki build environment can either be run directly on the target hardware via flashing an SD card, or emulated and debugged via QEMU and its GDB stub support. The Yocto based build-environment already provides you with an adequate built of QEMU.
Currently, the toki build- and test-environment is solely targeted at the [Xilinx Zynq UltraScale+ MPSoC ZCU102 Evaluation Kit](), a contemporary ARMv8 multi-core SoC with an integrated FPGA. Nevertheless, toki was designed with portability in mind, hence, it can easily be ported to other target platforms, such as [XXX by STmicro](). The Xilinx ZCU102 evaluation kit was chosen as the designated toki hardware platform, due to the fact that Xilinx provides a bare-metal board support package with drivers for all integrated peripherals, and the integrated FPGA allows to extend the hardware for instance to support a more accurate performance evaluation of the system.
Currently, the toki build- and test-environment is solely targeted at the [Xilinx Zynq UltraScale+ MPSoC ZCU102 Evaluation Kit](), a contemporary ARMv8 multi-core SoC with an integrated FPGA. The Xilinx ZCU102 evaluation kit was chosen as the designated toki hardware platform, due to the fact that Xilinx provides a bare-metal board support package with drivers for all integrated peripherals, and the integrated FPGA allows to extend the hardware for instance to support a more accurate performance evaluation of the system. Nevertheless, toki was designed with portability in mind, hence, it can easily be ported to other target platforms that provide the necessary bare-metal drivers, such as the [STM32 series by STmicro](https://www.st.com/en/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus.html).
## <a name="toki-setup"></a> Setting up your own toki build- and test-environment
To use toki, the following dependencies need to be installed on your system:
To use toki, the following dependencies need to be installed on your system.
##### Required System Packages
* curl
* chrpath
* dialog
* gawk
* git
* python3 >= 3.6
* python3-pip
* repo
* repo >= 2.8
* texinfo
Python/pip dependencies:
##### Required Python/PIP Packages
* automat
* pythondialog
* mako
* in_place
* mako
* pythondialog
* urllib3
Bitbake dependencies:
* chrpath
* gawk
* texinfo
##### Install toki's Requirements on Ubuntu
For Ubuntu based systems, please run:
On Ubuntu based systems you can install all required dependencies by running:
```bash
$ sudo apt-get install curl dialog git python3 python3-pip repo chrpath gawk texinfo
$ sudo pip3 install automat pythondialog mako in_place urllib3
```
To prepare the setup you shall furthermore obtain a personal access token from GitLab with at least 'api' and 'read_repository' access rights. This token is needed in the following steps of the setup process.
The actual setup of the toki build- and test-environment is conducted by an automatic setup script. Please download and execute the script by executing:
Unfortunately, Ubuntu up to 19.10 ships a too old version of Google's repo tool. Hence, you need to manually install it with the help of the following commands:
```bash
$ bash <(curl -s --request GET --header 'PRIVATE-TOKEN: [YOUR PRIVATE TOKEN]' 'https://git.fortiss.org/api/v4/projects/1245/repository/files/scripts%2Ftoki-setup/raw?ref=master')
$ sudo mkdir -p /usr/local/bin
$ sudo curl https://storage.googleapis.com/git-repo-downloads/repo > /usr/local/bin/repo
$ sudo chmod a+rx /usr/local/bin/repo
```
The script will download and setup the toki build- and test-environment within the folder you are executing it in, it will guide you through the setup process. The script will ask you to provide once again your personal GitLab access token, to clone all repositories, this token will be stored in a file called 'secrets.txt' (only accessible by your user) for future calls to the toki helper scripts.
Currently, Yocto only supports Ubuntu based systems and thus toki copies this requirement. We've successfully tested toki on top Ubuntu 16.04 (xenial) and Ubuntu 18.04 (bionic). Nevertheless, toki also supports other distributions through the means of a tailored Docker container. Please read the section ['toki on non Ubuntu distributions'](#toki-docker) for details on how-to setup the Docker container for toki on your system.
In the next section ['toki folder structure'](#toki-folders), the folder structure created by the setup script is explained. Section ['How-to use toki'](#toki-usage) continues with instructions on how-to use toki and Section ['Setting up your IDE for toki'](#toki-ide) provides you with an insight on how-to setup your IDE for developing and debugging with toki.
## <a name="toki-folders"></a> toki folder structure
The top-level folder of the toki build environment is divided into nine sub-folders: _build, applications, auxiliary, build-systems, components, configs, deployments, hardware, init. All individual sub-folders and there purpose are explained below.
##### Install toki
##### _build
To prepare the installation of toki you need to obtain a personal access token from GitLab with at least 'api' and 'read_repository' access rights. This token is needed in the following steps of the setup process and referred to as ``<PRIVATE_TOKEN>``.
The build folder contains all build related, temporary files for both build systems CMake and Yocto. It is safe to delete all files underneath this folder, however, as this induces a re-initialization of the Yocto build environment, we advise you to use the reset functionality of the toki setup script instead. It will delete all temporary files, except for the downloaded external sources and correctly set up the Yocto environment again. Just run the following command from within your toki environment:
The actual installation of the toki build- and test-environment is conducted by an automatic setup script. Please download and execute the script by executing the following command:
```bash
$ toki-setup-build-env.sh --reset
$ bash <(curl -s --request GET --header 'PRIVATE-TOKEN: <PRIVATE_TOKEN>' 'https://git.fortiss.org/api/v4/projects/1245/repository/files/scripts%2Ftoki-setup/raw?ref=master') --token <PRIVATE_TOKEN> <INSTALLATION_DIR>
```
There are three sub-folders located within the '_build' folder. 'cmake' and 'yocto' do keep the build specific files of the two build systems, and 'yocto_downloads' keeps all downloaded external sources required by the Yocto build process.
##### applications
This folder contains all user-level applications build for the toki runtime platform. This is the place where code should go that uses the toki platform from a user-level perspective. Hence, this is also the main place non system developers have to interact with.
The section ['How-to extend toki'](#toki-extension) provides you with instructions on how-to integrate new applications, i.e., user code, with the existing toki build system. The applications that are part of the final image, created by the Yocto build system, are selected with the toki-config script. More details on the usage of this script are provided in the section ['Configure your own deployment'](#toki-deployment-config).
##### auxiliary
Here all auxiliary helper scripts are located. Non toki maintainers hopefully do not need to edit any of these files. More details on the available toki helper scripts and their usage are given by the dedicated section ['The toki helper scripts'](#toki-scripts) on that topic.
##### build-systems
Within the sub-folders of the build-systems folder you find all files related to the two build systems used by toki: CMake and Yocto. The cmake sub-folder mainly contains a single top-level CMakeLists.txt and some auxiliary files needed by that CMakeLists.txt to build the overall toki platform with CMake. The sub-folder yocto, on the other hand, contains several sub-folders one for each Yocto layer used by the toki build, as well as Yocto's poki distribution itself. You find all toki specific recipes under build-systems/yocto/meta-toki and build-systems/yocto/meta-toki-xilinx. The section ['How-to extend toki'](#toki-extension) provides you with the necessary information to extend those two layers in case you want to integrate your own software components within toki. Apart from that it is hopefully not necessary to change any of the other, non toki, layers.
##### components
The components folder contains all software components that are part of the toki platform, each one located in its own sub-folder. At the moment of writing these are:
* freertos
* freertos+
* libxil
* libxilsecure
* libxilpm
* lwip
* newlib
##### configs
The configs folder holds all header files and generated source files for each of the components that needs it. The configs are clustered according to their target machine, configuration type, and whether they are designated for a master or slave core. Furthermore, the configs also hold the linker script used to produce the final executables for the target hardware platform. By a rule of thumb, the configs folder contains everything that configures, i.e., changes the behavior, of the software components found in the toki build tree. The flexibility introduced by these dedicated configuration files ensures that multiple deployments can be build and tested with one toki environment.
The configs are organized in sub-folders with respect to the machine they are intended for, their specific name, and whether the configuration is intended for a master- or slave-core.
Currently, toki comes with one example configuration, the baseline configuration, which provides a detailed description of every option in the header files. It provide users of toki with the necessary understanding to adapt the existing configuration or create their own one.
A speciality among the configurations is the linker script (ldscript). The linker script is provided as an interface link library that specifies specific link dependencies, which introduce the correct linker script parameters for the final linker step. This way the linker script can be propagated through the whole dependency stack up to the image creation, without fixing the linker script within the toolchain file, but rather bind it to a specific configuration.
##### deployments
In addition to the software configuration provided in the configs folder, different toki images might also want to include different software components in the first place. This can be achieved by specifying toki deployment configurations in form of JSON files. The deployments folder holds these deployment configurations. They specify which software in which configuration should run on which core and with which hardware configuration shall it be deployed within the final image. The deployment configurations in the deployments folder are grouped into sub-folders with respect to the machine they apply to. Below the machine level, they can be further organized into arbitrary sub-folders.
To assist in creating such deployment configuration, toki provides you with the toki-config tool, which is discussed in the section ['Configure your own deployment'](#toki-deployment-config). The toki build-system can cope with a various number of deployment configurations, to support a systematic evaluation of for instance different software configurations or configuration parameters. A deployment configuration can be marked as active for a certain build with the help of the toki-config tool.
##### hardware
This folder is dedicated to hardware specific additions to the toki platform. In case of the zcu102-zynqmp machine/platform, this folder contains different FPGA images and their associated Vivado design files.
This command also accepts ``--manifest-branch <MANIFEST_BRANCH>`` as parameter to indicate a certain toki manifest branch you would like to work with. A list of valid manifest branches can be obtained with the following command:
```bash
$ git ls-remote --heads https://git.fortiss.org/toki/manifests 2>/dev/null | grep -Po '(?<=refs/heads/).*' --color=never
```
Currently, toki only comes with a plain-tracing FPGA configuration for the ZCU102 evaulation kit, which enables the usage of the trace port on board of the platform. We have made use of the XXX PMOD interface on board of the ZCU102 to display information about the current FPGA image in use to the user. The plain-tracing configuration lights up LED X.
The toki setup script will download and install the toki build- and test-environment within the ``<INSTALLATION_DIR>`` you have specified on the command line. Please ensure that the folder is empty or not yet existing. The setup scripüt will guide you through the rest of the installation. Please note that the script will store your provided ``<PRIVATE_TOKEN>`` within the file '.git-credentials' in the ``<INSTALLATION_DIR>``. This file is stored with a umask of 0077 to ensure your privacy and used as credential helper for Git to simplify your future accesses to the toki repositories.
##### init
Please be aware that Yocto, currently, only supports Ubuntu based systems and thus toki copies this requirement. We have successfully tested toki on top Ubuntu 16.04 (xenial) and Ubuntu 18.04 (bionic). Nevertheless, toki also supports other distributions through the means of a tailored Docker container. Please read the section ['toki on non Ubuntu distributions'](#toki-docker) for details on how-to setup the Docker container for toki on your system.
Following the concept of the Linux initrd, the init folder contains the necessary code to initialize the overall system after the FreeRTOS kernel booted the system. The init is also responsible for loading and initializing the deployed applications. In case you would like to initialize additional components before the applications are started, this is the place to do so.
In the next section ['toki folder structure'](#toki-folders), the folder structure created by the setup script is explained. Section ['How-to use toki'](#toki-usage) continues with instructions on how-to use toki and Section ['Setting up your IDE for toki'](#toki-ide) provides you with an insight on how-to setup your IDE for developing and debugging with toki.
## <a name="toki-usage"></a> How-to use toki
Before you start using toki you should familiarize yourself with CMake and Yocto. Besides the basic knowledge on how-to use the two build systems it is of special importance that you have a good understanding of Yocto's multiconfig support, and CMake's cross-compilation support and how its find package algorithm works together with pre-installed target configs. Furthermore, a good understanding of the build process of a GCC cross-compiler for a new target triple with an OS specific libc and the relevancy of a linker script for building binaries for an embedded target would be beneficiary.
Every time you would like to use the toki build- and test-environment you shall open a new terminal and source the toki environment by running the following command with the toki source folder as working dir (see the section ['Setting up your own toki build- and test-environment'](#toki-setup) on how to correctly setup the toki source folder):
```bash
$ source toki-env
```
This initializes Yocto for you and defines the following environment variables
* _TOKI_SRC_DIR_. Points to the root dir of your toki setup.
* __TOKI_SRC_DIR__<br/>
Points to the root dir of your toki setup.
* _CMAKE_BUILD_DIR_. Points to the CMake build directory, the default is '$TOKI_SRC_DIR/_build/cmake'.
* __CMAKE_BUILD_DIR__<br/>
Points to the CMake build directory, the default is ``$TOKI_SRC_DIR/_build/cmake``.
* _YOCTO_BASE_DIR_. Points to the directory that holds the Yocto main sources, i.e., '$TOKI_SRC_DIR/build_systems/yocto/poky'.
* __YOCTO_BASE_DIR__<br/>
Points to the directory that holds the Yocto main sources, i.e., ``$TOKI_SRC_DIR/build_systems/yocto/poky``.
* _YOCTO_BUILD_DIR_. Points to the directory where Yocto places its (temporary) build files, the default is '$TOKI_SRC_DIR/_build/yocto'.
* __YOCTO_BUILD_DIR__<br/>
Points to the directory where Yocto places its (temporary) build files, the default is ``$TOKI_SRC_DIR/_build/yocto``.
* _YOCTO_DOWNLOAD_DIR_. To allow an easy deletion of the Yocto build folder without the necessity to download all external sources again during the next build, toki advises Yocto to use a separate download directory, its default location is '$TOKI_SRC_DIR/_build/yocto_downloads'.
* __YOCTO_DOWNLOAD_DIR__<br/>
To allow an easy deletion of the Yocto build folder without the necessity to download all external sources again during the next build, toki advises Yocto to use a separate download directory, its default location is ``$TOKI_SRC_DIR/_build/yocto_downloads``.
After initialization you are capable of using Yocto to build the individual components and full-fledged, bootable images. You can build individual targets by typing:
```bash
$ bitbake [target]
$ bitbake <target>
```
Valid targets are component names (see the section ['The toki build infrastructure'](#toki-build-infrastructure) on details on the target naming scheme) and toki-image. The latter builds a bootable SD-card image. This image can also be run in a QEMU based emulation environment. To initiate the emulation just type in the following command, after you have built the toki-image target:
Valid targets are component names (see the section ['The toki build infrastructure'](#toki-build-infrastructure) on details on the target naming scheme) and the following top-level targets:
* __multiconfig:amp-c0:meta-ide-support__<br/>
Builds all files that are required to configure your IDE for the development with toki. More details on how to setup your IDE for a proper toki development support are given in the ['Setting up your IDE for toki'](#toki-ide) section.
* __multiconfig:amp-c0:toki-amp-instance__<br/>
Builds a toki instance consisting out of FreeRTOS, all kernel services, and the init routine for the specified core (i.e., core 0).
* __multiconfig:amp-c0:toki-amp-master__<br/>
Builds a full toki master binary consisting out of up to four individual toki AMP instances and all deployed applications.
* __multiconfig:amp-c0:toki-xilinx-image__<br/>
Builds a complete SD card image that contains the First Stage Boot Loader (FSBL), PMU firmware, PL bitstream, and the toki AMP master binary. This image can be copied to a SD card with a simple dd command.
The full SD card image can also be run in a QEMU based emulation environment. To initiate the emulation just type in the following command, after you have built the toki-xilinx-image target:
```bash
$ runqemu toki-image
$ runqemu toki-xilinx-image
```
......@@ -169,12 +141,15 @@ $ runqemu toki-image
In addition to the simple commands above that are used to build and simulate full-fledged images with Yocto, developers might be interested in gaining full code insight and build support for their favorite IDE. This requires that you build the IDE support (meta-ide-support target) with Yocto. If not yet done during the setup of the toki environment, you can do this by typing:
```bash
$ bitbake meta-ide-support
$ bitbake multiconfig:amp-c0:meta-ide-support
```
With the IDE support target, Yocto builds you a GCC cross-compiler, CMake and make binaries, and generates you a CMake toolchain-file, which all match the target platform. You can use the binaries together with toolchain file to configure the code-insight and build features of your IDE of choice. Please do so by consulting the binary locations and CMake command line indicated below.
The meta-ide-support target builds a GCC cross-compiler, CMake, make, and QEMU for the configured toki target machine. Furthermore, a suitable CMake toolchain-file is generated to work with the compiler. Please note that the meta-ide-support is built for a specific core only. However, if you are using the same operating system on all cores, you do not have to worry about this point.
In any case, you can use the provided binaries together with toolchain file to configure the code-insight and build features of your IDE of choice. Please do so by consulting the binary locations and CMake command line indicated below.
### Generic
#### Generic
Environment variables specifying the binary locations:
```bash
......@@ -190,25 +165,174 @@ CMake command line:
${CMAKE_BINARY} \
-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE} \
-DCMAKE_MAKE_PROGRAM=${CMAKE_MAKE_PROGRAM} \
-DPLATFORM=zcu102-zynqmp \
-DPLATFORM=<MACHINE> \
-DAMP_USE_CORE="<CORE>"
${TOKI_SRC_DIR}
```
### Specific IDEs
Where ``<MACHINE>`` indicates the toki target machine configured in Yocto's local.conf. And ``<CORE>`` stands for the number of the core for which the software should be build. The value of ``<CORE>`` can only be set to a core that is part of the current toki deployment config and matches the operating system of the utilized meta-ide-support built. For more details on the local.conf configuration options, the toki deployment configs, and the allowed values for the ``<MACHINE>`` parameter are given in the ['Design Decisions'](#toki-design) section.
#### Specific IDEs
In this section we refer to instructions on how to set up specific IDEs. This list is in no way complete and does not aspire to be so. Not listed IDEs with the capability to manually set all the above mentioned binaries and a toolchain file are also supported by this feature. If you use such an IDE feel free to add the instructions here.
#### CLion
* __CLion__<br/>
As CLion is the preferred IDE of the developers at fortiss, we provide you with the specific steps to setup full code insight and build support for it. The specific instructions can be found [here](./setup-ide-support-clion.md)
As CLion seems to be the preferred IDE of many developers we provide you with the specific steps to setup full code insight and build support for it. The specific instructions can be found [here](./setup-ide-support-clion.md)
### Debugging
#### Debugging
In case you would also like to debug toki application that are emulated within QEMU from within your IDE, you can either use the GDB built by Yocto for this or a gdb-multiarch provided by the maintainers of your Linux distribution. The GDB built by Yocto is located under the path returned by this command (ran within a terminal with an initialized toki environment): ``realpath $YOCTO_BUILD_DIR/tmp/multiconfigs/amp-c0/work/aarch64-toki-freertos-elf/meta-ide-support/*/recipe-sysroot-native/usr/bin/aarch64-toki-freertos-elf/aarch64-toki-freertos-elf-gdb``.
To enable the matching GDB remote debugging support in QEMU, while emulating a toki application, start QEMU by using ``runqemu toki-image qemuparams='-S -s'``. This will launch QEMU with an enabled GDB debugging stub and will halt the execution of the emulated image at its entry point. Please connect to the QEMU GDB stub with the GDB remote debugging capabilities of your IDE on localhost, port 1234.
To enable the matching GDB remote debugging support in QEMU, while emulating a toki application, start QEMU by using ``runqemu toki-xilinx-image qemuparams='-S -s'``. This will launch QEMU with an enabled GDB debugging stub and will halt the execution of the emulated image at its entry point. Please connect to the QEMU GDB stub with the GDB remote debugging capabilities of your IDE on localhost, port 1234.
Please be aware that Yocto builds each target in its own Docker container with an individual sysroot. Thus, it is required to specify a path mapping for every target, to enable proper source-level debugging. Please use ``toki-usage`` to determine the appropriate substitutions.
## <a name="toki-design"></a> Design Decisions
toki combines several open-source projects within a unified build-environment that allows you to modify every piece of code in the process from the compiler, to the kernel, and to the applications. Even replacing individual components entirely is possible (e.g., replacing GCC with Clang). To manage all the different repositories of the aforementioned components toki uses [Google's repo](https://gerrit.googlesource.com/git-repo/). Repo allows to specify sets of compatible repository versions in form of manifests, which in turn allows to share component crossing feature branches with other developers. The [repo homepage](https://gerrit.googlesource.com/git-repo/) points you to additional documentation, usage instructions, and background information for repo.
Please be aware that Yocto builds each target in its own Docker container with an individual sysroot. Thus, it is required to specify a path mapping for every target, to enable proper source-level debugging in your IDE. Concretely, you need to map ``/usr/src/debug/[component]/`ls $YOCTO_DIR/build/tmp/work/aarch64-toki-freertos-elf/[component]/`/git`` to ``$SRC_TREE_DIR/components/[component] `` for each and every component that is part of your toki image.
###### Package Design Policies
In order to make the combination of all the various components possible, we introduced some strict policies with toki:
1. Every component uses its own include prefix (i.e., we include a FreeRTOS header with ``#include "freertos/FreeRTOS.h"`` instead of ``#include "FreeRTOS.h"``).
1. Each component/package is divided into multiple CMake targets:
1. ``package_name``<br/>
This is the complete component, this target includes all source files of the package and links against the headers, config, and port if available.
1. ``package_name-config``<br/>
Within toki all configuration options, i.e., defines, are moved to dedicated configuration header files. This is done to enable version control on the configurations, which in consequence helps to tag and archive a complete software revision that was used to obtain scientific results. Each configuration is hardware platform and operating system specific.
1. ``package_name-port``<br/>
The _port_ part of a package wraps all target specific parts of the code. It can be further divided into a operating system (_sys_) and hardware platform (_machine_) specific part, if needed. The ``package_name-port`` target is then replaced by the following two targets:
1. ``package_name-sys``<br/>
1. ``package_name-machine``<br/>
1. ``<target>-headers``<br/>
Every ``<target>`` in the above list can have an accompanying ``<target>-headers`` target that encapsulates the system-wide headers that are installed by ``<target>``.
An exception to this naming scheme is formed by the ``freertos-plus`` target. This target encapsulates several additions that were made to FreeRTOS within toki. It includes among other things ESFree, HST, and our Memguard implementation. We took this design decision to reduce our changes to the original kernel code to a minimum and thus offer easy upgradability.
1. The source tree of each package follows the following naming scheme for its sub-folders:
- ``src``<br/>
Contains the actual source code of the package.
- ``src-gen``<br/>
Contains all scripts needed to generate additional source files and the description files from which the source files are generated. If the generated files are configuration specific, this sub-folder would be included in the ``<package_name>-config`` target.
- ``include``
- ``<package_name>``
All include files are placed into a dedicated folder named after the package, this ensures that there are no conflicts due to headers that are installed by different packages. This ensures maximum flexibility in combining different components.
- ``ports``
- ``sys``
- ``machine``
Contains the platform specific parts of a package, which might be split into a operating system (_sys_) and hardware platform (_machine_) specific part, as discussed above.
###### Configuration Options and their Connections
local config vs multiconfig
deployment configs and their parsing
app config parameter
app-list binary
###### Kernel- vs. User-Space
Das Prinzip libc-repl und die Trennung zwischen User und Kernel Space (ohne Speicherbarriere)
yocto class toki-system
###### Boot Order
libxil bsp boot code > freertos > init > services, elfloader > apps
###### CMake Build Support
Das Verhältnis zwischen CMake und Yocto, insb. auch die TokiRoot.cmake Datei erläutern, mit dem Prinzip der temporär erstellten Find-Skripte
### <a name="toki-folders"></a> toki folder structure
In case you would like to start your own developments with toki it is best to begin with a good understanding of its folder structure and design decisions.
The top-level folder of the toki build environment is divided into ten sub-folders: _build, applications, auxiliary, build-systems, components, configs, deployments, hardware, init, manifests. All individual sub-folders and their purpose are explained below.
##### _build
The build folder contains all build related, temporary files for both build systems CMake and Yocto. There are four sub-folders located within the '_build' folder. 'cmake' and 'yocto' do keep the build specific files of the two build systems, 'yocto_downloads' keeps all downloaded external sources required by the Yocto build process, and 'yocto_sstate-cache' provides Yocto with a shared state cache to speed-up builds.
It is safe to delete all files underneath this folder, however, as this induces a re-initialization of the Yocto build environment, we advise you to use the reset functionality of the toki setup script instead. It will delete all temporary files, but keeps the downloaded external sources and the sstate cache. Furthermore, the script re-initializes the Yocot build environment for you again. Just run the following command from within your toki environment:
```bash
$ toki-setup-build-env.sh --reset
```
##### applications
This folder contains all user-level applications build for the toki runtime platform. This is the place where code should go that uses the toki platform from a user-level perspective. Hence, this is also the main place non system developers have to interact with.
The section ['How-to extend toki'](#toki-extension) provides you with instructions on how-to integrate new applications, i.e., user code, with the existing toki build system. The applications that are part of the final image, created by the Yocto build system, are selected with the toki-config script. More details on the usage of this script are provided in the section ['Configure your own deployment'](#toki-deployment-config).
Currently, toki feature five applications of which three are still under development:
* __adjtimex-demo__<br/>
Prototype of a test application for the adjtimex syscall extension of FreeRTOS and newlib that implements a clock adjustment feature for FreeRTOS.<p/>
* __intperf__<br/>
An application that provokes the best- and worst-case interrupt handling performance of the Zynq UltraScale+ MPSoc.<p/>
* __kybos-demo__<br/>
Prototype of a demonstrator for a new scheduling concept.<p/>
* __minimal__<br/>
Simple application to test the compilation and boot of the overall system.<p/>
* __ptpd__<br/>
Adaption of PTPd to FreeRTOS and lwIP, which is still under development.<p/>
##### auxiliary
Here all auxiliary helper scripts are located. Non toki maintainers hopefully do not need to edit any of these files. More details on the available toki helper scripts and their usage are given by the dedicated section ['The toki helper scripts'](#toki-scripts) on that topic. Furthermore, this folder contains the Dockerfile used to build the docker container in the ['toki on non Ubuntu distributions'](#toki-docker) section.
##### build-systems
Within the sub-folders of the build-systems folder you find all files related to the two build systems used by toki: CMake and Yocto. The cmake sub-folder mainly contains a single top-level CMakeLists.txt and some auxiliary files needed by that CMakeLists.txt to build the overall toki platform with CMake. The sub-folder yocto, on the other hand, contains several sub-folders one for each Yocto layer used by the toki build, as well as Yocto's poki distribution itself. You find all toki specific recipes under build-systems/yocto/meta-toki and build-systems/yocto/meta-toki-xilinx. The section ['How-to extend toki'](#toki-extension) provides you with the necessary information to extend those two layers in case you want to integrate your own software components within toki. Apart from that it is hopefully not necessary to change any of the other, non toki, layers.
##### components
The components folder contains all software components that are part of the toki platform, each one located in its own sub-folder. At the moment of writing these are:
* freertos
* freertos+
* libxil
* libxilsecure
* libxilpm
* lwip
* newlib
##### configs
The configs folder holds all header files and generated source files for each of the components that needs it. The configs are clustered according to their target machine, configuration type, and whether they are designated for a master or slave core. Furthermore, the configs also hold the linker script used to produce the final executables for the target hardware platform. By a rule of thumb, the configs folder contains everything that configures, i.e., changes the behavior, of the software components found in the toki build tree. The flexibility introduced by these dedicated configuration files ensures that multiple deployments can be build and tested with one toki environment.
The configs are organized in sub-folders with respect to the machine they are intended for, their specific name, and whether the configuration is intended for a master- or slave-core.
Currently, toki comes with one example configuration, the baseline configuration, which provides a detailed description of every option in the header files. It provide users of toki with the necessary understanding to adapt the existing configuration or create their own one.
A speciality among the configurations is the linker script (ldscript). The linker script is provided as an interface link library that specifies specific link dependencies, which introduce the correct linker script parameters for the final linker step. This way the linker script can be propagated through the whole dependency stack up to the image creation, without fixing the linker script within the toolchain file, but rather bind it to a specific configuration.
##### deployments
In addition to the software configuration provided in the configs folder, different toki images might also want to include different software components in the first place. This can be achieved by specifying toki deployment configurations in form of JSON files. The deployments folder holds these deployment configurations. They specify which software in which configuration should run on which core and with which hardware configuration shall it be deployed within the final image. The deployment configurations in the deployments folder are grouped into sub-folders with respect to the machine they apply to. Below the machine level, they can be further organized into arbitrary sub-folders.
To assist in creating such deployment configuration, toki provides you with the toki-config tool, which is discussed in the section ['Configure your own deployment'](#toki-deployment-config). The toki build-system can cope with a various number of deployment configurations, to support a systematic evaluation of for instance different software configurations or configuration parameters. A deployment configuration can be marked as active for a certain build with the help of the toki-config tool.
##### hardware
This folder is dedicated to hardware specific additions to the toki platform. In case of the zcu102-zynqmp machine/platform, this folder contains different FPGA images and their associated Vivado design files.
Currently, toki only comes with a plain-tracing FPGA configuration for the ZCU102 evaulation kit, which enables the usage of the trace port on board of the platform. We have made use of the XXX PMOD interface on board of the ZCU102 to display information about the current FPGA image in use to the user. The plain-tracing configuration lights up LED X.
##### init
Following the concept of the Linux initrd, the init folder contains the necessary code to initialize the overall system after the FreeRTOS kernel booted the system. The init is also responsible for loading and initializing the deployed applications. In case you would like to initialize additional components before the applications are started, this is the place to do so.
## <a name="toki-deployment-config"></a> Configure your own deployment
......@@ -247,7 +371,7 @@ In addition to the regular git commands, the git toki extension provides the ``g
##### toki-pull-upstream
is a hevily configurable script for pulling changes from remote repositories
is a heavily configurable script for pulling changes from remote repositories
* pulls upstream changes
* pull configs erklären und wie die pull steps mit den repsoitories zusammenhängen
......@@ -309,6 +433,8 @@ Within our own test setup, we are utilizing the [ARM DStream](https://developer.
Section ['Further reading'](#toki-literature), provides you with links to background information regarding the two tracing infrastructures and their implementation within the Xilinx ZCU102 evaluation kit.
___DS-5 debug script referenzieren und erklären!___
## <a name="toki-build-infrastructure"></a> The toki build infrastructure
......@@ -494,6 +620,11 @@ There you will find a description on how to get our Docker image. Log into the c
$ docker start -i toki-dev
```
## <a name="toki-papers"></a> Scientific Publications
- [RTSS@Work'19]
- [CPSIoT-Bench'20]
## <a name="toki-literature"></a> Further reading
......@@ -566,6 +697,7 @@ This section solely focuses on providing you with additional information regardi
[//]: # (TODO: Irgendwo erwähnen, in welchem boot mode wir laufen und das wir theoretisch auch in der TrustZone laufen könnten bzw. das auch schon getestet haben.)
[//]: # (einige Features der toki build umgebung machen aber evtl. keinen sinn für andere plattformen. so setzen wir fürs debuggen das selbe sd karten image ein, wie für das flashen des boards verwendet werden kann. so geben wir dem nutzer die möglichkeit 4 kerne zu spezifizieren und ein fpga hardware image auszuwälen. der gesamt image bau prozess ist dabei xilinx spezifisch. mit vertretbarem aufwand lassen sich diese sachen aber auch generalisierne und somit für andere platform lösungen zugänglich machen.)
......
......@@ -12,7 +12,7 @@ In the bottom drawer of CLion open the CMake tab and click on the gear icon. In
Switch in the left menu of the newly opended dialog to the tab "Toolchain" and create a new toolchain using the plus icon above the list. Select a name for the new toolchain and set the other fields using the paths returned by the commands from the following list.
- CMake: ``realpath $YOCTO_DIR/build/tmp/work/aarch64-toki-freertos-elf/meta-ide-support/*/recipe-sysroot-native/usr/bin/cmake``
- CMake: ``realpath $YOCTO_BUILD_DIR/tmp/multiconfigs/amp-c0/work/aarch64-toki-freertos-elf/meta-ide-support/*/recipe-sysroot-native/usr/bin/cmake``
- Make: ``realpath $YOCTO_BUILD_DIR/tmp/multiconfigs/amp-c0/work/aarch64-toki-freertos-elf/meta-ide-support/*/recipe-sysroot-native/usr/bin/make``
- C Compiler: ``realpath $YOCTO_BUILD_DIR/tmp/multiconfigs/amp-c0/work/aarch64-toki-freertos-elf/meta-ide-support/*/recipe-sysroot-native/usr/bin/aarch64-toki-freertos-elf/aarch64-toki-freertos-elf-gcc``
- C++ Compiler: ``realpath $YOCTO_BUILD_DIR/tmp/multiconfigs/amp-c0/work/aarch64-toki-freertos-elf/meta-ide-support/*/recipe-sysroot-native/usr/bin/aarch64-toki-freertos-elf/aarch64-toki-freertos-elf-g++``
......@@ -26,10 +26,10 @@ Switch to the tab "CMake" in the menu on the left and create a new profile using
- Build type: Debug
- Toolchain: Your toolchain created in the previous step
- CMake options: ``-DCMAKE_TOOLCHAIN_FILE=[PATH TO THE TOOLCHAIN FILE] -DCMAKE_INSTALL_PREFIX=[INSTALL_PREFIX] -DPLATFORM=zcu102-zynqmp -DAMP_USE_CORE="0"``
- CMake options: ``-DCMAKE_TOOLCHAIN_FILE=<TOOLCHAIN_FILE> -DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX> -DPLATFORM=zcu102-zynqmp -DAMP_USE_CORE="0"``
- Replace in the above value:
- ``[PATH TO THE TOOLCHAIN FILE]`` with the output of ``realpath $YOCTO_BUILD_DIR/tmp/multiconfigs/amp-c0/work/aarch64-toki-freertos-elf/meta-ide-support/*/toolchain.cmake``
- ``[INSTALL_PREFIX]`` with the output of ``realpath $YOCTO_BASE_DIR/../cmake/_install``
- ``<TOOLCHAIN_FILE>`` with the output of ``realpath $YOCTO_BUILD_DIR/tmp/multiconfigs/amp-c0/work/aarch64-toki-freertos-elf/meta-ide-support/*/toolchain.cmake``
- ``<INSTALL_PREFIX>`` with the output of ``realpath $TOKI_SRC_DIR/cmake/_install``
- Generation path: ``_build/cmake``
![CMake settings](./res/ide-support-clion-03.png "CMake settings")
......
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