Firmware for TROPIC01 chip.

Directory structure

├── main        # main for application
│   └── api     # API definition headers
├── build       # automatic created build destination
├── docs        # Doxygen documentation build system
├── scripts     # Build support scipts
└── ts-tr01-sdk # main SDK

Build environment Setup

The build system runs in Linux environment.

There are two environment kinds in which the build can be done:

• Public environment - For general public
• Tropic Square environment - For Tropic Square developers.

Public environment

The public build environment uses a Docker image. For instructions on how to build the Docker image, see ts-tr01-build-docker repository.

For instructions on how to build the FW see Build in public environment.

Tropic Square environment

If you are a Tropic Square developer, ask your colleagues on details of Tropic Square internal build environment.

For instructions on how to build the FW see Build in TS private environment.

Build

Prepare

Make sure you have the Docker image prepared, see Public environment above.

To get started, clone this repository and switch into its directory:

$ git clone <this git URL> ts-tr01-boot
$ cd ts-tr01-boot

Make sure submodules are up to date.

$ git submodule update --init --recursive

[!NOTE] Always run previous command after cloning or switching branches that may update submodules.

Build steps

Make sure your working directory is this project root.

There are two build scripts available:

• build_devel.sh produces FW for development chip version (latest state)
• build_tr01-c.sh produces FW for chips with P/N starting with TR01-C2P (ACAB Silicon revision).

Build in public environment

To build using the Docker image :

$ sudo docker run --rm -v "$PWD":/data -w / tr01-build-image ./build_tr01-c.sh

This command:

• Mounts the current working directory ($PWD) into the container at /data
• Sets /data as the working directory
• Runs the build_tr01-c.sh script inside the container (you may use build_devel.sh for development version)

After a successful build, the firmware binaries are available in the ./build/app/ directory.

The build system generates two output files:

• fw_v***.hex — standard Intel HEX format
• fw_v***.hex32 — Verilog-compatible HEX format used for hardware integration

Build in Tropic Square environment

To build the firmware in TS private environment, simply run either of build_tr01-c.sh or build_devel.sh build scripts in Tropic build environment.

Compiler directives

By default compiler directives are set for normal build and handled automatically. Supported cmake directives overview:

• -DCSP=<name> - Chip support package type, currently only umc55 supported (default).
• -DCSP_VERSION=<name> - select version of the CPS development or tr01-c
• -DMEMORY=<type> - select memory to place FW and data
• -DSIMULATION_BUILD=<1/0> - add some simulation support features like FTC messages (only in development version)

Static code analysis

The CodeChecker tool is used to perform static code analysis and generate reports.

You need to install CodeChecker and dependencies. Check out the official repository for guidance.

Generating reports

There are 2 options to get reports:

1. Generate HTML report using CLI.

   • Run following commands:

   CodeChecker check -b "./build_devel.sh" --config ./scripts/codechecker/codechecker_config.yml
   CodeChecker parse -e html ./.codechecker/reports -o ./.codechecker/reports_html
   

   • Open ./.codechecker/reports_html/index.html in your favorite web browser.

2. Use VS Code CodeChecker add-on.

   • Install the add-on from marketplace.
   • Add these lines to your VS Code's workspace settings (.vscode/settings.json):

   "codechecker.executor.executablePath": <path to CodeChecker>,
   "codechecker.analyze.arguments": "--config ./scripts/codechecker/codechecker_config.yml",
   "codechecker.log.buildCommand": "./build_devel.sh",
   "codechecker.backend.compilationDatabasePath": "${workspaceFolder}/.codechecker/compile_commands.json"
   

   • Note: <path to CodeChecker> can be replaced with "CodeChecker" if the CodeChecker is available in your $PATH. Otherwise, you need to specify full path to the CodeChecker executable.
   • Refer to the add-on's documentation on how to run analysis. Usually, you need to click the "Run CodeChecker log" and "Analyze entire project" buttons.
   • After running analysis, errors will be available either in CodeChecker panel or in VS Code's problems tab in the bottom.

Remarks

The current CodeChecker configuration is in YAML format, as it is more human-readable than JSON and also supports comments. The configuration file enables some strict checkers, which may produce a lot of warnings. It is recommended to run the analysis using the full configuration at least once. After that, you can manually disable any checkers you find unnecessary.

Build documentation

We use Doxygen (1.10.0) and LaTeX (pdfTeX 3.141592653-2.6-1.40.24 (TeX Live 2022))

Build HTML documentation

$ mkdir build/
$ cd build/
$ cmake -DBUILD_DOCS=1 ..
$ make doc_doxygen

Generated documentation will be available in directory build/docs/doxygen/html.

Start reading here: build/docs/doxygen/html/index.html.