xref: /btstack/src/hci.h (revision 933d8a808454948f97a99dd9513a227183e72f1e)
1 /*
2  * Copyright (C) 2009 by Matthias Ringwald
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  *
17  * THIS SOFTWARE IS PROVIDED BY MATTHIAS RINGWALD AND CONTRIBUTORS
18  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
20  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL MATTHIAS
21  * RINGWALD OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
22  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
23  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
24  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
25  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
26  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
27  * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28  * SUCH DAMAGE.
29  *
30  */
31 
32 /*
33  *  hci.h
34  *
35  *  Created by Matthias Ringwald on 4/29/09.
36  *
37  */
38 
39 #pragma once
40 
41 #include <btstack/hci_cmds.h>
42 #include <btstack/utils.h>
43 #include "hci_transport.h"
44 #include "bt_control.h"
45 #include "remote_device_db.h"
46 
47 #include <stdint.h>
48 #include <stdlib.h>
49 #include <stdarg.h>
50 
51 #if defined __cplusplus
52 extern "C" {
53 #endif
54 
55 // packet header lenghts
56 #define HCI_CMD_DATA_PKT_HDR	  0x03
57 #define HCI_ACL_DATA_PKT_HDR	  0x04
58 #define HCI_SCO_DATA_PKT_HDR	  0x03
59 #define HCI_EVENT_PKT_HDR         0x02
60 
61 // packet sizes
62 #define HCI_ACL_3DH5_SIZE         1021
63 #define HCI_ACL_DH5_SIZE           339
64 
65 // OGFs
66 #define OGF_LINK_CONTROL          0x01
67 #define OGF_LINK_POLICY           0x02
68 #define OGF_CONTROLLER_BASEBAND   0x03
69 #define OGF_INFORMATIONAL_PARAMETERS 0x04
70 #define OGF_BTSTACK 0x3d
71 #define OGF_VENDOR  0x3f
72 
73 // cmds for BTstack
74 // get state: @returns HCI_STATE
75 #define BTSTACK_GET_STATE                                  0x01
76 
77 // set power mode: @param HCI_POWER_MODE
78 #define BTSTACK_SET_POWER_MODE                             0x02
79 
80 // set capture mode: @param on
81 #define BTSTACK_SET_ACL_CAPTURE_MODE                       0x03
82 
83 // get BTstack version
84 #define BTSTACK_GET_VERSION                                0x04
85 
86 // get system Bluetooth state
87 #define BTSTACK_GET_SYSTEM_BLUETOOTH_ENABLED               0x05
88 
89 // set system Bluetooth state
90 #define BTSTACK_SET_SYSTEM_BLUETOOTH_ENABLED               0x06
91 
92 // enable inquiry scan for this client
93 #define BTSTACK_SET_DISCOVERABLE                           0x07
94 
95 // set global Bluetooth state
96 #define BTSTACK_SET_BLUETOOTH_ENABLED                      0x08
97 
98 // create l2cap channel: @param bd_addr(48), psm (16)
99 #define L2CAP_CREATE_CHANNEL                               0x20
100 
101 // disconnect l2cap disconnect, @param channel(16), reason(8)
102 #define L2CAP_DISCONNECT                                   0x21
103 
104 // register l2cap service: @param psm(16), mtu (16)
105 #define L2CAP_REGISTER_SERVICE                             0x22
106 
107 // unregister l2cap disconnect, @param psm(16)
108 #define L2CAP_UNREGISTER_SERVICE                           0x23
109 
110 // accept connection @param bd_addr(48), dest cid (16)
111 #define L2CAP_ACCEPT_CONNECTION                            0x24
112 
113 // decline l2cap disconnect,@param bd_addr(48), dest cid (16), reason(8)
114 #define L2CAP_DECLINE_CONNECTION                           0x25
115 
116 // create l2cap channel: @param bd_addr(48), psm (16), mtu (16)
117 #define L2CAP_CREATE_CHANNEL_MTU                           0x26
118 
119 // register SDP Service Record: service record (size)
120 #define SDP_REGISTER_SERVICE_RECORD                        0x30
121 
122 // unregister SDP Service Record
123 #define SDP_UNREGISTER_SERVICE_RECORD                      0x31
124 
125 // RFCOMM "HCI" Commands
126 #define RFCOMM_CREATE_CHANNEL       0x40
127 #define RFCOMM_DISCONNECT			0x41
128 #define RFCOMM_REGISTER_SERVICE     0x42
129 #define RFCOMM_UNREGISTER_SERVICE   0x43
130 #define RFCOMM_ACCEPT_CONNECTION    0x44
131 #define RFCOMM_DECLINE_CONNECTION   0x45
132 #define RFCOMM_PERSISTENT_CHANNEL   0x46
133 
134 //
135 #define IS_COMMAND(packet, command) (READ_BT_16(packet,0) == command.opcode)
136 
137 // data: event(8)
138 #define DAEMON_EVENT_CONNECTION_OPENED                     0x70
139 
140 // data: event(8)
141 #define DAEMON_EVENT_CONNECTION_CLOSED                     0x71
142 
143 // data: event(8), nr_connections(8)
144 #define DAEMON_NR_CONNECTIONS_CHANGED                      0x72
145 
146 
147 
148 /**
149  * Connection State
150  */
151 typedef enum {
152     RECV_LINK_KEY_REQUEST          = 0x01,
153     SENT_LINK_KEY_REPLY            = 0x02,
154     SENT_LINK_KEY_NEGATIVE_REQUEST = 0x04,
155     RECV_LINK_KEY_NOTIFICATION     = 0x08,
156     RECV_PIN_CODE_REQUEST          = 0x10,
157     SENT_PIN_CODE_REPLY            = 0x20,
158     SENT_PIN_CODE_NEGATIVE_REPLY   = 0x40
159 } hci_authentication_flags_t;
160 
161 typedef enum {
162     SENT_CREATE_CONNECTION = 1,
163     RECEIVED_CONNECTION_REQUEST,
164     ACCEPTED_CONNECTION_REQUEST,
165     REJECTED_CONNECTION_REQUEST,
166     OPEN,
167     SENT_DISCONNECT
168 } CONNECTION_STATE;
169 
170 typedef enum {
171     BLUETOOTH_OFF = 1,
172     BLUETOOTH_ON,
173     BLUETOOTH_ACTIVE
174 } BLUETOOTH_STATE;
175 
176 typedef struct {
177     // linked list - assert: first field
178     linked_item_t    item;
179 
180     // remote side
181     bd_addr_t address;
182 
183     // module handle
184     hci_con_handle_t con_handle;
185 
186     // state
187     CONNECTION_STATE state;
188 
189     // errands
190     hci_authentication_flags_t authentication_flags;
191 
192     // timer
193     timer_source_t timeout;
194     struct timeval timestamp;
195 
196     // ACL packet recombination
197     uint8_t  acl_recombination_buffer[HCI_ACL_3DH5_SIZE]; // max packet: DH5 = header(4) + payload (339)
198     uint16_t acl_recombination_pos;
199     uint16_t acl_recombination_length;
200 
201     // number ACL packets sent to controller
202     uint8_t num_acl_packets_sent;
203 
204 } hci_connection_t;
205 
206 /**
207  * main data structure
208  */
209 typedef struct {
210     // transport component with configuration
211     hci_transport_t  * hci_transport;
212     void             * config;
213 
214     // hardware power controller
215     bt_control_t     * control;
216 
217     // list of existing baseband connections
218     linked_list_t     connections;
219 
220     // single buffer for HCI Command assembly
221     uint8_t          * hci_cmd_buffer;
222 
223     /* host to controller flow control */
224     uint8_t  num_cmd_packets;
225     // uint8_t  total_num_cmd_packets;
226     uint8_t  total_num_acl_packets;
227     uint16_t acl_data_packet_length;
228 
229     /* callback to L2CAP layer */
230     void (*packet_handler)(uint8_t packet_type, uint8_t *packet, uint16_t size);
231 
232     /* remote device db */
233     remote_device_db_t *remote_device_db;
234 
235     /* hci state machine */
236     HCI_STATE state;
237     uint8_t   substate;
238     uint8_t   cmds_ready;
239 
240     /* */
241     uint8_t   discoverable;
242 
243 } hci_stack_t;
244 
245 // create and send hci command packets based on a template and a list of parameters
246 uint16_t hci_create_cmd(uint8_t *hci_cmd_buffer, hci_cmd_t *cmd, ...);
247 uint16_t hci_create_cmd_internal(uint8_t *hci_cmd_buffer, const hci_cmd_t *cmd, va_list argptr);
248 
249 // set up HCI
250 void hci_init(hci_transport_t *transport, void *config, bt_control_t *control, remote_device_db_t * remote_device_db);
251 void hci_register_packet_handler(void (*handler)(uint8_t packet_type, uint8_t *packet, uint16_t size));
252 void hci_close();
253 
254 // power and inquriy scan control
255 int hci_power_control(HCI_POWER_MODE mode);
256 void hci_discoverable_control(uint8_t enable);
257 
258 /**
259  * run the hci control loop once
260  */
261 void hci_run();
262 
263 // create and send hci command packets based on a template and a list of parameters
264 int hci_send_cmd(const hci_cmd_t *cmd, ...);
265 
266 // send complete CMD packet
267 int hci_send_cmd_packet(uint8_t *packet, int size);
268 
269 // send ACL packet
270 int hci_send_acl_packet(uint8_t *packet, int size);
271 
272 hci_connection_t * connection_for_handle(hci_con_handle_t con_handle);
273 uint8_t hci_number_outgoing_packets(hci_con_handle_t handle);
274 uint8_t hci_number_free_acl_slots();
275 int     hci_ready_to_send(hci_con_handle_t handle);
276 int     hci_authentication_active_for_handle(hci_con_handle_t handle);
277 void    hci_drop_link_key_for_bd_addr(bd_addr_t *addr);
278 uint16_t hci_max_acl_data_packet_length();
279 
280 //
281 void hci_emit_state();
282 void hci_emit_connection_complete(hci_connection_t *conn);
283 void hci_emit_l2cap_check_timeout(hci_connection_t *conn);
284 void hci_emit_disconnection_complete(uint16_t handle, uint8_t reason);
285 void hci_emit_nr_connections_changed();
286 void hci_emit_hci_open_failed();
287 void hci_emit_btstack_version();
288 void hci_emit_system_bluetooth_enabled(uint8_t enabled);
289 void hci_emit_remote_name_cached(bd_addr_t *addr, device_name_t *name);
290 void hci_emit_discoverable_enabled(uint8_t enabled);
291 
292 #if defined __cplusplus
293 }
294 #endif
295