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>

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 <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

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 <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`.
 

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
-``/<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.
+- :term:`board`, which has one or more
-         A board may contain multiple SoCs.
+- :term:`SoC`, each of which optionally belong to a
-         A build targets a specific CPU cluster on a board which has multiple
+- :term:`SoC series`, which in turn may optionally belong to an
-         CPUs, be these in different SOCs or in a SOC with multiple AMP CPU
+- :term:`SoC family`. Each SoC has one or more
-         clusters.
+- :term:`CPU cluster`, each containing one or more
-- SoC: the exact system on a chip the board's CPU is part of
+- :term:`CPU core`, of a particular
-- SoC series: a smaller group of tightly related SoCs
+- :term:`architecture`
-- 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
 
-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
+Below are some examples of the hierarchy described in this section, in the form
-not always used.
+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 |
+   | :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  | Arm          |
+   | :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  | Arm          |
+   | :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       |
+   | :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 | Arm          |
+   | :ref:`nrf5340dk <nrf5340dk_nrf5340>`       | nrf5340/cpuapp           | nRF5340     | nRF53              | Nordic nRF         | Arm Cortex-M33 | ARMv8-M              |
-   |                                            +-----------------------+-------------+---------------+---------------+----------------+--------------+
+   |                                            +--------------------------+-------------+--------------------+--------------------+----------------+----------------------+
-   |                                            | /nrf5340/cpunet       | nRF5340     | nRF53         | Nordic nRF    | Arm Cortex-M33 | Arm          |
+   |                                            | nrf5340/cpunet           | nRF5340     | nRF53              | Nordic nRF         | Arm Cortex-M33 | ARMv8-M              |
-   +--------------------------------------------+-----------------------+-------------+---------------+---------------+----------------+--------------+
+   +--------------------------------------------+--------------------------+-------------+--------------------+--------------------+----------------+----------------------+
-   | :ref:`mimx8mp_evk <imx8mp_evk>`            | /mimx8m/a53           | i.MX8M Plus | i.MXM8M A53   | NXP i.MX      | Arm Cortex-A53 | Arm64        |
+   | :ref:`mimx8mp_evk <imx8mp_evk>`            | mimx8ml8/a53             | i.MX8M Plus | i.MX8M             | NXP i.MX           | Arm Cortex-A53 | ARMv8-A              |
-   |                                            +-----------------------+-------------+---------------+---------------+----------------+--------------+
+   |                                            +--------------------------+-------------+--------------------+--------------------+----------------+----------------------+
-   |                                            | /mimx8m/m7            | i.MX8M Plus | i.MXM8MM M4   | NXP i.MX      | Arm Cortex-M7  | Arm          |
+   |                                            | 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