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

doc: add board terminology section to board porting guide 

Add a terminology section to the board porting guide.
This provides a single location where terminologies used for boards can
be found and linked to.

Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
This commit is contained in:
Carles Cufi 2024-03-19 17:24:50 +01:00 committed by Carles Cufí
parent d05d51d869
commit 68eb97ea05
4 changed files with 166 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/develop/getting_started/index.rst
View File

@ -568,7 +568,7 @@ another sample.
cluster for which the sample must be built.
For example to build :zephyr:code-sample:`blinky` for the ``cpuapp`` core on
the :ref:`nRF5340DK <nrf5340dk_nrf5340>` the board must be provided as:
``nrf5340dk/nrf5340/cpuapp``. Also read :ref:`board_and_identifiers` for more
``nrf5340dk/nrf5340/cpuapp``. See also :ref:`board_terminology` for more
details.
Flash the Sample

65
doc/glossary.rst
View File

@ -35,10 +35,14 @@ Glossary of Terms
Both application code and kernel code execute as privileged code
within a single shared address space.
architecture
An instruction set architecture (ISA) along with a programming model.
board
A target system with a defined set of devices and capabilities,
which can load and execute an application image. It may be an actual
hardware system or a simulated system running under QEMU.
hardware system or a simulated system running under QEMU. A board can
contain one or more :term:`SoCs <SoC>`.
The Zephyr kernel supports a :ref:`variety of boards <boards>`.
board configuration
@ -49,6 +53,45 @@ Glossary of Terms
specified by the build system can be over-ridden by the application,
if desired.
board name
The human-readable name of a :term:`board`. Uniquely and descriptively
identifies a particular system, but does not include additional
information that may be required to actually build a Zephyr image for it.
See :ref:`board_terminology` for additional details.
board qualifiers
The set of additional tokens, separated by a forward slash (`/`) that
follow the :term:`board name` (and optionally :term:`board revision`) to
form the :term:`board target`. The currently accepted qualifiers are
:term:`SoC`, :term:`CPU cluster` and :term:`variant`.
See :ref:`board_terminology` for additional details.
board revision
An optional version string that identifies a particular revision of a
hardware system. This is useful to avoid duplication of board files
whenever small changes are introduced to a hardware system.
See :ref:`porting_board_revisions` and :ref:`application_board_version`
for more information.
board target
The full string that can be provided to any of the Zephyr build tools to
compile and link an image for a particular hardware system. This string
uniquely identifies the combination of :term:`board name`, :term:`board
revision` and :term:`board qualifiers`.
See :ref:`board_terminology` for additional details.
CPU cluster
A group of one or more :term:`CPU cores <CPU core>`, all executing the same image
within the same address space and in a symmetrical (SMP) configuration.
Only :term:`CPU cores <CPU core>` of the same :term:`architecture` can be in a single
cluster. Multiple CPU clusters (each of one or more cores) can coexist in
the same :term:`SoC`.
CPU core
A single processing unit, with its own Program Counter, executing program
instructions sequentially. CPU cores are part of a :term:`CPU cluster`,
which can contain one or more cores.
device runtime power management
Device Runtime Power Management (PM) refers the capability of devices to
save energy independently of the system power state. Devices will keep
@ -85,12 +128,30 @@ Glossary of Terms
integrated circuit that are not in use.
SoC
`System on a chip`_
A `System on a chip`_, that is, an integrated circuit that contains at
least one :term:`CPU cluster` (in turn with at least one :term:`CPU core`),
as well as peripherals and memory.
SoC family
One or more :term:`SoCs <SoC>` or :term:`SoC series` that share enough
in common to consider them related and under a single family denomination.
SoC series
A number of different :term:`SoCs <SoC>` that share similar characteristics and
features, and that the vendor typically names and markets together.
system power state
System power states describe the power consumption of the system as a
whole. System power states are represented by :c:enum:`pm_state`.
variant
In the context of :term:`board qualifiers`, a variant designates a
particular type or configuration of a build for a combination of :term:`SoC`
and :term:`CPU cluster`. Common uses of the variant concept include
introducing both secure and non-secure builds for platforms with Trusted
Execution Environment support, or selecting the type of RAM used in a
build.
west
A multi-repo meta-tool developed for the Zephyr project. See :ref:`west`.

3
doc/hardware/porting/board/board-terminology.svg generated Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

190
doc/hardware/porting/board_porting.rst
View File

@ -65,112 +65,120 @@ complete conversion reference.
.. _example-application conversion Pull Request: https://github.com/zephyrproject-rtos/example-application/pull/58
.. _conversion script: https://github.com/zephyrproject-rtos/zephyr/blob/main/scripts/utils/board_v1_to_v2.py
.. _board_and_identifiers:
Board and board identifiers
***************************
A board may be a physical piece of hardware or an emulated board.
Furthermore a board may contain one or multiple SoCs. Also, each SoC may contain
one or multiple CPU clusters. A CPU cluster refers to a group of CPU cores.
Only CPU cores of same architecture can be in the same cluster. In the case
where a physical SoC considers a CPU cluster to contain CPU cores of different
architectures then those must be modelled as multiple clusters, where all CPU
cores within a cluster is having the same architecture.
It is possible to have only a single CPU core within a CPU cluster.
It's possible to define variants for dedicated use-cases.
Examples of such use-cases are:
- Variant which enables non-secure builds for SoCs containing a security
processor.
- Variant enabling / changing the type of RAM used in by the build.
A ``/`` is used as separator between the board name and the following:
SoC, CPU cluster, and variant identifiers.
If a board contains only a single core SoC, then the SoC can be omitted when
building.
Let's say there is a board named ``plank`` with a single-core SoC ``soc1``.
The board including the identifier is: ``plank/soc1``.
As ``plank`` is a single SoC board, then the following is sufficient: ``plank``
to use as board when building.
If ``plank`` defines board variants, then those are identified by appending the
``/<variant>`` name after the SoC, for example to build for the ``foo`` variant,
use: ``plank/soc1/foo``, and if omitting the SoC use: ``plank//foo``.
Here the double ``//`` indicates to the build system that the SoC has been
omitted.
So to build hello world for ``plank``, variant ``foo``, you can do:
.. code-block:: console
west build -b plank//foo samples/hello_world
When using multi-core SoCs, the CPU cluster is identified after the SoC
identifier.
If ``soc1`` above has two cores, ``first`` and ``second``, then those are
identified as: ``plank/soc1/first`` and ``plank/soc1/second``.
And similar to before, if the board has only a single SoC, the SoC can be
omitted, that is ``plank//first`` and ``plank//second`` is an identical short
form.
.. _hw_support_hierarchy:
Boards, SoCs, etc.
******************
Hardware support hierarchy
**************************
Zephyr's hardware support hierarchy has these layers, from most to least
Zephyr's hardware support hierarchy has the following levels, from most to least
specific:
- Board: a specific board which usually corresponds to a physical board.
A board may contain multiple SoCs.
A build targets a specific CPU cluster on a board which has multiple
CPUs, be these in different SOCs or in a SOC with multiple AMP CPU
clusters.
- SoC: the exact system on a chip the board's CPU is part of
- SoC series: a smaller group of tightly related SoCs
- SoC family: a wider group of SoCs with similar characteristics
- CPU Cluster: a cluster of one or more CPU cores.
- CPU core: a particular CPU in an architecture
- Architecture: an instruction set architecture
- :term:`board`, which has one or more
- :term:`SoC`, each of which optionally belong to a
- :term:`SoC series`, which in turn may optionally belong to an
- :term:`SoC family`. Each SoC has one or more
- :term:`CPU cluster`, each containing one or more
- :term:`CPU core`, of a particular
- :term:`architecture`
You can visualize the hierarchy like this:
You can visualize the hierarchy in the diagram below:
.. figure:: board/hierarchy.png
:width: 500px
:align: center
:alt: Configuration Hierarchy
:alt: Hardware support Hierarchy
Configuration Hierarchy
Hardware support Hierarchy
Here are some examples. Notice how the SoC series and family levels are
not always used.
Below are some examples of the hierarchy described in this section, in the form
of a :term:`board` per row with its corresponding hierarchy entries. Notice how
the :term:`SoC series` and :term:`SoC family` levels are not always used.
.. table::
+--------------------------------------------+-----------------------+-------------+---------------+---------------+----------------+--------------+
| Board | Identifier | SoC | SoC Series | SoC family | CPU core | Architecture |
+============================================+=======================+=============+===============+===============+================+==============+
| :ref:`nrf52dk <nrf52dk_nrf52832>` | /nrf52832 | nRF52832 | nRF52 | Nordic nRF | Arm Cortex-M4 | Arm |
+--------------------------------------------+-----------------------+-------------+---------------+---------------+----------------+--------------+
| :ref:`frdm_k64f <frdm_k64f>` | /mk64f12 | MK64F12 | Kinetis K6x | NXP Kinetis | Arm Cortex-M4 | Arm |
+--------------------------------------------+-----------------------+-------------+---------------+---------------+----------------+--------------+
| :ref:`rv32m1_vega <rv32m1_vega>` | /openisa_rv32m1/ri5cy | RV32M1 | (Not used) | (Not used) | RI5CY | RISC-V |
+--------------------------------------------+-----------------------+-------------+---------------+---------------+----------------+--------------+
| :ref:`nrf5340dk <nrf5340dk_nrf5340>` | /nrf5340/cpuapp | nRF5340 | nRF53 | Nordic nRF | Arm Cortex-M33 | Arm |
| +-----------------------+-------------+---------------+---------------+----------------+--------------+
| | /nrf5340/cpunet | nRF5340 | nRF53 | Nordic nRF | Arm Cortex-M33 | Arm |
+--------------------------------------------+-----------------------+-------------+---------------+---------------+----------------+--------------+
| :ref:`mimx8mp_evk <imx8mp_evk>` | /mimx8m/a53 | i.MX8M Plus | i.MXM8M A53 | NXP i.MX | Arm Cortex-A53 | Arm64 |
| +-----------------------+-------------+---------------+---------------+----------------+--------------+
| | /mimx8m/m7 | i.MX8M Plus | i.MXM8MM M4 | NXP i.MX | Arm Cortex-M7 | Arm |
+--------------------------------------------+-----------------------+-------------+---------------+---------------+----------------+--------------+
+--------------------------------------------+--------------------------+-------------+--------------------+--------------------+----------------+----------------------+
| :term:`board name` | :term:`board qualifiers` | :term:`SoC` | :term:`SoC Series` | :term:`SoC family` | CPU core | :term:`architecture` |
+============================================+==========================+=============+====================+====================+================+======================+
| :ref:`nrf52dk <nrf52dk_nrf52832>` | nrf52832 | nRF52832 | nRF52 | Nordic nRF | Arm Cortex-M4 | ARMv7-M |
+--------------------------------------------+--------------------------+-------------+--------------------+--------------------+----------------+----------------------+
| :ref:`frdm_k64f <frdm_k64f>` | mk64f12 | MK64F12 | Kinetis K6x | NXP Kinetis | Arm Cortex-M4 | ARMv7-M |
+--------------------------------------------+--------------------------+-------------+--------------------+--------------------+----------------+----------------------+
| :ref:`rv32m1_vega <rv32m1_vega>` | openisa_rv32m1/ri5cy | RV32M1 | (Not used) | (Not used) | RI5CY | RISC-V RV32 |
+--------------------------------------------+--------------------------+-------------+--------------------+--------------------+----------------+----------------------+
| :ref:`nrf5340dk <nrf5340dk_nrf5340>` | nrf5340/cpuapp | nRF5340 | nRF53 | Nordic nRF | Arm Cortex-M33 | ARMv8-M |
| +--------------------------+-------------+--------------------+--------------------+----------------+----------------------+
| | nrf5340/cpunet | nRF5340 | nRF53 | Nordic nRF | Arm Cortex-M33 | ARMv8-M |
+--------------------------------------------+--------------------------+-------------+--------------------+--------------------+----------------+----------------------+
| :ref:`mimx8mp_evk <imx8mp_evk>` | mimx8ml8/a53 | i.MX8M Plus | i.MX8M | NXP i.MX | Arm Cortex-A53 | ARMv8-A |
| +--------------------------+-------------+--------------------+--------------------+----------------+----------------------+
| | mimx8ml8/m7 | i.MX8M Plus | i.MX8M | NXP i.MX | Arm Cortex-M7 | ARMv7-M |
+--------------------------------------------+--------------------------+-------------+--------------------+--------------------+----------------+----------------------+
Additional details about terminology can be found in the next section.
.. _board_terminology:
Board terminology
*****************
The previous section introduced the hierarchical manner in which Zephyr
classifies and implements hardware support.
This section focuses on the terminology used around hardware support, and in
particular when defining and working with boards and SoCs.
The overall set of terms used around the concept of board in Zephyr is depicted
in the image below, which uses the :ref:`bl5340_dvk` board as reference.
.. figure:: board/board-terminology.svg
:width: 500px
:align: center
:alt: Board terminology diagram
Board terminology diagram
The diagram shows the different terms that are used to describe boards:
- The :term:`board name`: ``bl5340_dvk``
- The optional :term:`board revision`: ``1.2.0``
- The :term:`board qualifiers`, that optionally describe the :term:`SoC`,
:term:`CPU cluster` and :term:`variant`: ``nrf5340/cpuapp/ns``
- The :term:`board target`, which uniquely identifies a combination of the above
and can be used to specify the hardware to build for when using the tooling
provided by Zephyr: ``bl5340_dvk@1.2.0/nrf5340/cpuapp/ns``
Formally this can also be seen as
:samp:`{board name}[@{revision}][/{board qualifiers}]`, which can be extended to
:samp:`{board name}[@{revision}][/{SoC}[/{CPU cluster}][/{variant}]]`.
If a board contains only one single-core SoC, then the SoC can be omitted from
the board target. This implies that if the board does not define any board
qualifiers, the board name can be used as a board target. Conversely, if
board qualifiers are part of the board definition, then the SoC can be omitted
by leaving it out but including the corresponding forward-slashes: ``//``.
Continuing with the example above, The board :ref:`bl5340_dvk` is a single SoC
board where the SoC defines two CPU clusters: ``cpuapp`` and ``cpunet``. One of
the CPU clusters, ``cpuapp``, additionally defines a non-secure board variant,
``ns``.
The board qualifiers ``nrf5340/cpuapp/ns`` can be read as:
- ``nrf5340``: The SoC, which is a Nordic nRF5340 dual-core SoC
- ``cpuapp``: The CPU cluster ``cpuapp``, which consists of a single Cortex-M33
CPU core. The number of cores in a CPU cluster cannot be determined from the
board qualifiers.
- ``ns``: a variant, in this case ``ns`` is a common variant name is
Zephyr denoting a non-secure build for boards supporting :ref:`tfm`.
Not all SoCs define CPU clusters or variants. For example a simple board
like the :ref:`thingy52_nrf52832` contains a single SoC with no CPU clusters and
no variants.
For ``thingy52`` the board target ``thingy52/nrf52832`` can be read as:
- ``thingy52``: board name.
- ``nrf52832``: The board qualifiers, in this case identical to the SoC, which
is a Nordic nRF52832.
Make sure your SoC is supported