Name |
Date |
Size |
#Lines |
LOC |
||
|---|---|---|---|---|---|---|
| .. | - | - | ||||
| GPIO.md | D | 18-Mar-2025 | 4.3 KiB | 127 | 95 | |
| LICENSE | D | 18-Mar-2025 | 11.5 KiB | 210 | 175 | |
| RADIO_states.svg | D | 18-Mar-2025 | 191.9 KiB | 4 | 3 | |
| README.md | D | 18-Mar-2025 | 5.2 KiB | 110 | 85 | |
| README_HW_models.md | D | 18-Mar-2025 | 10.5 KiB | 234 | 181 | |
| README_impl_status.md | D | 18-Mar-2025 | 14.4 KiB | 76 | 69 | |
| Rx_Phy_paths.svg | D | 18-Mar-2025 | 554.9 KiB | 4 | 3 | |
| UART.md | D | 18-Mar-2025 | 4.8 KiB | 102 | 76 |
README.md
1# Models of the nRF5xxxx SOCs HW peripherals 2 3This repo contains models of the nRF5x HW peripherals and some replacement nrfx 4HAL functions. When used in combination with the real nrfx, these should enable code 5meant for the nrfx to run without needing further changes. 6This includes Zephyr SW. 7 8These models include models of peripherals for an 9[nRF52833](https://infocenter.nordicsemi.com/topic/struct_nrf52/struct/nrf52833.html?cp=5_1), 10an [nRF5340](https://infocenter.nordicsemi.com/topic/struct_nrf53/struct/nrf5340.html?cp=4_0), 11and [nRF54L15](https://www.nordicsemi.com/Products/nRF54L15) 12<br> Note that for these models use case, an nRF52833 is very similar to other 13[nRF52 series devices](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fstruct_nrf52%2Fstruct%2Fnrf52.html&cp=5) 14, so even if you are developing for another variant in that series these models may be enough for 15you.<br> 16Similarly, as the nRF54L15, L10 and L05 only differ in the amount of available RAM and RRAM either 17can be simulated using the nRF54L15 models variant.<br> 18It is the intention that models of other Nordic SOCs will be included in the future. 19 20These models library is intended to be used as an extension to the 21[native simulator](https://github.com/BabbleSim/native_simulator/). 22If you want to integrate them in another way, please check the section 23"Using these models without the native simulator" below. 24 25When compiling this component using the provided Makefile (not with Zephyr's build system), 26the environment variable `NRFX_BASE` and `NATIVE_SIM_PATH` must be set. 27`NRFX_BASE` must point to the path where nrfx has been cloned. 28The nrfx must be at least version 3.2.0 for the 52 models, and 3.6.0 for the 54L15 models. 29So for example, if nrfx has been cloned as: 30 31``` 32cd /some_path/nrfx/ 33git clone git@github.com:NordicSemiconductor/nrfx.git . 34``` 35`NRFX_BASE` must be set as: 36 37``` 38export NRFX_BASE=/some_path/nrfx/ 39``` 40 41See the [nrfx/hal/README.md](../src/nrfx/hal/README.md) for more details. 42 43`NATIVE_SIM_PATH` must point to the folder where the native simulator has been cloned. 44 45These models can be used directly with 46[Zephyr's nrf5*bsim targets](https://docs.zephyrproject.org/latest/boards/native/doc/bsim_boards_design.html). 47In that case, Zephyr's versions of the nrfx HAL and native simulator will be used by 48default. 49 50The NRF_RADIO peripheral model uses [BabbleSim](http://babblesim.github.io) 51for the radio environment simulation. 52 53For more information about the HW models, or how to use them without 54Zephyr please refer to [README_HW_models.md](./README_HW_models.md) 55 56## What these models include 57 58Not all SOCs peripherals are modeled yet, and for some of the included peripherals 59not all features or options are modeled. This is typically the case for HW functionality 60which is not used by the Zephyr drivers/OS. 61You can find what features of which peripherals are included so far, and with what approximations in 62[README_impl_status.md](./README_impl_status.md). 63It is certainly possible to expand these models to include the missing peripherals or functionality. 64 65### Faithfulness of these models 66 67These models are accurate enough to allow the current Zephyr to run, and 68its BLE and 15.4 stacks to function. For more details please see the notes on the source 69files for each peripheral model. 70In general, functionality is modeled only to the necessary degree as to enable the SW to run, 71in a manner that is comparable to the real HW. 72 73These models are based solely on 74[the public SOC specifications](https://infocenter.nordicsemi.com/topic/struct_nrf52/struct/nrf52833.html) 75 76They have been developed without any other knowledge and probably contain 77inaccuracies, and defects. 78 79### About the ARM processor peripherals 80 81These models do not include the ARM processor peripherals (for ex. the SCB) 82Even though it would be technically possible to add those, it is considered both 83risky and unnecessary. 84 85Risky in the sense that adding the equivalent register structures would 86immediately hide the compiler errors which otherwise would identify the places 87in which they are used in the embedded code; while at the same time these models 88would not be precise enough to not require, with very high likelihood, 89modification of that part of the embedded code which was using them. 90 91And unnecessary in the sense that the lack of these peripherals can be hidden 92most of the time if the CMSIS-Core APIs are used instead of direct register 93accesses, and where these APIs do not provide the necessary functionality, 94changes to the embedded code would be needed with high likelihood to trigger 95side-effects or so. 96 97## Using these models without the native simulator 98 99These models are designed as an extension to the native simulator core/common components. 100It is in principle still possible to use them without the native simulator, but it will 101require more work/adaptation than with the previous version of these models. 102Therefore you may want to consider to: 103 104* Use the [previous version](https://github.com/BabbleSim/ext_NRF52_hw_models), 105 which did not require the native simulator. 106* Or to use these newer models, providing a shim/adaptation between the native simulator 107 interfaces the models expect and your execution framework. If so, check the 108 "Integrating these models in another system" section of the 109 [HW models README](README_HW_models.md) 110
README_HW_models.md
1For general information about these models refer to [README.md](README.md) 2 3You will only need to continue reading if you are curious about how these 4models are built, or if you want to use them for some other purpose than with 5[Zephyr's nrf*bsim targets](https://docs.zephyrproject.org/latest/boards/native/doc/bsim_boards_design.html). 6 7This file is a particularized version of the first sections of 8[the general HW models architecture description](https://babblesim.github.io/arch_hw_models.html) 9provided with BabbleSim. You may continue reading 10[that other page](https://babblesim.github.io/arch_hw_models.html) from the "Time and time drift" 11section after reading this file, for further information. 12 13## Requirements 14 15The main purpose of these models is to provide a good enough HW model for BLE and 802.15.4 16protocols simulations, which will focus on the SW, to be able to debug it, 17and run long simulations fast.<br> 18As a secondary requirement, we want the HW models to be accurate enough to run relevant real HW 19drivers. 20<br> 21We are not interested in modeling the particularities of the HW when 22they are not relevant for the SW execution. 23Therefore many details can be simplified or omitted all together. 24 25The focus of these models is on the BLE and 802.15.4 stacks, and therefore 26mostly the peripherals which are necessary for its proper function have 27been modeled so far. 28Apart from this, some other peripherals have been modeled to enable running applications which 29also utilize them, or to enable some level of runtime testing of their drivers. 30 31Regarding the time accuracy, these models primarily focus on the radio 32activity accuracy. With other peripherals being overall more rough. Note that 33as all models are based on public specifications, all peripherals timings 34could, anyhow, not be better than what is described in those.<br> 35Overall these models have a time granularity of 1us. 36 37## Implementation specification 38 39Overall these models are "event driven". There is several ways 40of building these kind of models, but for simplicity, these models are built 41using a very nimble engine provided by the native simulator, the "HW scheduler" (`nsi_hws`). 42 43### About the event scheduling 44 45In reality any action performed by a HW peripheral will take some amount of 46time.<br> 47For our purposes any HW process which takes too short for the SW to 48realize, will be modeled as being instantaneous in simulation time. 49Such processes will just be implemented as a C function (or a set of them), 50which will change the models status as needed. 51 52Other processes do take a considerable amount of time, like for example sending 53a radio packet, or generating a random number.<br> 54Such processes will be modeled in a bit more complex way: 55 56 * The process model may use one or several "events"/timers. 57 * When needed these timers will be set at a point in the future where some 58 action needs to be performed. 59 * Whenever that time is reached, the HW scheduler will call a function in that 60 model tasked with continuing executing that task/process. 61 62In this model, all of these events|timers types and their callbacks are known 63in compile time. 64Meaning, there is no dynamic registration of events types.<br> 65Normally each peripheral model will have 1 of such event timers, and it will 66be up to the peripheral model to schedule several subevents using only that 67one timer and callback if needed. 68 69Whenever a HW model updates its event timer, it will call a function in the HW scheduler. 70 71The overall HW scheduler provided by the native_simulator will advance simulated time 72when needed, and call into the corresponding HW submodule "event|task runner" 73whenever its event time is reached. 74 75Note that several HW submodules may be scheduled to run in the same microsecond. 76In this case, they will be handled in different "delta cycles" in that same microsecond. 77Each timer|event has a given priority, and therefore will always be called 78in the same order relative to other HW events which may be schedule in the 79same microsecond.<br> 80Note also, that any HW submodule may schedule a new event to be called in the 81same microsecond in which it is running. This can be done for any purpose, 82like for example to defer a side-effect of writing to a register from a SW 83thread into the HW models thread. 84When they do so, their "event|task runner" will be called right after in the 85next delta cycle. 86 87### The SW registers IF 88 89Each peripheral model which has HW registers accessible by SW, presents 90a structure which matches those registers' layout. 91This structure will be allocated somewhere in the process memory, but certainly 92not in the same address as in the real HW. 93Therefore any access to the real registers must be, in some way, corrected 94to access this structure instead. 95In Zephyr's nrf*bsim case, this is achieved by providing a version of the 96nRF HAL MDK macros which, in real HW point to the peripherals base addresses, which points 97to these structures. 98 99Writing to this structure in itself will only cause that memory location to be 100changed. For many registers this is perfectly fine, as that is just the same 101that happens in the real HW (a register is changed, which later may be 102read by the actual HW).<br> 103But for some registers, accessing them (writing and/or reading them) causes some 104side-effect, that is, something else to happen in the HW. 105For example, in real HW, writing a `1` to 106`NRF_RNG->TASKS_START` will start the random number generation. 107 108For these type of registers with side-effects, the HW models must be triggered, 109this is achieved by calling `nhw_<periperal>_regw_sideeffects_<register name>()` 110after the write itself. 111In Zephyr's nrf*bsim case, this is done in the replacement nRFx HAL function. 112 113### HW interrupts 114 115For a HW model to raise an interrupt all it will need to do is call into the 116interrupt controller model functions 117`hw_irq_ctrl_raise/lower_level_irq_line(<cpu_nbr>, <irq_number>)`. 118 119The interrupt controller will update its status, and if the interrupt was not 120masked, one delta cycle later, awake the CPU by calling the corresponding 121`nsif_cpun_irq_raised(<cpu_nbr>)`. 122 123In Zephyr's nrf*bsim `nsif_cpun_irq_raised(<cpu_nbr>)` is provided by the Zephyr 124board code. 125 126### Structure of the HW models: 127 128The actual HW models of the SOC peripherals are normally split in one file per peripheral. 129The files are named `NHW_<PERIPHERAL>.{c|h}`. 130 131Mostly all these models have the following functions: 132 133#### Interface: 134 135These models use: 136 137 * The native simulator HW scheduler to register the events timers and callbacks 138 * The native simulator "tasks" interface, to register their initialization and cleanup functions 139 to be called during the HW initialization and program exit. 140 141Overall, they follow a pattern where each peripheral has these types of functions: 142 143``` 144nhw_<periperal>_init() : To initialize the model 145nhw_<periperal>_cleanup() : To free any resources used by the model 146nhw_<periperal>_<TASK name>() : Perform the actions triggered by <TASK> 147nhw_<periperal>_regw_sideeffects_<register name>() 148 : Trigger any possible sideeffect from writing 149 to that regiter 150Timer_<peripheral> & 151nhw_<periperal>_timer_triggered() : Models which take time to perform their work 152 Use a registered event. When that event timer 153 is reached, this function is called to perform 154 any neccessary step, including update that 155 event timer. 156``` 157#### Internal: 158``` 159signal_<event register name>() : Signal that <event> has just happened, 160 handle shortcuts, and raise interrupts. 161 162``` 163The tasks, registers and event names should match the register interface 164specified in the linked documentation. 165 166## Integrating these models in another system 167 168This subsection provides information you would need if you try to use 169these models without Zephyr's nrf*bsim wrapping logic, and without the native simulator. 170 171### Models interface towards a simulation scheduler 172 173As described before, overall the models are "event driven": 174They rely on an overall scheduler triggering (calling) them in 175the appropriate times. 176 177By default this overall scheduler is provided by the native simulator 178HW scheduler. 179 180The models register their events, their timers, callbacks and priorities with 181`NSI_HW_EVENT(timer, callback, priority)`. 182When two events times coincide, the one with the highest priority should be run first, 183and when two have the same priority, for most, it does not matter which is run first, while 184they are run in the same order consistently. 185 186The events timers represent, in microseconds, when the models need to perform 187the next action. 188 189It is the responsibility of that overall scheduler to ensure the HW models 190are called whenever their time is reached (and not later). 191 192These event timers may be changed after each execution of the models, or whenever 193a HW register is written. 194When the models change this timer, they will call `nsi_hws_find_next_event()` to 195notify that overall scheduler of the change. 196 197The models are initialized by calling their registered initialization functions 198(`NSI_TASK(*, HW_INIT, *);`) 199Similarly, on program exit, the models cleanup functions registered 200with `NSI_TASK(*, ON_EXIT_*, *);` should be called, to free any system resources. 201 202Some of these models will also require being called very early during the process 203execution to register command line arguments. 204These are registered with `NSI_TASK(*, PRE_BOOT_1, *);` 205 206### Models interface towards a CPU model: 207 208For details about the SW register IF please see check the 209"The SW registers IF" section above. 210For details about how interrupts are raised see "HW interrupts" above. 211 212### Thread safety 213 214This HW models API is NOT thread safe: This means a call to one of the 215HW models functions cannot be done if another thread of the same process 216is currently also calling another of these functions. 217Meaning, only one function may be called at a time.<br> 218This is not going to be a problem if only one thread calls into the HW models. 219It won't be a problem either if by any other synchronization mechanism it is 220ensured only one thread calls into these HW models at a time. 221(this second case is how it is done in Zephyr's nrf*bsim targets) 222 223### Command line interface arguments 224 225These models register their own command line arguments/options using 226babblesim's command line argument utilities. 227The integration program should support this. 228 229The way to describe the command line arguments follows Babblesim's 230`libUtilv1` command line parsing convention. 231 232You can check Zephyr's nrf*bsim wrapping code for an insight on how 233you can use these component. 234
README_impl_status.md
1# Current implementation status 2 3Currently peripherals of nRF52833, nrf5340 and nrf54L15 SOCs are modeled at varying degrees: 4 5Notation: 6 7| Mark | Meaning | 8|---|---| 9| ✅ | Fully completed | 10| ✔ | Implemented | 11| ☐ | Minimal/stubbed implementation | 12| 𐄂 | Missing | 13 14<br> 15 16| | | **nRF52833** | **nRF5340** | **nRF54L15** | Notes | 17|-----------------|------------------------------------------------------------|--------------|-------------|--------------|----------------------------------------------------------------------------------------------------------------------------| 18| **AAR** | Accelerated address resolver | ✔ | ✔ | ✔ | See [NHW_AAR.c](../src/HW_models/NHW_AAR.c) or [NHW_54_AAR_CCM_ECB.c](../src/HW_models/NHW_54_AAR_CCM_ECB.c) | 19| **ACL** | Access control lists | 𐄂 | 𐄂 | N/A | | 20| **CACHE** | Instruction/data cache | N/A | 𐄂 | 𐄂 | | 21| **CCM** | AES CCM mode encryption | ✔ | ✔ | ✔ | See [NHW_AES_CCM.c](../src/HW_models/NHW_AES_CCM.c) or [NHW_54_AAR_CCM_ECB.c](../src/HW_models/NHW_54_AAR_CCM_ECB.c) | 22| **CLOCK** | Clock control | ✔ | ✔ | ☐ | For 52 & 53 see [NHW_CLOCK.c](../src/HW_models/NHW_CLOCK.c). For 54L see [NHW_54L_CLOCK.c](../src/HW_models/NHW_54L_CLOCK.c) | 23| **COMP** | Comparator | 𐄂 | 𐄂 | 𐄂 | | 24| **CRACEN.CRYPTO** | | N/A | N/A | ✔ | Only AES Crypto Engine (only ECB mode) | 25| **CRACEN.IKG** | | N/A | N/A | ☐ | | 26| **CRACEN.PK** | | N/A | N/A | ☐ | | 27| **CRACEN.RNG** | | N/A | N/A | ✔ | | 28| **DPPI** | Distributed programmable peripheral interconnect | N/A | ✅ | ✅ | | 29| **ECB** | AES electronic codebook mode encryption | ✅ | ✅ | ✔ | | 30| **EGU** | Event generator unit | ✅ | ✅ | ✅ | | 31| **FICR** | Factory information configuration registers | ✔ | ✔ | ✔ | For 52: See [NHW_52_FICR.c](../src/HW_models/NHW_52_FICR.c)<br>For 53: See [NHW_53_FICR.c](../src/HW_models/NHW_53_FICR.c) | 32| **GLITCHDET** | Voltage glitch detectors | N/A | N/A | 𐄂 | | 33| **GPIO** | General purpose input/output | ✔ | ✔ | ✔ | See [NRF_GPIO.c](../src/HW_models/NRF_GPIO.c) | 34| **GPIOTE** | GPIO tasks and events | ✅ | ✔ | ✔ | See [NRF_GPIOTE.c](../src/HW_models/NRF_GPIOTE.c) | 35| **GRTC** | Global real-time counter | N/A | N/A | ✔ | | 36| **I2S** | Inter-IC sound interface | 𐄂 | 𐄂 | 𐄂 | | 37| **IPC** | Interprocessor communication | N/A | ✔ | N/A | See [NHW_IPC.c](../src/HW_models/NHW_IPC.c) | 38| **KMU** | Key management unit | N/A | 𐄂 | 𐄂 | | 39| **LPCOMP** | Low-power comparator | 𐄂 | 𐄂 | 𐄂 | | 40| **MEMCONF** | Memory configuration | N/A | N/A | 𐄂 | | 41| **MPC** | Memory Privilege Controller | N/A | N/A | 𐄂 | | 42| **MUTEX** | Mutual exclusive peripheral | N/A | ✅ | N/A | | 43| **MWU** | Memory watch unit | ☐ | N/A | N/A | | 44| **NFCT** | Near field communication tag | ☐ | ☐ | ☐ | | 45| **NVMC** | Non-volatile memory controller | ✔ | ✔ | N/A | See [NHW_NVMC.c](../src/HW_models/NHW_NVMC.c) | 46| **OSCILLATORS** | Oscillator control | N/A | 𐄂 | 𐄂 | | 47| **PDM** | Pulse density modulation interface | 𐄂 | 𐄂 | 𐄂 | | 48| **POWER** | Power supply | ☐ | ☐ | ☐ | Only register stubs | 49| **PPI** | Programmable peripheral interconnect | ✅ | N/A | N/A | Complete but some peripheral connections are missing | 50| **PPIB** | PPI Bridge | N/A | N/A | ✔ | | 51| **PWM** | Pulse width modulation | 𐄂 | 𐄂 | 𐄂 | | 52| **QDEC** | Quadrature decoder | 𐄂 | 𐄂 | 𐄂 | | 53| **RADIO** | 2.4 GHz radio | ✔ | ✔ | ✔ | See [NHW_RADIO.c](../src/HW_models/NHW_RADIO.c) | 54| **REGULATORS** | Regulator control | N/A | 𐄂 | 𐄂 | | 55| **RESET** | Reset control | N/A | ☐ | ☐ | Only register stubs | 56| **RNG** | Random number generator | ✔ | ✔ | N/A | See [NHW_RNG.c](../src/HW_models/NHW_RNG.c) | 57| **RRAMC** | Resistive random access memory controller | N/A | N/A | ✔ | See [NHW_RRAMC.c](../src/HW_models/NHW_RRAMC.c) | 58| **RTC** | Real-time counter | ✔ | ✔ | N/A | See [NHW_RTC.c](../src/HW_models/NHW_RTC.c) | 59| **SAADC** | Successive approximation analog-to-digital converter | 𐄂 | 𐄂 | 𐄂 | | 60| **[Q]SPI[M/S]** | [Quad] Serial peripheral interface [master/slave] | 𐄂 | 𐄂 | 𐄂 | | 61| **SPU** | System protection unit | N/A | ☐ | ☐ | | 62| **SWI** | Software interrupts | ✅ | ✅ | ✅ | | 63| **TAMPC** | Tamper controller | N/A | N/A | 𐄂 | | 64| **TEMP** | Temperature sensor | ✔ | ✔ | ✔ | See [NHW_TEMP.c](../src/HW_models/NHW_TEMP.c) | 65| **TIMER** | Timer/counter | ✅ | ✅ | ✅ | | 66| **TWI[M/S]** | I2C compatible two-wire interface | 𐄂 | 𐄂 | 𐄂 | | 67| **UART[E]** | Universal asynchronous receiver/transmitter [with EasyDMA] | ✔ | ✔ | ✔ | | 68| **UICR** | User information configuration registers | ✔ | ✔ | ✔ | See [NHW_NVMC.c](../src/HW_models/NHW_NVMC.c) | 69| **USBD** | Universal serial bus device | 𐄂 | 𐄂 | N/A | | 70| **USBREG** | Universal serial bus device | N/A | 𐄂 | N/A | | 71| **VMC** | Volatile memory controller | N/A | 𐄂 | N/A | | 72| **VREQCTRL** | Voltage request control | N/A | ☐ | N/A | Only register stubs | 73| **WDT** | Watchdog timer | 𐄂 | 𐄂 | 𐄂 | | 74 75ARM processor peripherals or the AHB interconnect are not part of these models 76