1 /*
2  * Copyright (c) 2021, 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_IE_WRITER_H__
36 #define NRF_802154_IE_WRITER_H__
37 
38 #include <stdint.h>
39 #include <stdbool.h>
40 
41 #include "nrf_802154_types_internal.h"
42 
43 /**
44  * @defgroup nrf_802154_ie_writer Radio driver Information Element data injection feature.
45  * @{
46  * @ingroup nrf_802154
47  * @brief Information element writer module.
48  */
49 
50 /**
51  * @brief Resets the IE writer module to pristine state.
52  */
53 
54 void nrf_802154_ie_writer_reset(void);
55 
56 /**
57  * @brief Prepares to write Information Element data to all elements recognized by the module.
58  *
59  * Calls to this function put the IE writer module into an armed state.
60  * In the armed state the addresses of recognized Information Element values
61  * are latched. The IE writer module shall perform necessary calculations and write
62  * the results to the latched addresses during the execution of either
63  * nrf_802154_ie_writer_tx_ack_started_hook or nrf_802154_ie_writer_tx_started_hook hooks.
64  *
65  * It is expected, that the layout of the frame does not change while the IE writer is in
66  * armed state.
67  *
68  * If this function detects a malformed header IE, the module state shall be reset to the
69  * unarmed state. There is no guarantee that all malformed header IEs will be detected, but
70  * it is guaranteed that the writer module shall never modify memory past the p_end_addr argument.
71  *
72  * @param[in]  p_ie_header  Address of the IE header.
73  * @param[in]  p_end_addr   First invalid address after p_ie_header.
74  *
75  */
76 void nrf_802154_ie_writer_prepare(uint8_t * p_ie_header, const uint8_t * p_end_addr);
77 
78 /**
79  * @brief Transmission setup hook for the IE writer module.
80  *
81  * This hook parses the frame in search of header Information Elements and arms
82  * the IE writer module. The IE writer module shall write data to recognized
83  * Information Elements during the execution of nrf_802154_ie_writer_tx_ack_started_hook
84  * and nrf_802154_ie_writer_tx_started_hook hooks.
85  *
86  * If this function detects a malformed frame, the module state shall be reset to the
87  * unarmed state. There is no guarantee that all malformed frames will be detected.
88  *
89  * @param[in]  p_frame          Pointer to the buffer that contains the PHR and PSDU
90  *                              of the transmitted frame.
91  * @param[in]  p_params         Pointer to the transmission parameters.
92  * @param[in]  notify_function  Function to be called to notify transmission failure.
93  *
94  * @retval  true         Always succeeds.
95  */
96 bool nrf_802154_ie_writer_tx_setup(
97     uint8_t                                 * p_frame,
98     nrf_802154_transmit_params_t            * p_params,
99     nrf_802154_transmit_failed_notification_t notify_function);
100 
101 /**
102  * @brief ACK TX started hook for the IE writer module.
103  *
104  * This hook executes during the EVENT_ADDRESS radio event. If the IE writer is armed,
105  * the IEs recognized by the writer module shall be modified. If IE writer is not armed
106  * no action shall be performed.
107  *
108  * The function writes to memory addresses that were found suitable by the call to
109  * nrf_802154_ie_writer_prepare function. No parsing of the frame pointed by the p_ack
110  * argument is performed and the argument itself is ignored due to timing requirements
111  * that this hook must not exceed.
112  *
113  * @param[in]  p_ack    Pointer to the buffer that contains the PHR and PSDU of the ACK frame.
114  *
115  */
116 void nrf_802154_ie_writer_tx_ack_started_hook(uint8_t * p_ack);
117 
118 /**
119  * @brief TX started hook for the IE writer module.
120  *
121  * This hook executes during the EVENT_ADDRESS radio event. If the IE writer is armed,
122  * the IEs recognized by the writer module shall be modified. If IE writer is not armed
123  * no action shall be performed.
124  *
125  * The function writes to memory addresses that were found suitable by the call to
126  * nrf_802154_ie_writer_prepare function. No parsing of the frame pointed by the p_frame
127  * argument is performed and the argument itself is ignored due to timing requirements
128  * that this hook must not exceed.
129  *
130  * @param[in]  p_frame  Pointer to the buffer that contains the PHR and PSDU of the transmitted frame.
131  *
132  * @retval  true  Always succeeds.
133  */
134 bool nrf_802154_ie_writer_tx_started_hook(uint8_t * p_frame);
135 
136 /**
137  * @brief Sets the value of CSL period to inject into the CSL information element.
138  *
139  * @param[in]  period  CSL period value.
140  */
141 void nrf_802154_ie_writer_csl_period_set(uint16_t period);
142 
143 /**
144  * @brief Sets the anchor time based on which the next CSL window time and the CSL phase is calculated.
145  *
146  * @param[in]  anchor_time  Anchor time value.
147  */
148 void nrf_802154_ie_writer_csl_anchor_time_set(uint64_t anchor_time);
149 
150 /**
151  * @brief Sets the value of CST period to inject into the CST information element.
152  *
153  * @param[in]  period  CST period value.
154  */
155 void nrf_802154_ie_writer_cst_period_set(uint16_t period);
156 
157 /**
158  * @brief Sets the anchor time based on which the next CST window time and the CST phase is calculated.
159  *
160  * @param[in]  anchor_time Anchor time value.
161  */
162 void nrf_802154_ie_writer_cst_anchor_time_set(uint64_t anchor_time);
163 
164 /**
165  *@}
166  **/
167 
168 #endif // NRF_802154_IE_WRITER_H__
169