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