TL;DR: a generated register header can compile without a warning and still define a wrong address, because a compiler checks syntax and not meaning. So each macro in the header is checked against a value computed again from the extracted register rows, using exact integer arithmetic that does not read anything the header generator produced. The header is then compiled with clang, warnings as errors, for three language targets, and a deliberately corrupted copy must fail or the whole check is rejected. The SVD file is run through the CMSIS-SVD checker, svdconv --strict. None of this shows that the extracted data matches the silicon. It shows the files match the data.
Sources: the checks' own code, which is the reference for every statement below, and the Open-CMSIS-Pack specification for the SVD file format. This post describes what each check does and what it cannot prove. It does not report a pass rate.
A header that compiles can still be wrong
A register header is a list of macros. A typical entry names a register, an offset, a field position and a field mask. The names below are illustrative, not taken from a real part:
#define UART_CR1_OFFSET 0x00CUL
#define UART_CR1_TE_POS 3U
#define UART_CR1_TE_MSK 0x00000008ULIf the extraction read the offset as 0x00D, the header still compiles. If the mask were 0x00000004 for bit 3, it still compiles. A compiler has no way to know. The only way to catch it is to state independently what each macro should equal and compare.
Step 1: recompute every macro without asking the generator
For each macro the generator emitted, the gate computes the expected value from the extracted row. The independence rule in the code is plain: nothing in this step reads a value the renderer produced. The renderer only says which macro name stands for which fact. The value comes from the printed source text:
- Field position and mask come from the printed bit range, for example
[3]or[7:4]. The mask is built as((1 << width) - 1) << lsbin arbitrary-precision integers. - Reset value and reset mask come from the printed reset text. The reader accepts
0xhex, a binary dump in groups of four bits, and decimal. A value wider than 64 bits is not turned into a macro, because a C integer constant cannot hold it. - Addresses come from the printed address text. When a register is printed with two addresses, the header may state either one, and no other.
- Register width comes from the width stated as evidence for the register.
A macro for which no extracted fact explains the value is listed as unexplained rather than ignored. Each expectation also records a JSON pointer to the row it came from, such as /register_map/4/bitfields/2, so a failure points at the extracted row and not only at a line of C.
Step 2: a text check that needs no compiler
The first referee is plain TypeScript. The generated header only states integer literals, so a small exact evaluator is enough. It parses every #define, evaluates the literal the way a C compiler reads it, and compares it with the expectation. It also reports:
- a macro that is missing, or defined twice;
- a value that is not a plain integer literal, including a literal with a leading zero, which C reads as octal;
- a macro the checker does not recognise;
- a broken include guard;
- two fields of one register whose masks share a bit. A read-only and a write-only field that deliberately share bits are allowed to.
This referee runs anywhere, so a header always gets at least this check. A pass at this level is labelled text_verified.
Step 3: compile it with clang, and assert every fact
The second referee builds a small C file that includes the header twice, which proves the guard works, and then asserts every expectation with a preprocessor check:
#ifndef UART_CR1_TE_MSK
#error "DV|DV_MACRO_MISSING|/register_map/4/bitfields/2|UART_CR1_TE_MSK"
#elif (UART_CR1_TE_MSK) != (0x8ULL)
#error "DV|DV_VALUE_MISMATCH|/register_map/4/bitfields/2|UART_CR1_TE_MSK"
#endifAn #if check works in C99, C11 and C++, including where _Static_assert does not exist. A failing check prints a marker that maps straight back to the extracted row. The file also takes every macro as an expression in an array, so a macro that only works inside #if is caught.
The compile is syntax-only and freestanding, with -pedantic-errors, -Wall, -Wextra, -Wconversion, -Wundef, -Wshadow and -Werror, so any warning fails the check. It runs for three targets:
- C99 on the host;
- C11 for
thumbv7em-none-eabi, an Arm Cortex-M target; - C++17 on the host.
The worker image installs clang for this purpose. A pass here is labelled compiler_verified. If no compiler is present, the compiler referee reports not_run with the reason, and it is never counted as a pass.
Step 4: prove the check can fail
A checker that has never been seen failing proves little. So the gate corrupts one macro in a copy of the header by adding one to its value, runs the same harness on the copy, and requires it to fail on exactly that macro. If the corrupted copy compiles cleanly, the real result is overturned to failed, with the message that the harness cannot detect a wrong value. Only a check that catches a known-bad header is allowed to vouch for the real one.
What the verdict says
The outcome is one of four words, and each carries a plain statement:
compiler_verified: every macro equals the value computed from the extracted data, and clang compiled the header with warnings as errors for the targets named.text_verified: every macro equals the computed value, checked by the exact evaluator, and no compiler ran. The reason is stated.failed: the header disagrees with the data in a stated number of places, the first of which are listed. The statement says not to use it as is.not_checked: no header was rendered.
Both passing statements end with the same sentence: this shows the header matches the extracted register data, not that the data matches the silicon. In delivery, a header that fails is blocked, not shipped with a warning.
The SVD file: the CMSIS-SVD checker
A CMSIS-SVD file is the XML a debugger reads to show named registers and fields. For the device.svd we deliver, the gate runs svdconv, the CMSIS-SVD checker, with --strict. It only checks: nothing is generated, and nothing is written except the copy it reads. The copy is named after the SVD's own device name, because svdconv reports an error when the file name and the device name differ, and that error would describe our temporary file and not the content.
The verdict has four values, and one of them is never a pass:
pass: svdconv ran and its result line says 0 errors and 0 warnings.pass_with_warnings: it ran, with 0 errors and at least one warning.fail: it ran and reported at least one error. The first errors are listed with their message ids and line numbers, and the rest are counted.not_run: the tool is missing, timed out, crashed, or printed a result line the parser does not understand.
An output the code cannot read is therefore never treated as a pass. The check runs after the delivery gate, so a file that was withheld is not checked, and after every edit to the XML, so the verdict describes the file that ships. The svdconv release the worker image installs is pinned, and the install verifies a checksum.
What this does not prove
- The data may still be wrong. If the extraction misread a bit position from the datasheet, the header agrees with the misreading and passes. The checks compare the files with the extracted rows. Per-value checks against other evidence are a separate layer, and the delivered rows carry their own status.
- A passing SVD is a well-formed SVD. svdconv checks the file against the SVD rules, not against the chip.
- Very large headers may skip the compiler. Above a macro-count limit the compile is not attempted, and the header can be verified by the text referee alone. The verdict says which referee ran.
- Draft status stays. A register file that passes is still a file for an engineer to read against the reference manual before it drives hardware.
FAQ
Does a compiled header mean the register values are right?
No. A compiler checks syntax. A wrong address or mask compiles cleanly, which is why each macro is also compared with a value computed from the extracted rows.
What is a control mutant?
A copy of the header with one macro deliberately changed by one. The check must fail on that macro. If it does not, the check is rejected, because it could not detect a wrong value.
What does svdconv --strict check?
svdconv validates an SVD file against the CMSIS-SVD rules and reports errors and warnings by message id. We run it in check-only mode on the file we deliver.
Does a verified header match the silicon?
Not by this check. It shows the header matches the extracted data. Whether the data matches the chip is for the engineer to confirm against the reference manual.
Run a reference manual and read the verdict on the files you get.
A new account gets five free passes. Each pass runs up to two modules, pinout and footprint included, on a PDF up to 25 MB.
The agent-facing side of the same product is described in How an AI agent pays for a datasheet extraction without an account.