1 /* SPDX-License-Identifier: GPL-2.0-only */ 2 /* 3 * IEEE802.15.4-2003 specification 4 * 5 * Copyright (C) 2007-2012 Siemens AG 6 */ 7 #ifndef NET_MAC802154_H 8 #define NET_MAC802154_H 9 10 #include <asm/unaligned.h> 11 #include <net/af_ieee802154.h> 12 #include <linux/ieee802154.h> 13 #include <linux/skbuff.h> 14 15 #include <net/cfg802154.h> 16 17 /** 18 * enum ieee802154_hw_addr_filt_flags - hardware address filtering flags 19 * 20 * The following flags are used to indicate changed address settings from 21 * the stack to the hardware. 22 * 23 * @IEEE802154_AFILT_SADDR_CHANGED: Indicates that the short address will be 24 * change. 25 * 26 * @IEEE802154_AFILT_IEEEADDR_CHANGED: Indicates that the extended address 27 * will be change. 28 * 29 * @IEEE802154_AFILT_PANID_CHANGED: Indicates that the pan id will be change. 30 * 31 * @IEEE802154_AFILT_PANC_CHANGED: Indicates that the address filter will 32 * do frame address filtering as a pan coordinator. 33 */ 34 enum ieee802154_hw_addr_filt_flags { 35 IEEE802154_AFILT_SADDR_CHANGED = BIT(0), 36 IEEE802154_AFILT_IEEEADDR_CHANGED = BIT(1), 37 IEEE802154_AFILT_PANID_CHANGED = BIT(2), 38 IEEE802154_AFILT_PANC_CHANGED = BIT(3), 39 }; 40 41 /** 42 * struct ieee802154_hw_addr_filt - hardware address filtering settings 43 * 44 * @pan_id: pan_id which should be set to the hardware address filter. 45 * 46 * @short_addr: short_addr which should be set to the hardware address filter. 47 * 48 * @ieee_addr: extended address which should be set to the hardware address 49 * filter. 50 * 51 * @pan_coord: boolean if hardware filtering should be operate as coordinator. 52 */ 53 struct ieee802154_hw_addr_filt { 54 __le16 pan_id; 55 __le16 short_addr; 56 __le64 ieee_addr; 57 bool pan_coord; 58 }; 59 60 /** 61 * struct ieee802154_hw - ieee802154 hardware 62 * 63 * @extra_tx_headroom: headroom to reserve in each transmit skb for use by the 64 * driver (e.g. for transmit headers.) 65 * 66 * @flags: hardware flags, see &enum ieee802154_hw_flags 67 * 68 * @parent: parent device of the hardware. 69 * 70 * @priv: pointer to private area that was allocated for driver use along with 71 * this structure. 72 * 73 * @phy: This points to the &struct wpan_phy allocated for this 802.15.4 PHY. 74 */ 75 struct ieee802154_hw { 76 /* filled by the driver */ 77 int extra_tx_headroom; 78 u32 flags; 79 struct device *parent; 80 void *priv; 81 82 /* filled by mac802154 core */ 83 struct wpan_phy *phy; 84 }; 85 86 /** 87 * enum ieee802154_hw_flags - hardware flags 88 * 89 * These flags are used to indicate hardware capabilities to 90 * the stack. Generally, flags here should have their meaning 91 * done in a way that the simplest hardware doesn't need setting 92 * any particular flags. There are some exceptions to this rule, 93 * however, so you are advised to review these flags carefully. 94 * 95 * @IEEE802154_HW_TX_OMIT_CKSUM: Indicates that xmitter will add FCS on it's 96 * own. 97 * 98 * @IEEE802154_HW_LBT: Indicates that transceiver will support listen before 99 * transmit. 100 * 101 * @IEEE802154_HW_CSMA_PARAMS: Indicates that transceiver will support csma 102 * parameters (max_be, min_be, backoff exponents). 103 * 104 * @IEEE802154_HW_FRAME_RETRIES: Indicates that transceiver will support ARET 105 * frame retries setting. 106 * 107 * @IEEE802154_HW_AFILT: Indicates that transceiver will support hardware 108 * address filter setting. 109 * 110 * @IEEE802154_HW_PROMISCUOUS: Indicates that transceiver will support 111 * promiscuous mode setting. 112 * 113 * @IEEE802154_HW_RX_OMIT_CKSUM: Indicates that receiver omits FCS. 114 * 115 * @IEEE802154_HW_RX_DROP_BAD_CKSUM: Indicates that receiver will not filter 116 * frames with bad checksum. 117 */ 118 enum ieee802154_hw_flags { 119 IEEE802154_HW_TX_OMIT_CKSUM = BIT(0), 120 IEEE802154_HW_LBT = BIT(1), 121 IEEE802154_HW_CSMA_PARAMS = BIT(2), 122 IEEE802154_HW_FRAME_RETRIES = BIT(3), 123 IEEE802154_HW_AFILT = BIT(4), 124 IEEE802154_HW_PROMISCUOUS = BIT(5), 125 IEEE802154_HW_RX_OMIT_CKSUM = BIT(6), 126 IEEE802154_HW_RX_DROP_BAD_CKSUM = BIT(7), 127 }; 128 129 /* Indicates that receiver omits FCS and xmitter will add FCS on it's own. */ 130 #define IEEE802154_HW_OMIT_CKSUM (IEEE802154_HW_TX_OMIT_CKSUM | \ 131 IEEE802154_HW_RX_OMIT_CKSUM) 132 133 /* struct ieee802154_ops - callbacks from mac802154 to the driver 134 * 135 * This structure contains various callbacks that the driver may 136 * handle or, in some cases, must handle, for example to transmit 137 * a frame. 138 * 139 * start: Handler that 802.15.4 module calls for device initialization. 140 * This function is called before the first interface is attached. 141 * 142 * stop: Handler that 802.15.4 module calls for device cleanup. 143 * This function is called after the last interface is removed. 144 * 145 * xmit_sync: 146 * Handler that 802.15.4 module calls for each transmitted frame. 147 * skb cntains the buffer starting from the IEEE 802.15.4 header. 148 * The low-level driver should send the frame based on available 149 * configuration. This is called by a workqueue and useful for 150 * synchronous 802.15.4 drivers. 151 * This function should return zero or negative errno. 152 * 153 * WARNING: 154 * This will be deprecated soon. We don't accept synced xmit callbacks 155 * drivers anymore. 156 * 157 * xmit_async: 158 * Handler that 802.15.4 module calls for each transmitted frame. 159 * skb cntains the buffer starting from the IEEE 802.15.4 header. 160 * The low-level driver should send the frame based on available 161 * configuration. 162 * This function should return zero or negative errno. 163 * 164 * ed: Handler that 802.15.4 module calls for Energy Detection. 165 * This function should place the value for detected energy 166 * (usually device-dependant) in the level pointer and return 167 * either zero or negative errno. Called with pib_lock held. 168 * 169 * set_channel: 170 * Set radio for listening on specific channel. 171 * Set the device for listening on specified channel. 172 * Returns either zero, or negative errno. Called with pib_lock held. 173 * 174 * set_hw_addr_filt: 175 * Set radio for listening on specific address. 176 * Set the device for listening on specified address. 177 * Returns either zero, or negative errno. 178 * 179 * set_txpower: 180 * Set radio transmit power in mBm. Called with pib_lock held. 181 * Returns either zero, or negative errno. 182 * 183 * set_lbt 184 * Enables or disables listen before talk on the device. Called with 185 * pib_lock held. 186 * Returns either zero, or negative errno. 187 * 188 * set_cca_mode 189 * Sets the CCA mode used by the device. Called with pib_lock held. 190 * Returns either zero, or negative errno. 191 * 192 * set_cca_ed_level 193 * Sets the CCA energy detection threshold in mBm. Called with pib_lock 194 * held. 195 * Returns either zero, or negative errno. 196 * 197 * set_csma_params 198 * Sets the CSMA parameter set for the PHY. Called with pib_lock held. 199 * Returns either zero, or negative errno. 200 * 201 * set_frame_retries 202 * Sets the retransmission attempt limit. Called with pib_lock held. 203 * Returns either zero, or negative errno. 204 * 205 * set_promiscuous_mode 206 * Enables or disable promiscuous mode. 207 */ 208 struct ieee802154_ops { 209 struct module *owner; 210 int (*start)(struct ieee802154_hw *hw); 211 void (*stop)(struct ieee802154_hw *hw); 212 int (*xmit_sync)(struct ieee802154_hw *hw, 213 struct sk_buff *skb); 214 int (*xmit_async)(struct ieee802154_hw *hw, 215 struct sk_buff *skb); 216 int (*ed)(struct ieee802154_hw *hw, u8 *level); 217 int (*set_channel)(struct ieee802154_hw *hw, u8 page, 218 u8 channel); 219 int (*set_hw_addr_filt)(struct ieee802154_hw *hw, 220 struct ieee802154_hw_addr_filt *filt, 221 unsigned long changed); 222 int (*set_txpower)(struct ieee802154_hw *hw, s32 mbm); 223 int (*set_lbt)(struct ieee802154_hw *hw, bool on); 224 int (*set_cca_mode)(struct ieee802154_hw *hw, 225 const struct wpan_phy_cca *cca); 226 int (*set_cca_ed_level)(struct ieee802154_hw *hw, s32 mbm); 227 int (*set_csma_params)(struct ieee802154_hw *hw, 228 u8 min_be, u8 max_be, u8 retries); 229 int (*set_frame_retries)(struct ieee802154_hw *hw, 230 s8 retries); 231 int (*set_promiscuous_mode)(struct ieee802154_hw *hw, 232 const bool on); 233 }; 234 235 /** 236 * ieee802154_get_fc_from_skb - get the frame control field from an skb 237 * @skb: skb where the frame control field will be get from 238 */ 239 static inline __le16 ieee802154_get_fc_from_skb(const struct sk_buff *skb) 240 { 241 __le16 fc; 242 243 /* check if we can fc at skb_mac_header of sk buffer */ 244 if (WARN_ON(!skb_mac_header_was_set(skb) || 245 (skb_tail_pointer(skb) - 246 skb_mac_header(skb)) < IEEE802154_FC_LEN)) 247 return cpu_to_le16(0); 248 249 memcpy(&fc, skb_mac_header(skb), IEEE802154_FC_LEN); 250 return fc; 251 } 252 253 /** 254 * ieee802154_skb_dst_pan - get the pointer to destination pan field 255 * @fc: mac header frame control field 256 * @skb: skb where the destination pan pointer will be get from 257 */ 258 static inline unsigned char *ieee802154_skb_dst_pan(__le16 fc, 259 const struct sk_buff *skb) 260 { 261 unsigned char *dst_pan; 262 263 switch (ieee802154_daddr_mode(fc)) { 264 case cpu_to_le16(IEEE802154_FCTL_ADDR_NONE): 265 dst_pan = NULL; 266 break; 267 case cpu_to_le16(IEEE802154_FCTL_DADDR_SHORT): 268 case cpu_to_le16(IEEE802154_FCTL_DADDR_EXTENDED): 269 dst_pan = skb_mac_header(skb) + 270 IEEE802154_FC_LEN + 271 IEEE802154_SEQ_LEN; 272 break; 273 default: 274 WARN_ONCE(1, "invalid addr mode detected"); 275 dst_pan = NULL; 276 break; 277 } 278 279 return dst_pan; 280 } 281 282 /** 283 * ieee802154_skb_src_pan - get the pointer to source pan field 284 * @fc: mac header frame control field 285 * @skb: skb where the source pan pointer will be get from 286 */ 287 static inline unsigned char *ieee802154_skb_src_pan(__le16 fc, 288 const struct sk_buff *skb) 289 { 290 unsigned char *src_pan; 291 292 switch (ieee802154_saddr_mode(fc)) { 293 case cpu_to_le16(IEEE802154_FCTL_ADDR_NONE): 294 src_pan = NULL; 295 break; 296 case cpu_to_le16(IEEE802154_FCTL_SADDR_SHORT): 297 case cpu_to_le16(IEEE802154_FCTL_SADDR_EXTENDED): 298 /* if intra-pan and source addr mode is non none, 299 * then source pan id is equal destination pan id. 300 */ 301 if (ieee802154_is_intra_pan(fc)) { 302 src_pan = ieee802154_skb_dst_pan(fc, skb); 303 break; 304 } 305 306 switch (ieee802154_daddr_mode(fc)) { 307 case cpu_to_le16(IEEE802154_FCTL_ADDR_NONE): 308 src_pan = skb_mac_header(skb) + 309 IEEE802154_FC_LEN + 310 IEEE802154_SEQ_LEN; 311 break; 312 case cpu_to_le16(IEEE802154_FCTL_DADDR_SHORT): 313 src_pan = skb_mac_header(skb) + 314 IEEE802154_FC_LEN + 315 IEEE802154_SEQ_LEN + 316 IEEE802154_PAN_ID_LEN + 317 IEEE802154_SHORT_ADDR_LEN; 318 break; 319 case cpu_to_le16(IEEE802154_FCTL_DADDR_EXTENDED): 320 src_pan = skb_mac_header(skb) + 321 IEEE802154_FC_LEN + 322 IEEE802154_SEQ_LEN + 323 IEEE802154_PAN_ID_LEN + 324 IEEE802154_EXTENDED_ADDR_LEN; 325 break; 326 default: 327 WARN_ONCE(1, "invalid addr mode detected"); 328 src_pan = NULL; 329 break; 330 } 331 break; 332 default: 333 WARN_ONCE(1, "invalid addr mode detected"); 334 src_pan = NULL; 335 break; 336 } 337 338 return src_pan; 339 } 340 341 /** 342 * ieee802154_skb_is_intra_pan_addressing - checks whenever the mac addressing 343 * is an intra pan communication 344 * @fc: mac header frame control field 345 * @skb: skb where the source and destination pan should be get from 346 */ 347 static inline bool ieee802154_skb_is_intra_pan_addressing(__le16 fc, 348 const struct sk_buff *skb) 349 { 350 unsigned char *dst_pan = ieee802154_skb_dst_pan(fc, skb), 351 *src_pan = ieee802154_skb_src_pan(fc, skb); 352 353 /* if one is NULL is no intra pan addressing */ 354 if (!dst_pan || !src_pan) 355 return false; 356 357 return !memcmp(dst_pan, src_pan, IEEE802154_PAN_ID_LEN); 358 } 359 360 /** 361 * ieee802154_be64_to_le64 - copies and convert be64 to le64 362 * @le64_dst: le64 destination pointer 363 * @be64_src: be64 source pointer 364 */ 365 static inline void ieee802154_be64_to_le64(void *le64_dst, const void *be64_src) 366 { 367 put_unaligned_le64(get_unaligned_be64(be64_src), le64_dst); 368 } 369 370 /** 371 * ieee802154_le64_to_be64 - copies and convert le64 to be64 372 * @be64_dst: be64 destination pointer 373 * @le64_src: le64 source pointer 374 */ 375 static inline void ieee802154_le64_to_be64(void *be64_dst, const void *le64_src) 376 { 377 put_unaligned_be64(get_unaligned_le64(le64_src), be64_dst); 378 } 379 380 /** 381 * ieee802154_le16_to_be16 - copies and convert le16 to be16 382 * @be16_dst: be16 destination pointer 383 * @le16_src: le16 source pointer 384 */ 385 static inline void ieee802154_le16_to_be16(void *be16_dst, const void *le16_src) 386 { 387 put_unaligned_be16(get_unaligned_le16(le16_src), be16_dst); 388 } 389 390 /** 391 * ieee802154_be16_to_le16 - copies and convert be16 to le16 392 * @le16_dst: le16 destination pointer 393 * @be16_src: be16 source pointer 394 */ 395 static inline void ieee802154_be16_to_le16(void *le16_dst, const void *be16_src) 396 { 397 put_unaligned_le16(get_unaligned_be16(be16_src), le16_dst); 398 } 399 400 /** 401 * ieee802154_alloc_hw - Allocate a new hardware device 402 * 403 * This must be called once for each hardware device. The returned pointer 404 * must be used to refer to this device when calling other functions. 405 * mac802154 allocates a private data area for the driver pointed to by 406 * @priv in &struct ieee802154_hw, the size of this area is given as 407 * @priv_data_len. 408 * 409 * @priv_data_len: length of private data 410 * @ops: callbacks for this device 411 * 412 * Return: A pointer to the new hardware device, or %NULL on error. 413 */ 414 struct ieee802154_hw * 415 ieee802154_alloc_hw(size_t priv_data_len, const struct ieee802154_ops *ops); 416 417 /** 418 * ieee802154_free_hw - free hardware descriptor 419 * 420 * This function frees everything that was allocated, including the 421 * private data for the driver. You must call ieee802154_unregister_hw() 422 * before calling this function. 423 * 424 * @hw: the hardware to free 425 */ 426 void ieee802154_free_hw(struct ieee802154_hw *hw); 427 428 /** 429 * ieee802154_register_hw - Register hardware device 430 * 431 * You must call this function before any other functions in 432 * mac802154. Note that before a hardware can be registered, you 433 * need to fill the contained wpan_phy's information. 434 * 435 * @hw: the device to register as returned by ieee802154_alloc_hw() 436 * 437 * Return: 0 on success. An error code otherwise. 438 */ 439 int ieee802154_register_hw(struct ieee802154_hw *hw); 440 441 /** 442 * ieee802154_unregister_hw - Unregister a hardware device 443 * 444 * This function instructs mac802154 to free allocated resources 445 * and unregister netdevices from the networking subsystem. 446 * 447 * @hw: the hardware to unregister 448 */ 449 void ieee802154_unregister_hw(struct ieee802154_hw *hw); 450 451 /** 452 * ieee802154_rx_irqsafe - receive frame 453 * 454 * Like ieee802154_rx() but can be called in IRQ context 455 * (internally defers to a tasklet.) 456 * 457 * @hw: the hardware this frame came in on 458 * @skb: the buffer to receive, owned by mac802154 after this call 459 * @lqi: link quality indicator 460 */ 461 void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, 462 u8 lqi); 463 /** 464 * ieee802154_wake_queue - wake ieee802154 queue 465 * @hw: pointer as obtained from ieee802154_alloc_hw(). 466 * 467 * Tranceivers usually have either one transmit framebuffer or one framebuffer 468 * for both transmitting and receiving. Hence, the core currently only handles 469 * one frame at a time for each phy, which means we had to stop the queue to 470 * avoid new skb to come during the transmission. The queue then needs to be 471 * woken up after the operation. 472 * 473 * Drivers should use this function instead of netif_wake_queue. 474 */ 475 void ieee802154_wake_queue(struct ieee802154_hw *hw); 476 477 /** 478 * ieee802154_stop_queue - stop ieee802154 queue 479 * @hw: pointer as obtained from ieee802154_alloc_hw(). 480 * 481 * Tranceivers usually have either one transmit framebuffer or one framebuffer 482 * for both transmitting and receiving. Hence, the core currently only handles 483 * one frame at a time for each phy, which means we need to tell upper layers to 484 * stop giving us new skbs while we are busy with the transmitted one. The queue 485 * must then be stopped before transmitting. 486 * 487 * Drivers should use this function instead of netif_stop_queue. 488 */ 489 void ieee802154_stop_queue(struct ieee802154_hw *hw); 490 491 /** 492 * ieee802154_xmit_complete - frame transmission complete 493 * 494 * @hw: pointer as obtained from ieee802154_alloc_hw(). 495 * @skb: buffer for transmission 496 * @ifs_handling: indicate interframe space handling 497 */ 498 void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, 499 bool ifs_handling); 500 501 /** 502 * ieee802154_xmit_error - offloaded frame transmission failed 503 * 504 * @hw: pointer as obtained from ieee802154_alloc_hw(). 505 * @skb: buffer for transmission 506 * @reason: error code 507 */ 508 void ieee802154_xmit_error(struct ieee802154_hw *hw, struct sk_buff *skb, 509 int reason); 510 511 /** 512 * ieee802154_xmit_hw_error - frame could not be offloaded to the transmitter 513 * because of a hardware error (bus error, timeout, etc) 514 * 515 * @hw: pointer as obtained from ieee802154_alloc_hw(). 516 * @skb: buffer for transmission 517 */ 518 void ieee802154_xmit_hw_error(struct ieee802154_hw *hw, struct sk_buff *skb); 519 520 #endif /* NET_MAC802154_H */ 521