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)
10and an [nRF5340](https://infocenter.nordicsemi.com/topic/struct_nrf53/struct/nrf5340.html?cp=4_0).
11<br> Note that for these models use case an nRF52833 is very similar to other
12[nRF52 series devices](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fstruct_nrf52%2Fstruct%2Fnrf52.html&cp=5)
13, so even if you are developing for another variant in that series these models may be enough for
14you.<br>
15It is the intention that models of other nordic SOCs will be included in the future.
16
17These models library is intended to be used as an extension to the
18[native simulator](https://github.com/BabbleSim/native_simulator/).
19If you want to integrate them in another way, please check the section
20"Using these models without the native simulator" below.
21
22When compiling this component using the provided Makefile (not with Zephyr's build system),
23the environment variable `NRFX_BASE` and `NATIVE_SIM_PATH` must be set.
24`NRFX_BASE` must point to the path where nrfx has been cloned.
25The nrfx must be at least version 3.2.0.
26So for example, if nrfx has been cloned as:
27
28```
29cd /some_path/nrfx/
30git clone git@github.com:NordicSemiconductor/nrfx.git .
31```
32`NRFX_BASE` must be set as:
33
34```
35export NRFX_BASE=/some_path/nrfx/
36```
37
38See the [nrfx/hal/README.md](../src/nrfx/hal/README.md) for more details.
39
40`NATIVE_SIM_PATH` must point to the folder where the native simulator has been cloned.
41
42These models can be used directly with
43[Zephyr's nrf52_bsim target](https://docs.zephyrproject.org/latest/boards/posix/nrf52_bsim/doc/index.html).
44In that case, Zephyr's versions of the nrfx HAL and native simulator will be used by
45default.
46
47The NRF_RADIO peripheral model uses [BabbleSim](http://babblesim.github.io)
48for the radio environment simulation.
49
50For more information about the HW models, or how to use them without
51Zephyr please refer to [README_HW_models.md](./README_HW_models.md)
52
53## What these models include
54
55Not all SOCs peripherals are modelled yet, and for some of the included peripherals
56not all features or options are modelled. This is typically the case for HW functionality
57which is not used by the Zephyr drivers/OS.
58You can find what features of which peripherals are included so far, and with what approximations in
59[README_impl_status.md](./README_impl_status.md).
60It is certainly possible to expand these models to include the missing peripherals or functionality.
61
62### Faithfullness of these models
63
64These models are accurate enough to allow the current Zephyr to run, and
65its BLE and 15.4 stacks to function. For more details please see the notes on the source
66files for each peripheral model.
67In general, functionality is modelled only to the necessary degree as to enable the SW to run,
68in a manner that is comparable to the real HW.
69
70These models are based solely on
71[the public SOC specifications](https://infocenter.nordicsemi.com/topic/struct_nrf52/struct/nrf52833.html)
72
73They have been developed without any other knowledge and probably contain
74inacuracies, and defects.
75
76### About the ARM processor peripherals
77
78These models do not include the ARM processor peripherals (for ex. the SCB)
79Even though it would be technically possible to add those, it is considered both
80risky and unnecessary.
81
82Risky in the sense that adding the equivalent register structures would
83immediately hide the compiler errors which otherwise would identify the places
84in which they are used in the embeded code; while at the same time these models
85would not be precise enough to not require, with very high likelyhood,
86modification of that part of the embedded code which was using them.
87
88And unnecessary in the sense that the lack of these peripherals can be hidden
89most of the time if the CMSIS-Core APIs are used instead of direct register
90accesses, and where these APIs do not provide the necessary functionality,
91changes to the embedded code would be needed with high likelyhood to trigger
92sideeffects or so.
93
94## Using these models without the native simulator
95
96These models are designed as an extension to the native simulator core/common components.
97It is in principle still possible to use them without the native simulator, but it will
98require more work/adaptation than with the previous version of these models.
99Therefore you may want to consider to:
100
101* Use the [previous version](https://github.com/BabbleSim/ext_NRF52_hw_models),
102 which did not require the native simulator.
103* Or to use these newer models, providing a shim/adaptation between the native simulator
104 interfaces the models expect and your execution framework. If so, check the
105 "Integrating these models in another system" section of the
106 [HW models README](README_HW_models.md)
107
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
5with Zephyr's nrf5*_bsim.
6
7## Requirements
8
9The purpose of these models is to provide a good enoug HW model for BLE
10protocol simulations, which will focus on the SW, to be able to debug it,
11and run long simulations fast.<br>
12We are not interested in modelling the particularities of the HW when
13they are not relevant for the SW execution.
14Therefore many details can be simplified or omited all together.
15
16The focus of these models is on the BLE and 15.4 stacks, and therefore
17mostly the peripherals which are necessary for its proper function have
18been modelled so far.
19
20Regarding the time accuracy, these models will focus mostly on the radio
21activity accuracy. With other peripherals being overall more rough. Note that
22as all models are based on public specifications, all peripherals timings
23could, anyhow, not be better than what is described in those.<br>
24Overall these models have a time granularity of 1us.
25
26## Implementation specification
27
28Overall these models are "event driven". There is several ways
29of building these kind of models, but for simplicity, these models are built
30using a very nimble engine provided by the native simulator, the "hw scheduler".
31
32### About the event scheduling
33
34In reality any action performed by a HW peripheral will take some amount of
35time.<br>
36For our purposes any HW process which takes too short for the SW to
37realize, will be modelled as being instantaneous in simulation time.
38Such processes will just be implemented as a C function (or a set of them),
39which will change the models status as needed.
40
41Other processes do take a considerable amount of time, like for example sending
42a radio packet, or generating a random number.<br>
43Such processes will be modelled in a bit more complex way:
44
45 * The process model may use one or several "events"/timers.
46 * When needed these timers will be set at a point in the future where some
47 action needs to be performed.
48 * Whenever that time is reached, the HW scheduler will call a function in that
49 model tasked with continuing executing that task/process.
50
51In this model, all of these events|timers types and their callbacks are known
52in compile time.
53Meaning, there is no dynamic registration of events types.<br>
54Normally each peripheral model will have 1 of such event timers, and it will
55be up to the peripheral model to schedule several subevents using only that
56one timer and callback if needed.
57
58Whenever a HW model updates its event timer, it will call a function in the HW scheduler.
59
60The overall HW scheduler provided by the native_simulator, will advance simulated time
61when needed, and call into the corresponding HW submodule "event|task runner"
62whenever its event time is reached.
63
64Note that several HW submodules may be scheduled to run in the same microsecond.
65In this case, they will be handled in different "delta cycles" in that same microsecond.
66Each timer|event has a given priority, and therefore will always be called
67in the same order relative to other HW events which may be schedule in the
68same microsecond.<br>
69Note also, that any HW submodule may schedule a new event to be called in the
70same microsecond in which it is running. This can be done for any purpose,
71like for example to deffer a sideeffect of writing to a register from a SW
72thread into the HW models thread.
73When they do so, their "event|task runner" will be called right after in the
74next delta cycle.
75
76### The SW registers IF
77
78Each peripheral model which has HW registers accessible by SW, presents
79a structure which matches those registers' layout.
80This structure will be allocated somewhere in the process memory, but certainly
81not in the same address as in the real HW.
82Therefore any access to the real registers must be, in someway, corrected
83to access this structure instead.
84In Zephyr's nrf5*_bsim case, this is achieved by providing a version of the
85macros which, in real HW point to the peripherals base addresses, which points
86to these structures.
87
88Writing to this structure in itself will only cause that memory location to be
89changed. For many registers this is perfectly fine, as that is just the same
90that happens in the real HW (a register is changed, which later may be
91read by the actual HW).<br>
92But for some registers, accesing them (writing and/or reading them) causes some
93sideeffect, that is, something else to happen in the HW.
94For example, in real HW, writting a `1` to
95`NRF_RNG->TASKS_START` will start the random number generation.
96
97For these type of registers with sideeffects, the HW models must be triggered,
98this is achieved by calling `nhw_<periperal>_regw_sideeffects_<register name>()`
99after the write itself.
100In Zephyr's nrf5*_bsim case, this is done in the replacement nRFx HAL function.
101
102### HW interrupts
103
104For a HW model to raise an interrupt all it will need to do is call into the
105interrupt controller model functions
106`hw_irq_ctrl_raise/lower_level_irq_line(<cpu_nbr>, <irq_number>)`.
107
108The interrupt controller will update its status, and if the interrupt was not
109masked, one delta cycle later, awake the CPU by calling the corresponding
110`nsif_cpun_irq_raised(<cpu_nbr>)`.
111
112In Zephyr's nrf5*_bsim `nsif_cpun_irq_raised(<cpu_nbr>)` is provided by the Zephyr
113board code.
114
115### Structure of the HW models:
116
117The actual HW models of the SOC peripherals are split in one file per peripheral.
118The files are named `NHW_<PERIPHERAL>.{c|h}`.
119
120Mostly all these models have the following functions:
121
122#### Interface:
123
124These models use:
125
126 * The native simulator HW scheduler to register the events timers and callbacks
127 * The native simulator "tasks" interface, to register their initialization and cleanup functions
128 to be called during the HW initialization and program exit.
129
130Overall, they follow a pattern where each peripheral has these types of functions:
131
132```
133nhw_<periperal>_init() : To initialize the model
134nhw_<periperal>_cleanup() : To free any resources used by the model
135nhw_<periperal>_<TASK name>() : Perform the actions triggered by <TASK>
136nhw_<periperal>_regw_sideeffects_<register name>()
137 : Trigger any possible sideeffect from writing
138 to that regiter
139Timer_<peripheral> &
140nhw_<periperal>_timer_triggered() : Models which take time to perform their work
141 Use a registered event. When that event timer
142 is reached, this function is called to perform
143 any neccessary step, including update that
144 event timer.
145```
146#### Internal:
147```
148signal_<event register name>() : Signal that <event> has just happened,
149 handle shortcuts, and raise interrupts.
150
151```
152The tasks, registers and event names should match the register interface
153specified in the linked documentation.
154
155## Integrating these models in another system
156
157This subsection provides information you would need if you try to use
158these models without Zephyr's nrf5*_bsim wrapping logic.
159
160### Models interface towards a simulation scheduler
161
162As described before, overall the models are "event driven":
163They rely on an overall scheduler triggering (calling) them in
164the appropriate times.
165
166By default this overall scheduler is provided by the native simulator
167HW scheduler.
168
169The models register their events, their timers, callbacks and priorities with
170`NSI_HW_EVENT(timer, callback, priority)`.
171When two events times coincide, the one with the highest priority should be run first,
172and when two have the same priority, it does not matter which is run first, while
173they are run in the same order consistently.
174
175The events timers represent, in microseconds, when the models need to perform
176the next action.
177
178It is the responsability of that overall scheduler to ensure the HW models
179are called whenever their time is reached (and not later).
180
181These event timers may be changed after each execution of the models, or whenever
182a HW register is written.
183When the models change this timer, they will call `nsi_hws_find_next_event()` to
184notify that overall scheduler of the change.
185
186The models are initalized by calling their registered initialization functions
187(`NSI_TASK(*, HW_INIT, *);`)
188Similarly, on program exit, the models cleanup functions registered
189with `NSI_TASK(*, ON_EXIT_*, *);` should be called, to free any system resources.
190
191Some of these models will also require being called very early during the process
192execution to register command line arguments.
193These are registered with `NSI_TASK(*, PRE_BOOT_1, *);`
194
195### Models interface towards a CPU model:
196
197For details about the SW register IF please see check the
198"The SW registers IF" section above.
199For details about how interrupts are raised see "HW interrupts" above.
200
201### Thread safety
202
203This HW models API is NOT thread safe: This means a call to one of the
204HW models functions cannot be done if another thread of the same process
205is currently also calling another of these functions.
206Meaning, only one function may be called at a time.<br>
207This is not going to be a problem if only one thread calls into the HW models.
208It won't be a problem either if by any other synchronization mechanism it is
209ensured only one thread calls into these HW models at a time.
210(this second case is how it is done in Zephyr's nrf5*_bsim)
211
212### Command line interface arguments
213
214These models register their own command line arguments/options using
215babblesim's command line argument utilities.
216The integration program should support this.
217
218The way to describe the command line arguments follows Babblesim's
219`libUtilv1` command line parsing convention.
220
221You can check Zephyr's nrf5*_bsim wrapping code for an insight on how
222you can use these component.
223
