@@ -99,6 +99,9 @@ areas of Zephyr, e.g: boards).
99
99
Board compatibility
100
100
*******************
101
101
102
+ Devicetree Nodelabel Convention for Common Connectors
103
+ -----------------------------------------------------
104
+
102
105
Hardware shield-to-board compatibility depends on the use of well-known
103
106
connectors used on popular boards (such as Arduino and 96boards). For
104
107
software compatibility, boards must also provide a configuration matching
@@ -116,6 +119,66 @@ This should be done at two different level:
116
119
117
120
arduino_i2c: &i2c1 {};
118
121
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
+
119
182
Board specific shield configuration
120
183
-----------------------------------
121
184
0 commit comments