1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20 #ifndef H_HCI_TRANSPORT_ 21 #define H_HCI_TRANSPORT_ 22 23 #include <stdint.h> 24 #include "os/os_mempool.h" 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 struct os_mbuf; 31 32 #define BLE_HCI_TRANS_CMD_SZ 260 33 34 /*** Type of buffers for holding commands and events. */ 35 /** 36 * Controller-to-host event buffers. Events have one of two priorities: 37 * o Low-priority (BLE_HCI_TRANS_BUF_EVT_LO) 38 * o High-priority (BLE_HCI_TRANS_BUF_EVT_HI) 39 * 40 * Low-priority event buffers are only used for advertising reports. If there 41 * are no free low-priority event buffers, then an incoming advertising report 42 * will get dropped. 43 * 44 * High-priority event buffers are for everything except advertising reports. 45 * If there are no free high-priority event buffers, a request to allocate one 46 * will try to allocate a low-priority buffer instead. 47 * 48 * If you want all events to be given equal treatment, then you should allocate 49 * low-priority events only. 50 * 51 * Event priorities solve the problem of critical events getting dropped due to 52 * a flood of advertising reports. This solution is likely temporary: when 53 * HCI flow control is added, event priorities may become obsolete. 54 * 55 * Not all transports distinguish between low and high priority events. If the 56 * transport does not have separate settings for low and high buffer counts, 57 * then it treats all events with equal priority. 58 */ 59 #define BLE_HCI_TRANS_BUF_EVT_LO 1 60 #define BLE_HCI_TRANS_BUF_EVT_HI 2 61 62 /* Host-to-controller command. */ 63 #define BLE_HCI_TRANS_BUF_CMD 3 64 65 /** Callback function types; executed when HCI packets are received. */ 66 typedef int ble_hci_trans_rx_cmd_fn(uint8_t *cmd, void *arg); 67 typedef int ble_hci_trans_rx_acl_fn(struct os_mbuf *om, void *arg); 68 69 /** 70 * Sends an HCI event from the controller to the host. 71 * 72 * @param cmd The HCI event to send. This buffer must be 73 * allocated via ble_hci_trans_buf_alloc(). 74 * 75 * @return 0 on success; 76 * A BLE_ERR_[...] error code on failure. 77 */ 78 int ble_hci_trans_ll_evt_tx(uint8_t *hci_ev); 79 80 /** 81 * Sends ACL data from controller to host. 82 * 83 * @param om The ACL data packet to send. 84 * 85 * @return 0 on success; 86 * A BLE_ERR_[...] error code on failure. 87 */ 88 int ble_hci_trans_ll_acl_tx(struct os_mbuf *om); 89 90 /** 91 * Sends an HCI command from the host to the controller. 92 * 93 * @param cmd The HCI command to send. This buffer must be 94 * allocated via ble_hci_trans_buf_alloc(). 95 * 96 * @return 0 on success; 97 * A BLE_ERR_[...] error code on failure. 98 */ 99 int ble_hci_trans_hs_cmd_tx(uint8_t *cmd); 100 101 /** 102 * Sends ACL data from host to controller. 103 * 104 * @param om The ACL data packet to send. 105 * 106 * @return 0 on success; 107 * A BLE_ERR_[...] error code on failure. 108 */ 109 int ble_hci_trans_hs_acl_tx(struct os_mbuf *om); 110 111 /** 112 * Allocates a flat buffer of the specified type. 113 * 114 * @param type The type of buffer to allocate; one of the 115 * BLE_HCI_TRANS_BUF_[...] constants. 116 * 117 * @return The allocated buffer on success; 118 * NULL on buffer exhaustion. 119 */ 120 uint8_t *ble_hci_trans_buf_alloc(int type); 121 122 /** 123 * Frees the specified flat buffer. The buffer must have been allocated via 124 * ble_hci_trans_buf_alloc(). 125 * 126 * @param buf The buffer to free. 127 */ 128 void ble_hci_trans_buf_free(uint8_t *buf); 129 130 /** 131 * Configures a callback to get executed whenever an ACL data packet is freed. 132 * The function is called immediately before the free occurs. 133 * 134 * @param cb The callback to configure. 135 * @param arg An optional argument to pass to the callback. 136 * 137 * @return 0 on success; 138 * BLE_ERR_UNSUPPORTED if the transport does not 139 * support this operation. 140 */ 141 int ble_hci_trans_set_acl_free_cb(os_mempool_put_fn *cb, void *arg); 142 143 /** 144 * Configures the HCI transport to operate with a controller. The transport 145 * will execute specified callbacks upon receiving HCI packets from the host. 146 * 147 * @param cmd_cb The callback to execute upon receiving an HCI 148 * command. 149 * @param cmd_arg Optional argument to pass to the command 150 * callback. 151 * @param acl_cb The callback to execute upon receiving ACL 152 * data. 153 * @param acl_arg Optional argument to pass to the ACL 154 * callback. 155 */ 156 void ble_hci_trans_cfg_ll(ble_hci_trans_rx_cmd_fn *cmd_cb, 157 void *cmd_arg, 158 ble_hci_trans_rx_acl_fn *acl_cb, 159 void *acl_arg); 160 161 /** 162 * Configures the HCI transport to operate with a host. The transport will 163 * execute specified callbacks upon receiving HCI packets from the controller. 164 * 165 * @param evt_cb The callback to execute upon receiving an HCI 166 * event. 167 * @param evt_arg Optional argument to pass to the event 168 * callback. 169 * @param acl_cb The callback to execute upon receiving ACL 170 * data. 171 * @param acl_arg Optional argument to pass to the ACL 172 * callback. 173 */ 174 void ble_hci_trans_cfg_hs(ble_hci_trans_rx_cmd_fn *evt_cb, 175 void *evt_arg, 176 ble_hci_trans_rx_acl_fn *acl_cb, 177 void *acl_arg); 178 179 /** 180 * Resets the HCI module to a clean state. Frees all buffers and reinitializes 181 * the underlying transport. 182 * 183 * @return 0 on success; 184 * A BLE_ERR_[...] error code on failure. 185 */ 186 int ble_hci_trans_reset(void); 187 188 #ifdef __cplusplus 189 } 190 #endif 191 192 #endif /* H_HCI_TRANSPORT_ */ 193