From 68eb97ea05450f3ebfd718470db84e42e988cbf6 Mon Sep 17 00:00:00 2001 From: Carles Cufi Date: Tue, 19 Mar 2024 17:24:50 +0100 Subject: [PATCH] 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 --- doc/develop/getting_started/index.rst | 2 +- doc/glossary.rst | 65 +++++- .../porting/board/board-terminology.svg | 3 + doc/hardware/porting/board_porting.rst | 190 +++++++++--------- 4 files changed, 166 insertions(+), 94 deletions(-) create mode 100644 doc/hardware/porting/board/board-terminology.svg diff --git a/doc/develop/getting_started/index.rst b/doc/develop/getting_started/index.rst index cbe67aade5..5946e37d06 100644 --- a/doc/develop/getting_started/index.rst +++ b/doc/develop/getting_started/index.rst @@ -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 ` 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 diff --git a/doc/glossary.rst b/doc/glossary.rst index 8571f4b6d4..240727d9e2 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -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 `. The Zephyr kernel supports a :ref:`variety of 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 `, all executing the same image + within the same address space and in a symmetrical (SMP) configuration. + Only :term:`CPU cores ` 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 ` 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 ` 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`. diff --git a/doc/hardware/porting/board/board-terminology.svg b/doc/hardware/porting/board/board-terminology.svg new file mode 100644 index 0000000000..60c3d8a8eb --- /dev/null +++ b/doc/hardware/porting/board/board-terminology.svg @@ -0,0 +1,3 @@ + + +
bl5340_dvk@1.2.0/nrf5340/cpuapp/ns
bl5340_dvk@1.2.0/nrf5340/cpuapp/ns
Board name
Board name
Board qualifiers
Board qualifiers
Board target
Board target
Board revision
Board revision
SoC
SoC
CPU cluster
CPU cluster
Variant
Variant \ No newline at end of file diff --git a/doc/hardware/porting/board_porting.rst b/doc/hardware/porting/board_porting.rst index ebd8ca5e28..d638a52a25 100644 --- a/doc/hardware/porting/board_porting.rst +++ b/doc/hardware/porting/board_porting.rst @@ -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 -``/`` 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 ` | /nrf52832 | nRF52832 | nRF52 | Nordic nRF | Arm Cortex-M4 | Arm | - +--------------------------------------------+-----------------------+-------------+---------------+---------------+----------------+--------------+ - | :ref:`frdm_k64f ` | /mk64f12 | MK64F12 | Kinetis K6x | NXP Kinetis | Arm Cortex-M4 | Arm | - +--------------------------------------------+-----------------------+-------------+---------------+---------------+----------------+--------------+ - | :ref:`rv32m1_vega ` | /openisa_rv32m1/ri5cy | RV32M1 | (Not used) | (Not used) | RI5CY | RISC-V | - +--------------------------------------------+-----------------------+-------------+---------------+---------------+----------------+--------------+ - | :ref:`nrf5340dk ` | /nrf5340/cpuapp | nRF5340 | nRF53 | Nordic nRF | Arm Cortex-M33 | Arm | - | +-----------------------+-------------+---------------+---------------+----------------+--------------+ - | | /nrf5340/cpunet | nRF5340 | nRF53 | Nordic nRF | Arm Cortex-M33 | Arm | - +--------------------------------------------+-----------------------+-------------+---------------+---------------+----------------+--------------+ - | :ref:`mimx8mp_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 ` | nrf52832 | nRF52832 | nRF52 | Nordic nRF | Arm Cortex-M4 | ARMv7-M | + +--------------------------------------------+--------------------------+-------------+--------------------+--------------------+----------------+----------------------+ + | :ref:`frdm_k64f ` | mk64f12 | MK64F12 | Kinetis K6x | NXP Kinetis | Arm Cortex-M4 | ARMv7-M | + +--------------------------------------------+--------------------------+-------------+--------------------+--------------------+----------------+----------------------+ + | :ref:`rv32m1_vega ` | openisa_rv32m1/ri5cy | RV32M1 | (Not used) | (Not used) | RI5CY | RISC-V RV32 | + +--------------------------------------------+--------------------------+-------------+--------------------+--------------------+----------------+----------------------+ + | :ref:`nrf5340dk ` | 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 ` | 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