1 /* 2 * Copyright (c) 2017, Nordic Semiconductor ASA 3 * All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions are met: 9 * 10 * 1. Redistributions of source code must retain the above copyright notice, this 11 * list of conditions and the following disclaimer. 12 * 13 * 2. Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in the 15 * documentation and/or other materials provided with the distribution. 16 * 17 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its 18 * contributors may be used to endorse or promote products derived from this 19 * software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 22 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23 * IMPLIED WARRANTIES OF MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE 24 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 25 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 26 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 27 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 28 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 29 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 30 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 31 * POSSIBILITY OF SUCH DAMAGE. 32 * 33 */ 34 35 /**@file nrf_802154_callouts.h 36 * @brief Provides function prototypes required by nRF 802.15.4 Radio Driver 37 * 38 * Functions whose prototypes are defined in this file are to be implemented 39 * by an application using the nRF 802.15.4 Radio Driver. 40 */ 41 42 /** 43 * @defgroup nrf_802154_calls Calls to higher layer 44 * @{ 45 */ 46 47 #ifndef NRF_802154_CALLOUTS_H_ 48 #define NRF_802154_CALLOUTS_H_ 49 50 #include <stdint.h> 51 #include <stdbool.h> 52 53 #include "nrf_802154_config.h" 54 #include "nrf_802154_types.h" 55 56 /** 57 * @brief Notifies that the CCA procedure has finished. 58 * 59 * @param[in] channel_free Indication if the channel is free. 60 */ 61 extern void nrf_802154_cca_done(bool channel_free); 62 63 /** 64 * @brief Notifies that the CCA procedure failed. 65 * 66 * @param[in] error Reason of the failure. 67 */ 68 extern void nrf_802154_cca_failed(nrf_802154_cca_error_t error); 69 70 /** 71 * @brief Notifies that the energy detection procedure finished. 72 * 73 * @param[in] p_result Pointer to structure containing the result of the operation. 74 * The pointer is valid within the @ref nrf_802154_energy_detected only. 75 */ 76 extern void nrf_802154_energy_detected(const nrf_802154_energy_detected_t * p_result); 77 78 /** 79 * @brief Notifies that the energy detection procedure failed. 80 * 81 * @param[in] error Reason of the failure. 82 */ 83 extern void nrf_802154_energy_detection_failed(nrf_802154_ed_error_t error); 84 85 /** 86 * @brief Notifies about the start of the ACK frame transmission. 87 * 88 * @note If a call to this function is performed by the same CPU running core 89 * of nRF 802.15.4 Radio Driver (non serialized call to @ref nrf_802154_tx_ack_started) 90 * the function must be very short to prevent dropping frames by the driver. 91 * If a call to this function is performed by a CPU through a serialization layer 92 * the call can be slightly delayed. The call can happen even after an ACK frame 93 * is fully transmitted. It is guaranteed that a call to @ref nrf_802154_tx_ack_started 94 * occurs before a call to @ref nrf_802154_received_timestamp_raw related to 95 * the same received frame. 96 * 97 * @param[in] p_data Pointer to a buffer with PHR and PSDU of the ACK frame. 98 */ 99 extern void nrf_802154_tx_ack_started(const uint8_t * p_data); 100 101 #if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN) 102 /** 103 * @brief Notifies that a frame was received. 104 * 105 * @note Currently this callout is only available on the CPU which is running the core of the radio driver. 106 * If the higher layer runs on a different core it should use nrf_802154_received_timestamp_raw instead. 107 * @note The buffer pointed to by @p p_data is not modified by the radio driver (and cannot be used 108 * to receive a frame) until @ref nrf_802154_buffer_free_raw is called. 109 * @note The buffer pointed to by @p p_data may be modified by the function handler (and other 110 * modules) until @ref nrf_802154_buffer_free_raw is called. 111 * @note Default implementation of this function provided by the nRF 802.15.4 Radio Driver 112 * calls @ref nrf_802154_received_timestamp_raw . 113 * 114 * @verbatim 115 * p_data 116 * v 117 * +-----+-----------------------------------------------------------+------------+ 118 * | PHR | MAC Header and payload | FCS | 119 * +-----+-----------------------------------------------------------+------------+ 120 * | | 121 * | <---------------------------- PHR -----------------------------------> | 122 * @endverbatim 123 * 124 * @param[in] p_data Pointer to a buffer that contains PHR and PSDU of the received frame. 125 * The first byte in the buffer is the length of the frame (PHR). The following 126 * bytes contain the frame itself (PSDU). The length byte (PHR) includes FCS. 127 * FCS is already verified by the hardware and may be modified by the hardware. 128 * @param[in] power RSSI of the received frame. 129 * @param[in] lqi LQI of the received frame. 130 */ 131 extern void nrf_802154_received_raw(uint8_t * p_data, int8_t power, uint8_t lqi); 132 133 #endif // !NRF_802154_SERIALIZATION_HOST 134 135 /** 136 * @brief Notifies that a frame was received at a given time. 137 * 138 * This function works like @ref nrf_802154_received_raw and adds a timestamp to the parameter 139 * list. 140 * 141 * @note The received frame usually contains a timestamp. However, due to a race condition, 142 * the timestamp may be invalid. This erroneous situation is indicated by 143 * the @ref NRF_802154_NO_TIMESTAMP value of the @p time parameter. 144 * 145 * @param[in] p_data Pointer to a buffer that contains PHR and PSDU of the received frame. 146 * The first byte in the buffer is the length of the frame (PHR). The following 147 * bytes contain the frame itself (PSDU). The length byte (PHR) includes FCS. 148 * FCS is already verified by the hardware and may be modified by the hardware. 149 * @param[in] power RSSI of the received frame. 150 * @param[in] lqi LQI of the received frame. 151 * @param[in] time Timestamp taken when the last symbol of the frame was received, in 152 * microseconds (us), or @ref NRF_802154_NO_TIMESTAMP if the timestamp 153 * is invalid. 154 */ 155 extern void nrf_802154_received_timestamp_raw(uint8_t * p_data, 156 int8_t power, 157 uint8_t lqi, 158 uint64_t time); 159 160 /** 161 * @brief Notifies that the reception of a frame failed. 162 * 163 * @param[in] error Error code that indicates the reason of the failure. 164 * @param[in] id Identifier of reception window the error occurred in. 165 * If the error is related to a delayed reception window requested through 166 * @ref nrf_802154_receive_at, the value of @p id equals the identifier 167 * of the scheduled reception window. Otherwise, the value of @p id equals 168 * @ref NRF_802154_RESERVED_IMM_RX_WINDOW_ID. 169 */ 170 extern void nrf_802154_receive_failed(nrf_802154_rx_error_t error, uint32_t id); 171 172 /** 173 * @brief Notifies that a frame was transmitted. 174 * 175 * @note If ACK was requested for the transmitted frame, this function is called after a proper ACK 176 * is received. If ACK was not requested, this function is called just after transmission has 177 * ended. 178 * @note The buffer pointed to by @c nrf_802154_transmit_done_metadata_t::data.transmitted.p_ack 179 * is not modified by the radio driver (and cannot be used to receive a frame) until 180 * @ref nrf_802154_buffer_free_raw is called. 181 * @note The buffer pointed to by @c nrf_802154_transmit_done_metadata_t::data.transmitted.p_ack 182 * may be modified by the function handler (and other modules) until 183 * @ref nrf_802154_buffer_free_raw is called. 184 * @note @c nrf_802154_transmit_done_metadata_t::data.transmitted.time granularity depends on the 185 * granularity of the timer driver in the 186 * platform/timer directory. 187 * 188 * @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the transmitted frame. 189 * @param[in] p_metadata Pointer to a metadata structure describing frame passed in @p p_frame. 190 */ 191 extern void nrf_802154_transmitted_raw(uint8_t * p_frame, 192 const nrf_802154_transmit_done_metadata_t * p_metadata); 193 194 /** 195 * @brief Notifies that a frame was not transmitted due to a busy channel. 196 * 197 * This function is called if the transmission procedure fails. 198 * 199 * @note Frame data values in @ref nrf_802154_transmit_done_metadata_t::data are invalid for 200 * @ref nrf_802154_transmit_failed callout. 201 * 202 * @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the frame that was not 203 * transmitted. 204 * @param[in] error Reason of the failure. 205 * @param[in] p_metadata Pointer to a metadata structure describing frame passed in @p p_frame. 206 */ 207 extern void nrf_802154_transmit_failed(uint8_t * p_frame, 208 nrf_802154_tx_error_t error, 209 const nrf_802154_transmit_done_metadata_t * p_metadata); 210 211 #if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN) 212 /** 213 * @brief Notifies that transmitting a frame has started. 214 * 215 * @note Currently this callout is only available on the CPU which is running the core of the radio driver. 216 * If the higher layer runs on a different core it should use nrf_802154_received_timestamp_raw instead. 217 * @note Usually, @ref nrf_802154_transmitted_raw is called shortly after this function. 218 * However, if the transmit procedure is interrupted, it might happen that 219 * @ref nrf_802154_transmitted_raw is not called. 220 * @note This function should be very short to prevent dropping frames by the driver. 221 * 222 * @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the frame being 223 * transmitted. 224 */ 225 extern void nrf_802154_tx_started(const uint8_t * p_frame); 226 227 /** 228 * @brief Perform some additional operations during initialization of the RADIO peripheral. 229 * 230 * By implementing this function the higher layer can provide some additional operations 231 * to be performed at the beginning of each new timeslot. These can in particular be 232 * modifications of RADIO peripheral register values. 233 */ 234 extern void nrf_802154_custom_part_of_radio_init(void); 235 236 #endif // !NRF_802154_SERIALIZATION_HOST 237 238 #endif /* NRF_802154_CALLOUTS_H_ */ 239 240 /** @} */ 241
