Lines Matching full:board
3 Board Porting Guide
6 To add Zephyr support for a new :term:`board`, you at least need a *board
7 directory* with various files in it. Files in the board directory inherit
23 - Support for reusing the SoC and board Kconfig trees outside of the Zephyr
43 referred to as "hardware model v2") requires modifications to all existing board
47 with two options if they have an out-of-tree board (or SoC):
49 #. Convert the out-of-tree board to the current hardware model (recommended)
52 :ref:`zephyr module <modules>` or ``SOC_ROOT``). This will allow your board,
55 When converting your board from the previous to the current hardware model, we
58 how to port a simple board. Additionally, a `conversion script`_ is available
74 Primarily, each :term:`board` has one or more :term:`SoC`.
80 .. figure:: board/hierarchy.png
88 of a :term:`board` per row with its corresponding hierarchy entries. Notice how
94 …| :term:`board name` | :term:`board qualifiers` | :term:`SoC` | :term:`SoC…
98 …| :zephyr:board:`frdm_k64f <frdm_k64f>` | mk64f12 | MK64F12 | Kinetis K6…
100 …| :zephyr:board:`rv32m1_vega <rv32m1_vega>` | openisa_rv32m1/ri5cy | RV32M1 | (Not used)…
106 …| :zephyr:board:`mimx8mp_evk <imx8mp_evk>` | mimx8ml8/a53 | i.MX8M Plus | i.MX8M …
117 Board terminology
125 The overall set of terms used around the concept of board in Zephyr is depicted
126 in the image below, which uses the :zephyr:board:`bl5340_dvk` board as reference.
128 .. figure:: board/board-terminology.svg
131 :alt: Board terminology diagram
133 Board terminology diagram
137 - The :term:`board name`: ``bl5340_dvk``
138 - The optional :term:`board revision`: ``1.2.0``
139 - The :term:`board qualifiers`, that optionally describe the :term:`SoC`,
141 - The :term:`board target`, which uniquely identifies a combination of the above
146 :samp:`{board name}[@{revision}][/{board qualifiers}]`, which can be extended to
147 :samp:`{board name}[@{revision}][/{SoC}[/{CPU cluster}][/{variant}]]`.
149 If a board contains only one single-core SoC, then the SoC can be omitted from
150 the board target. This implies that if the board does not define any board
151 qualifiers, the board name can be used as a board target. Conversely, if
152 board qualifiers are part of the board definition, then the SoC can be omitted
155 Continuing with the example above, The board :zephyr:board:`bl5340_dvk` is a single SoC
156 board where the SoC defines two CPU clusters: ``cpuapp`` and ``cpunet``. One of
157 the CPU clusters, ``cpuapp``, additionally defines a non-secure board variant,
160 The board qualifiers ``nrf5340/cpuapp/ns`` can be read as:
166 board qualifiers.
170 Not all SoCs define CPU clusters or variants. For example a simple board
173 For ``thingy52`` the board target ``thingy52/nrf52832`` can be read as:
175 - ``thingy52``: board name.
176 - ``nrf52832``: The board qualifiers, in this case identical to the SoC, which
184 :ref:`create-your-board-directory`. If you don't know, try:
187 board documentation to find out for sure.
222 .. _create-your-board-directory:
224 Create your board directory
227 Once you've found an existing board that uses your SoC, you can usually start
228 by copy/pasting its board directory and changing its contents for your
231 You need to give your board a unique name. Run ``west boards`` for a list of
232 names that are already taken, and pick something new. Let's say your board is
235 Start by creating the board directory ``zephyr/boards/<VENDOR>/plank``, where
237 board directory in the zephyr repository, but it's the easiest way to get
239 board directory to a separate repository once it's working.)
242 A ``<VENDOR>`` subdirectory is mandatory if contributing your board
243 to Zephyr, but if your board is placed in a local repo, then any folder
252 The board directory name does not need to match the name of the board.
255 Your board directory should look like this:
260 ├── board.yml
261 ├── board.cmake
272 Replace ``plank`` with your board's name, of course.
276 #. :file:`board.yml`: a YAML file describing the high-level meta data of the
287 other board and SoC related settings. Kconfig settings outside of the board
299 - :file:`board.cmake`: used for :ref:`flash-and-debug-support`
303 of your board. You only need this if you're :ref:`contributing-your-board` to
308 Board qualifiers of the form ``<soc>/<cpucluster>/<variant>`` are normalized so
314 Write your board YAML
317 The board YAML file describes the board at a high level.
318 This includes the SoC, board variants, and board revisions.
323 The skeleton of the board YAML file is:
327 board:
328 name: <board-name>
329 vendor: <board-vendor>
349 It is possible to have multiple boards located in the board folder.
350 If multiple boards are placed in the same board folder, then the file
351 :file:`board.yml` must describe those in a list as:
356 - name: <board-name-1>
357 vendor: <board-vendor>
359 - name: <board-name-2>
360 vendor: <board-vendor>
371 :file:`boards/<vendor>/plank/plank_<qualifiers>.dts` describes your board
373 your board's name). If you're new to devicetree, see :ref:`devicetree-intro`.
393 * Your board-specific hardware: buttons, LEDs, sensors, etc.
433 This allows board maintainers to write a base devicetree file for the board
434 or write specific devicetree files for a given board's SoC or variant.
449 This section contains concrete examples related to writing your board's
452 The FRDM-K64F and Hexiwear K64 board devicetrees are defined in
459 <dts/arm/nxp/nxp_k6x.dtsi>`, which is included by both board :file:`.dts`
477 It is up to the board :file:`.dts` or application overlay files to enable these
478 devices as desired, by setting ``status = "okay"``. The board :file:`.dts`
479 files are also responsible for any board-specific configuration of the device,
480 such as adding nodes for on-board sensors, LEDs, buttons, etc.
494 Other examples of board-specific customization is pointing properties in
503 Zephyr uses the Kconfig language to configure software features. Your board
510 There is one mandatory Kconfig file in the board directory, and several optional
511 files for a board named ``plank``:
528 Kconfig board and SoC trees.
537 The Kconfig symbols :samp:`BOARD_{board}` and
544 This file can add Kconfig settings which are specific to the current board.
548 A board specific setting should be defining a custom setting and usually with
554 bool "Board specific feature"
561 Board-specific default values for Kconfig options.
584 :file:`.config` whenever an application is compiled for your board.
586 If both the common :file:`plank_defconfig` file and one or more board
589 This allows you to place configuration which is common for all board SoCs,
590 CPU clusters, and board variants in the base :file:`plank_defconfig` and only
591 place the adjustments specific for a given SoC or board variant in the
605 :file:`.config` whenever an application is compiled for your board revision
612 board until you're satisfied.
631 that are not board specific for your board, please follow these guidelines
639 - Provide pin and driver configuration that matches the board's valuable
643 - If your board uses a well-known connector standard (like Arduino, Mikrobus,
657 that must be included in the board's Kconfig.defconfig file and
659 that must be included if the board's devicetree, if the board want to use the
662 - If your board supports networking, configure a default interface.
682 To add ``west flash`` and ``west debug`` support for your board, you need to
683 create a :file:`board.cmake` file in your board directory. This file's job is
684 to configure a "runner" for your board. (There's nothing special you need to
685 do to get ``west build`` support for your board.)
691 Python scripts in your :file:`board.cmake` to support those commands like this
692 example :file:`board.cmake`:
699 include(${ZEPHYR_BASE}/boards/common/nrfjprog.board.cmake)
700 include(${ZEPHYR_BASE}/boards/common/jlink.board.cmake)
701 include(${ZEPHYR_BASE}/boards/common/pyocd.board.cmake)
713 Runners and board configuration should be created without being targeted to
733 - Look for :file:`board.cmake` files for other boards similar to your own for
746 The order of the ``include()`` calls in your :file:`board.cmake` matters. The
748 including ``nrfjprog.board.cmake`` first means that ``nrfjprog`` is the default
749 flash runner for this board. Since ``nrfjprog`` does not support debugging,
754 Multiple board revisions
760 Board revisions are described in the ``revision`` entry of the
761 :file:`board.yml`.
765 board:
789 board ``plank`` defines revisions ``0.5.0``, and ``1.5.0`` and the user builds
796 -- Board: plank, Revision: 0.7.0 (Active: 0.5.0)
798 This allows you to only create revision configuration files for board revision
809 revision section in :file:`board.yml`.
816 Board revision `0.7.0` not found. Please specify a valid board revision.
818 Board revision configuration adjustment
821 When the user builds for board ``plank@<revision>`` it is possible to make
822 adjustments to the board's normal configuration.
825 :ref:`board_kconfig_files` sections the board default configuration is created
826 from the files :file:`<board>.dts` / :file:`<board>_<qualifiers>.dts` and
827 :file:`<board>_defconfig` / :file:`<board>_<qualifiers>_defconfig`.
828 When building for a specific board revision, the above files are used as a
829 starting point and the following board files will be used in addition:
831 - :file:`<board>_<qualifiers>_<revision>_defconfig`: a specific revision
832 defconfig which is only used for the board and SOC / variants identified by
833 ``<board>_<qualifiers>``.
835 - :file:`<board>_<revision>_defconfig`: a specific revision defconfig which is
836 used for the board regardless of the SOC / variants.
838 - :file:`<board>_<qualifiers>_<revision>.overlay`: a specific revision dts
839 overlay which is only used for the board and SOC / variants identified by
840 ``<board>_<qualifiers>``.
842 - :file:`<board>_<revision>.overlay`: a specific revision dts overlay which is
843 used for the board regardless of the SOC / variants.
850 Using the ``plank`` board from previous sections, then we could have the following
856 …├── plank_0_5_0_defconfig # Kconfig adjustment for all plank board qualifiers on revision…
857 ├── plank_0_5_0.overlay # DTS overlay for all plank board qualifiers on revision 0.5.0
858 …└── plank_soc1_foo_1_5_0_defconfig # Kconfig adjustment for plank board when building for soc1 var…
863 Some boards may not use board revisions supported natively by Zephyr.
877 field in the ``revision`` section of the :file:`board.yml` must be written as:
881 board:
886 board directory.
889 for the board and it is the responsibility of the file to validate the revision
899 :file:`<board>_<ACTIVE_BOARD_REVISION>_defconfig` and
900 :file:`<board>_<ACTIVE_BOARD_REVISION>.overlay`.
902 .. _contributing-your-board:
904 Contributing your board
907 If you want to contribute your board to Zephyr, first -- thanks!
914 #. Add documentation for your board using the template file
915 :zephyr_file:`doc/templates/board.tmpl`. See :ref:`zephyr_doc` for
919 #. Prepare a pull request adding your board which follows the
922 .. _extend-board: argument
924 Board extensions
927 The board hardware model in Zephyr allows you to extend an existing board with
928 new board variants. Such board extensions can be done in your custom repository
931 Extending an existing board with an extra variant allows you to adjust an
932 existing board and thereby during build to select building for the existing,
933 unmodified board, or the new variant.
935 To extend an existing board, first create a :file:`board.yml` in your extended
936 board. Make sure to use the directory structure described in
937 :ref:`create-your-board-directory`.
939 The skeleton of the board YAML file for extending a board is:
943 board:
944 extend: <existing-board-name>
949 When extending a board, your board directory should look like:
954 ├── board.yml
958 Replace ``plank`` with the real name of the board you extend.
961 :file:`Kconfig.defconfig` or :file:`Kconfig.{board}`.
963 extending a board.
968 ├── board.cmake
974 Board extensions (Old hardware model)
981 feature described in :ref:`extend-board`.
988 useful in development phases, when the board skeleton lives upstream, but other
991 Board extensions are board fragments that can be present in an out-of-tree board
993 structure of an extension for the ``plank`` board and its revisions:
1003 A board extension directory must follow the naming structure of the original
1004 board it extends. It may contain Kconfig fragments and/or devicetree overlays.
1005 Extensions are, by default, automatically loaded and applied on top of board
1010 Note that board extensions need to follow the
1012 example, it is wrong to enable extra peripherals or subsystems in a board
1017 Board extensions are not allowed in any module referenced in Zephyr's
1018 ``west.yml`` manifest file. Any board changes are required to be submitted to