ChibiOS: reading a mirror of an SVN embedded RTOS

A mirror you can read but not change

The repository description is the whole story in one line: read only mirror of SVN ChibiOS repository at the SourceForge project. The canonical home of the code is a Subversion repository hosted on SourceForge, and what sits on GitHub is a copy of it.

That has practical consequences for anyone who arrives here with a patch in hand. Commits cannot be made against the mirror, so the contribution path is the Subversion trunk on SourceForge. The mirror is a reading and searching tool, and a good one, since a GitHub code search over a tree this size is far quicker than browsing an SVN repository.

The top-level listing shows what a mirror carries beyond the source. There is an AGENTS.md file, a tools/ directory, a doc/ directory, a documentation.html shortcut to the web documentation, a release_note_next.txt file, and a readme.txt that is the file organisation guide rendered in the README. There is also a set of test directories that the README's own tree does not mention in the same form: testrt/, testsb/, testxhal/ and testhal/.

On maintenance, the facts are modest. The repository is not archived, the last push was on 2026-05-31, and there are no GitHub releases, because the release history of the project lives with the Subversion repository rather than with the mirror.

HAL, NIL and RT are three products in one tree

The file organisation guide in the README is the most valuable thing in the repository, because it explains the shape of ChibiOS in a way the documentation site does not summarise.

Under os/ the ChibiOS components are split into five directories. os/hal/ is the HAL component, os/nil/ is the NIL RTOS component, os/rt/ is the RT RTOS component, os/ex/ is the EX component, and os/common/ holds the shared OS modules.

The two RTOS directories are worth pausing on, because NIL and RT are not the same thing with different names. NIL is the simpler one and RT is the full real-time system, and the tree treats them as separate products with separate documentation resources, headers, source and configuration templates. A project that only needs a fast, small scheduler is not paying for RT, and a project that needs the RT features is not forced to take NIL's constraints.

Between them sits os/oslib/, described as OSLIB modules usable by both RT and NIL, with its own include, src and templates directories. That is the mechanism that lets a driver written against the HAL be shared by both kernels, and the presence of os/common/ports/, described as RTOS ports usable by both RT and NIL, extends the same idea upward to the port layer.

os/ex/ is the third product line, with a devices/ directory for complex drivers and its own header and documentation directories. The EX component exists so that heavier drivers, the ones that are too big for the HAL, still have a home with a consistent API.

The common layer is where portability is actually handled

os/common/ is where the abstractions live, and its subdirectories describe the compatibility work in plain terms.

The abstractions/ directory holds what the README calls API emulator wrappers, and two of them are named: cmsis_os/, the CMSIS OS emulation layer for RT, and nasa_osal/, the NASA Operating System Abstraction Layer. Both are the same idea in different directions. ChibiOS can present itself through a CMSIS-RTOS or CMSIS-RTOS2 shaped API so that portable code compiles against it, and it can present an OSAL surface to code written for a flight or space qualification toolchain.

Beside them, ext/ holds vendor files used by the OS, oop/ is an object-oriented framework, ports/ holds the RTOS ports usable by both RT and NIL, startup/ holds startup support, and utils/ holds generic and portable C modules. That last one is the least glamorous and often the most reused part of any embedded stack.

A separate os/various/ directory at the end of the os/ tree holds portable support files, which is the kind of directory that accumulates the workarounds nobody wants to re-invent.

The change log shows this layer is not dormant. One of the entries in the current list is new memory areas functions in OSLIB addressed for portability, and another adds multicore memory classes modifiers to RT in order to support NUMA architectures and non-coherent cache architectures. Both are about making the same code behave correctly on hardware that does not share a uniform memory model, which is exactly the class of problem the common layer exists to absorb.

HAL's lib/ directory shows the driver strategy

The HAL component is the biggest part of the tree, and its lib/ directory is where the philosophy is visible.

There is a complex/ directory for a collection of complex drivers, and inside it three flash storage stacks: mfs/, described as the managed flash storage driver, serial_nor/, the legacy SNOR stack, and xsnor/, the improved SNOR stack. Keeping a legacy stack and an improved stack side by side, each in its own directory, is a compatibility decision rather than a cleanliness one, and it means a project that is nervous about a change has somewhere to go.

Under complex/ there is also fallback/, described as fall back software drivers, which is the standard embedded trick of emulating a missing peripheral in software so that a feature is at least present on a board that lacks the hardware.

The rest of lib/ is a normal driver library: peripherals/ for peripherals interfaces, streams/ for HAL streams, and osal/ for HAL OSAL implementations with a lib/ of common modules. The HAL component also has boards/ for board support files, include/ for high level headers, src/ for high level source, ports/ for HAL ports, dox/ for documentation resources, and templates/ with an osal/ subdirectory for template files.

Those templates are the part with the highest value per line for a new user. A template is the working example you copy when you add a driver, and the README's tree shows that both the OSAL implementations and the driver templates have one, which tells you the project expects people to write drivers and wants that path to be obvious.

The test tree is the part many embedded projects skip

The test/ directory in the README is unusually thorough, and it is worth reading as a statement of what the project considers done.

At the bottom sits lib/, the portable test engine, which is the harness the rest of the suites are written against. Above it are hal/, nil/ and rt/, each holding the test suites for that component, and each with a testbuild/ subdirectory described as a build test and MISRA check. A MISRA check in the build means the code is being checked against a static analysis standard as part of the build rather than as a separate compliance exercise, and it applies per component.

The rt/ suite also carries a coverage/ subdirectory, an RT code coverage project, so the RT kernel has coverage measurement configured in the tree rather than being measured afterwards.

Integration testing sits alongside, in testex/ for EX integration test demos and testhal/ for HAL integration test demos. The split between unit-level suites, build checks and integration demos is the standard three-layer arrangement, and the fact that all three exist for the same components is the point.

The change log adds to the picture. New integration demos for VFS+LittleFS/FatFS+XSHELL were added, now also available on STM32U0 Nucleo-64, and a new EFL driver for the simulator with a simulator MFS test application came with simulator support for x86-64 on Posix and Linux. Running the driver tests on a workstation instead of on hardware is the difference between a test suite that runs on every commit and one that runs when a board is free.

What the change log says about the current work

The Releases and Change Log section of the README is a long Next section, and it is the best available picture of where the project is spending its effort.

Two entries are functional safety work. A dedicated functional safety module was added to RT, and the function chSysIntegrityCheckI() was moved into that module and renamed to chSftIntegrityCheckI(), with a separate entry noting that chSftIntegrityCheckI() was rewritten to be much more efficient in performing lists integrity checks. A dedicated module with a fixed prefix is a way of keeping safety-critical code identifiable, which matters for a certification argument.

The rest of the list is kernel and port work. Faster context switch modes were added in the ARMv7-M and ARMv8-M ports, and the new modes allow to avoid saving FP context for threads that do not use the FPU. A new ARMv8-M port was added, aligned with the features of the ARMv7-M port for sandboxing. MPU initialization settings were added in the ARMv7-M, ARMv7-M-ALT and ARMv8-ML-ALT ports, and the settings allow to statically initialize any region. Interrupts processing was improved in the ARMv7-M-ALT and ARMv8-M-ML-ALT ports, specifically saving a few cycles on the context switch code path, and a missing context switch hook was added in the same ports.

There are driver and tooling items too: an ADC driver and an RTC driver in XHAL, a thread mode for EP0 handling in the USB HAL driver, XShell support for a change prompt, multi-command per line, line editing, user definable extra fields, and init and execution hooks, plus improved LFS support, so it is now possible to make an LFS file system at arbitrary positions in flash.

Two bug fixes at the top of the list show how fixes travel: the alignment of a heap-created thread working area size in RT, bug 1307, and a wrong alignment check in chThdCreateI() in NIL, bug 1306. Both are marked as backported to 21.11.6, which is the clearest signal in the repository about which line is the stable one.

Licence, documentation and what a reader should check

The licence is GPL-3.0, with the GPL licence text in license.txt at the root of the tree, and the project description points at chibios.org as the homepage. The documentation is split between the repository and the web: the README's tree has a docs/ directory with builders for HAL, NIL and RT, the top-level listing has a doc/ directory, and documentation.html is described as a shortcut to the web documentation page.

Those two spellings of the same directory, docs/ in the guide and doc/ in the mirror's listing, are a small reminder that the README was written against the Subversion layout and the mirror is not byte-identical to it. The same applies to the test directories. A reader navigating by the tree in the README will find most of what it promises, and will also find a few names that have moved.

For anyone evaluating ChibiOS against an alternative, three checks are worth doing before reading further into the code. First, work out which kernel you actually need, because NIL and RT are separate products with separate obligations and the choice changes the licence analysis, since the GPL-3.0 label in the repository metadata describes the project as a whole rather than each component. Second, find the version you would build, which the change log's 21.11.6 backport markers help with, and check the release notes in the Subversion repository rather than the mirror. Third, decide where your code goes: this is a framework you include in your firmware, so the licence of the framework and the licence of your product are two separate questions, and only a lawyer can answer the second one.

What the mirror is good for is everything else. It is a complete, searchable, well-organised snapshot of a mature embedded stack, and the file organisation guide at the top of the README is worth reading on its own.

Editorial conclusion

Use this repository to read and search ChibiOS, because the mirror is complete enough to trace a driver, a port or a test suite, and the file organisation in the README is more informative than most vendor documentation. Do not plan to contribute through it, since it is a read-only mirror of the Subversion repository and a pull request opened here will not reach the maintainers, so send patches to the SVN trunk or the SourceForge project instead. Before you base a design on what you read here, check two things: whether the code you are looking at has been carried into the current stable line, because the change log shows fixes backported to 21.11.6, and whether the licence terms in license.txt suit your product, since the project is GPL-3.0 and ChibiOS is a ChibiOS/RT and ChibiOS/NIL dual product with different obligations on the RT side.

Frequently asked questions

Official sources

1. ChibiOS/ChibiOS on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README