1 /* 2 * Copyright (c) 2020-2024, Texas Instruments Incorporated 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of Texas Instruments Incorporated nor the names of 17 * its contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 #ifndef ti_drivers_RCL_handlers_ieee_h__include 34 #define ti_drivers_RCL_handlers_ieee_h__include 35 36 #include <stdint.h> 37 #include <ti/drivers/rcl/RCL_Command.h> 38 #include <ti/drivers/rcl/RCL_Buffer.h> 39 #include <ti/drivers/rcl/LRF.h> 40 #include <ti/drivers/rcl/commands/ieee.h> 41 42 /* Handler functions */ 43 RCL_Events RCL_Handler_Ieee_RxTx(RCL_Command *cmd, LRF_Events lrfEvents, RCL_Events rclEventsIn); 44 RCL_Events RCL_Handler_Ieee_TxTest(RCL_Command *cmd, LRF_Events lrfEvents, RCL_Events rclEventsIn); 45 46 /** 47 * @brief Result of IEEE command update API 48 * 49 * Tells if update of IEEE command fields succeeded 50 */ 51 typedef enum 52 { 53 RCL_IEEE_UpdateOk, /*!< Update was successful */ 54 RCL_IEEE_UpdateIndexError, /*!< Index was out of range or pointer was NULL */ 55 } RCL_IEEE_UpdateResult; 56 57 /** 58 * @brief Result of entering ACK frame 59 * 60 * Tells if ACK frame was entered successfully 61 */ 62 typedef enum 63 { 64 RCL_IEEE_AckOk, /*!< ACK was entered successfully */ 65 RCL_IEEE_AckNotExpected, /*!< Ack was not expected */ 66 RCL_IEEE_AckTooLate, /*!< Ack was provided too late */ 67 RCL_IEEE_AckError, /*!< Data entry or pointer was not correct */ 68 } RCL_IEEE_AckEntryResult; 69 70 71 /* API functions */ 72 /** 73 * @brief Update short source matching table 74 * 75 * Update the given source matching table filter list in a way that is safe even if a running command is using 76 * the filter table. 77 * 78 * @param newAddr New address and PAN ID to apply; NULL to leave unchanged 79 * @param framePending Value of frame pending bit 80 * @param table Source matching table to update 81 * @param index Index into source matching table to update 82 * 83 * @return Result telling if update was successful 84 * @note Not supported in this version 85 * 86 */ 87 RCL_IEEE_UpdateResult RCL_IEEE_updateSourceMatchingTableShort(RCL_CmdIeee_PanIdAddr *newAddr, uint8_t framePending, RCL_CmdIeee_SourceMatchingTableShort *table, uint32_t index); 88 89 /** 90 * @brief Update frame filtering settings extended source matching table 91 * 92 * Update the given frame filtering settings in a way that is safe even if a running command is receiving a frame 93 * 94 * @param cmd Existing IEEE command to update 95 * @param newPanConfig New PAN configuration to apply 96 * @param panNumber Index of PAN to update 97 * 98 * @return Result telling if update was successful 99 * @note Not supported in this version 100 * 101 */ 102 RCL_IEEE_UpdateResult RCL_IEEE_updateSourceMatchingTableExt(RCL_CmdIeeeRxTx *cmd, RCL_CmdIeee_PanConfig *newPanConfig, uint32_t panNumber); 103 104 /** 105 * @brief Provide ACK frame to be transmitted in response to received packet 106 * 107 * Provide an ACK frame, which will be transmitted if the frame was received successfully 108 * 109 * @param cmd Existing IEEE command for which to enter ACK 110 * @param ackEntry ACK to be transmitted over the air 111 * 112 * @return Result telling if update was successful 113 * @note Not supported in this version 114 * 115 */ 116 RCL_IEEE_AckEntryResult RCL_IEEE_enterAck(RCL_CmdIeeeRxTx *cmd, RCL_Buffer_DataEntry *ackEntry); 117 118 /** 119 * @brief Update tx action 120 * 121 * @param cmd Existing IEEE command to submit the TX on top of 122 * @param txAction TX action to apply 123 * 124 * @return %RCL_CommandStatus result of the submission 125 * 126 */ 127 RCL_CommandStatus RCL_IEEE_Tx_submit(RCL_CmdIeeeRxTx *cmd, RCL_CmdIeee_TxAction *txAction); 128 129 /** 130 * @brief Stop a Tx action in an IEEE command 131 * 132 * Sends the message to try to stop a TX action. When the function returns, the command may still be 133 * running. Depending on the stop type, the operation may stop after some time. 134 * 135 * @param cmd [in] IEEE command 136 * @param stopType [in] Stop type; telling which situations the operation will stop 137 * 138 * @return Status of the TX operation; if the operation is not finished, a wait is needed. 139 * 140 */ 141 RCL_CommandStatus RCL_IEEE_Tx_stop(RCL_CmdIeeeRxTx *cmd, RCL_StopType stopType); 142 143 /** 144 * @brief Wait for a submitted TX operation to complete. 145 * 146 * Uses %SemaphoreP_pend to block in the callers context. 147 * 148 * @pre This function must be called from a task context, with interrupts enabled. 149 * 150 * @param[in] cmd IEEE command running 151 * 152 * @return Status of the TX operation 153 * @note Not supported in this version 154 * 155 */ 156 RCL_CommandStatus RCL_IEEE_Tx_pend(RCL_CmdIeeeRxTx *cmd); 157 158 /** 159 * @brief Get received RSSI from packet 160 * 161 * Returns the RSSI field of a received packet, or LRF_RSSI_INVALID if RSSI is not enabled 162 * 163 * @param rxEntry Received data entry 164 * 165 * @return Reported RSSI of received packet 166 * @note Not supported in this version 167 * 168 */ 169 int8_t RCL_IEEE_getRxRssi(const RCL_Buffer_DataEntry *rxEntry); 170 171 /** 172 * @brief Get received timestamp from packet 173 * 174 * Returns the timestamp a received packet, adjusted to point to the start of the preamble. 175 * If timestamp is not enabled, 0 is returned. 176 * Note that 0 is a valid value, so it cannot be used for error checking. 177 * 178 * @param rxEntry Received data entry 179 * 180 * @return Timestamp of received packet 181 * @note Not supported in this version 182 * 183 */ 184 uint32_t RCL_IEEE_getRxTimestamp(const RCL_Buffer_DataEntry *rxEntry); 185 186 #endif /* ti_drivers_RCL_handlers_ble5_h__include */ 187
