This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

Bsim boards

This page covers the design, architecture and rationale, of the nrf52_bsim board and other similar bsim boards. Particular details on the nRF52 simulation board, including how to use it, can be found in that board documentation. These boards are postfixed with _bsim as they use BabbleSim (shortened bsim).

Overall objective

Bsim boards main purpose is to be test-benches for integration testing of embedded code on workstation/simulation. Integration testing in the sense that the code under test will, at the very least, run with the Zephyr RTOS just like for any other POSIX arch based board, but in addition these will include some HW models which, to some degree, pretend to be the real embedded HW.

These tests are run in workstation, that is, without using real embedded HW. The intention being to be able to run tests much faster than real time, without the need for real HW, and in a deterministic/reproducible fashion.

Unlike native_posix, bsim boards do not interact directly with any host peripherals, and their execution is independent of the host load, or timing.

Different types of tests and how the bsim boards relate to them

With the POSIX architecture we provided an overall comparison of what the POSIX arch provides vs other options. That comparison applies fully to these boards, but in this section we expand further on the differences, benefits and drawbacks of different testing methodologies normally employed by embedded SW developers and how they relate to these boards.

  • Unit tests: Typical unit tests frameworks provide unit testing support which covers a different need: testing a component in isolation. Zephyr provides a unit testing target (unit_testing) which is not related to these bsim boards.

  • Integration tests on real HW: Allows testing with the real SW components that may be too dependent on the exact HW particularities, and possibly without any changes compared to the final solution. As such can provide better integration coverage than simulation ins ome cases, but at the expense of slower execution, needing the real HW setups, test in general not being reproducible, and in many cases failures not being easy to debug. They otherwise serve a very similar purpose to simulation integration tests.

  • Integration tests on workstation (what the POSIX arch and these boards enable)

    • Using bsim boards: Allow testing the embedded SW (or a subset), including the OS, models of peripherals etc. By testing them in conjunction, it is possible to test the components interactions and their integration.

    • Using bsim boards with the BabbleSim Physical layer simulation allows testing how several devices would interact with each other. For ex. how a left and a right earbud synchronize and exchange data and audio over their radio link, and how they interact with a mobile phone.

    • Using bsim boards, and the EDTT framework: With the EDTT framework we can test the embedded code under test while controlling the test from external python test scripts. This is supported by compiling the embedded code with an special driver that handles the EDTT communication (its RPC transport) and an embedded application that handles the RPC calls themselves, while the python test scripts provide the test logic.

    • Using Zephyr’s native_posix board: It also allows integration testing of the embedded code, but without any specific HW. In that way, many embedded components which are dependent on the HW would not be suited for testing in that platform. Just like the bsim boards, this Zephyr target board can be used with or without Zephyr’s ztest system and twister. The native_posix board shares the POSIX architecture with the bsim boards.

  • Zephyr’s ztest infrastructure and Zephyr’s twister: Based on dedicated embedded test applications build with the code under test. The embedded test application is responsible for driving the tests and check the results on its own, and provide a test result to a PC which directs the test. Originally used as a framework for integration testing on target, with a very dedicated test application, these are fully supported with the bsim boards.

Design

Layering: Zephyr’s arch, soc and board layers

The basic architecture layering of these boards is as follows:

  • The architecture, SOC and board components of Zephyr are replaced with simulation specific ones.

  • The architecture (arch) is the Zephyr POSIX architecture layer. The SOC layer is the soc_inf layer. And the board layer is dependent on the specific device we are simulating.

  • The POSIX architecture provides an adaptation from the Zephyr arch API (which handles mostly the thread context switching) to the Linux kernel. See POSIX arch architecture

  • The soc_inf layer provides the overall CPU “simulation” and the handling of control between the “CPU simulation” (Zephyr threads) and the HW models thread ( See Threading )

  • The board layer provides all SOC/ IC specific content, including (or linking to) HW models, IRQ handling, busy wait API (see posix_busy_wait), and Zephyr’s printk backend. Note that in a normal Zephyr target interrupt handling and a custom busy wait would be provided by the SOC layer, but abusing Zephyr’s layering, and for the soc_inf layer to be generic, these were delegated to the board. The board layer also provides the main() entry point for the linux program, command line argument handling, the overall time scheduling of the simulated device, and other test specific functionality like bs_tests hooks, trace control, etc. Note that the POSIX arch and soc_inf expect a set of APIs being provided by the board. This includes the busy wait API, a basic tracing API, the interrupt controller and interrupt handling APIs, posix_exit(), and posix_get_hw_cycle() (see posix_board_if.h and posix_soc_if.h ).

Zephyr layering in native & bsim builds

Fig. 219 Overall architecture in a Zephyr application in an embedded target vs a bsim target

Important limitations

All native and bsim boards share the same set of important limitations which are inherited from the POSIX arch and soc_inf design.

Threading and overall scheduling of CPU and HW models

The threading description, as well as the general SOC and board architecture introduced in POSIX arch architecture apply to the bsim boards.

Moreover in Architecture of HW models used for FW development and testing more details on the HW models and their scheduling are provided.

Time and the time_machine

Simulated time in bsim boards is in principle fully decoupled from real wall-clock time. As described in POSIX arch architecture, simulated time is advanced as needed to the next scheduled HW event, and does not progress while the simulated CPU is executing code.

In general simulation time will pass much faster than real time, and the simulation results will not be affected in any way by the load of the simulation host or by the process execution being “paused” in a debugger or similar.

The time_machine component provides the overall HW event time loop required by the HW models, which consists of a very simple “search for next event”, “advance time to next event and execute it” loop, together with an API for components that use it to inform about their events timers having been updated. Events are defined at design time, they are not registered dynamically for simplicity and speed.

Use of babblesim components: tracing, random number generation, logging activity

The same considerations as for the HW models apply to the bsim boards, see Architecture of HW models used for FW development and testing.

The communication between a Zephyr device and other simulated devices is handled over the bsim libPhyCom libraries. For the radio activity the figure below represents this communication:

Communication between a Zephyr device and other simulated devices

Fig. 220 Communication between a Zephyr device and other simulated devices

Test code may also communicate with other devices’ test code using the bsim backchannels. These provide a direct, reliable pipe between devices’ test code can use to exchange data.

About using Zephyr APIs

Note that even though bsim board code is linked with the Zephyr kernel, one should in general not call Zephyr APIs from the board code itself. In particular, one should not call Zephyr APIs from the original/HW models thread as the Zephyr code would be called from the wrong context, and will with all likelihood cause all kind of difficult to debug issues.

In general board code should be considered as lower level than the Zephyr OS, and not dependent on it. For example, board code should not use the printk API as that anyhow would result in a call back into the board code (the bsim specific printk backend) which relies on the bs_trace API. Instead, for tracing the bs_trace API should be used directly. The same applies to other Zephyr APIs, including the entropy API, etc.

printk and posix_print backend

The bsim board provides a very simple backend for Zephyr’s printk(), which simply routes the printk strings to the bs_trace bsim API. So printk messages are printed in the console (stdout) together with all other device messages. The board also provides the posix_print API which is expected by the posix ARCH and soc inf code, and which is based on the same bs_trace API.

bs_tests

The bsim boards provide also the bs_tests facility.

This allows tests to be defined (registered), and for each of these tests to use a number of special test hooks which are present only in these simulated targets.

These tests are built together with the embedded SW, and are present in the binary but will not be executed by default. From the command line the user can query what tests are present, and select which test (if any) should be executed. When a test is selected its registered callbacks are assigned to the respective hooks.

There is a set of one time hooks at different levels of initialization of the HW and Zephyr OS, a hook to process possible command line arguments, and, a hook that can be used to sniff or capture interrupts. bs_tests also provides a hook which will be called from the embedded application main(), but this will only work if the main application supports it, that is, if the main app is a version for simulation which calls bst_main() when running in the bsim board.

Apart from these hooks, the bs_tests system provides facilities to build a dedicated test “task”. This will be executed in the HW models thread context, but will have access to all SW variables. This task will be driven with a special timer which can be configured to produce either periodic or one time ticks. When these ticks occur a registered test tick function will be called. This can be used to support the test logic, like run checks or perform actions at specific points in time. This can be combined with Babblesim’s tb_defs macros to build quite complex test tasks which can wait for a given amount of time, for conditions to be fulfilled, etc.

Note: When writing the tests with bs_tests one needs to be aware that other bs tests will probably be built with the same application, and that therefore the tests should not be registering initialization or callback functions using NATIVE_TASKS or Zephyr’s PRE/POST kernel driver initialization APIs as this will execute even if the test is not selected. Instead the equivalent bs_tests provided hooks should be used.

Command line argument parsing

bsim boards need to handle command line arguments. There are several sets of arguments:

  • Basic arguments: to enable selecting things like trace verbosity, random seed, simulation device number and simulation id (when connected to a phy), etc. This follow as much as possible the same convention as other bsim devices to ease use for developers.

  • The HW models command line arguments: The HW models will expose which arguments they need to have processed, but the bsim board as actual integrating program ensures they are handled.

  • Test (bs_tests) control: To select a test, print which are available, and pass arguments to the tests themselves.

Command line argument parsing is handled by using the bs_cmd_line component from Babblesim’s base/libUtilv1 library. And basic arguments definitions that comply with the expected convention are provided in bs_cmd_line_typical.h.

Other considerations

  • Endianness: Code will be built for the host target architecture, which is typically x86. x86 is little endian, which is typically also the case for the target architecture. If this is not the case, embedded code which works in one may not work in the other due to endianness bugs. Note that Zephyr code is be written to support both big and little endian.

  • WordSize: The bsim targets, as well as normal embedded targets are 32 bit targets. In the case of the bsim targets this is done by explicitly targeting x86 (ILP32 ABI) instead of x86_64. This is done purposefully to provide more accurate structures layout in memory and therefore better reproduce possible issues related to access to structures members or array overflows.