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