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_ACK_TIMEOUT_H__
36 #define NRF_802154_ACK_TIMEOUT_H__
37 
38 #include <stdbool.h>
39 #include <stdint.h>
40 
41 #include "nrf_802154_const.h"
42 #include "nrf_802154_types.h"
43 
44 /**
45  * @defgroup nrf_802154_ack_timeout 802.15.4 driver ACK timeout support
46  * @{
47  * @ingroup nrf_802154
48  * @brief ACK timeout feature.
49  */
50 
51 /**
52  * @brief Initializes the ACK timeout handling feature.
53  */
54 void nrf_802154_ack_timeout_init(void);
55 
56 /**
57  * @brief Deinitializes the ACK timeout handling feature.
58  */
59 void nrf_802154_ack_timeout_deinit(void);
60 
61 /**
62  * @brief Sets the timeout time for the ACK timeout feature.
63  *
64  * @param[in]  time  Timeout time in microseconds.
65  *                   The default value is defined in nrf_802154_config.h.
66  */
67 void nrf_802154_ack_timeout_time_set(uint32_t time);
68 
69 /**
70  * @brief Aborts a started ACK timeout procedure.
71  *
72  * @param[in]  term_lvl  Termination level set by the request for aborting the ongoing operation.
73  * @param[in]  req_orig  Module that originates the abort request.
74  *
75  * If the ACK timeout procedure is not running during the call, this function does nothing.
76  *
77  * @retval  true   ACK timeout procedure han been stopped.
78  */
79 bool nrf_802154_ack_timeout_abort(nrf_802154_term_t term_lvl, req_originator_t req_orig);
80 
81 /**
82  * @brief Handles a transmitted event.
83  *
84  * @param[in]  p_frame  Pointer to the buffer that contains the transmitted frame.
85  */
86 void nrf_802154_ack_timeout_transmitted_hook(const uint8_t * p_frame);
87 
88 /**
89  * @brief Handles a TX failed event.
90  *
91  * @param[in]  p_frame  Pointer to the buffer that contains a frame that was not transmitted.
92  * @param[in]  error    Cause of failed transmission.
93  *
94  * @retval  true   TX failed event is to be propagated to the MAC layer.
95  * @retval  false  TX failed event is not to be propagated to the MAC layer. It is handled
96  *                 internally in the ACK timeout module.
97  */
98 bool nrf_802154_ack_timeout_tx_failed_hook(uint8_t * p_frame, nrf_802154_tx_error_t error);
99 
100 /**
101  * @brief Handles a TX started event.
102  *
103  * @param[in]  p_frame  Pointer to the buffer that contains a frame being transmitted.
104  *
105  * @retval  true   TX started event is to be propagated to the MAC layer.
106  * @retval  false  TX started event is not to be propagated to the MAC layer. It is handled
107  *                 internally in the ACK timeout module.
108  */
109 bool nrf_802154_ack_timeout_tx_started_hook(uint8_t * p_frame);
110 
111 /**
112  * @brief Handles a RX ACK started event.
113  *
114  */
115 void nrf_802154_ack_timeout_rx_ack_started_hook(void);
116 
117 /**
118  *@}
119  **/
120 
121 #endif // NRF_802154_CSMA_CA_H__
122