Line data Source code
1 1 : /*
2 : * Copyright (c) 2016 Intel Corporation.
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @brief IEEE 802.15.4 native L2 stack public header
10 : *
11 : * @note All references to the standard in this file cite IEEE 802.15.4-2020.
12 : */
13 :
14 : #ifndef ZEPHYR_INCLUDE_NET_IEEE802154_H_
15 : #define ZEPHYR_INCLUDE_NET_IEEE802154_H_
16 :
17 : #include <limits.h>
18 : #include <zephyr/net/net_l2.h>
19 : #include <zephyr/net/net_mgmt.h>
20 : #include <zephyr/crypto/cipher.h>
21 : #include <zephyr/net/ieee802154_radio.h>
22 :
23 : #ifdef __cplusplus
24 : extern "C" {
25 : #endif
26 :
27 : /**
28 : * @defgroup ieee802154 IEEE 802.15.4 and Thread APIs
29 : * @since 1.0
30 : * @version 0.8.0
31 : * @ingroup connectivity
32 : *
33 : * @brief IEEE 802.15.4 native and OpenThread L2, configuration, management and
34 : * driver APIs
35 : *
36 : * @details The IEEE 802.15.4 and Thread subsystems comprise the OpenThread L2
37 : * subsystem, the native IEEE 802.15.4 L2 subsystem ("Soft" MAC), a mostly
38 : * vendor and protocol agnostic driver API shared between the OpenThread and
39 : * native L2 stacks ("Hard" MAC and PHY) as well as several APIs to configure
40 : * the subsystem (shell, net management, Kconfig, devicetree, etc.).
41 : *
42 : * The **OpenThread subsystem API** integrates the external <a
43 : * href="https://openthread.io">OpenThread</a> stack into Zephyr. It builds upon
44 : * Zephyr's native IEEE 802.15.4 driver API.
45 : *
46 : * The **native IEEE 802.15.4 subsystem APIs** are exposed at different levels
47 : * and address several audiences:
48 : * - shell (end users, application developers):
49 : * - a set of IEEE 802.15.4 shell commands (see `shell> ieee802154 help`)
50 : * - application API (application developers):
51 : * - IPv6, DGRAM and RAW sockets for actual peer-to-peer, multicast and
52 : * broadcast data exchange between nodes including connection specific
53 : * configuration (sample coming soon, see
54 : * https://github.com/linux-wpan/wpan-tools/tree/master/examples for now
55 : * which inspired our API and therefore has a similar socket API),
56 : * - Kconfig and devicetree configuration options (net config library
57 : * extension, subsystem-wide MAC and PHY Kconfig/DT options, driver/vendor
58 : * specific Kconfig/DT options, watch out for options prefixed with
59 : * IEEE802154/ieee802154),
60 : * - Network Management: runtime configuration of the IEEE 802.15.4
61 : * protocols stack at the MAC (L2) and PHY (L1) levels
62 : * (see @ref ieee802154_mgmt),
63 : * - L2 integration (subsystem contributors):
64 : * - see @ref ieee802154_l2
65 : * - implementation of Zephyr's internal L2-level socket and network context
66 : * abstractions (context/socket operations, see @ref net_l2),
67 : * - protocol-specific extension to the interface structure (see @ref net_if)
68 : * - protocol-specific extensions to the network packet structure
69 : * (see @ref net_pkt),
70 : *
71 : * - OpenThread and native IEEE 802.15.4 share a common **driver API** (driver
72 : * maintainers/contributors):
73 : * - see @ref ieee802154_driver
74 : * - a basic, mostly PHY-level driver API to be implemented by all drivers,
75 : * - several "hard MAC" (hardware/firmware offloading) extension points for
76 : * performance critical or timing sensitive aspects of the protocol
77 : */
78 :
79 : /**
80 : * @defgroup ieee802154_l2 IEEE 802.15.4 L2
81 : * @since 1.0
82 : * @version 0.8.0
83 : * @ingroup ieee802154
84 : *
85 : * @brief IEEE 802.15.4 L2 APIs
86 : *
87 : * @details This API provides integration with Zephyr's sockets and network
88 : * contexts. **Application and driver developers should never interface directly
89 : * with this API.** It is of interest to subsystem maintainers only.
90 : *
91 : * The API implements and extends the following structures:
92 : * - implements Zephyr's internal L2-level socket and network context
93 : * abstractions (context/socket operations, see @ref net_l2),
94 : * - protocol-specific extension to the interface structure (see @ref net_if)
95 : * - protocol-specific extensions to the network packet structure
96 : * (see @ref net_pkt),
97 : *
98 : * @note All section, table and figure references are to the IEEE 802.15.4-2020
99 : * standard.
100 : *
101 : * @{
102 : */
103 :
104 : /**
105 : * @brief Represents the PHY constant aMaxPhyPacketSize, see section 11.3.
106 : *
107 : * @note Currently only 127 byte sized packets are supported although some PHYs
108 : * (e.g. SUN, MSK, LECIM, ...) support larger packet sizes. Needs to be changed
109 : * once those PHYs should be fully supported.
110 : */
111 1 : #define IEEE802154_MAX_PHY_PACKET_SIZE 127
112 :
113 : /**
114 : * @brief Represents the frame check sequence length, see section 7.2.1.1.
115 : *
116 : * @note Currently only a 2 byte FCS is supported although some PHYs (e.g. SUN,
117 : * TVWS, ...) optionally support a 4 byte FCS. Needs to be changed once those
118 : * PHYs should be fully supported.
119 : */
120 1 : #define IEEE802154_FCS_LENGTH 2
121 :
122 : /**
123 : * @brief IEEE 802.15.4 "hardware" MTU (not to be confused with L3/IP MTU), i.e.
124 : * the actual payload available to the next higher layer.
125 : *
126 : * @details This is equivalent to the IEEE 802.15.4 MAC frame length minus
127 : * checksum bytes which is again equivalent to the PHY payload aka PSDU length
128 : * minus checksum bytes. This definition exists for compatibility with the same
129 : * concept in Linux and Zephyr's L3. It is not a concept from the IEEE 802.15.4
130 : * standard.
131 : *
132 : * @note Currently only the original frame size from the 2006 standard version
133 : * and earlier is supported. The 2015+ standard introduced PHYs with larger PHY
134 : * payload. These are not (yet) supported in Zephyr.
135 : */
136 1 : #define IEEE802154_MTU (IEEE802154_MAX_PHY_PACKET_SIZE - IEEE802154_FCS_LENGTH)
137 :
138 : /* TODO: Support flexible MTU and FCS lengths for IEEE 802.15.4-2015ff */
139 :
140 : /** IEEE 802.15.4 short address length. */
141 1 : #define IEEE802154_SHORT_ADDR_LENGTH 2
142 :
143 : /** IEEE 802.15.4 extended address length. */
144 1 : #define IEEE802154_EXT_ADDR_LENGTH 8
145 :
146 : /** IEEE 802.15.4 maximum address length. */
147 1 : #define IEEE802154_MAX_ADDR_LENGTH IEEE802154_EXT_ADDR_LENGTH
148 :
149 : /**
150 : * A special channel value that symbolizes "all" channels or "any" channel -
151 : * depending on context.
152 : */
153 1 : #define IEEE802154_NO_CHANNEL USHRT_MAX
154 :
155 : /**
156 : * Represents the IEEE 802.15.4 broadcast short address, see sections 6.1 and
157 : * 8.4.3, table 8-94, macShortAddress.
158 : */
159 1 : #define IEEE802154_BROADCAST_ADDRESS 0xffff
160 :
161 : /**
162 : * Represents a special IEEE 802.15.4 short address that indicates that a device
163 : * has been associated with a coordinator but did not receive a short address,
164 : * see sections 6.4.1 and 8.4.3, table 8-94, macShortAddress.
165 : */
166 1 : #define IEEE802154_NO_SHORT_ADDRESS_ASSIGNED 0xfffe
167 :
168 : /** Represents the IEEE 802.15.4 broadcast PAN ID, see section 6.1. */
169 1 : #define IEEE802154_BROADCAST_PAN_ID 0xffff
170 :
171 : /**
172 : * Represents a special value of the macShortAddress MAC PIB attribute, while the
173 : * device is not associated, see section 8.4.3, table 8-94.
174 : */
175 1 : #define IEEE802154_SHORT_ADDRESS_NOT_ASSOCIATED IEEE802154_BROADCAST_ADDRESS
176 :
177 : /**
178 : * Represents a special value of the macPanId MAC PIB attribute, while the
179 : * device is not associated, see section 8.4.3, table 8-94.
180 : */
181 1 : #define IEEE802154_PAN_ID_NOT_ASSOCIATED IEEE802154_BROADCAST_PAN_ID
182 :
183 : /** Interface-level security attributes, see section 9.5. */
184 1 : struct ieee802154_security_ctx {
185 : /**
186 : * Interface-level outgoing frame counter, section 9.5, table 9-8,
187 : * secFrameCounter.
188 : *
189 : * Only used when the driver does not implement key-specific frame
190 : * counters.
191 : */
192 1 : uint32_t frame_counter;
193 :
194 : /** @cond INTERNAL_HIDDEN */
195 : struct cipher_ctx enc;
196 : struct cipher_ctx dec;
197 : /** INTERNAL_HIDDEN @endcond */
198 :
199 : /**
200 : * @brief Interface-level frame encryption security key material
201 : *
202 : * @details Currently native L2 only supports a single secKeySource, see
203 : * section 9.5, table 9-9, in combination with secKeyMode zero (implicit
204 : * key mode), see section 9.4.2.3, table 9-7.
205 : *
206 : * @warning This is no longer in accordance with the 2015+ versions of
207 : * the standard and needs to be extended in the future for full security
208 : * procedure compliance.
209 : */
210 1 : uint8_t key[16];
211 :
212 : /** Length in bytes of the interface-level security key material. */
213 1 : uint8_t key_len;
214 :
215 : /**
216 : * @brief Frame security level, possible values are defined in section
217 : * 9.4.2.2, table 9-6.
218 : *
219 : * @warning Currently native L2 allows to configure one common security
220 : * level for all frame types, commands and information elements. This is
221 : * no longer in accordance with the 2015+ versions of the standard and
222 : * needs to be extended in the future for full security procedure
223 : * compliance.
224 : */
225 1 : uint8_t level : 3;
226 :
227 : /**
228 : * @brief Frame security key mode
229 : *
230 : * @details Currently only implicit key mode is partially supported, see
231 : * section 9.4.2.3, table 9-7, secKeyMode.
232 : *
233 : * @warning This is no longer in accordance with the 2015+ versions of
234 : * the standard and needs to be extended in the future for full security
235 : * procedure compliance.
236 : */
237 1 : uint8_t key_mode : 2;
238 :
239 : /** @cond INTERNAL_HIDDEN */
240 : uint8_t _unused : 3;
241 : /** INTERNAL_HIDDEN @endcond */
242 : };
243 :
244 : /** @brief IEEE 802.15.4 device role */
245 1 : enum ieee802154_device_role {
246 : IEEE802154_DEVICE_ROLE_ENDDEVICE, /**< End device */
247 : IEEE802154_DEVICE_ROLE_COORDINATOR, /**< Coordinator */
248 : IEEE802154_DEVICE_ROLE_PAN_COORDINATOR, /**< PAN coordinator */
249 : };
250 :
251 : /** IEEE 802.15.4 L2 context. */
252 1 : struct ieee802154_context {
253 : /**
254 : * @brief PAN ID
255 : *
256 : * @details The identifier of the PAN on which the device is operating.
257 : * If this value is 0xffff, the device is not associated. See section
258 : * 8.4.3.1, table 8-94, macPanId.
259 : *
260 : * in CPU byte order
261 : */
262 1 : uint16_t pan_id;
263 :
264 : /**
265 : * @brief Channel Number
266 : *
267 : * @details The RF channel to use for all transmissions and receptions,
268 : * see section 11.3, table 11-2, phyCurrentChannel. The allowable range
269 : * of values is PHY dependent as defined in section 10.1.3.
270 : *
271 : * in CPU byte order
272 : */
273 1 : uint16_t channel;
274 :
275 : /**
276 : * @brief Short Address (in CPU byte order)
277 : *
278 : * @details Range:
279 : * * 0x0000–0xfffd: associated, short address was assigned
280 : * * 0xfffe: associated but no short address assigned
281 : * * 0xffff: not associated (default),
282 : *
283 : * See section 6.4.1, table 6-4 (Usage of the shart address) and
284 : * section 8.4.3.1, table 8-94, macShortAddress.
285 : */
286 1 : uint16_t short_addr;
287 :
288 : /**
289 : * @brief Extended Address (in little endian)
290 : *
291 : * @details The extended address is device specific, usually permanently
292 : * stored on the device and immutable.
293 : *
294 : * See section 8.4.3.1, table 8-94, macExtendedAddress.
295 : */
296 1 : uint8_t ext_addr[IEEE802154_MAX_ADDR_LENGTH];
297 :
298 : /** Link layer address (in big endian) */
299 1 : struct net_linkaddr_storage linkaddr;
300 :
301 : #ifdef CONFIG_NET_L2_IEEE802154_SECURITY
302 : /** Security context */
303 1 : struct ieee802154_security_ctx sec_ctx;
304 : #endif
305 :
306 : #ifdef CONFIG_NET_L2_IEEE802154_MGMT
307 : /** Pointer to scanning parameters and results, guarded by scan_ctx_lock */
308 1 : struct ieee802154_req_params *scan_ctx;
309 :
310 : /**
311 : * Used to maintain integrity of data for all fields in this struct
312 : * unless otherwise documented on field level.
313 : */
314 1 : struct k_sem scan_ctx_lock;
315 :
316 : /**
317 : * @brief Coordinator extended address
318 : *
319 : * @details see section 8.4.3.1, table 8-94, macCoordExtendedAddress,
320 : * the address of the coordinator through which the device is
321 : * associated.
322 : *
323 : * A value of zero indicates that a coordinator extended address is
324 : * unknown (default).
325 : *
326 : * in little endian
327 : */
328 1 : uint8_t coord_ext_addr[IEEE802154_MAX_ADDR_LENGTH];
329 :
330 : /**
331 : * @brief Coordinator short address
332 : *
333 : * @details see section 8.4.3.1, table 8-94, macCoordShortAddress, the
334 : * short address assigned to the coordinator through which the device is
335 : * associated.
336 : *
337 : * A value of 0xfffe indicates that the coordinator is only using its
338 : * extended address. A value of 0xffff indicates that this value is
339 : * unknown.
340 : *
341 : * in CPU byte order
342 : */
343 1 : uint16_t coord_short_addr;
344 : #endif
345 :
346 : /** Transmission power in dBm. */
347 1 : int16_t tx_power;
348 :
349 : /** L2 flags */
350 1 : enum net_l2_flags flags;
351 :
352 : /**
353 : * @brief Data sequence number
354 : *
355 : * @details The sequence number added to the transmitted Data frame or
356 : * MAC command, see section 8.4.3.1, table 8-94, macDsn.
357 : */
358 1 : uint8_t sequence;
359 :
360 : /**
361 : * @brief Device Role
362 : *
363 : * @details See section 6.1: A device may be operating as end device
364 : * (0), coordinator (1), or PAN coordinator (2). If no device role is
365 : * explicitly configured then the device will be treated as an end
366 : * device.
367 : *
368 : * A value of 3 is undefined.
369 : *
370 : * Can be read/set via @ref ieee802154_device_role.
371 : */
372 1 : uint8_t device_role : 2;
373 :
374 : /** @cond INTERNAL_HIDDEN */
375 : uint8_t _unused : 5;
376 : /** INTERNAL_HIDDEN @endcond */
377 :
378 : /**
379 : * ACK requested flag, guarded by ack_lock
380 : */
381 1 : uint8_t ack_requested: 1;
382 :
383 : /** ACK expected sequence number, guarded by ack_lock */
384 1 : uint8_t ack_seq;
385 :
386 : /** ACK lock, guards ack_* fields */
387 1 : struct k_sem ack_lock;
388 :
389 : /**
390 : * @brief Context lock
391 : *
392 : * @details This lock guards all mutable context attributes unless
393 : * otherwise mentioned on attribute level.
394 : */
395 1 : struct k_sem ctx_lock;
396 : };
397 :
398 : /** @cond INTERNAL_HIDDEN */
399 :
400 : /* L2 context type to be used with NET_L2_GET_CTX_TYPE */
401 : #define IEEE802154_L2_CTX_TYPE struct ieee802154_context
402 :
403 : /** INTERNAL_HIDDEN @endcond */
404 :
405 : #ifdef __cplusplus
406 : }
407 : #endif
408 :
409 : /**
410 : * @}
411 : */
412 :
413 : #endif /* ZEPHYR_INCLUDE_NET_IEEE802154_H_ */
|
