1.. _nrf5340bsim:
2
3NRF5340 simulated boards (BabbleSim)
4####################################
5
6.. contents::
7   :depth: 1
8   :backlinks: entry
9   :local:
10
11
12Overview
13********
14
15To allow simulating nrf5340 SOCs two Zephyr target boards are provided: the
16``nrf5340bsim_nrf5340_cpuapp`` and ``nrf5340bsim_nrf5340_cpunet``.
17
18These use `BabbleSim`_ to simulate the radio activity, and the
19:ref:`POSIX architecture<Posix arch>` and the `native simulator`_ to
20run applications natively on the development system. This has the benefit of
21providing native code execution performance and easy debugging using
22native tools, but inherits :ref:`its limitations <posix_arch_limitations>`.
23
24Just like for the nrf5340dk targets,
25the nrf5340bsim_nrf5340_cpuapp build target provides support for the application core,
26and the nrf5340bsim_nrf5340_cpunet build target provides support for the network
27core on the simulated nRF5340 SOC.
28
29These boards include models of some of the nRF5340 SOC peripherals:
30
31* Radio
32* Timers
33* AAR (Accelerated Address Resolver)
34* AES CCM & AES ECB encryption HW
35* CLOCK (Clock control)
36* DPPI (Distributed Programmable Peripheral Interconnect)
37* EGU (Event Generator Unit)
38* FICR (Factory Information Configuration Registers)
39* NVMC (Non-Volatile Memory Controller / Flash)
40* RNG (Random Number Generator)
41* RTC (Real Time Counter)
42* TEMP (Temperature sensor)
43* UICR (User Information Configuration Registers)
44
45and will use the same drivers as the nrf5340dk targets for these.
46For more information on what is modelled to which level of detail,
47check the `HW models implementation status`_.
48
49.. note::
50
51   The IPC and MUTEX peripherals are not yet present in these models. Therefore communication
52   between the cores using Zephyr's IPC driver is not yet possible.
53
54Note that unlike a real nrf5340 device, the nrf5340bsim boards have unlimited RAM and flash for
55code.
56
57.. _BabbleSim:
58   https://BabbleSim.github.io
59
60.. _native simulator:
61   https://github.com/BabbleSim/native_simulator/blob/main/docs/README.md
62
63.. _HW models implementation status:
64   https://github.com/BabbleSim/ext_nRF_hw_models/blob/main/docs/README_impl_status.md
65
66
67Building for, and using these boards
68************************************
69
70If you are interested in developing on only one of the MCUs in this SOC, you
71can use the corresponding simulated target, nrf5340bsim_nrf5340_cpuapp or nrf5340bsim_nrf5340_cpunet
72following the instructions from the :ref:`nrf52_bsim board <nrf52bsim_build_and_run>`.
73Simply change the board/target appropriately when building.
74
75
76.. note::
77
78   Unlike in real HW, the net core MCU is set-up to automatically boot at start, to facilitate
79   developing without an image in the application core. You can control
80   this with either :kconfig:option:`CONFIG_NATIVE_SIMULATOR_AUTOSTART_MCU`, or the command line
81   option ``--cpu1_autostart``.
82
83   If an MCU is booted without any image, it will automatically set itself to sleep.
84
85
86Assembling both MCUs images into a single executable
87****************************************************
88
89By default, when you build targeting either nrf5340bsim_nrf5340_cpuapp or
90nrf5340bsim_nrf5340_cpunet you will end up with a library (``zephyr/zephyr.elf``) that corresponds
91to that MCU code image, and an executable (``zephyr/zephyr.exe``) that includes the native simulator
92runner, SOC HW models, that image, and an empty image for the other MCU.
93
94If you want to assemble an executable including a previously built image for the other MCU,
95built with either Zephyr's build system or another native simulator compatible build system,
96you can provide that image to the Zephyr build of the second image using
97:kconfig:option:`CONFIG_NATIVE_SIMULATOR_EXTRA_IMAGE_PATHS`.
98
99
100.. note::
101
102   These libraries/images are **not** embedded images. You cannot use them for embedded devices,
103   and cannot use an embedded image to assemble a native executable.
104
105.. note::
106
107   OpenAMP is not yet supported in these boards.
108
109TrustZone, TF-M and other security considerations
110*************************************************
111
112ARM's TrustZone is not modelled in these boards. This means that:
113
114* There is no differentiation between secure and non secure execution states or bus accesses.
115* All RAM, flash and peripherals are in principle accessible from all SW. Peripherals with their
116  own interconnect master ports can, in principle, access any other peripheral or RAM area.
117* There is no nrf5340bsim_nrf5340_cpuapp_ns board/build target, or posibility of mixing secure
118  and non-secure images.
119* Currently there is no model of the SPU, and therefore neither flash, RAM areas or peripherals
120  can be labelled as restricted for secure or non secure access.
121* TF-M cannot be used.
122
123Note that the ARM cryptocell-312 peripheral is not modelled. The mbedTLS library can still be used
124but with a SW crypto backend instead of the cryptocell HW acceleration.
125