1 /*$Id: //dwh/bluetooth/DWC_ble154combo/firmware/rel/1.32a-lca02/firmware/public_inc/pta.h#1 $*/ 2 /** 3 ****************************************************************************** 4 * @file pta.h 5 * @brief This file contains all prototypes for the public PTA APIs 6 ****************************************************************************** 7 * @copy 8 * This Synopsys DWC Bluetooth Low Energy Combo Link Layer/MAC software and 9 * associated documentation ( hereinafter the "Software") is an unsupported 10 * proprietary work of Synopsys, Inc. unless otherwise expressly agreed to in 11 * writing between Synopsys and you. The Software IS NOT an item of Licensed 12 * Software or a Licensed Product under any End User Software License Agreement 13 * or Agreement for Licensed Products with Synopsys or any supplement thereto. 14 * Synopsys is a registered trademark of Synopsys, Inc. Other names included in 15 * the SOFTWARE may be the trademarks of their respective owners. 16 * 17 * Synopsys MIT License: 18 * Copyright (c) 2020-Present Synopsys, Inc 19 * 20 * Permission is hereby granted, free of charge, to any person obtaining a copy of 21 * the Software), to deal in the Software without restriction, including without 22 * limitation the rights to use, copy, modify, merge, publish, distribute, 23 * sublicense, and/or sell copies of the Software, and to permit persons to whom 24 * the Software is furnished to do so, subject to the following conditions: 25 * 26 * The above copyright notice and this permission notice shall be included in all 27 * copies or substantial portions of the Software. 28 * 29 * THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 30 * IMPLIED, INCLUDING, BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 31 * FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE 32 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 33 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE ARISING FROM, 34 * OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 35 * 36 * */ 37 38 #ifndef PTA_H_ 39 #define PTA_H_ 40 #include "common_types.h" 41 #if (SUPPORT_PTA) 42 43 #define PTA_HCI_TESTING 0 44 45 /***************************** PUBLIC ENUMERATIONS *****************************/ 46 /** 47 * @brief Enumeration holding the PTA enable and disable. 48 */ 49 typedef enum { 50 PTA_DISABLED = 0, 51 PTA_ENABLED, 52 } pta_state; 53 54 #if (SUPPORT_MASTER_CONNECTION || SUPPORT_SLAVE_CONNECTION || (SUPPORT_LE_PERIODIC_ADVERTISING && (SUPPORT_EXPLCT_OBSERVER_ROLE || SUPPORT_SYNC_ISOCHRONOUS))) 55 /** 56 * @brief Enumeration holding the event types passed to the BLE_SetLinkCoexPriority(). 57 */ 58 typedef enum { 59 PTA_LINK_COEX_CONN, 60 PTA_LINK_COEX_PRDC_SCAN, 61 } pta_link_coex_event_type; 62 #endif /* (SUPPORT_MASTER_CONNECTION || SUPPORT_SLAVE_CONNECTION || \ 63 (SUPPORT_LE_PERIODIC_ADVERTISING && (SUPPORT_EXPLCT_OBSERVER_ROLE || SUPPORT_SYNC_ISOCHRONOUS))) */ 64 65 #if (SUPPORT_BRD_ISOCHRONOUS || SUPPORT_SYNC_ISOCHRONOUS || (SUPPORT_CONNECTED_ISOCHRONOUS && (SUPPORT_MASTER_CONNECTION || SUPPORT_SLAVE_CONNECTION))) 66 /** 67 * @brief Enumeration holding the event types passed to the BLE_SetISOCoexPriority(). 68 */ 69 typedef enum { 70 PTA_ISO_CIG, 71 PTA_ISO_BIG, 72 } pta_iso_type; 73 #endif /* (SUPPORT_BRD_ISOCHRONOUS || SUPPORT_SYNC_ISOCHRONOUS || \ 74 (SUPPORT_CONNECTED_ISOCHRONOUS && (SUPPORT_MASTER_CONNECTION || SUPPORT_SLAVE_CONNECTION))) */ 75 76 77 /** 78 * @brief Enumeration holding all the error codes for the PTA interfaces 79 */ 80 typedef enum pta_error { 81 PTA_ERROR_SUCCESS, 82 PTA_ERROR_PTA_NOT_ENABLED, 83 PTA_ERROR_INVALID_PRIORITY_CONF, 84 PTA_ERROR_UNKNOWN_CONN_HANDLE, 85 PTA_ERROR_UNKNOWN_PRDC_SYNC_HANDLE, 86 PTA_ERROR_UNKNOWN_CIG_HANDLE, 87 PTA_ERROR_UNKNOWN_BIG_HANDLE, 88 PTA_ERROR_INVALID_NBR_OF_PKTS, 89 PTA_ERROR_INVALID_TIMEOUT, 90 PTA_ERROR_INVALID_REQUEST_TO_EVENT_TIME, 91 PTA_ERROR_INVALID_PTA_STATE, 92 PTA_ERROR_INIT_ALREADY_CALLED, 93 PTA_ERROR_PTA_ENABLED_IN_INIT, 94 PTA_ERROR_PTA_INIT_NOT_CALLED, 95 } pta_error; 96 97 /***************************** Functions Prototypes *****************************/ 98 /*##### PTA' Group #####*/ 99 /** @ingroup pta_functions 100 * @{ 101 */ 102 /** 103 * @brief Used to enable and disable the PTA. 104 * @note This API can be called directly to enable/disable the PTA feature. In case the BLE controller is supported, beside this API, 105 * there is an option to enable/disable the PTA feature through the "HCI_CMD_OCF_PTA_ENABLE" custom HCI command. 106 * 107 * @param enable: [in] 0: Disable. 1: Enable. 108 * 109 * @retval pta_error : PTA_ERROR_INVALID_PTA_STATE: 110 * - If enable is passed while the PTA is already enabled. 111 * - If disabled is passed while the PTA is already disabled. 112 * - If a value outside of the pta_state enumeration is passed. 113 * PTA_ERROR_SUCCESS : Otherwise. 114 */ 115 pta_error pta_enable( 116 pta_state enable); 117 118 /** 119 * @brief Used to initialize the PTA feature. The PHY sequences are configured with 120 * respect to the "request_to_event_time" parameter. 121 * @note This API can be called directly to initialize the PTA feature. In case the BLE controller is supported, beside this API, 122 * there is an option to initialize the PTA feature through the "HCI_CMD_OCF_PTA_INIT" custom HCI command. 123 * 124 * @param request_to_event_time : [in] Time between the request signal assertion 125 * and beginning of event on air. 126 * 127 * @retval pta_error : PTA_DISABLED: If PTA is disabled. 128 * PTA_ERROR_INVALID_REQUEST_TO_EVENT_TIME: If the request_to_event_time is greater than the minimum time of the TX/RX interpacket time. 129 * PTA_ERROR_SUCCESS : Otherwise. 130 */ 131 pta_error pta_init( 132 uint8_t request_to_event_time); 133 134 /***************************** BLE Functions *****************************/ 135 #if (SUPPORT_BLE) 136 #if (SUPPORT_MASTER_CONNECTION || SUPPORT_SLAVE_CONNECTION || \ 137 (SUPPORT_LE_EXTENDED_ADVERTISING && SUPPORT_LE_PERIODIC_ADVERTISING && (SUPPORT_EXPLCT_OBSERVER_ROLE || SUPPORT_SYNC_ISOCHRONOUS))) 138 /** 139 * @brief Used to configure the priority of the ACL and Periodic Scan events. 140 * @note This API can be called directly to configure the priority of the ACL and Periodic Scan events. In case the BLE controller is supported, beside this API, 141 * there is an option to configure the priority of the ACL and Periodic Scan events through the "HCI_CMD_OCF_PTA_BLE_SetLinkCoexPriority" custom HCI command. 142 * 143 * @param event_type : [in] Either ACL or Periodic Scan event. 144 * @param handle : [in] ACL Handle or Periodic Scan Handle. 145 * @param priority : [in] Determines the state of each priority mode. 146 * @param priority_mask : [in] Determines which priorities are in effect in 147 * the priority variable. 148 * @param acl_multi_slot_nbr_of_packets : [in] Number of protected slots. 149 * @param link_loss_limit_timeout : [in] Timeout percentage for link loss mode 150 * 151 * @retval pta_error : PTA_DISABLED: If PTA is disabled. 152 * PTA_ERROR_INVALID_PRIORITY_CONF: 153 * - If Forced configuration = 11 154 * - priority_mask did not mask away the reserved bits in priority 155 * - priority_mask masked one bit only of the first two bits in the priority. 156 * - event_type has invalid event type. 157 * - ACL Multi Slot is used with periodic sync event. 158 * - ACL Multi Slot is used with Link Loss Limit. 159 * PTA_ERROR_UNKNOWN_CONN_HANDLE : Connection Handle not found. 160 * PTA_ERROR_UNKNOWN_PRDC_SYNC_HANDLE : Periodic Sync Handle not found. 161 * PTA_ERROR_INVALID_NBR_OF_PKTS : acl_multi_slot_nbr_of_slots > PACKETS_PER_EVENT_MAX 162 * PTA_ERROR_INVALID_TIMEOUT : link_loss_limit_timeout < 0 or > 100. 163 * PTA_ERROR_SUCCESS : Otherwise. 164 */ 165 pta_error pta_set_link_coex_priority( 166 pta_link_coex_event_type event_type, 167 uint16_t handle, 168 uint32_t priority, 169 uint32_t priority_mask, 170 uint8_t acl_multi_slot_nbr_of_packets, 171 uint8_t link_loss_limit_timeout); 172 #endif /* (SUPPORT_MASTER_CONNECTION || SUPPORT_SLAVE_CONNECTION || \ 173 (SUPPORT_LE_EXTENDED_ADVERTISING && SUPPORT_LE_PERIODIC_ADVERTISING && (SUPPORT_EXPLCT_OBSERVER_ROLE || SUPPORT_SYNC_ISOCHRONOUS))) */ 174 175 #if (SUPPORT_BRD_ISOCHRONOUS || SUPPORT_SYNC_ISOCHRONOUS || SUPPORT_CONNECTED_ISOCHRONOUS) 176 /** 177 * @brief Used to configure the priority of the BIG and CIG events. 178 * @note This API can be called directly to configure the priority of the BIG and CIG events. In case the BLE controller is supported, beside this API, 179 * there is an option to configure the priority of the BIG and CIG events through the "HCI_CMD_OCF_PTA_BLE_SetISOCoexPriority" custom HCI command. 180 * 181 * @param iso_type : [in] Either BIG or CIG event. 182 * @param group_id : [in] Isochronous Group ID. 183 * @param priority : [in] Determines the state of each priority mode. 184 * @param priority_mask : [in] Determines which priorities are in effect in 185 * the priority variable. 186 * @param link_loss_limit_timeout : [in] Timeout percentage for link loss mode 187 * 188 * @retval pta_error : PTA_DISABLED: If PTA is disabled. 189 * PTA_ERROR_INVALID_PRIORITY_CONF: 190 * - If Forced configuration = 11 191 * - priority_mask did not mask away the reserved bits in priority 192 * - priority_mask masked one bit only of the first two bits in the priority. 193 * - iso_type has invalid event type. 194 * - Protect All or Protect RTN is used with BIG. 195 * - Link Loss Limit is configured for Broadcaster Role for BIG. 196 * PTA_ERROR_UNKNOWN_BIG_HANDLE : BIG ID not found. 197 * PTA_ERROR_UNKNOWN_CIG_HANDLE : CIG ID not found. 198 * PTA_ERROR_INVALID_TIMEOUT : link_loss_limit_timeout < 0 or > 100. 199 * PTA_ERROR_SUCCESS : Otherwise. 200 */ 201 pta_error pta_set_iso_coex_priority( 202 pta_iso_type iso_type, 203 uint8_t group_id, 204 uint32_t priority, 205 uint32_t priority_mask, 206 uint8_t link_loss_limit_timeout); 207 #endif /* (SUPPORT_BRD_ISOCHRONOUS || SUPPORT_SYNC_ISOCHRONOUS || SUPPORT_CONNECTED_ISOCHRONOUS) */ 208 #endif /* SUPPORT_BLE */ 209 210 /** 211 * @brief Used to configure the priority of the generic BLE events. 212 * @note This API can be called directly to configure the priority of the generic BLE events. In case the BLE controller is supported, beside this API, 213 * there is an option to configure the priority of the generic BLE events through the "HCI_CMD_OCF_PTA_BLE_SetCoexPriority" custom HCI command. 214 * 215 * @param priority : [in] Determines the state of each priority mode. 216 * @param priority_mask : [in] Determines which priorities are in effect in 217 * the priority variable. 218 * 219 * @retval pta_error : PTA_DISABLED: If PTA is disabled. 220 * PTA_ERROR_INVALID_PRIORITY_CONF: 221 * - If Forced configuration = 11 222 * - priority_mask did not mask away the reserved bits in priority 223 * - priority_mask masked one bit only of the first two bits in the priority. 224 * PTA_ERROR_SUCCESS : Otherwise. 225 */ 226 pta_error pta_set_coex_priority( 227 uint32_t priority, 228 uint32_t priority_mask); 229 230 /***************************** MAC Functions *****************************/ 231 #if (SUPPORT_MAC) 232 /** 233 * @brief Used to configure the priority of the MAC Packets. 234 * @note This API can be called directly to configure the priority of the MAC Packets. Beside this API, 235 * there is an option to configure the priority of the MAC Packets through the "PTA_SET_PRIORITY" MAC custom HCI command. 236 * 237 * @param priority : [in] Determines the state of each priority mode. 238 * @param priority_mask : [in] Determines which priorities are in effect in 239 * the priority variable. 240 * 241 * @retval pta_error : PTA_DISABLED: If PTA is disabled. 242 * PTA_ERROR_INVALID_PRIORITY_CONF: 243 * - If Forced configuration = 11 244 * - priority_mask did not mask away the reserved bits in priority 245 * - priority_mask masked one bit only of the first two bits in the priority. 246 * PTA_ERROR_SUCCESS : Otherwise. 247 */ 248 pta_error pta_set_mac_coex_priority( 249 uint32_t priority, 250 uint32_t priority_mask); 251 #endif /* SUPPORT_MAC */ 252 /** @} 253 */ 254 #endif /* SUPPORT_PTA */ 255 #endif /* PTA_H_ */ 256 257
