1.. _shields:
2
3Shields
4#######
5
6Shields, also known as "add-on" or "daughter boards", attach to a board
7to extend its features and services for easier and modularized prototyping.
8In Zephyr, the shield feature provides Zephyr-formatted shield
9descriptions for easier compatibility with applications.
10
11.. _shield_porting_guide:
12
13Shield porting and configuration
14********************************
15
16Shield configuration files are available in the board directory
17under :zephyr_file:`boards/shields`:
18
19.. code-block:: none
20
21   boards/shields/<shield>
22   ├── shield.yml
23   ├── <shield>.overlay
24   ├── Kconfig.shield
25   ├── Kconfig.defconfig
26   └── pre_dt_shield.cmake
27
28These files provides shield configuration as follows:
29
30* **shield.yml**: This file provides metadata about the shield in YAML format.
31  It must contain the following fields:
32
33  * ``name``: Name of the shield used in Kconfig and build system (required)
34  * ``full_name``: Full commercial name of the shield (required)
35  * ``vendor``: Manufacturer/vendor of the shield (required)
36  * ``supported_features``: List of hardware features the shield supports (optional). In order to
37    help users identify the features a shield supports without having to dig into its overlay file,
38    the ``supported_features`` field can be used to list the types of features the shield supports.
39    The values should be the same as the ones defined in the
40    :zephyr_file:`dts/bindings/binding-types.txt` file.
41
42  Example:
43
44  .. code-block:: yaml
45
46     name: foo_shield
47     full_name: Foo Shield for Arduino
48     vendor: acme
49     supported_features:
50       - display
51       - input
52
53* **<shield>.overlay**: This file provides a shield description in devicetree
54  format that is merged with the board's :ref:`devicetree <dt-guide>`
55  before compilation.
56
57* **Kconfig.shield**: This file defines shield Kconfig symbols that will be
58  used for default shield configuration. To ease use with applications,
59  the default shield configuration here should be consistent with those in
60  the :ref:`default_board_configuration`.
61
62* **Kconfig.defconfig**: This file defines the default shield configuration. It
63  is made to be consistent with the :ref:`default_board_configuration`. Hence,
64  shield configuration should be done by keeping in mind that features
65  activation is application responsibility.
66
67* **pre_dt_shield.cmake**: This optional file can be used to pass additional
68  arguments to the devicetree compiler ``dtc``.
69
70Besides, in order to avoid name conflicts with devices that may be defined at
71board level, it is advised, specifically for shields devicetree descriptions,
72to provide a device nodelabel is the form <device>_<shield>, for instance:
73
74.. code-block:: devicetree
75
76        sdhc_myshield: sdhc@1 {
77                reg = <1>;
78                ...
79        };
80
81Adding Source Code
82******************
83
84It is possible to add source code to shields, as a way to meet configuration
85requirements that are specific to the shield (e.g: initialization routines,
86timing constraints, etc), in order to enable it for proper operation with the
87different Zephyr components.
88
89.. note::
90
91   Source code in shields shall not be used for purposes other than the
92   one described above. Generic functionalities that could be reused among
93   shields (and/or targets) shall not be captured here.
94
95To effectively incorporate source code: add a :file:`CMakeLists.txt` file, as
96well as the corresponding source files (referenced in CMake similar to other
97areas of Zephyr, e.g: boards).
98
99Board compatibility
100*******************
101
102Hardware shield-to-board compatibility depends on the use of well-known
103connectors used on popular boards (such as Arduino and 96boards).  For
104software compatibility, boards must also provide a configuration matching
105their supported connectors.
106
107This should be done at two different level:
108
109* Pinmux: Connector pins should be correctly configured to match shield pins
110
111* Devicetree: A board :ref:`devicetree <dt-guide>` file,
112  :file:`BOARD.dts` should define an alternate nodelabel for each connector interface.
113  For example, for Arduino I2C:
114
115.. code-block:: devicetree
116
117        arduino_i2c: &i2c1 {};
118
119Board specific shield configuration
120-----------------------------------
121
122If modifications are needed to fit a shield to a particular board or board
123revision, you can override a shield description for a specific board by adding
124board or board revision overriding files to a shield, as follows:
125
126.. code-block:: none
127
128   boards/shields/<shield>
129   └── boards
130       ├── <board>_<revision>.overlay
131       ├── <board>.overlay
132       ├── <board>.defconfig
133       ├── <board>_<revision>.conf
134       └── <board>.conf
135
136
137Shield activation
138*****************
139
140Activate support for one or more shields by adding the matching ``--shield`` arguments
141to the west command:
142
143  .. zephyr-app-commands::
144     :app: your_app
145     :shield: x_nucleo_idb05a1,x_nucleo_iks01a1
146     :goals: build
147
148
149Alternatively, it could be set by default in a project's CMakeLists.txt:
150
151.. code-block:: cmake
152
153	set(SHIELD x_nucleo_iks01a1)
154
155Shield variants
156***************
157
158Some shields may support several variants or revisions. In that case, it is
159possible to provide multiple version of the shields description:
160
161.. code-block:: none
162
163   boards/shields/<shield>
164   ├── <shield_v1>.overlay
165   ├── <shield_v1>.defconfig
166   ├── <shield_v2>.overlay
167   └── <shield_v2>.defconfig
168
169In this case, a shield-particular revision name can be used:
170
171  .. zephyr-app-commands::
172     :app: your_app
173     :shield: shield_v2
174     :goals: build
175
176You can also provide a board-specific configuration to a specific shield
177revision:
178
179.. code-block:: none
180
181   boards/shields/<shield>
182   ├── <shield_v1>.overlay
183   ├── <shield_v1>.defconfig
184   ├── <shield_v2>.overlay
185   ├── <shield_v2>.defconfig
186   └── boards
187       └── <shield_v2>
188           ├── <board>.overlay
189           └── <board>.defconfig
190
191GPIO nexus nodes
192****************
193
194GPIOs accessed by the shield peripherals must be identified using the
195shield GPIO abstraction, for example from the ``arduino-header-r3``
196compatible.  Boards that provide the header must map the header pins
197to SOC-specific pins.  This is accomplished by including a `nexus
198node`_ that looks like the following into the board devicetree file:
199
200.. _nexus node:
201    https://github.com/devicetree-org/devicetree-specification/blob/4b1dac80eaca45b4babf5299452a951008a5d864/source/devicetree-basics.rst#nexus-nodes-and-specifier-mapping
202
203.. code-block:: devicetree
204
205    arduino_header: connector {
206            compatible = "arduino-header-r3";
207            #gpio-cells = <2>;
208            gpio-map-mask = <0xffffffff 0xffffffc0>;
209            gpio-map-pass-thru = <0 0x3f>;
210            gpio-map = <0 0 &gpioa 0 0>,    /* A0 */
211                       <1 0 &gpioa 1 0>,    /* A1 */
212                       <2 0 &gpioa 4 0>,    /* A2 */
213                       <3 0 &gpiob 0 0>,    /* A3 */
214                       <4 0 &gpioc 1 0>,    /* A4 */
215                       <5 0 &gpioc 0 0>,    /* A5 */
216                       <6 0 &gpioa 3 0>,    /* D0 */
217                       <7 0 &gpioa 2 0>,    /* D1 */
218                       <8 0 &gpioa 10 0>,   /* D2 */
219                       <9 0 &gpiob 3 0>,    /* D3 */
220                       <10 0 &gpiob 5 0>,   /* D4 */
221                       <11 0 &gpiob 4 0>,   /* D5 */
222                       <12 0 &gpiob 10 0>,  /* D6 */
223                       <13 0 &gpioa 8 0>,   /* D7 */
224                       <14 0 &gpioa 9 0>,   /* D8 */
225                       <15 0 &gpioc 7 0>,   /* D9 */
226                       <16 0 &gpiob 6 0>,   /* D10 */
227                       <17 0 &gpioa 7 0>,   /* D11 */
228                       <18 0 &gpioa 6 0>,   /* D12 */
229                       <19 0 &gpioa 5 0>,   /* D13 */
230                       <20 0 &gpiob 9 0>,   /* D14 */
231                       <21 0 &gpiob 8 0>;   /* D15 */
232    };
233
234This specifies how Arduino pin references like ``<&arduino_header 11
2350>`` are converted to SOC gpio pin references like ``<&gpiob 4 0>``.
236
237In Zephyr GPIO specifiers generally have two parameters (indicated by
238``#gpio-cells = <2>``): the pin number and a set of flags.  The low 6
239bits of the flags correspond to features that can be configured in
240devicetree.  In some cases it's necessary to use a non-zero flag value
241to tell the driver how a particular pin behaves, as with:
242
243.. code-block:: devicetree
244
245    drdy-gpios = <&arduino_header 11 GPIO_ACTIVE_LOW>;
246
247After preprocessing this becomes ``<&arduino_header 11 1>``.  Normally
248the presence of such a flag would cause the map lookup to fail,
249because there is no map entry with a non-zero flags value.  The
250``gpio-map-mask`` property specifies that, for lookup, all bits of the
251pin and all but the low 6 bits of the flags are used to identify the
252specifier.  Then the ``gpio-map-pass-thru`` specifies that the low 6
253bits of the flags are copied over, so the SOC GPIO reference becomes
254``<&gpiob 4 1>`` as intended.
255
256See `nexus node`_ for more information about this capability.
257