gen-rdb

Generate the debug files from Astrobe compiler output

Name

gen-rdb – generate the rdb debug data directory from Astrobe compiler output

Synopsis

gen-rdb map_file [--mcu MCU] [--rdb-dir dir] [--attr-cfg path] [--nsc-dir dir] [-v]

Description

gen-rdb reads an Astrobe linker .map file and the corresponding .bin and per-module .lst files to produce the rdb/ directory. This directory contains the debug data files that make-elf needs to build an ELF executable with DWARF debug information.

The tool performs two passes over the listing files:

Generate .alst files – Each module's .lst file is transformed into an assembly listing with absolute addresses, resolved opcodes, and annotated data references (globals, constants, strings, type descriptors).
Patch bl.w call targets – Branch-with-link instructions are annotated with the target procedure name (eg. UART.GetBaseCfg) by cross-referencing the procedure address database built from all .alst files.

In addition, gen-rdb generates:

_startup.alst – a listing showing the module initialisation call sequence, derived from module entry addresses in the .map file.
arm-attr.cfg – ARM ELF build attributes for the target MCU, extracted from the master attribute configuration file.

Warning: gen-rdb deletes all existing files in the target rdb directory before generating new ones. Do not store other files there.

Prerequisites

Before running gen-rdb, the Astrobe compilation and linking must be complete. The following files must be present and unmodified in the project directory:

The linker .map file (passed as the positional argument)
The program .bin file (same base name as the .map file)
All per-module .lst files (referenced by the .map file)

Options

map_file: Path to the Astrobe linker .map file (positional, required). The .bin file is expected at the same path with the .bin extension.
--mcu MCU / --mcu=MCU: Override the MCU identifier. When given, this value is used instead of the Configuration line in the .map file to select the correct ARM attribute section from the master configuration file.
--rdb-dir dir / --rdb-dir=dir: Output directory path, relative to the current working directory. Default: rdb. For TrustZone projects the Secure rdb directory is typically placed in a subdirectory, eg. --rdb-dir sec/rdb.
--nsc-dir dir / --nsc-dir=dir: Directory containing an NSC.alst file (produced by gen-secure. When given, NSC.alst is copied into the output rdb directory so that make-elf can include the veneer code in the DWARF debug data. A warning is printed if the file is not found.
--attr-cfg path / --attr-cfg=path: Path to the master arm-elf-attr.cfg file. This INI-style file contains ARM ELF attribute definitions organised by MCU and core. If not given, the RTK_ARM_ATTR_CFG environment variable is checked. If neither is set, no arm-attr.cfg is generated.
-v, --verbose: Verbose output. Print each created .alst file, skipped modules, and attribute generation details.

The --mcu and --attr-cfg options relate to MCU resolution and ARM attribute generation, described in the MCU Resolution section below.

Output Files

All output is written to the rdb directory (or the path given by --rdb-dir), relative to the current working directory.

Absolute Assembly Listings (.alst)

One .alst file per linked module. Each file contains:

A header with tool name, program name, and MCU identifier
Interleaved Oberon source lines and ARM assembly with absolute addresses, resolved opcodes, and annotated branch targets
Data annotations: <Global:>, <Const:>, <String:>, <Type:>, <LineNo:>, <Case:>

The format is designed to be parsed by the elfdata library, which extracts procedure boundaries, variables, types, and line mappings for DWARF generation.

Startup Listing (_startup.alst)

A listing of the startup code appended by the linker after the program code. Each line represents a bl.w instruction to a module's ..init entry point, in link order. The sequence starts at the code end address from the .map file.

NSC Listing (NSC.alst)

When --nsc-dir is given, NSC.alst is copied from the specified directory into the rdb output directory. This file is a listing of the Non-secure Callable veneer code generated by gen-secure, and allows make-elf to include veneer symbols and line mappings in the ELF debug data.

ARM Attributes (arm-attr.cfg)

An INI-style file containing Tag_* attribute lines for the target MCU. Generated by looking up the MCU name in the master arm-elf-attr.cfg. MCU-specific tags override the core defaults. This file is read by make-elf" to populate the .ARM.attributes section in the ELF output.

MCU Resolution

The MCU identifier determines which section of the master arm-elf-attr.cfg to use for ARM attribute generation. It can be set in two ways:

Explicitly, via the --mcu option.
Automatically, from the Configuration line in the .map file.

The Configuration value in the .map file is a verbatim copy of ConfigDescription from the Astrobe .ini file (the "Description" field in Astrobe's configuration editor). It is a free-form string describing the build configuration – for example:

STM32U585 IOT v3.0 k-v4 SRAM3
v2.1 RP2350 Pico2 k-v1 code@100H
MCX-N947 FRDM v3.0 k-v1 secure SRAM_C

When no --mcu override is given, gen-rdb splits the Configuration value into whitespace-delimited tokens and scans them left to right. The first token that matches a section name in the master arm-elf-attr.cfg is used as the MCU identifier. For the examples above, the matched tokens are STM32U585, RP2350, and MCX-N947 respectively.

For this to work, the ConfigDescription must contain a token that exactly matches a section name in the master file. The position within the string does not matter – the MCU name can appear as the first token, the second, or later – but only the first match is used. If the master file is not available or no token matches, gen-rdb prints a warning and skips arm-attr.cfg generation.

Users can add new MCU types to the master arm-elf-attr.cfg by adding a section with the MCU name and a CPU key referencing the core:

[LPC55S69]
CPU = Cortex-M33
Tag_DSP_extension = 1

Environment

RTK_ARM_ATTR_CFG: Path to the master arm-elf-attr.cfg file. Used when --attr-cfg is not given on the command line. There is no built-in default.

Diagnostics

The tool exits with status 0 on success and status 1 on any error. Common error conditions include:

.map file not found
.bin file not found (expected at same path as .map with .bin extension)
--attr-cfg path does not exist

Warnings (non-fatal) are printed to standard error for:

MCU not resolved from the .map Configuration line
no master arm-elf-attr.cfg available (skips arm-attr.cfg generation)
no End Addr / Total line in .map (skips _startup.alst generation)

With -v, the tool prints each created file and skipped module to standard output.

Compatibility

Developed and tested with Astrobe for RP2350 version 10. The .map and .lst file formats are specific to the Astrobe compiler and linker. Older Astrobe versions may produce files with different formats.

Notes

Modules listed in the .map file but lacking a corresponding .lst file are skipped silently (or with a verbose message). This is normal for library modules distributed without source.

The _startup.alst listing represents the startup code appended by the Astrobe linker after the program code in the binary. It contains the module initialisation call sequence executed at program start.