Customizable runtimes

[damaki]

Summary

This adds a new mechanism to allow generated runtimes to be customized with user-defined board parameters defined in JSON files. For example, to change the clock speed of the generated runtime.

Rationale

The purpose of this work is to make it easier for users to adapt runtimes to different boards without needing to manually edit the generated runtime sources (which can be complicated and requires knowledge of how the runtime sources are organised).

With this new feature, the user can define a custom JSON file that contains various configuration values for a specific target. This JSON file is then used by the Python scripts use to customize the generate runtime.

For example, the STM32F0xx runtime configures a 8 MHz HSE by default. If a user has a project that uses a 16 MHz HSE oscillator on their board, they can now easily generate a suitable runtime by creating the following JSON file instead of modifying runtime sources:

{
    "base_target": "stm32f072rb",
    "board_name": "my-board",
    "board_params": {
        "sysclk_frequency": 48000000,
        "hse_frequency": 16000000,
        "clock_source": "HSE"
    }
}

and then pass it to build_rts.py:

./build_rts.py --output=/path/to/gnat --build my-board.json

which will generate then following runtimes that will configure the system clocks to use a 16 MHz HSE:

• ravenscar-full-my-board
• ravenscar-sfp-my-board
• zfp-my-board

Implementation

When a JSON file is specified on the command line to build_rts.py, the contents of the file are loaded and passed to the Python class that configures the runtime sources for the specific target. The Python code can then use the board parameters, along with the new template system, to customize the generated runtime.

For example, the Stm32F0 class in cortexm.py now calculates the PLL and system clock parameters based on the configuration loaded from the JSON file. If no JSON file was given, then sensible default values are used instead.

Supported targets

For now, I've only updated the stm32f0xx and nRF52 runtimes to make use of this feature. The README.md has been updated to document which board parameters can be configured.