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_CORE_HOOKS_H__ 36 #define NRF_802154_CORE_HOOKS_H__ 37 38 #include <stdbool.h> 39 #include <stdint.h> 40 41 #include "nrf_802154_const.h" 42 #include "nrf_802154_types_internal.h" 43 44 /** 45 * @defgroup nrf_802154_hooks Hooks for the 802.15.4 driver core 46 * @{ 47 * @ingroup nrf_802154 48 * @brief Hooks for the 802.15.4 driver core module. 49 * 50 * Hooks are used by the optional driver features to modify the way in which notifications 51 * are propagated through the driver. 52 */ 53 54 /** 55 * @brief Processes hooks for the termination request. 56 * 57 * @param[in] term_lvl Termination level of the request that terminates the current operation. 58 * @param[in] req_orig Module that originates this request. 59 * 60 * @retval true All procedures are aborted. 61 * @retval false There is an ongoing procedure that cannot be aborted due to a too low @p term_lvl. 62 */ 63 bool nrf_802154_core_hooks_terminate(nrf_802154_term_t term_lvl, req_originator_t req_orig); 64 65 /** 66 * @brief Processes hooks which are to fire before the transmission request and before 67 * attempt to terminate previous operation. 68 * 69 * @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the frame 70 * that is to be transmitted. 71 * @param[in] p_params Pointer to the transmission parameters. 72 * @param[in] notify_function Function to be called to notify transmission failure. 73 * 74 * @retval true Frame can be sent immediately. 75 * @retval false Hooks have handled the frame - upper layer should not worry about it anymore. 76 */ 77 bool nrf_802154_core_hooks_pre_transmission( 78 uint8_t * p_frame, 79 nrf_802154_transmit_params_t * p_params, 80 nrf_802154_transmit_failed_notification_t notify_function); 81 82 /** 83 * @brief Processes hooks which are to fire before the transmission but after previous operation 84 * has been already terminated. 85 * 86 * @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the frame 87 * that is to be transmitted. 88 * @param[in] p_params Pointer to the transmission parameters. 89 * @param[in] notify_function Function to be called to notify transmission failure. 90 * 91 * @retval true Frame can be sent immediately. 92 * @retval false Hooks have handled the frame - upper layer should not worry about it anymore. 93 */ 94 bool nrf_802154_core_hooks_tx_setup( 95 uint8_t * p_frame, 96 nrf_802154_transmit_params_t * p_params, 97 nrf_802154_transmit_failed_notification_t notify_function); 98 99 /** 100 * @brief Processes hooks for the transmitted event. 101 * 102 * @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the frame 103 * that was transmitted. 104 */ 105 void nrf_802154_core_hooks_transmitted(const uint8_t * p_frame); 106 107 /** 108 * @brief Processes hooks for the TX failed event. 109 * 110 * @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the frame 111 * that was not transmitted. 112 * @param[in] error Cause of the failed transmission. 113 * 114 * @retval true TX failed event is to be propagated to the MAC layer. 115 * @retval false TX failed event is not to be propagated to the MAC layer. It is handled 116 * internally. 117 */ 118 bool nrf_802154_core_hooks_tx_failed(uint8_t * p_frame, nrf_802154_tx_error_t error); 119 120 /** 121 * @brief Processes hooks for the ACK TX failed event. 122 * 123 * @param[in] p_ack Pointer to a buffer that contains PHR and PSDU of the ACK frame 124 * that was not transmitted. 125 * @param[in] error Cause of the failed transmission. 126 */ 127 void nrf_802154_core_hooks_tx_ack_failed(uint8_t * p_ack, nrf_802154_tx_error_t error); 128 129 /** 130 * @brief Processes hooks for the TX started event. 131 * 132 * @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the frame 133 * that is being transmitted. 134 * 135 * @retval true TX started event is to be propagated to the MAC layer. 136 * @retval false TX started event is not to be propagated to the MAC layer. It is handled 137 * internally. 138 */ 139 bool nrf_802154_core_hooks_tx_started(uint8_t * p_frame); 140 141 /** 142 * @brief Processes hooks for the RX started event. 143 * 144 * @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the frame 145 * that is being received. 146 */ 147 void nrf_802154_core_hooks_rx_started(const uint8_t * p_frame); 148 149 /** 150 * @brief Processes hooks for the RX ACK started event. 151 */ 152 void nrf_802154_core_hooks_rx_ack_started(void); 153 154 /** 155 * @brief Processes hooks for the TX ACK started event. 156 * 157 * @param[in] p_ack Pointer to a buffer that contains PHR and PSDU of the ACK frame 158 * that is being transmitted. 159 */ 160 void nrf_802154_core_hooks_tx_ack_started(uint8_t * p_ack); 161 162 /** 163 *@} 164 **/ 165 166 #endif // NRF_802154_CORE_HOOKS_H__ 167
