Code organisation

This section of the documentation serves as a guide for the HotRIO microcontroller firmware software project.

The Git repo for such software can be found on F4E’s GitLab repo under the Software/MicrocontrollerFirmware path. Such path contains a single software project which serves as the backend for all the microcontrollers which need to execute HotRIO firmware and contains all code dependecies, so the developer is free to compile such firmware any time with a reduced set of tools.

It is worth noting that although all the microcontrollers will run the same subset of functionalities, and therefore the source code for such functions is shared across all the microcontrollers, the specific hardware configuration (number of peripherals, configuration of such, routing of the microcontroller pins…) for each scenario may change due to hardware requirements and constraints. To deal with such fanout of different configurations, the firmware itself is broken down into three code pieces which get compiled into a specific firmware version:

  • Hardware configuration source code is the part of the code which represents the specific hardware configuration for a given microcontroller in a specific product (for instance the HotRIO Piranha or Ipanema boards). Apart from strict hardware configuration, this part of the code also specialises the peripherals that will be available within the HotRIO firmware code and the different OS tasks that will run on the firmware and their purpose/operation. We define this part of the code as the Application or Target, which needs to be developed for each specific HotRIO product or product version.

  • HotRIO firmware source code is the part of the code which provides all the common behavior and components to the microcontroller and servers as the base ground across all the HotRIO product spectrum, providing a standard way to program and interact with these subsystems. This code is the same for all the Applications or Targets independently from their specific hardware configuration, although some applications may not use the full library as they do not require all the components to be used.

  • Third party source code is the part of the code which comes from a Third-Party, meaning that the HotRIO team is not in control of such code. In this package we can find the FreeRTOS OS libraries, STMicroelectronics hardware drivers (HAL and LL libraries) and other specific libraries such as FatFS and USB stack. This source code is also the same independently of the specific Application or Target that the developer must develop. Some libraries may not be used on some application if such functionality is not needed.

Deployment tools

This subsection describes the tools needed to build and deploy the firmware for one of the microcontroller applications in one of the HotRIO products. This set of tools is effectively a subset of the development tools which is described further down in this documentation chapter.

The tools needed to perform a deployment of this firmware are here described:

  • GNU Make dependency management tool. This is the basic Linux tool to build code and its dependencies. The software project requires Make to be installed as it is the backbone of the compilation procedure.

  • ARM cross-compilation tools provided by ARM. This software package can be found on the ARM Developer Page and is avaialble for a number of host architectures and targets. To compile for STM32 microcontrollers, the desired toolchain is the arm-none-eabi variant. The project is prepared to only use gcc and g++ from such software package although it could be modified to use other compilers such as ARMCC, but it is highly discouraged.

  • HotRIO CLI utility which is provided as part of the software tooling in the . HotRIO-Software repository. Such utility, apart from allowing the developer or manager to control and configure the HotRIO devices, also embeds some functionality that provide the capability to flash a HotRIO device either locally or remotely. Please refer to the specific documentation of such software in this manual pages.

The deployment of the firmware in one of the micros can usually be done thorugh a local USB connection directly to the microcontroller, which allows the host computer to download the firmware directly to the microcontroller flash memory. A second option is to flash the microcontroller remotely through a number of microcontrollers/local systems; being this a HotRIO specific capability accessed thorugh the HotRIO CLI utility.

Repository structure

The project structure in the repository is organised as follows:

MicrocontrollerFirmware
├── Apps
│   ├── App1
│   └── App2
├── Source
│   ├── Core
│   ├── System
│   └── Drivers
├── Test
├── Targets
│   ├── G0
│   │    └── HAL
│   └── F4
│        └── HAL
└── ThirdParty
    ├── FreeRTOS
    ├── CMSIS
    ├── USB
    ├── EK18
    └── FatFS

Compilation procedure and structure

The compilation structure of the project is designed to provide vertical integration of the microcontroller applications. The firmware is compiled on a per-application basis, meaning that each specific firmware depending on the hardware and functionality for a specific product is compiled separately.

The compilation process is simply initiated by calling the GNU Makefile at the project root folder. The makefile is prepared to compile all the available applications or targets if not instructed otherwise. A developer can choose which specific firmware application to compile by simply passing the TARGET argument to the make call with the application identifier (the same name as the folder under /Apps containing the specific application).

make
make TARGET=<Application>

Such GNU make script will call the appropriate Makefile inside the Application folder, which will start the compilation process. It is within such Makefile script that for each specific application, the dependencies which need to be compiled will be compiled by calling their GNU make files. Such a hierarchy is needed as each specific hardware configuration for a specific application will trigger static pre-compiler definitions that change the outcome of the compilation procedure of the dependencies themselves (statically allocated resources or different hardware-related inlined functions), therefore each application will need a slightly and customized dependecy.

digraph foo { Make [label="Compilation start"] Application [label="App makescript"] Dep1 [label="ThirdParty Libs"] Dep1lib [label="ThirdPartyLib.a" shape=tab] Dep2 [label="HotRIO Src"] Dep2lib [label="HotRIOLib.a" shape=tab] Dep3 [label="HAL libraries"] Dep3lib [label="HAL.a" shape=tab] ApplicationCompile [label="Application source"] Bin [label="Binary file" shape=folder] d1 [shape=point,width=0.01,height=0.01]; Make->Application [label=" make"] Application->ApplicationCompile [label=" make"] Application->Dep1 [label=" make"] Dep1->Dep1lib [label=" compile"] Application->Dep2 [label=" make"] Dep2->Dep2lib [label=" compile"] Application->Dep3 [label=" make"] Dep3->Dep3lib [label=" compile"] ApplicationCompile->d1 [label=" compile" dir=none] Dep1lib->d1 [label=" link" dir=none] Dep2lib->d1 [label=" link" dir=none] Dep3lib->d1 [label=" link" dir=none] d1->Bin [label=""] }

The compilation procedure starts by compiling each one of the dependencies (configured accordingly to the specific application) into a static library. After such compilation is performed, the compilation of the source code of HotRIO firmware is done and also saved as a static library.

Finally, the application-specific source code is compiled and linked against all the produced dependency libraries to produce an executable meant to be flashed into the target microcontroller. Such executable can be found under the /Build/<Application identifier> path as two different executable files, an elf file and a bin file; both equal in functionality and weight once flashed into the microcontroller; the decision on which to use depends on the set of tools the developer is currently using.

Development tools

In order to develop a new application for a HotRIO device or expand the capabilities of a the existing firmware, a set of software tools need to be used to interface to the specific microcontroller.

As previously stated, the GNU Make tool and the ARM cross-compilation tools are essential tools to build the code for the project, and therefore needed during the development process.

Apart from such tools, the developer may also need:

  • STM32CubeMX is the STMicroelectronics software suite used to generate the initialisation code for peripherials on the microcontrollers. With this tool the developer can modify the hardware configuration of the mircocontroller, the peripherials that are connected and their properties easily. Cube MX also has the capability to copy the required libraries for the selected peripherals and middlewares. In this project organisation this behavior is not desired as it makes difficult to integrate the same software components and layers into a single project supporting multiple microcontrollers and hardware configurations.

Warning

When using STM32CubeMX, it is desired to deactivate the library copy for middlewares and/or driver libraries, as these are already available in the custom project structure. To deactivate such behavior, the developer must select the option “Add necessary library files as reference in the toolchain project configuration file” under Project Manager > Code Generator options in the CubeMX.

It is also desired to handle the toolchain script manually to make sure all the necessary libraries are compiled and linked as required. It is therefore advised to set the Toolchain/IDE option under Project Manager > Project to Makefile, as this option will generate a Makefile which will not be used by our custom code compilation scheme.

To flash the produced code, the developer can use the HotRIO CLI utility to simply load the firmware, but if the developer desires to debug the generated code the following software tools are advised to be used:

  • STMicroelectronics STLink as debugger hardware, which grants access to the microcontroller debug features and registers. Since STMicroelectronics offers software support for this hardware through its own IDE and other commercial IDEs, it is advised to pair this STLink hardware with OpenOCD software suite as a bridge to enable GDB to be used as debugger. This tool can be directly downloaded from STMicroelectronics website, and the use of the latest version is advised as no forward compatibility is provided in such software.

  • OpenOCD (Open On-Chip Debugger) is an Open-Source software suite that enables multiple hardware debugger to be interfaced with open-source tools such as GDB. Therefore, it is advised as the software of choice to interface the STLink debug hardware to the debugger. This software suite is open source and can be found readily available as a package for many Linux distributions as well as source code, refer to OpenOCD documentation on how to install such software. The developer is provided a configuration file “debug.cfg” at the root of the project which configures OpenOCD accordingly to use it as a STLink bridge.

  • GDB Debugger as the debug software. Since the binary generated during the compilation procedure is a cross-compiled program, the cross-compatible version of gdb provided on the ARM cross-compilation tools (arm-none-eabi-gdb) version of this tool must be used to interface the debugger. Otherwise, gdb-multiarch package supporting multiple architectures is also recommended as it is avaialble as a standard software package on may Linmux distributions.

In order to intialise the GDB debug procedure, the following command sequence can be used:

gdb-multiarch <Path to project root>/Build/<Application>/HotRIO.elf
arm-none-eabi-gdb <Path to project root>/Build/<Application>/HotRIO.elf

Once in the GDB session, make sure the OpenOCD server is started by issuing the following command on the project root folder :

openocd -f ./debug.cfg

After the GDB session is started and the OpenOCD server is running, the following command can be used in the GDB session to connect through the OpenOCD server:

target extended-remote: 3333

Warning

Usage of IDEs with embedded toolchains and/or hardware configurators such as the official STMicroelectronics IDE, STMCubeIDE, is not advised, as these tools lack the configurability needed on a project of this size and characteristics and become cumbersome to use and debug (yes, debug the IDE).