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 #ifndef NRF_802154_REQUEST_H__ 36 #define NRF_802154_REQUEST_H__ 37 38 #include <stdbool.h> 39 #include <stdint.h> 40 41 #include "nrf_802154_const.h" 42 #include "nrf_802154_notification.h" 43 #include "nrf_802154_types_internal.h" 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @defgroup nrf_802154_request 802.15.4 driver request 51 * @{ 52 * @ingroup nrf_802154 53 * @brief Requests to the driver triggered from the MAC layer. 54 */ 55 56 /** 57 * @brief Initializes the request module. 58 */ 59 void nrf_802154_request_init(void); 60 61 /** 62 * @brief Requests entering the @ref RADIO_STATE_SLEEP state for the driver. 63 * 64 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 65 * 66 * @retval true The driver will enter sleep state. 67 * @retval false The driver cannot enter the sleep state due to an ongoing operation. 68 */ 69 bool nrf_802154_request_sleep(nrf_802154_term_t term_lvl); 70 71 /** 72 * @brief Requests entering the @ref RADIO_STATE_RX state for the driver. 73 * 74 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 75 * @param[in] req_orig Module that originates this request. 76 * @param[in] notify_function Function called to notify the status of this procedure. May be NULL. 77 * @param[in] notify_abort If the abort notification is to be triggered automatically. 78 * @param[in] id Identifier of a reception window. 79 * 80 * @retval true The driver will enter the receive state. 81 * @retval false The driver cannot enter the receive state due to ongoing operation. 82 */ 83 bool nrf_802154_request_receive(nrf_802154_term_t term_lvl, 84 req_originator_t req_orig, 85 nrf_802154_notification_func_t notify_function, 86 bool notify_abort, 87 uint32_t id); 88 89 /** 90 * @brief Request entering the @ref RADIO_STATE_TX state for the driver. 91 * 92 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 93 * @param[in] req_orig Module that originates this request. 94 * @param[in] p_data Pointer to the frame to transmit. 95 * @param[in] p_params Pointer to transmission parameters. 96 * @param[in] notify_function Function called to notify the status of this procedure. May be NULL. 97 * 98 * @retval true The driver will enter the transmit state. 99 * @retval false The driver cannot enter the transmit state due to an ongoing operation. 100 */ 101 bool nrf_802154_request_transmit(nrf_802154_term_t term_lvl, 102 req_originator_t req_orig, 103 uint8_t * p_data, 104 nrf_802154_transmit_params_t * p_params, 105 nrf_802154_notification_func_t notify_function); 106 107 /** 108 * @brief Request to handle Ack timeout by the core module. 109 * 110 * @param[in] p_param Parameter to pass to nrf_802154_core_ack_timeout_handle 111 * 112 */ 113 bool nrf_802154_request_ack_timeout_handle(const nrf_802154_ack_timeout_handle_params_t * p_param); 114 115 /** 116 * @brief Requests entering the @ref RADIO_STATE_ED state. 117 * 118 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 119 * @param[in] time_us Requested duration of the energy detection procedure. 120 * 121 * @retval true The driver will enter energy detection state. 122 * @retval false The driver cannot enter the energy detection state due to an ongoing operation. 123 */ 124 bool nrf_802154_request_energy_detection(nrf_802154_term_t term_lvl, uint32_t time_us); 125 126 /** 127 * @brief Requests entering the @ref RADIO_STATE_CCA state. 128 * 129 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 130 * 131 * @retval true The driver will enter the CCA state. 132 * @retval false The driver cannot enter the CCA state due to an ongoing operation. 133 */ 134 bool nrf_802154_request_cca(nrf_802154_term_t term_lvl); 135 136 #if NRF_802154_CARRIER_FUNCTIONS_ENABLED 137 138 /** 139 * @brief Requests entering the @ref RADIO_STATE_CONTINUOUS_CARRIER state. 140 * 141 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 142 * 143 * @retval true The driver will enter the continuous carrier state. 144 * @retval false The driver cannot enter the continuous carrier state due to an ongoing operation. 145 */ 146 bool nrf_802154_request_continuous_carrier(nrf_802154_term_t term_lvl); 147 148 /** 149 * @brief Requests entering the @ref RADIO_STATE_MODULATED_CARRIER state. 150 * 151 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 152 * @param[in] p_data Pointer to a buffer to modulate the carrier with. 153 * 154 * @retval true The driver will enter the modulated carrier state. 155 * @retval false The driver cannot enter the modulated carrier state due to an ongoing operation. 156 */ 157 bool nrf_802154_request_modulated_carrier(nrf_802154_term_t term_lvl, 158 const uint8_t * p_data); 159 160 #endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED 161 162 /** 163 * @brief Requests the driver to free the given buffer. 164 * 165 * @param[in] p_data Pointer to the buffer to be freed. 166 */ 167 bool nrf_802154_request_buffer_free(uint8_t * p_data); 168 169 /** 170 * @brief Requests the driver to update the antenna used. 171 */ 172 bool nrf_802154_request_antenna_update(void); 173 174 /** 175 * @brief Requests the driver to update the channel number used by the RADIO peripheral. 176 * 177 * @param[in] req_orig Module that originates this request. 178 */ 179 bool nrf_802154_request_channel_update(req_originator_t req_orig); 180 181 /** 182 * @brief Requests the driver to update the CCA configuration used by the RADIO peripheral. 183 */ 184 bool nrf_802154_request_cca_cfg_update(void); 185 186 /** 187 * @brief Requests the RSSI measurement. 188 */ 189 bool nrf_802154_request_rssi_measure(void); 190 191 /** 192 * @brief Requests getting the last RSSI measurement result. 193 */ 194 bool nrf_802154_request_rssi_measurement_get(int8_t * p_rssi); 195 196 #if NRF_802154_DELAYED_TRX_ENABLED 197 /** 198 * @brief Requests a call to @ref nrf_802154_delayed_trx_transmit. 199 * 200 * @param[in] p_data Pointer to the array with data to transmit. The first byte must contain 201 * the frame length (including FCS). The following bytes contain data. 202 * The CRC is computed automatically by the radio hardware. Therefore, 203 * the FCS field can contain any bytes. 204 * @param[in] tx_time Absolute time used by the SL timer, in microseconds (us). 205 * @param[in] p_metadata Pointer to metadata structure. Contains detailed properties of data 206 * to transmit. If @c NULL following metadata are used: 207 * Field | Value 208 * ----------------|----------------------------------------------------- 209 * @c frame_props | @ref NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT 210 * @c cca | @c true 211 * @c channel | As returned by @ref nrf_802154_channel_get 212 * 213 * @retval true The transmission procedure was scheduled. 214 * @retval false The driver could not schedule the transmission procedure. 215 */ 216 bool nrf_802154_request_transmit_raw_at(uint8_t * p_data, 217 uint64_t tx_time, 218 const nrf_802154_transmit_at_metadata_t * p_metadata); 219 220 /** 221 * @brief Requests a call to @ref nrf_802154_delayed_trx_transmit_cancel. 222 * 223 * @retval true The delayed transmission was scheduled and successfully cancelled. 224 * @retval false No delayed transmission was scheduled. 225 */ 226 bool nrf_802154_request_transmit_at_cancel(void); 227 228 /** 229 * @brief Requests a call to @ref nrf_802154_delayed_trx_receive. 230 * 231 * @param[in] rx_time Absolute time used by the SL Timer, in microseconds (us). 232 * @param[in] timeout Reception timeout (counted from @p rx_time), in microseconds (us). 233 * @param[in] channel Radio channel on which the frame is to be received. 234 * @param[in] id Identifier of the scheduled reception window. If the reception has been 235 * scheduled successfully, the value of this parameter can be used in 236 * @ref nrf_802154_receive_at_cancel to cancel it. 237 * 238 * @retval true The reception procedure was scheduled. 239 * @retval false The driver could not schedule the reception procedure. 240 */ 241 bool nrf_802154_request_receive_at(uint64_t rx_time, 242 uint32_t timeout, 243 uint8_t channel, 244 uint32_t id); 245 246 /** 247 * @brief Requests a call to @ref nrf_802154_delayed_trx_receive_cancel. 248 * 249 * @param[in] id Identifier of the delayed reception window to be cancelled. If the provided 250 * value does not refer to any scheduled or active receive window, the function 251 * returns false. 252 * 253 * @retval true The delayed reception was scheduled and successfully cancelled. 254 * @retval false No delayed reception was scheduled. 255 */ 256 bool nrf_802154_request_receive_at_cancel(uint32_t id); 257 258 #endif // NRF_802154_DELAYED_TRX_ENABLED 259 260 /** 261 * @brief Requests CSMA-CA procedure for the transmission of a given frame. 262 * 263 * @param[in] p_data Pointer to a buffer the contains PHR and PSDU of the frame that is 264 * to be transmitted. 265 * @param[in] p_metadata Pointer to metadata structure. Contains detailed properties of data 266 * to transmit. 267 */ 268 bool nrf_802154_request_csma_ca_start(uint8_t * p_data, 269 const nrf_802154_transmit_csma_ca_metadata_t * p_metadata); 270 271 /** 272 *@} 273 **/ 274 275 #ifdef __cplusplus 276 } 277 #endif 278 279 #endif // NRF_802154_REQUEST_H__ 280
