Build configuration

Features that cost flash, and values that differ per radio, are chosen at build time. Defaults live in config/features.mk. A platform changes them for every radio on it in platform/<p>/config.mk, a board changes them in boards/<board>/config.mk, and the make command line overrides all of them. The Makefile reads the board's file before the platform's: both use ?=, which keeps the first value set, so the board wins over its platform:

make BOARD=<id>                          # the board's defaults
make BOARD=<id> CONFIG_DMR=n             # FM only
make BOARD=<id> CONFIG_VFO=n             # programmed channels only
make BOARD=<id> CONFIG_DISPLAY_INSET=3   # smaller screen margins
make BOARD=<id> BAND=vhf                 # a build option, on a board that has one: build/<id>-vhf

Each switch reaches C as CONFIG_<NAME> = 0 or 1, always defined: test it with #if CONFIG_X, never #ifdef. core/config.h holds the same defaults (all on) for host tests and checks the dependencies. Switches can also leave whole source directories out of the build (Makefile, platform/*/platform.mk). A sub-feature follows its parent unless it is set: CONFIG_DMR=n turns off every DMR feature, and asking for a sub-feature without its parent is an error. Changing a switch rebuilds everything (the build keeps the flags in build/<board>/flags, checked when make starts). make BOARD=<b> print-config lists the resolved switches.

Every feature is on by default wherever the radio has what it needs. A board turns a feature off only for hardware it lacks, for board code not written yet, or when the image doesn't fit, and then the most obscure large features go first. Bench diagnostics such as CONFIG_AUDIO_PROBE stay off.

A feature that needs a part only some radios have (a vibration motor, a GPS receiver, SPI NAND) is a hardware switch: hardware = "..." on its entry in tests/hil/features.toml. Each board then builds it, lists it in BOARD_UNSUPPORTED or BOARD_NOT_WRITTEN, or names it in board.toml [hardware] unconfirmed, and tools/boards.py check enforces that. The accelerometer is the next one: today its driver (drivers/sensor/lis3dh) only feeds a board's diagnostics page under CONFIG_DIAG, so it has no switch. The first feature that uses motion brings a hardware switch with it. A real-time clock driver is the same: none exists yet, and it arrives as CONFIG_RTC, a hardware switch (radio-features.md 5.6).

Unsupported, not written, unconfirmed

A feature a radio's default image leaves out is in exactly one of these. ✕ is only for what no firmware can change, so the docs never understate what a radio can do.

Both config.mk lists take one switch a line with the reason in its comment (tools/boards.py check fails on one without a reason, or on a switch in both). Either one turns the switch off by default (CONFIG_X ?= n next to it), keeps it out of ci's maximal configuration, and satisfies a hardware switch's check. A platform's config.mk can list switches for all of its radios. The feature matrix and the web site show the mark. Say "untested" in bring-up records and pull requests, never in config.mk.

Variants

A variant is a named preset of switches for the prebuilt release images and the web flasher's build picker (website.md): config/variants/<name>.mk, read after the board's board.mk and before its config.mk, so it wins over the board's defaults and the command line wins over it. A variant only turns switches off (CONFIG_X ?= n); the board's own limits still apply. Without VARIANT the build is the full default.

make BOARD=<id> VARIANT=amateur          # build/<id>-amateur/
make BOARD=<id> VARIANT=commercial       # build/<id>-commercial/

Each variant file starts with ## title: and ## summary: lines, and the comment above each switch says why it is left out; the site shows both. The lists are a draft for the project lead to settle.

The firmware version (RFOUNDRY_GIT) is the commit plus -dirty when the tree differs from it (tracked changes, or untracked sources in the built directories); only the few files that use it are rebuilt when it changes.

Switches

What each switch costs in flash, and where it's on by default: feature-matrix.md. RAM figures below are for an STM32F4 radio.

Derived (not set by hand): CONFIG_DMR_DATA_CORE, the shared packet data / CSBK code, on when any data feature is.

Values

Board build variables

Not feature switches: they pick the hardware variant or set bench knobs, and print-config doesn't list them.

Board defaults

A board's config.mk (and its platform's) turn switches off where the radio differs from the project defaults, each with its reason in a comment. Two lists carry the reasons that matter to the docs: BOARD_UNSUPPORTED and BOARD_NOT_WRITTEN (above). To see them for a board:

make BOARD=<id> print-config            # the resolved switches
make BOARD=<id> print-unsupported       # what the hardware can't do
make BOARD=<id> print-not-written       # what is not written yet

feature-matrix.md shows the result for every radio ("Built by default on each radio") and its notes give the reasons; a radio's hardware spec (hardware-<id>.md) holds the facts behind them. The switches off on most boards are CONFIG_AUDIO_PROBE (a bench diagnostic) and the ones that need a part the radio lacks.

Adding a feature

1. Add the switch with a comment and its default to config/features.mk, to FEATURES, and to the dependency checks.
2. Add the default and the checks to core/config.h.
3. Guard the code, and leave a directory out in the Makefile when the whole directory belongs to the feature.
4. Add a row here and in feature-matrix.md (the web site takes the feature's group, title and size from it; site/build.py --strict fails without the row), and check the build links with the switch off (make BOARD=<b> CONFIG_X=n BUILD=build/test-x). tools/ci.sh builds every board with each default-on switch off alone, an FM-minimal and a maximal configuration, all with zero warnings, and reports the image sizes (docs/testing/README.md). The maximal configuration leaves out the switches a board lists in BOARD_UNSUPPORTED (its config.mk: what its hardware can't do, such as SFR on a modem chip lacking what the glue uses) or BOARD_NOT_WRITTEN (what its code doesn't do yet). Leaving the not-written switches out keeps the maximal build to code that runs on the radio: built on, they can fill a radio's memory (one radio's maximal build reached 99% of its CCM RAM), and any shared addition would then fail CI on unrelated pull requests.

View the source of this page