zephyr
/
nrf_hw_models
mirror of https://github.com/zephyrproject-rtos/nrf_hw_models.git
1
0
Fork 0
Code Issues Releases Wiki Activity

doc: Update as we now have also nrf5340 models 

And remove non ASCII characters,
and align internal implementation description with the
new naming convention.

Signed-off-by: Alberto Escolar Piedras <alberto.escolar.piedras@nordicsemi.no>
This commit is contained in:
Alberto Escolar Piedras 2023-09-29 16:00:26 +02:00
parent f4595802d3
commit 54e6e57bc4
4 changed files with 99 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/GPIO.md
View File

@ -53,8 +53,8 @@ time(microsecond),port,pin,level
101624,0,0,1
```
Where pin 0 in port 0, is toggled at boot, 200µs, 600µs, 800µs, 1ms (up and immediately down),
and 101.624ms.
Where pin 0 in port 0, is toggled at boot, 200microseconds, 600microseconds, 800microseconds, 1ms
(up and immediately down), and 101.624ms.
### Configuration file format
@ -82,7 +82,7 @@ For example:
short 0.1 1.2
short 0.1 1.3
```
To short pint 1 from port 0, to both pins 2 and 3 from port 1,<br>
To short pin 1 from port 0, to both pins 2 and 3 from port 1,<br>
```
short 1.0 0.2

19
docs/README.md
View File

@ -5,11 +5,14 @@ HAL functions. When used in combination with the real nrfx, these should enable
meant for the nrfx to run without needing further changes.
This includes Zephyr SW.
Where relevant
[differences](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fstruct_nrf52%2Fstruct%2Fnrf52.html&cp=5)
exist, these models try to align with an
[nRF52833](https://infocenter.nordicsemi.com/topic/struct_nrf52/struct/nrf52833.html?cp=5_1).
Though it is the intention that models of other nordic SOCs will be included in the future.
These models include models of peripherals for an
[nRF52833](https://infocenter.nordicsemi.com/topic/struct_nrf52/struct/nrf52833.html?cp=5_1)
and an [nRF5340](https://infocenter.nordicsemi.com/topic/struct_nrf53/struct/nrf5340.html?cp=4_0).
<br> Note that for these models use case an nRF52833 is very similar to other
[nRF52 series devices](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fstruct_nrf52%2Fstruct%2Fnrf52.html&cp=5)
, so even if you are developing for another variant in that series these models may be enough for
you.<br>
It is the intention that models of other nordic SOCs will be included in the future.
These models library is intended to be used as an extension to the
[native simulator](https://github.com/BabbleSim/native_simulator/).
@ -44,12 +47,12 @@ default.
The NRF_RADIO peripheral model uses [BabbleSim](http://babblesim.github.io)
for the radio environment simulation.
For more information about the HW models, or how to use them without the
nrf52_bsim please refer to [README_HW_models.md](./README_HW_models.md)
For more information about the HW models, or how to use them without
Zephyr please refer to [README_HW_models.md](./README_HW_models.md)
## What these models include
Not all SOC peripherals are modelled yet, and for some of the included peripherals
Not all SOCs peripherals are modelled yet, and for some of the included peripherals
not all features or options are modelled. This is typically the case for HW functionality
which is not used by the Zephyr drivers/OS.
You can find what features of which peripherals are included so far, and with what approximations in

51
docs/README_HW_models.md
View File

@ -2,7 +2,7 @@ For general information about these models refer to [README.md](README.md)
You will only need to continue reading if you are curious about how these
models are built, or if you want to use them for some other purpose than
with Zephyr's nrf52_bsim.
with Zephyr's nrf5*_bsim.
## Requirements
@ -13,8 +13,8 @@ We are not interested in modelling the particularities of the HW when
they are not relevant for the SW execution.
Therefore many details can be simplified or omited all together.
The focus of these models is on the Zephyr BLE stack, and therefore
only the peripherals which are necessary for its proper function have
The focus of these models is on the BLE and 15.4 stacks, and therefore
mostly the peripherals which are necessary for its proper function have
been modelled so far.
Regarding the time accuracy, these models will focus mostly on the radio
@ -61,13 +61,13 @@ The overall HW scheduler provided by the native_simulator, will advance simulate
when needed, and call into the corresponding HW submodule "event|task runner"
whenever its event time is reached.
Note that several HW submodules may be scheduled to run in the same µs.
In this case, they will be handled in different "delta cycles" in that same µs.
Note that several HW submodules may be scheduled to run in the same microsecond.
In this case, they will be handled in different "delta cycles" in that same microsecond.
Each timer|event has a given priority, and therefore will always be called
in the same order relative to other HW events which may be schedule in the
same µs.<br>
same microsecond.<br>
Note also, that any HW submodule may schedule a new event to be called in the
same µs in which it is running. This can be done for any purpose,
same microsecond in which it is running. This can be done for any purpose,
like for example to deffer a sideeffect of writing to a register from a SW
thread into the HW models thread.
When they do so, their "event|task runner" will be called right after in the
@ -81,8 +81,8 @@ This structure will be allocated somewhere in the process memory, but certainly
not in the same address as in the real HW.
Therefore any access to the real registers must be, in someway, corrected
to access this structure instead.
In Zephyr's nrf52_bsim case, this is achieved by providing a version of the
macros which, in real point to the peripherals base addresses, which points
In Zephyr's nrf5*_bsim case, this is achieved by providing a version of the
macros which, in real HW point to the peripherals base addresses, which points
to these structures.
Writing to this structure in itself will only cause that memory location to be
@ -95,26 +95,27 @@ For example, in real HW, writting a `1` to
`NRF_RNG->TASKS_START` will start the random number generation.
For these type of registers with sideeffects, the HW models must be triggered,
this is achieved by calling `nrf_<periperal>_regw_sideeffects_<register name>()`
this is achieved by calling `nhw_<periperal>_regw_sideeffects_<register name>()`
after the write itself.
In the nrf52_bsim case, this is done in the replacement nRFx HAL function.
In Zephyr's nrf5*_bsim case, this is done in the replacement nRFx HAL function.
### HW interrupts
For a HW model to raise an interrupt all it will need to do is call into the
interrupt controller model function `hw_irq_ctrl_set_irq(<irq_nbr>)`.
interrupt controller model functions
`hw_irq_ctrl_raise/lower_level_irq_line(<cpu_nbr>, <irq_number>)`.
The interrupt controller will update its status, and if the interrupt was not
masked, one delta cycle later, awake the CPU by calling
`posix_interrupt_raised()`.
masked, one delta cycle later, awake the CPU by calling the corresponding
`nsif_cpun_irq_raised(<cpu_nbr>)`.
In the nrf52_bsim `posix_interrupt_raised()` is provided by the Zephyr
POSIX arch `inf_clock`.
In Zephyr's nrf5*_bsim `nsif_cpun_irq_raised(<cpu_nbr>)` is provided by the Zephyr
board code.
### Structure of the HW models:
The actual HW models of the SOC peripherals are split in one file per peripheral.
The files are named `NRF_<PERIPHERAL>.{c|h}`.
The files are named `NHW_<PERIPHERAL>.{c|h}`.
Mostly all these models have the following functions:
@ -129,14 +130,14 @@ These models use:
Overall, they follow a pattern where each peripheral has these types of functions:
```
nrf_<periperal>_init() : To initialize the model
nrf_<periperal>_cleanup() : To free any resources used by the model
nrf_<periperal>_<TASK name>() : Perform the actions triggered by <TASK>
nrf_<periperal>_regw_sideeffects_<register name>()
nhw_<periperal>_init() : To initialize the model
nhw_<periperal>_cleanup() : To free any resources used by the model
nhw_<periperal>_<TASK name>() : Perform the actions triggered by <TASK>
nhw_<periperal>_regw_sideeffects_<register name>()
: Trigger any possible sideeffect from writing
to that regiter
Timer_<peripheral> &
nrf_<periperal>_timer_triggered() : Models which take time to perform their work
nhw_<periperal>_timer_triggered() : Models which take time to perform their work
Use a registered event. When that event timer
is reached, this function is called to perform
any neccessary step, including update that
@ -154,7 +155,7 @@ specified in the linked documentation.
## Integrating these models in another system
This subsection provides information you would need if you try to use
these models without the nrf52_bsim wrapping logic.
these models without Zephyr's nrf5*_bsim wrapping logic.
### Models interface towards a simulation scheduler
@ -206,7 +207,7 @@ Meaning, only one function may be called at a time.<br>
This is not going to be a problem if only one thread calls into the HW models.
It won't be a problem either if by any other synchronization mechanism it is
ensured only one thread calls into these HW models at a time.
(this second case is how it is done in the nrf52_bsim)
(this second case is how it is done in Zephyr's nrf5*_bsim)
### Command line intercace arguments
@ -217,5 +218,5 @@ The integration program should support this.
The way to describe the command line arguments follows Babblesim's
`libUtilv1` command line parsing convention.
You can check the nrf52_bsim wrapping code for an insight on how
You can check Zephyr's nrf5*_bsim wrapping code for an insight on how
you can use these component.

138
docs/README_impl_status.md
View File

@ -1,84 +1,64 @@
# Current implementation status
Currently these models aim at modelling the peripherals of a nRF52833 SOC at varying degrees:
Currently peripherals of a nRF52833 and nrf5340 SOCs are modelled at varying degrees:
* &#x2713; **NVMC** — Non-volatile memory controller
* See [NRF_NVMC.c](../src/HW_models/NRF_NVMC.c)
* &#x2713; **FICR** — Factory information configuration registers
* See [NRF_FICR.c](../src/HW_models/NRF_FICR.c)
* &#x2713; **UICR** — User information configuration registers
* See [NRF_NVMC.c](../src/HW_models/NRF_NVMC.c)
* &#x10102; **POWER** — Power supply
* Only register stubs
* &#x2713; **CLOCK** — Clock control
* See [NRF_CLOCK.c](../src/HW_models/NRF_CLOCK.c)
* &#x2713; **AAR** — Accelerated address resolver
* See [NRF_AAR.c](../src/HW_models/NRF_AAR.c)
* &#x10102; **ACL** — Access control lists
* Not modelled yet
* &#x2713; **CCM** — AES CCM mode encryption
* See [NRF_AES_CCM.c](../src/HW_models/NRF_AES_CCM.c)
* &#x10102; **COMP** — Comparator
* Not modelled yet
* &#x2714; **ECB** — AES electronic codebook mode encryption
* Complete
* &#x2714; **EGU** — Event generator unit
* Complete
* &#x2713; **GPIO** — General purpose input/output
* See [NRF_GPIO.c](../src/HW_models/NRF_GPIO.c)
* &#x2714; **GPIOTE** — GPIO tasks and events
* Complete with very minor differences
* See [NRF_GPIOTE.c](../src/HW_models/NRF_GPIOTE.c)
* &#x10102; **I2S** — Inter-IC sound interface
* Not modelled yet
* &#x10102; **LPCOMP** — Low-power comparator
* Not modelled yet
* &#x10102; **MWU** — Memory watch unit
* Not modelled yet
* &#x10102; **NFCT** — Near field communication tag
* Not modelled yet
* &#x10102; **PDM** — Pulse density modulation interface
* Not modelled yet
* &#x2714; **PPI** — Programmable peripheral interconnect
* Complete but some peripheral connections are missing
* &#x10102; **PWM** — Pulse width modulation
* Not modelled yet
* &#x10102; **QDEC** — Quadrature decoder
* Not modelled yet
* &#x2713; **RADIO** — 2.4 GHz radio
* See [NRF_RADIO.c](../src/HW_models/NRF_RADIO.c)
* &#x2713; **RNG** — Random number generator
* See [NRF_RNG.c](../src/HW_models/NRF_RNG.c)
* &#x2713; **RTC** — Real-time counter
* See [NRF_RTC.c](../src/HW_models/NRF_RTC.c)
* &#x10102; **SAADC** — Successive approximation analog-to-digital converter
* Not modelled yet
* &#x10102; **SPI** — Serial peripheral interface master
* Not modelled yet
* &#x10102; **SPIM** — Serial peripheral interface master with EasyDMA
* Not modelled yet
* &#x10102; **SPIS** — Serial peripheral interface slave with EasyDMA
* Not modelled yet
* &#x2714; **SWI** — Software interrupts
* See EGU
* &#x2713; **TEMP** — Temperature sensor
* See [NRF_TEMP.c](../src/HW_models/NRF_TEMP.c)
* &#x10102; **TWI** — I2C compatible two-wire interface
* Not modelled yet
* &#x2714; **TIMER** — Timer/counter
* Complete
* &#x10102; **TWIM** — I2C compatible two-wire interface master with EasyDMA
* Not modelled yet
* &#x10102; **TWIS** — I2C compatible two-wire interface slave with EasyDMA
* Not modelled yet
* &#x10102; **UART** — Universal asynchronous receiver/transmitter
* Not modelled yet
* &#x10102; **UARTE** — Universal asynchronous receiver/transmitter with EasyDMA
* Not modelled yet
* &#x10102; **USBD** — Universal serial bus device
* Not modelled yet
* &#x10102; **WDT** — Watchdog timer
* Not modelled yet
Notation:
| Mark | Meaning |
|---|---|
|&#x2714;| Fully completed |
|&#x2705;| Implemented |
|&#x2610;| Minimal/stubbed implementation |
|&#x10102;| Missing |
ARM processor peripherals or the AHB interconnect are not part of these models
<br>
| | | **nRF52833** | **nRF5340** | Notes |
|---|---|---|---|---|
| **AAR** | Accelerated address resolver | &#x2705; | &#x2705; | See [NRF_AAR.c](../src/HW_models/NRF_AAR.c) |
| **ACL** | Access control lists | &#x10102; | &#x10102; | |
| **CACHE** | Instruction/data cache | N/A | &#x10102; | |
| **CCM** | AES CCM mode encryption | &#x2705; | &#x2705; | See [NRF_AES_CCM.c](../src/HW_models/NRF_AES_CCM.c) |
| **CLOCK** | Clock control | &#x2705; | &#x2705; | See [NRF_CLOCK.c](../src/HW_models/NRF_CLOCK.c) |
| **COMP** | Comparator | &#x10102; | &#x10102; | |
| **DPPI** | Distributed programmable peripheral interconnect | N/A | &#x2714; | |
| **ECB** | AES electronic codebook mode encryption | &#x2714; | &#x2714; | |
| **EGU** | Event generator unit | &#x2714; | &#x2714; | |
| **FICR** | Factory information configuration registers | &#x2705; | &#x2705; | See [NRF_FICR.c](../src/HW_models/NRF_FICR.c) |
| **GPIO** | General purpose input/output | &#x2705; | &#x10102; | For 52: See [NRF_GPIO.c](../src/HW_models/NRF_GPIO.c) |
| **GPIOTE** | GPIO tasks and events | &#x2714; | &#x10102; | For 52: Complete with very minor differences, see [NRF_GPIOTE.c](../src/HW_models/NRF_GPIOTE.c) |
| **I2S** | Inter-IC sound interface | &#x10102; | &#x10102; | |
| **IPC** | Interprocessor communication | &#x10102; | &#x10102; | |
| **KMU** | Key management unit | &#x10102; | &#x10102; | |
| **LPCOMP** | Low-power comparator | &#x10102; | &#x10102; | |
| **MUTEX** | Mutual exclusive peripheral | N/A | &#x10102; | |
| **MWU** | Memory watch unit | &#x10102; | N/A | |
| **NFCT** | Near field communication tag | &#x10102; | &#x10102; | |
| **NVMC** | Non-volatile memory controller | &#x2705; | &#x2705; | See [NRF_NVMC.c](../src/HW_models/NRF_NVMC.c) |
| **OSCILLATORS** | Oscillator control | N/A | &#x10102; | |
| **PDM** | Pulse density modulation interface | &#x10102; | &#x10102; | |
| **POWER** | Power supply | &#x2610; | &#x2610; | Only register stubs |
| **PPI** | Programmable peripheral interconnect | &#x2714; | N/A | Complete but some peripheral connections are missing |
| **PWM** | Pulse width modulation | &#x10102; | &#x10102; | |
| **QDEC** | Quadrature decoder | &#x10102; | &#x10102; | |
| **RADIO** | 2.4 GHz radio | &#x2705; | &#x2705; | See [NRF_RADIO.c](../src/HW_models/NRF_RADIO.c) |
| **REGULATORS** | Regulator control | N/A | &#x10102; | |
| **RESET** | Reset control | N/A | &#x2610; | Only register stubs |
| **RNG** | Random number generator | &#x2705; | &#x2705; | See [NRF_RNG.c](../src/HW_models/NRF_RNG.c) |
| **RTC** | Real-time counter | &#x2705; | &#x2705; | See [NRF_RTC.c](../src/HW_models/NRF_RTC.c) |
| **SAADC** | Successive approximation analog-to-digital converter | &#x10102; | &#x10102; | |
| **[Q]SPI[M/S]** | [Quad] Serial peripheral interface [master/slave] | &#x10102; | &#x10102; | |
| **SPU** | System protection unit | N/A | &#x10102; | |
| **SWI** | Software interrupts | &#x2714; | &#x2714; | |
| **TEMP** | Temperature sensor | &#x2705; | &#x2705; | See [NRF_TEMP.c](../src/HW_models/NRF_TEMP.c) |
| **TIMER** | Timer/counter | &#x2714; | &#x2714; | |
| **TWI[M/S]** | I2C compatible two-wire interface | &#x10102; | &#x10102; | |
| **UART[E]** | Universal asynchronous receiver/transmitter [with EasyDMA] | &#x10102; | &#x10102; | |
| **UICR** | User information configuration registers | &#x2705; | &#x2705; | See [NRF_NVMC.c](../src/HW_models/NRF_NVMC.c) |
| **USBD** | Universal serial bus device | &#x10102; | &#x10102; | |
| **USBREG** | Universal serial bus device | N/A | &#x10102; | |
| **VREQCTRL** | Voltage request control | N/A | &#x2610; | Only register stubs |
| **VMC** | Volatile memory controller | N/A | &#x10102; | |
| **WDT** | Watchdog timer | &#x10102; | &#x10102; | |
ARM processor peripherals or the AHB interconnect are not part of these models