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
Carles Cufí
parent
d05d51d869
commit
68eb97ea05
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
3
doc/hardware/porting/board/board-terminology.svg
generated
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 13 KiB |
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue