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_DELAYED_TRX_H__ 36 #define NRF_802154_DELAYED_TRX_H__ 37 38 #include <stdbool.h> 39 #include <stdint.h> 40 41 #include "nrf_802154_const.h" 42 #include "nrf_802154_config.h" 43 #include "nrf_802154_types.h" 44 45 #if NRF_802154_DELAYED_TRX_ENABLED || defined(__DOXYGEN__) 46 47 /** 48 * @defgroup nrf_802154_delayed_trx Delayed transmission and reception window features 49 * @{ 50 * @ingroup nrf_802154 51 * @brief Delayed transmission or receive window. 52 * 53 * This module implements delayed transmission and receive window features used in the CSL and TSCH 54 * modes. 55 */ 56 57 /** 58 * @brief Initializes delayed transmission and reception window features. 59 */ 60 void nrf_802154_delayed_trx_init(void); 61 62 /** 63 * @brief Deinitializes delayed transmission and reception window features. 64 */ 65 void nrf_802154_delayed_trx_deinit(void); 66 67 /** 68 * @brief Requests transmission of a frame at a given time. 69 * 70 * If the requested transmission is successful and the frame is transmitted, the 71 * @ref nrf_802154_tx_started function is called. If the requested frame cannot be transmitted 72 * at the given time, the @ref nrf_802154_transmit_failed function is called. 73 * 74 * @note The delayed transmission does not time out automatically when waiting for ACK. 75 * Waiting for ACK must be timed out by the next higher layer or the ACK timeout module. 76 * The ACK timeout timer must start when the @ref nrf_802154_tx_started function is called. 77 * 78 * @param[in] p_data Pointer to a buffer containing PHR and PSDU of the frame to be 79 * transmitted. 80 * @param[in] tx_time Absolute time used by the SL Timer, in microseconds (us). 81 * @param[in] p_metadata Pointer to metadata structure. Contains detailed properties of data 82 * to transmit and additional parameters for the procedure. 83 */ 84 bool nrf_802154_delayed_trx_transmit(uint8_t * p_data, 85 uint64_t tx_time, 86 const nrf_802154_transmit_at_metadata_t * p_metadata); 87 88 /** 89 * @brief Cancels a transmission scheduled by a call to @ref nrf_802154_delayed_trx_transmit. 90 * 91 * This function does not cancel transmission if the transmission is already ongoing. 92 * 93 * @retval true Successfully cancelled a scheduled transmission. 94 * @retval false No delayed transmission was scheduled. 95 */ 96 bool nrf_802154_delayed_trx_transmit_cancel(void); 97 98 /** 99 * @brief Requests the reception of a frame at a given time. 100 * 101 * If the request is accepted and a frame is received during the defined time slot, 102 * the @ref nrf_802154_received_raw function is called. If the request is rejected due 103 * to a denied timeslot request or the reception timeout expires, 104 * the @ref nrf_802154_receive_failed function is called. 105 * 106 * @note The identifier @p id must be unique. It must not have the same value as identifiers 107 * of other delayed timeslots active at the moment, so that it can be mapped unambiguously 108 * to an active delayed operation if the request is successful. In particular, none of the reserved 109 * identifiers can be used. 110 * 111 * @param[in] rx_time Absolute time used by the SL Timer, in microseconds (us). 112 * @param[in] timeout Reception timeout (counted from @p rx_time) in microseconds. 113 * @param[in] channel Number of the channel on which the frame is to be received. 114 * @param[in] id Identifier of the scheduled reception window. If the reception has been 115 * scheduled successfully, the value of this parameter can be used in 116 * @ref nrf_802154_delayed_trx_receive_cancel to cancel it. 117 * 118 * @retval true The reception procedure was scheduled. 119 * @retval false The driver could not schedule the reception procedure. 120 */ 121 bool nrf_802154_delayed_trx_receive(uint64_t rx_time, 122 uint32_t timeout, 123 uint8_t channel, 124 uint32_t id); 125 126 /** 127 * @brief Cancels a reception scheduled by a call to @ref nrf_802154_delayed_trx_receive. 128 * 129 * After a call to this function, no reception timeout event will be notified. 130 * 131 * @param[in] id Identifier of the delayed reception window to be cancelled. If the provided 132 * value does not refer to any scheduled or active receive window, the function 133 * returns false. 134 * 135 * @retval true Successfully cancelled a scheduled transmission. 136 * @retval false No delayed reception was scheduled. 137 */ 138 bool nrf_802154_delayed_trx_receive_cancel(uint32_t id); 139 140 /** 141 * @brief Aborts an ongoing delayed reception procedure. 142 * 143 * @param[in] term_lvl Termination level set by the request to abort the ongoing operation. 144 * @param[in] req_orig Module that originates this request. 145 * 146 * If the delayed transmission/reception procedures are not running during the call, 147 * this function does nothing. 148 * 149 * @retval true Transmission/reception procedures have been stopped. 150 * @retval false Transmission/reception procedures were not running. 151 * 152 */ 153 bool nrf_802154_delayed_trx_abort(nrf_802154_term_t term_lvl, req_originator_t req_orig); 154 155 /** 156 * @brief Extends the timeout timer when the reception start is detected and there is not enough 157 * time left for a delayed RX operation. 158 * 159 * @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the frame 160 * that is being received. 161 * 162 * If the delayed transmission/reception procedures are not running during call, 163 * this function does nothing. 164 * 165 */ 166 void nrf_802154_delayed_trx_rx_started_hook(const uint8_t * p_frame); 167 168 /** 169 * @brief Gets the time in microseconds to the midpoint of the nearest scheduled DRX window. 170 * 171 * @param[out] p_drx_time_to_midpoint Pointer to a 32-bit variable where the time to the 172 * midpoint of the nearest DRX will be stored. 173 * 174 * @retval true A pending DRX was scheduled and p_drx_time_to_start contains a valid value. 175 * @retval false A pending DRX was not scheduled and p_drx_time_to_start was not modified. 176 * 177 */ 178 bool nrf_802154_delayed_trx_nearest_drx_time_to_midpoint_get(uint32_t * p_drx_time_to_midpoint); 179 180 /** 181 *@} 182 **/ 183 184 #endif // NRF_802154_DELAYED_TRX_ENABLED 185 186 #endif // NRF_802154_DELAYED_TRX_H__ 187
