xref: /btstack/src/hci.h (revision e3b6fe7eb191043b15a822b25050d4d9db7db00f)
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 // create l2cap channel: @param bd_addr(48), psm (16)
93 #define L2CAP_CREATE_CHANNEL                               0x20
94 
95 // disconnect l2cap disconnect, @param channel(16), reason(8)
96 #define L2CAP_DISCONNECT                                   0x21
97 
98 // register l2cap service: @param psm(16), mtu (16)
99 #define L2CAP_REGISTER_SERVICE                             0x22
100 
101 // unregister l2cap disconnect, @param psm(16)
102 #define L2CAP_UNREGISTER_SERVICE                           0x23
103 
104 // accept connection @param bd_addr(48), dest cid (16)
105 #define L2CAP_ACCEPT_CONNECTION                            0x24
106 
107 // decline l2cap disconnect,@param bd_addr(48), dest cid (16), reason(8)
108 #define L2CAP_DECLINE_CONNECTION                           0x25
109 
110 // create l2cap channel: @param bd_addr(48), psm (16), mtu (16)
111 #define L2CAP_CREATE_CHANNEL_MTU                           0x26
112 
113 // register SDP Service Record: service record (size)
114 #define SDP_REGISTER_SERVICE_RECORD                        0x30
115 
116 // unregister SDP Service Record
117 #define SDP_UNREGISTER_SERVICE_RECORD                      0x31
118 
119 
120 
121 //
122 #define IS_COMMAND(packet, command) (READ_BT_16(packet,0) == command.opcode)
123 
124 // data: event(8)
125 #define DAEMON_EVENT_CONNECTION_CLOSED                     0x70
126 
127 // data: event(8), nr_connections(8)
128 #define DAEMON_NR_CONNECTIONS_CHANGED                      0x71
129 
130 
131 /**
132  * Connection State
133  */
134 typedef enum {
135     RECV_LINK_KEY_REQUEST          = 0x01,
136     SENT_LINK_KEY_REPLY            = 0x02,
137     SENT_LINK_KEY_NEGATIVE_REQUEST = 0x04,
138     RECV_LINK_KEY_NOTIFICATION     = 0x08,
139     RECV_PIN_CODE_REQUEST          = 0x10,
140     SENT_PIN_CODE_REPLY            = 0x20,
141     SENT_PIN_CODE_NEGATIVE_REPLY   = 0x40
142 } hci_authentication_flags_t;
143 
144 typedef enum {
145     SENT_CREATE_CONNECTION = 1,
146     RECEIVED_CONNECTION_REQUEST,
147     ACCEPTED_CONNECTION_REQUEST,
148     REJECTED_CONNECTION_REQUEST,
149     OPEN,
150     SENT_DISCONNECT
151 } CONNECTION_STATE;
152 
153 typedef enum {
154     BLUETOOTH_OFF = 1,
155     BLUETOOTH_ON,
156     BLUETOOTH_ACTIVE
157 } BLUETOOTH_STATE;
158 
159 typedef struct {
160     // linked list - assert: first field
161     linked_item_t    item;
162 
163     // remote side
164     bd_addr_t address;
165 
166     // module handle
167     hci_con_handle_t con_handle;
168 
169     // state
170     CONNECTION_STATE state;
171 
172     // errands
173     hci_authentication_flags_t authentication_flags;
174 
175     // timer
176     timer_source_t timeout;
177     struct timeval timestamp;
178 
179     // ACL packet recombination
180     uint8_t  acl_recombination_buffer[HCI_ACL_3DH5_SIZE]; // max packet: DH5 = header(4) + payload (339)
181     uint16_t acl_recombination_pos;
182     uint16_t acl_recombination_length;
183 
184     // number ACL packets sent to controller
185     uint8_t num_acl_packets_sent;
186 
187 } hci_connection_t;
188 
189 /**
190  * main data structure
191  */
192 typedef struct {
193     // transport component with configuration
194     hci_transport_t  * hci_transport;
195     void             * config;
196 
197     // hardware power controller
198     bt_control_t     * control;
199 
200     // list of existing baseband connections
201     linked_list_t     connections;
202 
203     // single buffer for HCI Command assembly
204     uint8_t          * hci_cmd_buffer;
205 
206     /* host to controller flow control */
207     uint8_t  num_cmd_packets;
208     // uint8_t  total_num_cmd_packets;
209     uint8_t  total_num_acl_packets;
210     uint16_t acl_data_packet_length;
211 
212     /* callback to L2CAP layer */
213     void (*packet_handler)(uint8_t packet_type, uint8_t *packet, uint16_t size);
214 
215     /* remote device db */
216     remote_device_db_t *remote_device_db;
217 
218     /* hci state machine */
219     HCI_STATE state;
220     uint8_t   substate;
221     uint8_t   cmds_ready;
222 
223 } hci_stack_t;
224 
225 // create and send hci command packets based on a template and a list of parameters
226 uint16_t hci_create_cmd(uint8_t *hci_cmd_buffer, hci_cmd_t *cmd, ...);
227 uint16_t hci_create_cmd_internal(uint8_t *hci_cmd_buffer, const hci_cmd_t *cmd, va_list argptr);
228 
229 // set up HCI
230 void hci_init(hci_transport_t *transport, void *config, bt_control_t *control, remote_device_db_t * remote_device_db);
231 void hci_register_packet_handler(void (*handler)(uint8_t packet_type, uint8_t *packet, uint16_t size));
232 void hci_close();
233 
234 // power control
235 int hci_power_control(HCI_POWER_MODE mode);
236 
237 /**
238  * run the hci control loop once
239  */
240 void hci_run();
241 
242 // create and send hci command packets based on a template and a list of parameters
243 int hci_send_cmd(const hci_cmd_t *cmd, ...);
244 
245 // send complete CMD packet
246 int hci_send_cmd_packet(uint8_t *packet, int size);
247 
248 // send ACL packet
249 int hci_send_acl_packet(uint8_t *packet, int size);
250 
251 hci_connection_t * connection_for_handle(hci_con_handle_t con_handle);
252 uint8_t hci_number_outgoing_packets(hci_con_handle_t handle);
253 uint8_t hci_number_free_acl_slots();
254 int     hci_ready_to_send(hci_con_handle_t handle);
255 int     hci_authentication_active_for_handle(hci_con_handle_t handle);
256 void    hci_drop_link_key_for_bd_addr(bd_addr_t *addr);
257 uint16_t hci_max_acl_data_packet_length();
258 
259 //
260 void hci_emit_state();
261 void hci_emit_connection_complete(hci_connection_t *conn);
262 void hci_emit_l2cap_check_timeout(hci_connection_t *conn);
263 void hci_emit_nr_connections_changed();
264 void hci_emit_hci_open_failed();
265 void hci_emit_btstack_version();
266 void hci_emit_system_bluetooth_enabled(uint8_t enabled);
267 void hci_emit_remote_name_cached(bd_addr_t *addr, device_name_t *name);
268 
269 #if defined __cplusplus
270 }
271 #endif
272