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_NOTIFICATION_H__ 36 #define NRF_802154_NOTIFICATION_H__ 37 38 #include <stdbool.h> 39 #include <stdint.h> 40 41 #include "nrf_802154.h" 42 #include "nrf_802154_types.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * @defgroup nrf_802154_notification 802.15.4 driver notification 50 * @{ 51 * @ingroup nrf_802154 52 * @brief Notifications to the next higher layer triggered from the 802.15.4 radio driver. 53 */ 54 55 /** 56 * @brief Function type used for notifications from critical sections in the core module. 57 * 58 * This function is called instead of the default notification. The function is passed to request 59 * notifications from a critical section during the request processing. 60 * 61 * @param[in] result If the called request succeeded. 62 */ 63 typedef void (* nrf_802154_notification_func_t)(bool result); 64 65 /** 66 * @brief Initializes the notification module. 67 */ 68 void nrf_802154_notification_init(void); 69 70 /** 71 * @brief Notifies the next higher layer that a frame was received. 72 * 73 * @param[in] p_data Pointer to a buffer that contains PHR and PSDU of the received frame. 74 * @param[in] power RSSI measured during the frame reception. 75 * @param[in] lqi LQI indicating measured link quality during the frame reception. 76 */ 77 void nrf_802154_notify_received(uint8_t * p_data, int8_t power, uint8_t lqi); 78 79 /** 80 * @brief Notifies the next higher layer that the reception of a frame failed. 81 * 82 * @param[in] error Error code that indicates the reason of the failure. 83 * @param[in] id Identifier of reception window the error occurred in. 84 * If the error is related to a delayed reception window requested through 85 * @ref nrf_802154_receive_at, the value of @p id equals the identifier 86 * of the scheduled reception window. Otherwise, the value of @p id equals 87 * @ref NRF_802154_RESERVED_IMM_RX_WINDOW_ID. 88 * @param[in] allow_drop Indicates if the notification can be dropped safely. 89 * 90 * @retval true The next higher layer is bound to be notified about the frame reception failure. 91 * @retval false Notification could not be executed. 92 */ 93 bool nrf_802154_notify_receive_failed(nrf_802154_rx_error_t error, uint32_t id, bool allow_drop); 94 95 /** 96 * @brief Notifies the next higher layer that a frame was transmitted. 97 * 98 * @note This function performs an update of the original frame and modifies @p p_metadata structure 99 * passed to the public callout. 100 * 101 * @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the transmitted frame. 102 * @param[in] p_metadata Pointer to a metadata structure describing frame passed in @p p_frame. 103 */ 104 void nrf_802154_notify_transmitted(uint8_t * p_frame, 105 nrf_802154_transmit_done_metadata_t * p_metadata); 106 107 /** 108 * @brief Notifies the next higher layer that a frame was not transmitted. 109 * 110 * @note This function performs an update of the original frame and prepares 111 * @ref nrf_802154_transmit_done_metadata_t structure passed to the public callout. 112 * 113 * @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the frame that failed 114 * the transmission operation. 115 * @param[in] error An error code indicating the reason of the failure. 116 * @param[in] p_metadata Pointer to a metadata structure to be notified. 117 */ 118 void nrf_802154_notify_transmit_failed(uint8_t * p_frame, 119 nrf_802154_tx_error_t error, 120 const nrf_802154_transmit_done_metadata_t * p_metadata); 121 122 /** 123 * @brief Notifies the next higher layer that the energy detection procedure ended. 124 * 125 * @param[in] p_result Pointer to structure containing the result of the ED operation. 126 */ 127 void nrf_802154_notify_energy_detected(const nrf_802154_energy_detected_t * p_result); 128 129 /** 130 * @brief Notifies the next higher layer that the energy detection procedure failed. 131 * 132 * @param[in] error Error code indicating the reason of the failure. 133 */ 134 void nrf_802154_notify_energy_detection_failed(nrf_802154_ed_error_t error); 135 136 /** 137 * @brief Notifies the next higher layer that the CCA procedure ended. 138 * 139 * @param[in] is_free If detected that channel is free. 140 */ 141 void nrf_802154_notify_cca(bool is_free); 142 143 /** 144 * @brief Notifies the next higher layer that the CCA procedure failed. 145 * 146 * @param[in] error Error code indicating reason of the failure. 147 */ 148 void nrf_802154_notify_cca_failed(nrf_802154_cca_error_t error); 149 150 /** 151 *@} 152 **/ 153 154 #ifdef __cplusplus 155 } 156 #endif 157 158 #endif // NRF_802154_NOTIFICATION_H__ 159
