xref: /btstack/src/hci.h (revision 90af00b83ef3cf38af21be9d8e98b07db75c02f3)
1 /*
2  * Copyright (C) 2014 BlueKitchen GmbH
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  *
8  * 1. Redistributions of source code must retain the above copyright
9  *    notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  *    notice, this list of conditions and the following disclaimer in the
12  *    documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the copyright holders nor the names of
14  *    contributors may be used to endorse or promote products derived
15  *    from this software without specific prior written permission.
16  * 4. Any redistribution, use, or modification is done solely for
17  *    personal benefit and not for any commercial purpose or for
18  *    monetary gain.
19  *
20  * THIS SOFTWARE IS PROVIDED BY BLUEKITCHEN GMBH AND CONTRIBUTORS
21  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
23  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL MATTHIAS
24  * RINGWALD OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
25  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
26  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
27  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
28  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
29  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
30  * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31  * SUCH DAMAGE.
32  *
33  * Please inquire about commercial licensing options at
34  * [email protected]
35  *
36  */
37 
38 /*
39  *  hci.h
40  *
41  *  Created by Matthias Ringwald on 4/29/09.
42  *
43  */
44 
45 #ifndef HCI_H
46 #define HCI_H
47 
48 #include "btstack_config.h"
49 
50 #include "btstack_chipset.h"
51 #include "btstack_control.h"
52 #include "btstack_linked_list.h"
53 #include "btstack_util.h"
54 #include "hci_cmd.h"
55 #include "gap.h"
56 #include "hci_transport.h"
57 #include "btstack_run_loop.h"
58 
59 #ifdef ENABLE_CLASSIC
60 #include "classic/btstack_link_key_db.h"
61 #endif
62 
63 #ifdef ENABLE_BLE
64 #include "ble/att_db.h"
65 #endif
66 
67 #ifdef HAVE_SCO_TRANSPORT
68 #include "btstack_sco_transport.h"
69 #endif
70 
71 #include <stdint.h>
72 #include <stdlib.h>
73 #include <stdarg.h>
74 
75 #if defined __cplusplus
76 extern "C" {
77 #endif
78 
79 // packet buffer sizes
80 #define HCI_CMD_HEADER_SIZE          3
81 #define HCI_ACL_HEADER_SIZE          4
82 #define HCI_SCO_HEADER_SIZE          3
83 #define HCI_EVENT_HEADER_SIZE        2
84 
85 #define HCI_EVENT_PAYLOAD_SIZE     255
86 #define HCI_CMD_PAYLOAD_SIZE       255
87 
88 // Max HCI Command LE payload size:
89 // 64 from LE Generate DHKey command
90 // 32 from LE Encrypt command
91 #if defined(ENABLE_LE_SECURE_CONNECTIONS) && !defined(ENABLE_MICRO_ECC_FOR_LE_SECURE_CONNECTIONS)
92 #define HCI_CMD_PAYLOAD_SIZE_LE 64
93 #else
94 #define HCI_CMD_PAYLOAD_SIZE_LE 32
95 #endif
96 
97 // HCI_ACL_PAYLOAD_SIZE is configurable and defined in config.h
98 // addition byte in even to terminate remote name request with '\0'
99 #define HCI_EVENT_BUFFER_SIZE      (HCI_EVENT_HEADER_SIZE + HCI_EVENT_PAYLOAD_SIZE + 1)
100 
101 #ifdef ENABLE_CLASSIC
102 #define HCI_CMD_BUFFER_SIZE        (HCI_CMD_HEADER_SIZE   + HCI_CMD_PAYLOAD_SIZE)
103 #else
104 #define HCI_CMD_BUFFER_SIZE        (HCI_CMD_HEADER_SIZE   + HCI_CMD_PAYLOAD_SIZE_LE)
105 #endif
106 
107 #define HCI_ACL_BUFFER_SIZE        (HCI_ACL_HEADER_SIZE   + HCI_ACL_PAYLOAD_SIZE)
108 
109 // size of hci incoming buffer, big enough for event or acl packet without H4 packet type
110 #ifdef HCI_INCOMING_PACKET_BUFFER_SIZE
111     #if HCI_INCOMING_PACKET_BUFFER_SIZE < HCI_ACL_BUFFER_SIZE
112         #error HCI_INCOMING_PACKET_BUFFER_SIZE must be equal or larger than HCI_ACL_BUFFER_SIZE
113     #endif
114     #if HCI_INCOMING_PACKET_BUFFER_SIZE < HCI_EVENT_BUFFER_SIZE
115         #error HCI_INCOMING_PACKET_BUFFER_SIZE must be equal or larger than HCI_EVENT_BUFFER_SIZE
116     #endif
117 #else
118     #if HCI_ACL_BUFFER_SIZE > HCI_EVENT_BUFFER_SIZE
119         #define HCI_INCOMING_PACKET_BUFFER_SIZE HCI_ACL_BUFFER_SIZE
120     #else
121         #define HCI_INCOMING_PACKET_BUFFER_SIZE HCI_EVENT_BUFFER_SIZE
122     #endif
123 #endif
124 
125 // size of hci outgoing buffer, big enough for command or acl packet without H4 packet type
126 #ifdef HCI_OUTGOING_PACKET_BUFFER_SIZE
127     #if HCI_OUTGOING_PACKET_BUFFER_SIZE < HCI_ACL_BUFFER_SIZE
128         #error HCI_OUTGOING_PACKET_BUFFER_SIZE must be equal or larger than HCI_ACL_BUFFER_SIZE
129     #endif
130     #if HCI_OUTGOING_PACKET_BUFFER_SIZE < HCI_CMD_BUFFER_SIZE
131         #error HCI_OUTGOING_PACKET_BUFFER_SIZE must be equal or larger than HCI_CMD_BUFFER_SIZE
132     #endif
133 #else
134     #if HCI_ACL_BUFFER_SIZE > HCI_CMD_BUFFER_SIZE
135         #define HCI_OUTGOING_PACKET_BUFFER_SIZE HCI_ACL_BUFFER_SIZE
136     #else
137         #define HCI_OUTGOING_PACKET_BUFFER_SIZE HCI_CMD_BUFFER_SIZE
138     #endif
139 #endif
140 
141 // additional pre-buffer space for packets to Bluetooth module
142 // - H4 requires 1 byte for the packet type
143 // - h5 requires 4 bytes for H5 header
144 #ifndef HCI_OUTGOING_PRE_BUFFER_SIZE
145     #ifdef HAVE_HOST_CONTROLLER_API
146         #define HCI_OUTGOING_PRE_BUFFER_SIZE 0
147     #else
148         #ifdef ENABLE_H5
149             #define HCI_OUTGOING_PRE_BUFFER_SIZE 4
150         #else
151             #define HCI_OUTGOING_PRE_BUFFER_SIZE 1
152         #endif
153     #endif
154 #endif
155 
156 // BNEP may uncompress the IP Header by 16 bytes, GATT Client requires two additional bytes for long characteristic reads
157 #ifndef HCI_INCOMING_PRE_BUFFER_SIZE
158 #ifdef ENABLE_CLASSIC
159 #define HCI_INCOMING_PRE_BUFFER_SIZE (16 - HCI_ACL_HEADER_SIZE - 4)
160 #else
161 #define HCI_INCOMING_PRE_BUFFER_SIZE 2
162 #endif
163 #endif
164 
165 //
166 #define IS_COMMAND(packet, command) ( little_endian_read_16(packet,0) == command.opcode )
167 
168 // check if command complete event for given command
169 #define HCI_EVENT_IS_COMMAND_COMPLETE(event,cmd) ( (event[0] == HCI_EVENT_COMMAND_COMPLETE) && (little_endian_read_16(event,3) == cmd.opcode) )
170 #define HCI_EVENT_IS_COMMAND_STATUS(event,cmd)   ( (event[0] == HCI_EVENT_COMMAND_STATUS)   && (little_endian_read_16(event,4) == cmd.opcode) )
171 
172 // Code+Len=2, Pkts+Opcode=3; total=5
173 #define OFFSET_OF_DATA_IN_COMMAND_COMPLETE 5
174 
175 // ACL Packet
176 #define READ_ACL_CONNECTION_HANDLE( buffer ) ( little_endian_read_16(buffer,0) & 0x0fff)
177 #define READ_SCO_CONNECTION_HANDLE( buffer ) ( little_endian_read_16(buffer,0) & 0x0fff)
178 #define READ_ACL_FLAGS( buffer )      ( buffer[1] >> 4 )
179 #define READ_ACL_LENGTH( buffer )     (little_endian_read_16(buffer, 2))
180 
181 // Sneak peak into L2CAP Packet
182 #define READ_L2CAP_LENGTH(buffer)     ( little_endian_read_16(buffer, 4))
183 #define READ_L2CAP_CHANNEL_ID(buffer) ( little_endian_read_16(buffer, 6))
184 
185 /**
186  * LE connection parameter update state
187  */
188 
189 typedef enum {
190     CON_PARAMETER_UPDATE_NONE,
191     // L2CAP
192     CON_PARAMETER_UPDATE_SEND_REQUEST,
193     CON_PARAMETER_UPDATE_SEND_RESPONSE,
194     CON_PARAMETER_UPDATE_CHANGE_HCI_CON_PARAMETERS,
195     CON_PARAMETER_UPDATE_DENY,
196     // HCI - in respnose to HCI_SUBEVENT_LE_REMOTE_CONNECTION_PARAMETER_REQUEST
197     CON_PARAMETER_UPDATE_REPLY,
198     CON_PARAMETER_UPDATE_NEGATIVE_REPLY,
199 } le_con_parameter_update_state_t;
200 
201 // Authentication flags
202 typedef enum {
203     AUTH_FLAGS_NONE                = 0x0000,
204     RECV_LINK_KEY_REQUEST          = 0x0001,
205     HANDLE_LINK_KEY_REQUEST        = 0x0002,
206     SENT_LINK_KEY_REPLY            = 0x0004,
207     SENT_LINK_KEY_NEGATIVE_REQUEST = 0x0008,
208     RECV_LINK_KEY_NOTIFICATION     = 0x0010,
209     DENY_PIN_CODE_REQUEST          = 0x0040,
210     RECV_IO_CAPABILITIES_REQUEST   = 0x0080,
211     SEND_IO_CAPABILITIES_REPLY     = 0x0100,
212     SEND_IO_CAPABILITIES_NEGATIVE_REPLY = 0x0200,
213     SEND_USER_CONFIRM_REPLY        = 0x0400,
214     SEND_USER_PASSKEY_REPLY        = 0x0800,
215 
216     // Classic OOB
217     SEND_REMOTE_OOB_DATA_REPLY     = 0x1800,
218 
219     // pairing status
220     LEGACY_PAIRING_ACTIVE          = 0x2000,
221     SSP_PAIRING_ACTIVE             = 0x4000,
222 
223     // connection status
224     CONNECTION_AUTHENTICATED       = 0x8000,
225     CONNECTION_ENCRYPTED           = 0x10000,
226 
227     // errands
228     READ_RSSI                      = 0x20000,
229     WRITE_SUPERVISION_TIMEOUT      = 0x40000,
230 
231 } hci_authentication_flags_t;
232 
233 /**
234  * Connection State
235  */
236 typedef enum {
237     SEND_CREATE_CONNECTION = 0,
238     SENT_CREATE_CONNECTION,
239     SEND_CANCEL_CONNECTION,
240     SENT_CANCEL_CONNECTION,
241     RECEIVED_CONNECTION_REQUEST,
242     ACCEPTED_CONNECTION_REQUEST,
243     REJECTED_CONNECTION_REQUEST,
244     OPEN,
245     SEND_DISCONNECT,
246     SENT_DISCONNECT,
247     RECEIVED_DISCONNECTION_COMPLETE
248 } CONNECTION_STATE;
249 
250 // bonding flags
251 enum {
252     BONDING_REQUEST_REMOTE_FEATURES_PAGE_0    = 0x0001,
253     BONDING_REQUEST_REMOTE_FEATURES_PAGE_1    = 0x0002,
254     BONDING_REQUEST_REMOTE_FEATURES_PAGE_2    = 0x0004,
255     BONDING_RECEIVED_REMOTE_FEATURES          = 0x0008,
256     BONDING_REMOTE_SUPPORTS_SSP_CONTROLLER    = 0x0010,
257     BONDING_REMOTE_SUPPORTS_SSP_HOST          = 0x0020,
258     BONDING_REMOTE_SUPPORTS_SC_CONTROLLER     = 0x0040,
259     BONDING_REMOTE_SUPPORTS_SC_HOST           = 0x0080,
260     BONDING_DISCONNECT_SECURITY_BLOCK         = 0x0100,
261     BONDING_DISCONNECT_DEDICATED_DONE         = 0x0200,
262     BONDING_SEND_AUTHENTICATE_REQUEST         = 0x0400,
263     BONDING_SEND_ENCRYPTION_REQUEST           = 0x0800,
264     BONDING_SEND_READ_ENCRYPTION_KEY_SIZE     = 0x1000,
265     BONDING_DEDICATED                         = 0x2000,
266     BONDING_EMIT_COMPLETE_ON_DISCONNECT       = 0x4000,
267     BONDING_SENT_AUTHENTICATE_REQUEST         = 0x8000
268 };
269 
270 typedef enum {
271     BLUETOOTH_OFF = 1,
272     BLUETOOTH_ON,
273     BLUETOOTH_ACTIVE
274 } BLUETOOTH_STATE;
275 
276 typedef enum {
277     LE_CONNECTING_IDLE,
278     LE_CONNECTING_CANCEL,
279     LE_CONNECTING_DIRECT,
280     LE_CONNECTING_WHITELIST,
281 } le_connecting_state_t;
282 
283 #ifdef ENABLE_BLE
284 
285 //
286 // SM internal types and globals
287 //
288 
289 typedef enum {
290 
291     // general states
292     SM_GENERAL_IDLE,
293     SM_GENERAL_SEND_PAIRING_FAILED,
294     SM_GENERAL_TIMEOUT, // no other security messages are exchanged
295     SM_GENERAL_REENCRYPTION_FAILED,
296 
297     // Phase 1: Pairing Feature Exchange
298     SM_PH1_W4_USER_RESPONSE,
299 
300     // Phase 2: Authenticating and Encrypting
301 
302     // get random number for use as TK Passkey if we show it
303     SM_PH2_GET_RANDOM_TK,
304     SM_PH2_W4_RANDOM_TK,
305 
306     // get local random number for confirm c1
307     SM_PH2_C1_GET_RANDOM_A,
308     SM_PH2_C1_W4_RANDOM_A,
309     SM_PH2_C1_GET_RANDOM_B,
310     SM_PH2_C1_W4_RANDOM_B,
311 
312     // calculate confirm value for local side
313     SM_PH2_C1_GET_ENC_A,
314     SM_PH2_C1_W4_ENC_A,
315 
316     // calculate confirm value for remote side
317     SM_PH2_C1_GET_ENC_C,
318     SM_PH2_C1_W4_ENC_C,
319 
320     SM_PH2_C1_SEND_PAIRING_CONFIRM,
321     SM_PH2_SEND_PAIRING_RANDOM,
322 
323     // calc STK
324     SM_PH2_CALC_STK,
325     SM_PH2_W4_STK,
326 
327     SM_PH2_W4_CONNECTION_ENCRYPTED,
328 
329     // Phase 3: Transport Specific Key Distribution
330     // calculate DHK, Y, EDIV, and LTK
331     SM_PH3_Y_GET_ENC,
332     SM_PH3_Y_W4_ENC,
333     SM_PH3_LTK_GET_ENC,
334 
335     // exchange keys
336     SM_PH3_DISTRIBUTE_KEYS,
337     SM_PH3_RECEIVE_KEYS,
338 
339     // Phase 4: re-establish previously distributed LTK
340     SM_PH4_W4_CONNECTION_ENCRYPTED,
341 
342     // RESPONDER ROLE
343     SM_RESPONDER_IDLE,
344     SM_RESPONDER_SEND_SECURITY_REQUEST,
345     SM_RESPONDER_PH0_RECEIVED_LTK_REQUEST,
346     SM_RESPONDER_PH0_RECEIVED_LTK_W4_IRK,
347     SM_RESPONDER_PH0_SEND_LTK_REQUESTED_NEGATIVE_REPLY,
348     SM_RESPONDER_PH1_W4_PAIRING_REQUEST,
349     SM_RESPONDER_PH1_PAIRING_REQUEST_RECEIVED,
350     SM_RESPONDER_PH1_PAIRING_REQUEST_RECEIVED_W4_IRK,
351     SM_RESPONDER_PH1_SEND_PAIRING_RESPONSE,
352     SM_RESPONDER_PH1_W4_PAIRING_CONFIRM,
353     SM_RESPONDER_PH2_W4_PAIRING_RANDOM,
354     SM_RESPONDER_PH2_W4_LTK_REQUEST,
355     SM_RESPONDER_PH2_SEND_LTK_REPLY,
356     SM_RESPONDER_PH4_Y_W4_ENC,
357     SM_RESPONDER_PH4_SEND_LTK_REPLY,
358 
359     // INITIATOR ROLE
360     SM_INITIATOR_CONNECTED,
361     SM_INITIATOR_PH1_W2_SEND_PAIRING_REQUEST,
362     SM_INITIATOR_PH1_W4_PAIRING_RESPONSE,
363     SM_INITIATOR_PH2_W4_PAIRING_CONFIRM,
364     SM_INITIATOR_PH2_W4_PAIRING_RANDOM,
365     SM_INITIATOR_PH3_SEND_START_ENCRYPTION,
366     SM_INITIATOR_PH4_HAS_LTK,
367 
368     // LE Secure Connections
369     SM_SC_RECEIVED_LTK_REQUEST,
370     SM_SC_SEND_PUBLIC_KEY_COMMAND,
371     SM_SC_W4_PUBLIC_KEY_COMMAND,
372     SM_SC_W4_LOCAL_NONCE,
373     SM_SC_W2_CMAC_FOR_CONFIRMATION,
374     SM_SC_W4_CMAC_FOR_CONFIRMATION,
375     SM_SC_SEND_CONFIRMATION,
376     SM_SC_W2_CMAC_FOR_CHECK_CONFIRMATION,
377     SM_SC_W4_CMAC_FOR_CHECK_CONFIRMATION,
378     SM_SC_W4_CONFIRMATION,
379     SM_SC_SEND_PAIRING_RANDOM,
380     SM_SC_W4_PAIRING_RANDOM,
381     SM_SC_W2_CALCULATE_G2,
382     SM_SC_W4_CALCULATE_G2,
383     SM_SC_W4_CALCULATE_DHKEY,
384     SM_SC_W2_CALCULATE_F5_SALT,
385     SM_SC_W4_CALCULATE_F5_SALT,
386     SM_SC_W2_CALCULATE_F5_MACKEY,
387     SM_SC_W4_CALCULATE_F5_MACKEY,
388     SM_SC_W2_CALCULATE_F5_LTK,
389     SM_SC_W4_CALCULATE_F5_LTK,
390     SM_SC_W2_CALCULATE_F6_FOR_DHKEY_CHECK,
391     SM_SC_W4_CALCULATE_F6_FOR_DHKEY_CHECK,
392     SM_SC_W2_CALCULATE_F6_TO_VERIFY_DHKEY_CHECK,
393     SM_SC_W4_CALCULATE_F6_TO_VERIFY_DHKEY_CHECK,
394     SM_SC_W4_USER_RESPONSE,
395     SM_SC_SEND_DHKEY_CHECK_COMMAND,
396     SM_SC_W4_DHKEY_CHECK_COMMAND,
397     SM_SC_W4_LTK_REQUEST_SC,
398     SM_SC_W2_CALCULATE_ILK_USING_H6,
399 	SM_SC_W2_CALCULATE_ILK_USING_H7,
400     SM_SC_W4_CALCULATE_ILK,
401     SM_SC_W2_CALCULATE_BR_EDR_LINK_KEY,
402     SM_SC_W4_CALCULATE_BR_EDR_LINK_KEY,
403 } security_manager_state_t;
404 
405 typedef enum {
406     IRK_LOOKUP_IDLE,
407     IRK_LOOKUP_W4_READY,
408     IRK_LOOKUP_STARTED,
409     IRK_LOOKUP_SUCCEEDED,
410     IRK_LOOKUP_FAILED
411 } irk_lookup_state_t;
412 
413 typedef uint8_t sm_pairing_packet_t[7];
414 
415 // connection info available as long as connection exists
416 typedef struct sm_connection {
417     hci_con_handle_t         sm_handle;
418     uint8_t                  sm_role;   // 0 - IamMaster, 1 = IamSlave
419     uint8_t                  sm_security_request_received;
420     uint8_t                  sm_pairing_requested;
421     uint8_t                  sm_peer_addr_type;
422     bd_addr_t                sm_peer_address;
423     security_manager_state_t sm_engine_state;
424     irk_lookup_state_t       sm_irk_lookup_state;
425     uint8_t                  sm_connection_encrypted;
426     uint8_t                  sm_connection_authenticated;   // [0..1]
427     uint8_t                  sm_connection_sc;
428     uint8_t                  sm_actual_encryption_key_size;
429     sm_pairing_packet_t      sm_m_preq;  // only used during c1
430     authorization_state_t    sm_connection_authorization_state;
431     uint16_t                 sm_local_ediv;
432     uint8_t                  sm_local_rand[8];
433     int                      sm_le_db_index;
434     bool                     sm_pairing_active;
435     bool                     sm_reencryption_active;
436 } sm_connection_t;
437 
438 //
439 // ATT Server
440 //
441 
442 // max ATT request matches L2CAP PDU -- allow to use smaller buffer
443 #ifndef ATT_REQUEST_BUFFER_SIZE
444 #define ATT_REQUEST_BUFFER_SIZE HCI_ACL_PAYLOAD_SIZE
445 #endif
446 
447 typedef enum {
448     ATT_SERVER_IDLE,
449     ATT_SERVER_REQUEST_RECEIVED,
450     ATT_SERVER_W4_SIGNED_WRITE_VALIDATION,
451     ATT_SERVER_REQUEST_RECEIVED_AND_VALIDATED,
452     ATT_SERVER_RESPONSE_PENDING,
453 } att_server_state_t;
454 
455 typedef struct {
456     att_server_state_t      state;
457 
458     uint8_t                 peer_addr_type;
459     bd_addr_t               peer_address;
460 
461     int                     ir_le_device_db_index;
462     uint8_t                 ir_lookup_active;
463     uint8_t                 pairing_active;
464 
465     int                     value_indication_handle;
466     btstack_timer_source_t  value_indication_timer;
467 
468     btstack_linked_list_t   notification_requests;
469     btstack_linked_list_t   indication_requests;
470 
471 #ifdef ENABLE_GATT_OVER_CLASSIC
472     uint16_t                l2cap_cid;
473 #endif
474 
475     uint16_t                request_size;
476     uint8_t                 request_buffer[ATT_REQUEST_BUFFER_SIZE];
477 
478 } att_server_t;
479 
480 #endif
481 
482 #ifdef ENABLE_L2CAP_ENHANCED_RETRANSMISSION_MODE
483 typedef enum {
484     L2CAP_INFORMATION_STATE_IDLE = 0,
485     L2CAP_INFORMATION_STATE_W2_SEND_EXTENDED_FEATURE_REQUEST,
486     L2CAP_INFORMATION_STATE_W4_EXTENDED_FEATURE_RESPONSE,
487     L2CAP_INFORMATION_STATE_DONE
488 } l2cap_information_state_t;
489 
490 typedef struct {
491     l2cap_information_state_t information_state;
492     uint16_t                  extended_feature_mask;
493 } l2cap_state_t;
494 #endif
495 
496 //
497 typedef struct {
498     // linked list - assert: first field
499     btstack_linked_item_t    item;
500 
501     // remote side
502     bd_addr_t address;
503 
504     // module handle
505     hci_con_handle_t con_handle;
506 
507     // le public, le random, classic
508     bd_addr_type_t address_type;
509 
510     // role: 0 - master, 1 - slave
511     uint8_t role;
512 
513     // connection state
514     CONNECTION_STATE state;
515 
516     // bonding
517     uint16_t bonding_flags;
518     uint8_t  bonding_status;
519 
520     // encryption key size (in octets)
521     uint8_t encryption_key_size;
522 
523     // requested security level
524     gap_security_level_t requested_security_level;
525 
526     //
527     link_key_type_t link_key_type;
528 
529     // remote supported features
530     /* bit 0 - eSCO */
531     /* bit 1 - extended features */
532     uint8_t remote_supported_features[1];
533 
534 #ifdef ENABLE_CLASSIC
535     // IO Capabilities Response
536     uint8_t io_cap_response_auth_req;
537 
538     // connection mode, default ACL_CONNECTION_MODE_ACTIVE
539     uint8_t connection_mode;
540 
541     // enter/exit sniff mode requests
542     uint16_t sniff_min_interval;    // 0: idle, 0xffff exit sniff, else enter sniff
543     uint16_t sniff_max_interval;
544     uint16_t sniff_attempt;
545     uint16_t sniff_timeout;
546 
547     // sniff subrating
548     uint16_t sniff_subrating_max_latency;   // 0xffff = not set
549     uint16_t sniff_subrating_min_remote_timeout;
550     uint16_t sniff_subrating_min_local_timeout;
551 
552     // QoS
553     hci_service_type_t qos_service_type;
554     uint32_t qos_token_rate;
555     uint32_t qos_peak_bandwidth;
556     uint32_t qos_latency;
557     uint32_t qos_delay_variation;
558 
559 #ifdef ENABLE_SCO_OVER_HCI
560     // track SCO rx event
561     uint32_t sco_rx_ms;
562     uint8_t  sco_rx_count;
563     uint8_t  sco_rx_valid;
564 #endif
565     // generate sco can send now based on received packets, using timeout below
566     uint8_t  sco_tx_ready;
567 
568     // request role switch
569     hci_role_t request_role;
570 
571     btstack_timer_source_t timeout_sco;
572 #endif /* ENABLE_CLASSIC */
573 
574     // authentication and other errands
575     uint32_t authentication_flags;
576 
577     btstack_timer_source_t timeout;
578 
579     // timeout in system ticks (HAVE_EMBEDDED_TICK) or milliseconds (HAVE_EMBEDDED_TIME_MS)
580     uint32_t timestamp;
581 
582     // ACL packet recombination - PRE_BUFFER + ACL Header + ACL payload
583     uint8_t  acl_recombination_buffer[HCI_INCOMING_PRE_BUFFER_SIZE + 4 + HCI_ACL_BUFFER_SIZE];
584     uint16_t acl_recombination_pos;
585     uint16_t acl_recombination_length;
586 
587 
588     // number packets sent to controller
589     uint8_t num_packets_sent;
590 
591 #ifdef ENABLE_HCI_CONTROLLER_TO_HOST_FLOW_CONTROL
592     uint8_t num_packets_completed;
593 #endif
594 
595     // LE Connection parameter update
596     le_con_parameter_update_state_t le_con_parameter_update_state;
597     uint8_t  le_con_param_update_identifier;
598     uint16_t le_conn_interval_min;
599     uint16_t le_conn_interval_max;
600     uint16_t le_conn_latency;
601     uint16_t le_supervision_timeout;
602 
603 #ifdef ENABLE_BLE
604     uint16_t le_connection_interval;
605 
606     // LE PHY Update via set phy command
607     uint8_t le_phy_update_all_phys;      // 0xff for idle
608     uint8_t le_phy_update_tx_phys;
609     uint8_t le_phy_update_rx_phys;
610     int8_t  le_phy_update_phy_options;
611 
612     // LE Security Manager
613     sm_connection_t sm_connection;
614 
615 #ifdef ENABLE_LE_LIMIT_ACL_FRAGMENT_BY_MAX_OCTETS
616     uint16_t le_max_tx_octets;
617 #endif
618 
619     // ATT Connection
620     att_connection_t att_connection;
621 
622     // ATT Server
623     att_server_t    att_server;
624 
625 #endif
626 
627 #ifdef ENABLE_L2CAP_ENHANCED_RETRANSMISSION_MODE
628     l2cap_state_t l2cap_state;
629 #endif
630 
631 #ifdef ENABLE_CLASSIC_PAIRING_OOB
632     const uint8_t * classic_oob_c_192;
633     const uint8_t * classic_oob_r_192;
634     const uint8_t * classic_oob_c_256;
635     const uint8_t * classic_oob_r_256;
636 #endif
637 
638 } hci_connection_t;
639 
640 
641 /**
642  * HCI Inititizlization State Machine
643  */
644 typedef enum hci_init_state{
645     HCI_INIT_SEND_RESET = 0,
646     HCI_INIT_W4_SEND_RESET,
647     HCI_INIT_SEND_READ_LOCAL_VERSION_INFORMATION,
648     HCI_INIT_W4_SEND_READ_LOCAL_VERSION_INFORMATION,
649     HCI_INIT_SEND_READ_LOCAL_NAME,
650     HCI_INIT_W4_SEND_READ_LOCAL_NAME,
651 
652     HCI_INIT_SEND_BAUD_CHANGE,
653     HCI_INIT_W4_SEND_BAUD_CHANGE,
654     HCI_INIT_CUSTOM_INIT,
655     HCI_INIT_W4_CUSTOM_INIT,
656     HCI_INIT_SEND_RESET_CSR_WARM_BOOT,
657     HCI_INIT_W4_CUSTOM_INIT_CSR_WARM_BOOT,
658     HCI_INIT_W4_CUSTOM_INIT_CSR_WARM_BOOT_LINK_RESET,
659     HCI_INIT_W4_CUSTOM_INIT_BCM_DELAY,
660 
661     HCI_INIT_READ_LOCAL_SUPPORTED_COMMANDS,
662     HCI_INIT_W4_READ_LOCAL_SUPPORTED_COMMANDS,
663 
664     HCI_INIT_SEND_BAUD_CHANGE_BCM,
665     HCI_INIT_W4_SEND_BAUD_CHANGE_BCM,
666 
667     HCI_INIT_SET_BD_ADDR,
668     HCI_INIT_W4_SET_BD_ADDR,
669 
670     HCI_INIT_SEND_RESET_ST_WARM_BOOT,
671     HCI_INIT_W4_SEND_RESET_ST_WARM_BOOT,
672 
673     HCI_INIT_READ_BD_ADDR,
674     HCI_INIT_W4_READ_BD_ADDR,
675 
676     HCI_INIT_READ_BUFFER_SIZE,
677     HCI_INIT_W4_READ_BUFFER_SIZE,
678     HCI_INIT_READ_LOCAL_SUPPORTED_FEATURES,
679     HCI_INIT_W4_READ_LOCAL_SUPPORTED_FEATURES,
680 
681 #ifdef ENABLE_HCI_CONTROLLER_TO_HOST_FLOW_CONTROL
682     HCI_INIT_HOST_BUFFER_SIZE,
683     HCI_INIT_W4_HOST_BUFFER_SIZE,
684     HCI_INIT_SET_CONTROLLER_TO_HOST_FLOW_CONTROL,
685     HCI_INIT_W4_SET_CONTROLLER_TO_HOST_FLOW_CONTROL,
686 #endif
687 
688     HCI_INIT_SET_EVENT_MASK,
689     HCI_INIT_W4_SET_EVENT_MASK,
690 
691     HCI_INIT_WRITE_SIMPLE_PAIRING_MODE,
692     HCI_INIT_W4_WRITE_SIMPLE_PAIRING_MODE,
693     HCI_INIT_WRITE_PAGE_TIMEOUT,
694     HCI_INIT_W4_WRITE_PAGE_TIMEOUT,
695     HCI_INIT_WRITE_DEFAULT_LINK_POLICY_SETTING,
696     HCI_INIT_W4_WRITE_DEFAULT_LINK_POLICY_SETTING,
697     HCI_INIT_WRITE_CLASS_OF_DEVICE,
698     HCI_INIT_W4_WRITE_CLASS_OF_DEVICE,
699     HCI_INIT_WRITE_LOCAL_NAME,
700     HCI_INIT_W4_WRITE_LOCAL_NAME,
701     HCI_INIT_WRITE_EIR_DATA,
702     HCI_INIT_W4_WRITE_EIR_DATA,
703     HCI_INIT_WRITE_INQUIRY_MODE,
704     HCI_INIT_W4_WRITE_INQUIRY_MODE,
705     HCI_INIT_WRITE_SECURE_CONNECTIONS_HOST_ENABLE,
706     HCI_INIT_W4_WRITE_SECURE_CONNECTIONS_HOST_ENABLE,
707     HCI_INIT_WRITE_SCAN_ENABLE,
708     HCI_INIT_W4_WRITE_SCAN_ENABLE,
709 
710     // SCO over HCI
711     HCI_INIT_WRITE_SYNCHRONOUS_FLOW_CONTROL_ENABLE,
712     HCI_INIT_W4_WRITE_SYNCHRONOUS_FLOW_CONTROL_ENABLE,
713     HCI_INIT_WRITE_DEFAULT_ERRONEOUS_DATA_REPORTING,
714     HCI_INIT_W4_WRITE_DEFAULT_ERRONEOUS_DATA_REPORTING,
715 
716     // Broadcom SCO Routing and Configuration
717     HCI_INIT_BCM_WRITE_SCO_PCM_INT,
718     HCI_INIT_W4_BCM_WRITE_SCO_PCM_INT,
719     HCI_INIT_BCM_WRITE_I2SPCM_INTERFACE_PARAM,
720     HCI_INIT_W4_BCM_WRITE_I2SPCM_INTERFACE_PARAM,
721 
722 #ifdef ENABLE_BLE
723     HCI_INIT_LE_READ_BUFFER_SIZE,
724     HCI_INIT_W4_LE_READ_BUFFER_SIZE,
725     HCI_INIT_WRITE_LE_HOST_SUPPORTED,
726     HCI_INIT_W4_WRITE_LE_HOST_SUPPORTED,
727     HCI_INIT_LE_SET_EVENT_MASK,
728     HCI_INIT_W4_LE_SET_EVENT_MASK,
729 #endif
730 
731 #ifdef ENABLE_LE_DATA_LENGTH_EXTENSION
732     HCI_INIT_LE_READ_MAX_DATA_LENGTH,
733     HCI_INIT_W4_LE_READ_MAX_DATA_LENGTH,
734     HCI_INIT_LE_WRITE_SUGGESTED_DATA_LENGTH,
735     HCI_INIT_W4_LE_WRITE_SUGGESTED_DATA_LENGTH,
736 #endif
737 
738 #ifdef ENABLE_LE_CENTRAL
739     HCI_INIT_READ_WHITE_LIST_SIZE,
740     HCI_INIT_W4_READ_WHITE_LIST_SIZE,
741 
742     HCI_INIT_LE_SET_SCAN_PARAMETERS,
743     HCI_INIT_W4_LE_SET_SCAN_PARAMETERS,
744 #endif
745 
746     HCI_INIT_DONE,
747 
748     HCI_FALLING_ASLEEP_DISCONNECT,
749     HCI_FALLING_ASLEEP_W4_WRITE_SCAN_ENABLE,
750     HCI_FALLING_ASLEEP_COMPLETE,
751 
752     HCI_INIT_AFTER_SLEEP,
753 
754     HCI_HALTING_DISCONNECT_ALL_NO_TIMER,
755     HCI_HALTING_DISCONNECT_ALL_TIMER,
756     HCI_HALTING_W4_TIMER,
757     HCI_HALTING_CLOSE,
758 
759 } hci_substate_t;
760 
761 enum {
762     LE_ADVERTISEMENT_TASKS_SET_ADV_DATA  = 1 << 0,
763     LE_ADVERTISEMENT_TASKS_SET_SCAN_DATA = 1 << 1,
764     LE_ADVERTISEMENT_TASKS_SET_PARAMS    = 1 << 2,
765 };
766 
767 enum {
768     LE_WHITELIST_ON_CONTROLLER          = 1 << 0,
769     LE_WHITELIST_ADD_TO_CONTROLLER      = 1 << 1,
770     LE_WHITELIST_REMOVE_FROM_CONTROLLER = 1 << 2,
771 };
772 
773 typedef struct {
774     btstack_linked_item_t  item;
775     bd_addr_t      address;
776     bd_addr_type_t address_type;
777     uint8_t        state;
778 } whitelist_entry_t;
779 
780 #define MAX_NUM_RESOLVING_LIST_ENTRIES 64
781 typedef enum {
782     LE_RESOLVING_LIST_SEND_ENABLE_ADDRESS_RESOLUTION,
783     LE_RESOLVING_LIST_READ_SIZE,
784     LE_RESOLVING_LIST_SEND_CLEAR,
785 	LE_RESOLVING_LIST_REMOVE_ENTRIES,
786     LE_RESOLVING_LIST_ADD_ENTRIES,
787     LE_RESOLVING_LIST_DONE
788 } le_resolving_list_state_t;
789 
790 /**
791  * main data structure
792  */
793 typedef struct {
794     // transport component with configuration
795     const hci_transport_t * hci_transport;
796     const void            * config;
797 
798     // chipset driver
799     const btstack_chipset_t * chipset;
800 
801     // hardware power controller
802     const btstack_control_t * control;
803 
804     /* link key db */
805     const btstack_link_key_db_t * link_key_db;
806 
807     // list of existing baseband connections
808     btstack_linked_list_t     connections;
809 
810     /* callback to L2CAP layer */
811     btstack_packet_handler_t acl_packet_handler;
812 
813     /* callback for SCO data */
814     btstack_packet_handler_t sco_packet_handler;
815 
816     /* callbacks for events */
817     btstack_linked_list_t event_handlers;
818 
819 #ifdef ENABLE_CLASSIC
820     /* callback for reject classic connection */
821     int (*gap_classic_accept_callback)(bd_addr_t addr, hci_link_type_t link_type);
822 #endif
823 
824     // hardware error callback
825     void (*hardware_error_callback)(uint8_t error);
826 
827     // basic configuration
828     const char *       local_name;
829     const uint8_t *    eir_data;
830     uint32_t           class_of_device;
831     bd_addr_t          local_bd_addr;
832     uint8_t            default_link_policy_settings;
833     uint8_t            allow_role_switch;
834     uint8_t            ssp_enable;
835     uint8_t            ssp_io_capability;
836     uint8_t            ssp_authentication_requirement;
837     uint8_t            ssp_auto_accept;
838     bool               secure_connections_enable;
839     bool               secure_connections_active;
840     inquiry_mode_t     inquiry_mode;
841 
842 #ifdef ENABLE_CLASSIC
843     /* write page scan activity, 0xffff is no change */
844     uint16_t           new_page_scan_interval;
845     uint16_t           new_page_scan_window;
846 
847     /* write page scan type, 0xff is no change */
848     uint8_t            new_page_scan_type;
849 
850     // Errata-11838 mandates 7 bytes for GAP Security Level 1-3, we use 16 as default
851     uint8_t            gap_required_encyrption_key_size;
852     uint16_t           link_supervision_timeout;
853     gap_security_level_t gap_security_level;
854 #endif
855 
856     // single buffer for HCI packet assembly + additional prebuffer for H4 drivers
857     uint8_t   * hci_packet_buffer;
858     uint8_t   hci_packet_buffer_data[HCI_OUTGOING_PRE_BUFFER_SIZE + HCI_OUTGOING_PACKET_BUFFER_SIZE];
859     uint8_t   hci_packet_buffer_reserved;
860     uint16_t  acl_fragmentation_pos;
861     uint16_t  acl_fragmentation_total_size;
862     uint8_t   acl_fragmentation_tx_active;
863 
864     /* host to controller flow control */
865     uint8_t  num_cmd_packets;
866     uint8_t  acl_packets_total_num;
867     uint16_t acl_data_packet_length;
868     uint8_t  sco_packets_total_num;
869     uint8_t  sco_data_packet_length;
870     uint8_t  synchronous_flow_control_enabled;
871     uint8_t  le_acl_packets_total_num;
872     uint16_t le_data_packets_length;
873     uint8_t  sco_waiting_for_can_send_now;
874     uint8_t  sco_can_send_now;
875 
876     /* local supported features */
877     uint8_t local_supported_features[8];
878 
879     /* local supported commands summary - complete info is 64 bytes */
880     /*  0 - Read Buffer Size                        (Octet 14/bit 7) */
881     /*  1 - Write Le Host Supported                 (Octet 24/bit 6) */
882     /*  2 - Write Synchronous Flow Control Enable   (Octet 10/bit 4) */
883     /*  3 - Write Default Erroneous Data Reporting  (Octet 18/bit 3) */
884     /*  4 - LE Write Suggested Default Data Length  (Octet 34/bit 0) */
885     /*  5 - LE Read Maximum Data Length             (Octet 35/bit 3) */
886     /*  6 - LE Set Default PHY                      (Octet 35/bit 5) */
887     /*  7 - Read Encryption Key Size                (Octet 20/bit 4) */
888     /*  8 - Read Remote Extended Features           (Octet  2/bit 5) */
889     /*  9 - Write Secure Connections Host           (Octet 32/bit 3) */
890     /* 10 - LE Set Address Resolution Enable        (Octet 35/bit 1) */
891     /* 11 - Remote OOB Extended Data Request Reply  (Octet 32/bit 1) */
892     /* 12 - Read Local OOB Extended Data command    (Octet 32/bit 6) */
893     uint8_t local_supported_commands[2];
894 
895     /* bluetooth device information from hci read local version information */
896     // uint16_t hci_version;
897     // uint16_t hci_revision;
898     // uint16_t lmp_version;
899     uint16_t manufacturer;
900     // uint16_t lmp_subversion;
901 
902     // usable packet types given acl_data_packet_length and HCI_ACL_BUFFER_SIZE
903     uint16_t packet_types;
904 
905 
906     /* hci state machine */
907     HCI_STATE      state;
908     hci_substate_t substate;
909     btstack_timer_source_t timeout;
910     btstack_chipset_result_t chipset_result;
911 
912     uint16_t  last_cmd_opcode;
913 
914     uint8_t   cmds_ready;
915 
916     /* buffer for scan enable cmd - 0xff no change */
917     uint8_t   new_scan_enable_value;
918 
919     uint8_t   discoverable;
920     uint8_t   connectable;
921     uint8_t   bondable;
922 
923     uint8_t   inquiry_state;    // see hci.c for state defines
924 
925     bd_addr_t remote_name_addr;
926     uint16_t  remote_name_clock_offset;
927     uint8_t   remote_name_page_scan_repetition_mode;
928     uint8_t   remote_name_state;    // see hci.c for state defines
929 
930     bd_addr_t gap_pairing_addr;
931     uint8_t   gap_pairing_state;    // see hci.c for state defines
932     uint8_t   gap_pairing_pin_len;
933     union {
934         const uint8_t * gap_pairing_pin;
935         uint32_t     gap_pairing_passkey;
936     } gap_pairing_input;
937 
938     uint16_t  sco_voice_setting;
939     uint16_t  sco_voice_setting_active;
940 
941     uint8_t   loopback_mode;
942 
943     // buffer for single connection decline
944     uint8_t   decline_reason;
945     bd_addr_t decline_addr;
946 
947 #ifdef ENABLE_HCI_CONTROLLER_TO_HOST_FLOW_CONTROL
948     uint8_t   host_completed_packets;
949 #endif
950 
951 #ifdef ENABLE_BLE
952     uint8_t   le_own_addr_type;
953     bd_addr_t le_random_address;
954     uint8_t   le_random_address_set;
955 
956     // LE Whitelist Management
957     uint8_t               le_whitelist_capacity;
958     btstack_linked_list_t le_whitelist;
959 #endif
960 
961 #ifdef ENABLE_LE_CENTRAL
962     bool   le_scanning_enabled;
963     bool   le_scanning_active;
964 
965     le_connecting_state_t le_connecting_state;
966     le_connecting_state_t le_connecting_request;
967 
968     bool     le_scanning_param_update;
969     uint8_t  le_scan_type;
970     uint8_t  le_scan_filter_policy;
971     uint16_t le_scan_interval;
972     uint16_t le_scan_window;
973 
974     // Connection parameters
975     uint16_t le_connection_interval_min;
976     uint16_t le_connection_interval_max;
977     uint16_t le_connection_latency;
978     uint16_t le_supervision_timeout;
979     uint16_t le_minimum_ce_length;
980     uint16_t le_maximum_ce_length;
981     uint16_t le_connection_scan_interval;
982     uint16_t le_connection_scan_window;
983 #endif
984 
985     le_connection_parameter_range_t le_connection_parameter_range;
986 
987 #ifdef ENABLE_LE_PERIPHERAL
988     uint8_t  * le_advertisements_data;
989     uint8_t    le_advertisements_data_len;
990 
991     uint8_t  * le_scan_response_data;
992     uint8_t    le_scan_response_data_len;
993 
994     bool     le_advertisements_active;
995     bool     le_advertisements_enabled;
996     bool     le_advertisements_enabled_for_current_roles;
997     uint8_t  le_advertisements_todo;
998 
999     uint16_t le_advertisements_interval_min;
1000     uint16_t le_advertisements_interval_max;
1001     uint8_t  le_advertisements_type;
1002     uint8_t  le_advertisements_direct_address_type;
1003     uint8_t  le_advertisements_channel_map;
1004     uint8_t  le_advertisements_filter_policy;
1005     bd_addr_t le_advertisements_direct_address;
1006 
1007     uint8_t le_max_number_peripheral_connections;
1008 #endif
1009 
1010 #ifdef ENABLE_LE_DATA_LENGTH_EXTENSION
1011     // LE Data Length
1012     uint16_t le_supported_max_tx_octets;
1013     uint16_t le_supported_max_tx_time;
1014 #endif
1015 
1016     // custom BD ADDR
1017     bd_addr_t custom_bd_addr;
1018     uint8_t   custom_bd_addr_set;
1019 
1020 #ifdef ENABLE_CLASSIC
1021     uint8_t master_slave_policy;
1022 #endif
1023 
1024     // address and address_type of active create connection command (ACL, SCO, LE)
1025     bd_addr_t      outgoing_addr;
1026     bd_addr_type_t outgoing_addr_type;
1027 
1028     // LE Resolving List
1029 #ifdef ENABLE_LE_PRIVACY_ADDRESS_RESOLUTION
1030     le_resolving_list_state_t le_resolving_list_state;
1031     uint16_t                  le_resolving_list_size;
1032     uint8_t                   le_resolving_list_add_entries[(MAX_NUM_RESOLVING_LIST_ENTRIES + 7) / 8];
1033 	uint8_t                   le_resolving_list_remove_entries[(MAX_NUM_RESOLVING_LIST_ENTRIES + 7) / 8];
1034 #endif
1035 
1036 #ifdef ENABLE_CLASSIC_PAIRING_OOB
1037 	bool                      classic_read_local_oob_data;
1038 #endif
1039 
1040 #ifdef HAVE_SCO_TRANSPORT
1041 	const btstack_sco_transport_t * sco_transport;
1042 #endif
1043 } hci_stack_t;
1044 
1045 
1046 /* API_START */
1047 
1048 
1049 // HCI init and configuration
1050 
1051 
1052 /**
1053  * @brief Set up HCI. Needs to be called before any other function.
1054  */
1055 void hci_init(const hci_transport_t *transport, const void *config);
1056 
1057 /**
1058  * @brief Configure Bluetooth chipset driver. Has to be called before power on, or right after receiving the local version information.
1059  */
1060 void hci_set_chipset(const btstack_chipset_t *chipset_driver);
1061 
1062 /**
1063  * @brief Configure Bluetooth hardware control. Has to be called before power on.
1064  * @[aram hardware_control implementation
1065  */
1066 void hci_set_control(const btstack_control_t *hardware_control);
1067 
1068 #ifdef HAVE_SCO_TRANSPORT
1069 /**
1070  * @brief Set SCO Transport implementation for SCO over PCM mode
1071  * @param sco_transport that sends SCO over I2S or PCM interface
1072  */
1073 void hci_set_sco_transport(const btstack_sco_transport_t *sco_transport);
1074 #endif
1075 
1076 /**
1077  * @brief Configure Bluetooth hardware control. Has to be called before power on.
1078  */
1079 void hci_set_link_key_db(btstack_link_key_db_t const * link_key_db);
1080 
1081 /**
1082  * @brief Set callback for Bluetooth Hardware Error
1083  */
1084 void hci_set_hardware_error_callback(void (*fn)(uint8_t error));
1085 
1086 /**
1087  * @brief Set Public BD ADDR - passed on to Bluetooth chipset during init if supported in bt_control_h
1088  */
1089 void hci_set_bd_addr(bd_addr_t addr);
1090 
1091 /**
1092  * @brief Configure Voice Setting for use with SCO data in HSP/HFP
1093  */
1094 void hci_set_sco_voice_setting(uint16_t voice_setting);
1095 
1096 /**
1097  * @brief Get SCO Voice Setting
1098  * @return current voice setting
1099  */
1100 uint16_t hci_get_sco_voice_setting(void);
1101 
1102 /**
1103  * @brief Set inquiry mode: standard, with RSSI, with RSSI + Extended Inquiry Results. Has to be called before power on.
1104  * @param inquriy_mode see bluetooth_defines.h
1105  */
1106 void hci_set_inquiry_mode(inquiry_mode_t mode);
1107 
1108 /**
1109  * @brief Requests the change of BTstack power mode.
1110  */
1111 int  hci_power_control(HCI_POWER_MODE mode);
1112 
1113 /**
1114  * @brief Shutdown HCI
1115  */
1116 void hci_close(void);
1117 
1118 
1119 // Callback registration
1120 
1121 
1122 /**
1123  * @brief Add event packet handler.
1124  */
1125 void hci_add_event_handler(btstack_packet_callback_registration_t * callback_handler);
1126 
1127 /**
1128  * @brief Registers a packet handler for ACL data. Used by L2CAP
1129  */
1130 void hci_register_acl_packet_handler(btstack_packet_handler_t handler);
1131 
1132 /**
1133  * @brief Registers a packet handler for SCO data. Used for HSP and HFP profiles.
1134  */
1135 void hci_register_sco_packet_handler(btstack_packet_handler_t handler);
1136 
1137 
1138 // Sending HCI Commands
1139 
1140 /**
1141  * @brief Check if CMD packet can be sent to controller
1142  */
1143 int hci_can_send_command_packet_now(void);
1144 
1145 /**
1146  * @brief Creates and sends HCI command packets based on a template and a list of parameters. Will return error if outgoing data buffer is occupied.
1147  */
1148 int hci_send_cmd(const hci_cmd_t *cmd, ...);
1149 
1150 
1151 // Sending SCO Packets
1152 
1153 /** @brief Get SCO packet length for current SCO Voice setting
1154  *  @note  Using SCO packets of the exact length is required for USB transfer
1155  *  @return Length of SCO packets in bytes (not audio frames) incl. 3 byte header
1156  */
1157 int hci_get_sco_packet_length(void);
1158 
1159 /**
1160  * @brief Request emission of HCI_EVENT_SCO_CAN_SEND_NOW as soon as possible
1161  * @note HCI_EVENT_SCO_CAN_SEND_NOW might be emitted during call to this function
1162  *       so packet handler should be ready to handle it
1163  */
1164 void hci_request_sco_can_send_now_event(void);
1165 
1166 /**
1167  * @brief Check HCI packet buffer and if SCO packet can be sent to controller
1168  */
1169 int hci_can_send_sco_packet_now(void);
1170 
1171 /**
1172  * @brief Check if SCO packet can be sent to controller
1173  */
1174 int hci_can_send_prepared_sco_packet_now(void);
1175 
1176 /**
1177  * @brief Send SCO packet prepared in HCI packet buffer
1178  */
1179 int hci_send_sco_packet_buffer(int size);
1180 
1181 
1182 // Outgoing packet buffer, also used for SCO packets
1183 // see hci_can_send_prepared_sco_packet_now amn hci_send_sco_packet_buffer
1184 
1185 /**
1186  * Reserves outgoing packet buffer.
1187  * @return 1 on success
1188  */
1189 int hci_reserve_packet_buffer(void);
1190 
1191 /**
1192  * Get pointer for outgoing packet buffer
1193  */
1194 uint8_t* hci_get_outgoing_packet_buffer(void);
1195 
1196 /**
1197  * Release outgoing packet buffer\
1198  * @note only called instead of hci_send_preparared
1199  */
1200 void hci_release_packet_buffer(void);
1201 
1202 /**
1203 * @brief Sets the master/slave policy
1204 * @param policy (0: attempt to become master, 1: let connecting device decide)
1205 */
1206 void hci_set_master_slave_policy(uint8_t policy);
1207 
1208 /* API_END */
1209 
1210 
1211 /**
1212  * va_list version of hci_send_cmd, call hci_send_cmd_packet
1213  */
1214 int hci_send_cmd_va_arg(const hci_cmd_t *cmd, va_list argtr);
1215 
1216 /**
1217  * Get connection iterator. Only used by l2cap.c and sm.c
1218  */
1219 void hci_connections_get_iterator(btstack_linked_list_iterator_t *it);
1220 
1221 /**
1222  * Get internal hci_connection_t for given handle. Used by L2CAP, SM, daemon
1223  */
1224 hci_connection_t * hci_connection_for_handle(hci_con_handle_t con_handle);
1225 
1226 /**
1227  * Get internal hci_connection_t for given Bluetooth addres. Called by L2CAP
1228  */
1229 hci_connection_t * hci_connection_for_bd_addr_and_type(const bd_addr_t addr, bd_addr_type_t addr_type);
1230 
1231 /**
1232  * Check if outgoing packet buffer is reserved. Used for internal checks in l2cap.c
1233  */
1234 int hci_is_packet_buffer_reserved(void);
1235 
1236 /**
1237  * Check hci packet buffer is free and a classic acl packet can be sent to controller
1238  */
1239 int hci_can_send_acl_classic_packet_now(void);
1240 
1241 /**
1242  * Check hci packet buffer is free and an LE acl packet can be sent to controller
1243  */
1244 int hci_can_send_acl_le_packet_now(void);
1245 
1246 /**
1247  * Check hci packet buffer is free and an acl packet for the given handle can be sent to controller
1248  */
1249 int hci_can_send_acl_packet_now(hci_con_handle_t con_handle);
1250 
1251 /**
1252  * Check if acl packet for the given handle can be sent to controller
1253  */
1254 int hci_can_send_prepared_acl_packet_now(hci_con_handle_t con_handle);
1255 
1256 /**
1257  * Send acl packet prepared in hci packet buffer
1258  */
1259 int hci_send_acl_packet_buffer(int size);
1260 
1261 /**
1262  * Check if authentication is active. It delays automatic disconnect while no L2CAP connection
1263  * Called by l2cap.
1264  */
1265 int hci_authentication_active_for_handle(hci_con_handle_t handle);
1266 
1267 /**
1268  * Get maximal ACL Classic data packet length based on used buffer size. Called by L2CAP
1269  */
1270 uint16_t hci_max_acl_data_packet_length(void);
1271 
1272 /**
1273  * Get supported packet types. Called by L2CAP
1274  */
1275 uint16_t hci_usable_acl_packet_types(void);
1276 
1277 /**
1278  * Check if ACL packets marked as non flushable can be sent. Called by L2CAP
1279  */
1280 int hci_non_flushable_packet_boundary_flag_supported(void);
1281 
1282 /**
1283  * Check if extended SCO Link is supported
1284  */
1285 int hci_extended_sco_link_supported(void);
1286 
1287 /**
1288  * Check if SSP is supported on both sides. Called by L2CAP
1289  */
1290 int gap_ssp_supported_on_both_sides(hci_con_handle_t handle);
1291 
1292 /**
1293  * Disconn because of security block. Called by L2CAP
1294  */
1295 void hci_disconnect_security_block(hci_con_handle_t con_handle);
1296 
1297 /**
1298  * Query if remote side supports eSCO
1299  */
1300 int hci_remote_esco_supported(hci_con_handle_t con_handle);
1301 
1302 /**
1303  * Emit current HCI state. Called by daemon
1304  */
1305 void hci_emit_state(void);
1306 
1307 /**
1308  * Send complete CMD packet. Called by daemon and hci_send_cmd_va_arg
1309  * @returns 0 if command was successfully sent to HCI Transport layer
1310  */
1311 int hci_send_cmd_packet(uint8_t *packet, int size);
1312 
1313 /**
1314  * Disconnect all HCI connections. Called by daemon
1315  */
1316 void hci_disconnect_all(void);
1317 
1318 /**
1319  * Get number of free acl slots for packets of given handle. Called by daemon
1320  */
1321 int hci_number_free_acl_slots_for_handle(hci_con_handle_t con_handle);
1322 
1323 /**
1324  * @brief Set Advertisement Parameters
1325  * @param adv_int_min
1326  * @param adv_int_max
1327  * @param adv_type
1328  * @param direct_address_type
1329  * @param direct_address
1330  * @param channel_map
1331  * @param filter_policy
1332  *
1333  * @note internal use. use gap_advertisements_set_params from gap.h instead.
1334  */
1335 void hci_le_advertisements_set_params(uint16_t adv_int_min, uint16_t adv_int_max, uint8_t adv_type,
1336     uint8_t direct_address_typ, bd_addr_t direct_address, uint8_t channel_map, uint8_t filter_policy);
1337 
1338 /**
1339  *
1340  * @note internal use. use gap_random_address_set_mode from gap.h instead.
1341  */
1342 void hci_le_set_own_address_type(uint8_t own_address_type);
1343 
1344 /**
1345  * @note internal use by sm
1346  */
1347 void hci_load_le_device_db_entry_into_resolving_list(uint16_t le_device_db_index);
1348 
1349 /**
1350  * @note internal use by sm
1351  */
1352 void hci_remove_le_device_db_entry_from_resolving_list(uint16_t le_device_db_index);
1353 
1354 /**
1355  * @brief Get Manufactured
1356  * @return manufacturer id
1357  */
1358 uint16_t hci_get_manufacturer(void);
1359 
1360 /**
1361  * Defer halt. Used by btstack_crypto to allow current HCI operation to complete
1362  */
1363 void hci_halting_defer(void);
1364 
1365 // Only for PTS testing
1366 
1367 /**
1368  * Disable automatic L2CAP disconnect if no L2CAP connection is established
1369  */
1370 void hci_disable_l2cap_timeout_check(void);
1371 
1372 /**
1373  *  Get Classic Allow Role Switch param
1374  */
1375 uint8_t hci_get_allow_role_switch(void);
1376 
1377 /**
1378  * Get state
1379  */
1380 HCI_STATE hci_get_state(void);
1381 
1382 /**
1383  * @brief De-Init HCI
1384  */
1385 void hci_deinit(void);
1386 
1387 // setup test connections, used for fuzzing
1388 void hci_setup_test_connections_fuzz(void);
1389 
1390 // free all connections, used for fuzzing
1391 void hci_free_connections_fuzz(void);
1392 
1393 // simulate stack bootup
1394 void hci_simulate_working_fuzz(void);
1395 
1396 
1397 #if defined __cplusplus
1398 }
1399 #endif
1400 
1401 #endif // HCI_H
1402