Skip to content

Commit 05919f7

Browse files
committed
doc: shields: convention for zephyr_[protocol] DT nodelabels
Add guidance on using extra devicetree nodelabels (zephyr_i2c, zephyr_spi, zephyr_mipi_dsi) in board DTS files for common communication protocols. This convention enables shields to reference standard bus nodes in a portable and generic way. Signed-off-by: Abderrahmane JARMOUNI <git@jarmouni.me>
1 parent ad4c3e3 commit 05919f7

File tree

1 file changed

+63
-0
lines changed

1 file changed

+63
-0
lines changed

doc/hardware/porting/shields.rst

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,9 @@ areas of Zephyr, e.g: boards).
9999
Board compatibility
100100
*******************
101101

102+
Devicetree Nodelabel Convention for Common Connectors
103+
-----------------------------------------------------
104+
102105
Hardware shield-to-board compatibility depends on the use of well-known
103106
connectors used on popular boards (such as Arduino and 96boards). For
104107
software compatibility, boards must also provide a configuration matching
@@ -116,6 +119,66 @@ This should be done at two different level:
116119
117120
arduino_i2c: &i2c1 {};
118121
122+
Devicetree Nodelabel Convention for Common Protocols
123+
-----------------------------------------------------
124+
125+
When adding shields or board support for Zephyr, it is often necessary to reference common
126+
communication interfaces like I2C, SPI, or MIPI DSI in a generic way. To facilitate this, Zephyr
127+
has adopted a convention of adding extra devicetree nodelabels in the board's DTS file for these
128+
common protocols.
129+
130+
These labels follow the pattern:
131+
132+
zephyr_[protocol]
133+
134+
Where ``[protocol]`` is the name of the communication interface, such as ``i2c``, ``spi``, or
135+
``mipi_dsi``.
136+
137+
This allows shields to reference the appropriate controller node in a portable and generic manner,
138+
regardless of the specific hardware instance.
139+
140+
**Example:**
141+
142+
In your board's DTS file, you can add an extra nodelabel as follows:
143+
144+
.. code-block:: devicetree
145+
146+
zephyr_i2c: &i2c0 {
147+
status = "okay";
148+
clock-frequency = ...;
149+
};
150+
151+
.. code-block:: devicetree
152+
153+
zephyr_mipi_dsi: &mipi_dsi {};
154+
155+
**Why use these labels?**
156+
157+
- They enable shields to reference communication buses without hard-coding instance names.
158+
- This convention improves portability and simplifies shield and driver development across boards.
159+
160+
**How to use in shields or overlays?**
161+
162+
When writing a shield devicetree overlay, use the nodelabel for maximum portability:
163+
164+
.. code-block:: devicetree
165+
166+
&zephyr_i2c {
167+
/* shield-specific configuration */
168+
};
169+
170+
**Supported Protocols**
171+
172+
Common protocols using this convention include, but are not limited to:
173+
174+
- I2C (``zephyr_i2c``)
175+
- MIPI DSI (``zephyr_mipi_dsi``)
176+
- SPI (``zephyr_spi``)
177+
- USB (``zephyr_udc0``)
178+
179+
When adding board support or shields, check existing board DTS files for these labels, and add them
180+
if missing for the protocols your shield depends on.
181+
119182
Board specific shield configuration
120183
-----------------------------------
121184

0 commit comments

Comments
 (0)