Getting Started with the µOS++ Tracing Infrastructure

Dedicated Pages for Different Audiences

To accommodate the diverse requirements of its audience, this site provides distinct pages: User's Guide, Contributor's Guide and Maintainer's Guide. Each guide is tailored to ensure users can efficiently access the information and resources most relevant to their specific roles or requirements.

Overview

The µOS++ Tracing Infrastructure project is a C++ source code library that provides ...

info

In this context, the term embedded pertains specifically to bare-metal systems, excluding embedded Linux. The latter requires an entirely distinct methodology for developing Linux user-space applications.

The open-source µOS++ Tracing Infrastructure project is available on GitHub under the repository name micro-os-plus/diag-trace-xpack. Additionally, the content is published on the npmjs.com repository as @micro-os-plus/diag-trace, making it accessible for integration into projects as an xpm dependency.

What are xpm packages? (xPacks)

xpm packages, also known as xPacks, are highly adaptable and language-neutral software solutions. They have been effectively employed in C and C++ projects, demonstrating their versatility and practicality.

What the heck are xpm packages (xPacks)? Please, do not introduce another package format!

At first glance, the use of xpm packages may appear complex; however, in practice, they are remarkably straightforward. Their design philosophy is centred on automating frequent tasks in software development, such as dependency installation, and ensuring reproducibility.

xpm packages are managed by xpm (the xPack Project Manager), a utility that complements the npm CLI, the widely-utilised JavaScript package manager, by introducing language-neutral features.

The xPacks Framework does not establish a new package format. Instead, it adopts the standard npm package format, which comprises a collection of files and folders, along with a package.json file containing the metadata.

xpm is capable of installing packages from the same repositories as npm, whether they are public or private.

Packages, which are typically regular archives or git repositories, are extracted into distinct folders within the project.

Based on their contents, xpm packages fall into two categories:

• Source xpm packages: These contain source libraries.
• Binary xpm packages: These typically consist of executables, often platform-specific binary tools.

Source xpm packages are standard npm packages that incorporate library source files, usually written in C/C++, although they are not restricted to any particular programming language.

Binary xpm packages are also standard npm packages but have minimal contents, generally limited to a package.json file. Since these packages provide executables for multiple platforms — many of which can be considerably large — it is impractical to include all binaries within the npm package itself. Instead, the package.json file includes references (URLs) to platform-specific binary archives (e.g., .tar.gz for Unix or .zip for Windows).

These archives, along with the package metadata, are extracted. Additionally, links or forwarders to the executables are created within a .bin folder, thereby eliminating the need to add multiple folders to the system PATH.

In conclusion, xpm packages simplify and streamline the installation process for source libraries and tools, enhancing efficiency and automation. For further information, please refer to the xpm Concepts page.

Features & Benefits

The main attributes of the µOS++ Tracing Infrastructure are:

• Dedicated diagnostic channel — trace output is routed through a separate, user-supplied back-end, completely independent of stdout; diagnostic traffic never interferes with application-level I/O streams
• Familiar, printf-style API — the trace::printf(), trace::puts(), and trace::putchar() functions mirror the standard C output interface, making adoption straightforward for developers already familiar with standard I/O
• Dual C++ and C APIs — a modern C++ API in the micro_os_plus::trace namespace and a compatible C-linkage API (prefixed micro_os_plus_trace_) allow the library to be used from both C++ and plain C translation units within the same application
• Policy-based, testable design — the C++ API is built on the tracer<T> class template, parameterised on a policy class that supplies three static primitives (initialise(), write(), and flush()); alternative policy classes can be substituted for testing without modifying application code
• Zero overhead when disabled — when MICRO_OS_PLUS_TRACE is not defined, every trace call is replaced by an empty inline function; no #if defined(MICRO_OS_PLUS_TRACE) guards are required at call sites, keeping the source code clean and readable
• C++20 concepts enforcement — the trace_policy concept validates the policy class at instantiation time, producing a clear compiler diagnostic if any required method is absent, has the wrong signature, or is not noexcept
• Portable and target-agnostic — the library itself imposes no dependency on any specific output mechanism; ready-made back-end implementations for ARM semihosting, Arm ITM, SEGGER RTT, and POSIX file descriptors are available as separate xPack components
• Single-header integration — the entire public API is available by including one header, <micro-os-plus/diag/trace.h>; the user need only provide a single translation unit that implements the three policy primitives
• Configurable buffer size — the internal printf formatting buffer size is controlled by the MICRO_OS_PLUS_DIAG_TRACE_PRINTF_BUFFER_ARRAY_SIZE_INTEGER macro (default: 200 bytes), allowing the trade-off between stack usage and message length to be adjusted per project

Install

The source code library can be installed either automatically via xpm or manually. Manual installation can be performed by copying the necessary files directly into the target project or by linking the entire project as a Git submodule.

Comprehensive instructions for installing the µOS++ Tracing Infrastructure are available in the Installation Guide.

Status

The µOS++ Tracing Infrastructure project is robust, reliable, and fully operational, making it well-suited for deployment in production environments.

Testing

The library is subject to continuous integration (CI) testing with every push utilising GitHub Actions. This ensures compatibility and stability across Ubuntu, macOS, and Windows operating systems.

Testing is conducted on both 32-bit and 64-bit bare-metal platforms, including Arm Cortex-M0, Cortex-M3, Cortex-M4F, Cortex-M7F, Cortex-A15, Cortex-A72, RISC-V RV32IMAC, and RV64IMAFDC. Additionally, native testing is performed utilising GCC and LLVM/clang compilers, ensuring comprehensive validation across various environments.

Release schedule

The project employs a continuous release strategy, with updates published as development progresses, rather than following a fixed release schedule.

Releases

A comprehensive list of releases may be found on the Releases pages.

Change log

The release notes and change log may be accessed within the repository's CHANGELOG.md file.

Support & feedback

For prompt support and to provide feedback, it is recommended to utilise GitHub Discussions.

For more detailed information, please visit the Help Centre page.

Compatibility notices

According to SemVer rules:

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.

The breaking changes introduced in each major release are documented in reverse chronological order. This information provides a comprehensive overview of significant modifications and is readily available in the respective release notes.

v5.0 (2026-07-13)

To improve testability, the code was refactored to use a tracer<T> class template, parameterised on a policy class that supplies three static primitives (initialise(), write(), and flush()). Alternative policy classes can be substituted for testing without modifying application code.

Projects must provide a single translation unit that implements the three policy primitives as the micro-os-plus::trace::detail::implementation class. The library itself imposes no dependency on any specific output mechanism; ready-made back-end implementations are provided as separate xPack components for ARM semihosting, Arm ITM, SEGGER RTT, and native platforms.

v4.0 (2022-07-28)

Rename MICRO_OS_PLUS_INTEGER_TRACE_PRINTF_BUFFER_ARRAY_SIZE.

v3.0 (2022-02-13)

Include <micro-os-plus/config.h>, rename MICRO_OS_PLUS_TRACE, update cmake & meson configs, and add support to run all tests on all platforms.

v2.0 (2021-03-01)

The library was refactored to use a modern C++ API in the micro_os_plus::trace namespace, while maintaining a compatible C-linkage API (prefixed micro_os_plus_trace_) to allow the library to be used from both C++ and plain C translation units within the same application.

v1.0 (2017-09-04)

The initial version, extracted from µOS++.

Licence

Unless explicitly stated otherwise, the original content is distributed under the terms of the MIT Licence, with all rights reserved by Liviu Ionescu.

Credits

Grateful acknowledgement is extended to:

• GitHub Copilot (Claude Sonnet) for its assistance with code review, refactoring, and improving the Doxygen documentation.
• Doxygen – for the API documentation tools.

Thanks to Shields IO for the badges and SVG REPO for the SVG icons.

Enjoyed Using This Project? Please Let Us Know!

If you have found this project valuable, we would appreciate hearing from you! Here are some ways you can demonstrate your support:

• Donate: Every contribution, regardless of size, helps sustain the µOS++ project. Your generosity maintains the development and ensures continued progress.
• Star the project on GitHub: Assist others in discovering our work by giving it a star — it truly makes a difference!
• Follow Us on X/Twitter: Stay informed about our latest updates, releases, and news by following our account.

Your support is greatly appreciated and motivates us to continue improving!