1 /* 2 * Copyright (c) 2016 Intel Corporation. 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 /** 8 * @file 9 * @brief Private IEEE 802.15.4 low level L2 helper utilities 10 * 11 * These utilities are internal to the native IEEE 802.15.4 L2 12 * stack and must not be included and used elsewhere. 13 * 14 * All references to the spec refer to IEEE 802.15.4-2020. 15 */ 16 17 #ifndef __IEEE802154_PRIV_H__ 18 #define __IEEE802154_PRIV_H__ 19 20 #include <zephyr/net_buf.h> 21 #include <zephyr/net/net_if.h> 22 #include <zephyr/net/net_pkt.h> 23 24 /** 25 * @brief Sends the given fragment respecting the configured IEEE 802.15.4 access arbitration 26 * algorithm (CSMA/CA, ALOHA, etc.) and re-transmission protocol. See sections 6.2.5 (random 27 * access methods) and 6.7.4.4 (retransmissions). 28 * 29 * This function checks for and supports both, software and hardware access arbitration and 30 * acknowledgment depending on driver capabilities. 31 * 32 * @param iface A valid pointer on a network interface to send from 33 * @param pkt A valid pointer on a packet to send 34 * @param frag The fragment to be sent 35 * 36 * @return 0 on success, negative value otherwise 37 */ 38 int ieee802154_radio_send(struct net_if *iface, struct net_pkt *pkt, struct net_buf *frag); 39 40 /** 41 * @brief This function implements the configured channel access algorithm (CSMA/CA, ALOHA, 42 * etc.). Currently only one implementation of this function may be compiled into the 43 * source code. The implementation will be selected via Kconfig variables (see 44 * @ref NET_L2_IEEE802154_RADIO_CSMA_CA and @ref NET_L2_IEEE802154_RADIO_ALOHA). 45 * 46 * This method will be called by ieee802154_radio_send() to determine if and when the 47 * radio channel is clear to send. It blocks the thread during backoff if the selected 48 * algorithm implements a backoff strategy. 49 * 50 * See sections 6.2.5 and 10.2.8. 51 * 52 * @param iface A valid pointer on a network interface to assesss 53 * 54 * @return 0 if the channel is clear to send, -EBUSY if a timeout was reached while waiting for 55 * a clear channel, other negative values to signal internal error conditions. 56 */ 57 int ieee802154_wait_for_clear_channel(struct net_if *iface); 58 59 /** 60 * @brief Checks whether the given packet requires acknowledgment, and if so, prepares ACK 61 * reception on the TX path, i.e. sets up the necessary internal state before a transmission. 62 * 63 * This function has side effects and must be called before each individual transmission 64 * attempt. 65 * 66 * This function checks for and supports both, software and hardware acknowledgement, 67 * depending on driver capabilities. 68 * 69 * See sections 6.7.4.1 through 6.7.4.3. 70 * 71 * @param iface A valid pointer on the network the packet will be transmitted to 72 * @param pkt A valid pointer on a packet to send 73 * @param frag The fragment that needs to be acknowledged 74 * 75 * @return true if the given packet requires acknowledgement, false otherwise. 76 */ 77 bool ieee802154_prepare_for_ack(struct net_if *iface, struct net_pkt *pkt, struct net_buf *frag); 78 79 /** 80 * @brief Waits for ACK reception on the TX path with standard compliant timeout settings, i.e. 81 * listens for incoming packages with the correct attributes and sequence number, see 82 * section 6.7.4.4 (retransmissions). 83 * 84 * This function has side effects and must be called after each transmission attempt if (and only 85 * if) @ref ieee802154_prepare_for_ack() had been called before. 86 * 87 * This function checks for and supports both, software and hardware acknowledgement, depending on 88 * driver capabilities. 89 * 90 * @param iface A valid pointer on the network the packet was transmitted to 91 * @param ack_required The return value from the corresponding call to 92 * @ref ieee802154_prepare_for_ack() 93 * 94 * @return 0 if no ACK was required or the expected ACK was received in time, -EIO if the expected 95 * ACK was not received within the standard compliant timeout. 96 */ 97 int ieee802154_wait_for_ack(struct net_if *iface, bool ack_required); 98 99 #endif /* __IEEE802154_PRIV_H__ */ 100
