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 #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 #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 #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 #define IEEE802154_SHORT_ADDR_LENGTH 2 142 143 /** IEEE 802.15.4 extended address length. */ 144 #define IEEE802154_EXT_ADDR_LENGTH 8 145 146 /** IEEE 802.15.4 maximum address length. */ 147 #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 #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 #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 #define IEEE802154_NO_SHORT_ADDRESS_ASSIGNED 0xfffe 167 168 /** Represents the IEEE 802.15.4 broadcast PAN ID, see section 6.1. */ 169 #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 #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 #define IEEE802154_PAN_ID_NOT_ASSOCIATED IEEE802154_BROADCAST_PAN_ID 182 183 /** Interface-level security attributes, see section 9.5. */ 184 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 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 uint8_t key[16]; 211 212 /** Length in bytes of the interface-level security key material. */ 213 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 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 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 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 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 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 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 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 uint8_t ext_addr[IEEE802154_MAX_ADDR_LENGTH]; 297 298 /** Link layer address (in big endian) */ 299 struct net_linkaddr_storage linkaddr; 300 301 #ifdef CONFIG_NET_L2_IEEE802154_SECURITY 302 /** Security context */ 303 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 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 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 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 uint16_t coord_short_addr; 344 #endif 345 346 /** Transmission power in dBm. */ 347 int16_t tx_power; 348 349 /** L2 flags */ 350 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 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 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 uint8_t ack_requested: 1; 382 383 /** ACK expected sequence number, guarded by ack_lock */ 384 uint8_t ack_seq; 385 386 /** ACK lock, guards ack_* fields */ 387 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 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_ */ 414
