1 /* 2 * Copyright (c) 2020 - 2023, 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 /** 36 * @brief Module that contains PPI management functions for 37 * the nRF IEEE 802.15.4 radio driver. 38 */ 39 40 #ifndef NRF_802154_TRX_PPI_H_ 41 #define NRF_802154_TRX_PPI_H_ 42 43 #include <stdbool.h> 44 #include <stdint.h> 45 46 #include "hal/nrf_egu.h" 47 #include "hal/nrf_radio.h" 48 #include "nrf_802154_trx.h" 49 50 /** 51 * @brief Configures (D)PPI connections required for TRX operation. 52 * 53 * Actions performed by this function in DPPI variant: 54 * - RADIO_DISABLED event is published to DPPI designated by NRF_802154_DPPI_RADIO_DISABLED 55 * - NRF_RADIO_EVENT_CCAIDLE is published to DPPI designated by NRF_802154_DPPI_RADIO_CCAIDLE 56 * The DPPIs mentioned above may be then subscribed to. 57 */ 58 void nrf_802154_trx_ppi_for_enable(void); 59 60 /** 61 * @brief Clears (D)PPI connections required for TRX operation. 62 */ 63 void nrf_802154_trx_ppi_for_disable(void); 64 65 /** 66 * @brief Set PPIs to connect trigger event with tasks needed to ramp up. 67 * 68 * When @p trigg_mode is TRX_RAMP_UP_SW_TRIGGER, the trigger event is RADIO_DISABLED and 69 * PPI connections are made to it. 70 * When @p trigg_mode is TRX_RAMP_UP_HW_TRIGGER, the trigger event is defined outside the module 71 * and PPI connections are only partially created. To complete the connection creation, the trigger 72 * event must be connected to the (D)PPI channel specified with 73 * @ref nrf_802154_trx_ppi_for_ramp_up_channel_id_get. 74 * 75 * Connections created by this function in DPPI variant and TRX_RAMP_UP_SW_TRIGGER mode: 76 * 77 * RADIO_DISABLED ----> EGU -----> ramp_up_task 78 * | \--> self disable 79 * if (start_timer) 80 * \-------------> TIMER_START 81 * 82 * Connections created by this function in DPPI variant and TRX_RAMP_UP_HW_TRIGGER mode: 83 * 84 * [DPPI] -----------------------> RADIO_TASK_DISABLE 85 * 86 * RADIO_DISABLED ----> EGU -----> ramp_up_task 87 * | \--> self disable 88 * if (start_timer) 89 * \--------------> TIMER_START 90 * 91 * Connections created by this function in PPI variant and TRX_RAMP_UP_SW_TRIGGER mode: 92 * 93 * RADIO_DISABLED ----> EGU -----> ramp_up_task 94 * \--> self disable 95 * 96 * EGU ---> if (start_timer) ----> TIMER_START 97 * 98 * Connections created by this function in PPI variant and TRX_RAMP_UP_HW_TRIGGER mode: 99 * 100 * [PPI] --------> EGU ----------> ramp_up_task 101 * \--> self disable 102 * 103 * EGU ---> if (start_timer) ----> TIMER_START 104 * 105 * @param[in] ramp_up_task Task triggered to start ramp up procedure. 106 * @param[in] trigg_mode Trigger mode the connections must conform to. 107 * @param[in] start_timer If timer is to be started on RADIO DISABLED event. 108 */ 109 void nrf_802154_trx_ppi_for_ramp_up_set(nrf_radio_task_t ramp_up_task, 110 nrf_802154_trx_ramp_up_trigger_mode_t trigg_mode, 111 bool start_timer); 112 113 /** 114 * @brief Reconfigure (D)PPIs for the next steps in receiving or transmitting. 115 * 116 * Due to limited resources on some platforms, some PPIs have many uses: when starting an operation, 117 * one is used to trigger the radio ramp up, then when the radio is "up", this PPI must be 118 * reconfigured so it can be used to disable the radio when needed. 119 * This is the PPI reconfiguration routine. It is intended to be called in the radio READY event 120 * handler. 121 */ 122 void nrf_802154_trx_ppi_for_ramp_up_reconfigure(void); 123 124 /** 125 * @brief Clear (D)PPIs that are configured for ramp up procedure. 126 * 127 * @param[in] ramp_up_task Task triggered to start ramp up procedure. 128 * @param[in] start_timer If timer start on RADIO DISABLED event is to be deconfigured as well. See @ref nrf_802154_trx_ppi_for_ramp_up_set. 129 */ 130 void nrf_802154_trx_ppi_for_ramp_up_clear(nrf_radio_task_t ramp_up_task, bool start_timer); 131 132 /** 133 * @brief Get (D)PPI channel used to trigger ramp up procedure start. 134 * 135 * @retval NRF_802154_DPPI_EGU_TO_RADIO_RAMP_UP in DPPI variant. 136 * @retval NRF_802154_PPI_RADIO_RAMP_UP_TRIGG in PPI variant. 137 */ 138 uint8_t nrf_802154_trx_ppi_for_ramp_up_channel_id_get(void); 139 140 /** 141 * @brief Wait until PPIs configured to ramp up radio are propagated through PPI system. 142 * 143 * During detection if trigger of DISABLED event caused start of hardware procedure, detecting 144 * function needs to wait until event is propagated from RADIO through PPI to EGU. This delay is 145 * required to make sure EGU event is set if hardware was prepared before DISABLED event was 146 * triggered. 147 */ 148 void nrf_802154_trx_ppi_for_ramp_up_propagation_delay_wait(void); 149 150 /** 151 * @brief Detect if PPIs configured to start radio operation were triggered. 152 * 153 * In TRX_RAMP_UP_SW_TRIGGER mode, radio ramp up starts by design from RADIO DISABLED event. 154 * This functions verifies occurrence of this event and PPIs status. 155 * 156 * The function is intended to be used only when all of the following conditions apply: 157 * - the connections are already made with @ref nrf_802154_trx_ppi_for_ramp_up_set 158 * - TRX_RAMP_UP_SW_TRIGGER mode was used to create connections 159 * - connections have not yet been cleared 160 * 161 * @retval true PPIs were triggered. 162 * @retval false PPIs were not triggered. To trigger them, the caller must trigger RADIO DISABLE task. 163 */ 164 bool nrf_802154_trx_ppi_for_ramp_up_was_triggered(void); 165 166 /** 167 * @brief Set PPIs to connect TIMER event with radio TXEN task, needed to ramp up for ACK TX. 168 */ 169 void nrf_802154_trx_ppi_for_ack_tx_set(void); 170 171 /** 172 * @brief Clear PPIs to connect TIMER event with radio TXEN task, needed to ramp up for ACK TX. See @ref nrf_802154_trx_ppi_for_ack_tx_set 173 */ 174 void nrf_802154_trx_ppi_for_ack_tx_clear(void); 175 176 /** 177 * @brief Configure PPIs needed for external LNA or PA. Radio DISABLED event will be connected to timer START task. 178 * As a result, FEM ramp-up will be scheduled during the radio ramp-up period, with timing based on FEM implementation used. 179 */ 180 void nrf_802154_trx_ppi_for_fem_set(void); 181 182 /** 183 * @brief Deconfigure PPIs needed for external LNA or PA. See @ref nrf_802154_trx_ppi_for_fem_set 184 */ 185 void nrf_802154_trx_ppi_for_fem_clear(void); 186 187 /** 188 * @brief Get PPI group id used for disabling radio operations by an external event. 189 */ 190 uint32_t nrf_802154_trx_ppi_group_for_abort_get(void); 191 192 /** 193 * @brief Configure PPIs needed to trigger IRQ from RADIO event SYNC. 194 * 195 * @param[in] task EGU task used for triggering IRQ on radio SYNC event. 196 */ 197 void nrf_802154_trx_ppi_for_radio_sync_set(nrf_egu_task_t task); 198 199 /** 200 * @brief Unconfigure PPIs needed to trigger IRQ from RADIO event SYNC. 201 * 202 * @param[in] task EGU task used for triggering IRQ on radio SYNC event. See @ref nrf_802154_trx_ppi_for_radio_sync_set 203 */ 204 void nrf_802154_trx_ppi_for_radio_sync_clear(nrf_egu_task_t task); 205 206 #endif /* NRF_802154_TRX_PPI_H_ */ 207
