xref: /btstack/src/l2cap.h (revision a4774f9a173f7ff3a51a68f73443dffeedefb670)
1 /*
2  * Copyright (C) 2009-2012 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  * 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 MATTHIAS RINGWALD 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 [email protected]
34  *
35  */
36 
37 /*
38  *  l2cap.h
39  *
40  *  Logical Link Control and Adaption Protocl (L2CAP)
41  *
42  *  Created by Matthias Ringwald on 5/16/09.
43  */
44 
45 #pragma once
46 
47 #include "hci.h"
48 #include "l2cap_signaling.h"
49 #include <btstack/utils.h>
50 #include <btstack/btstack.h>
51 
52 #if defined __cplusplus
53 extern "C" {
54 #endif
55 
56 #define L2CAP_SIG_ID_INVALID 0
57 
58 #define L2CAP_HEADER_SIZE 4
59 
60 // size of HCI ACL + L2CAP Header for regular data packets (8)
61 #define COMPLETE_L2CAP_HEADER (HCI_ACL_HEADER_SIZE + L2CAP_HEADER_SIZE)
62 
63 // minimum signaling MTU
64 #define L2CAP_MINIMAL_MTU 48
65 #define L2CAP_DEFAULT_MTU 672
66 
67 // check L2CAP MTU
68 #if (L2CAP_MINIMAL_MTU + L2CAP_HEADER_SIZE) > HCI_ACL_PAYLOAD_SIZE
69 #error "HCI_ACL_PAYLOAD_SIZE too small for minimal L2CAP MTU of 48 bytes"
70 #endif
71 
72 // L2CAP Fixed Channel IDs
73 #define L2CAP_CID_SIGNALING                 0x0001
74 #define L2CAP_CID_CONNECTIONLESS_CHANNEL    0x0002
75 #define L2CAP_CID_ATTRIBUTE_PROTOCOL        0x0004
76 #define L2CAP_CID_SIGNALING_LE              0x0005
77 #define L2CAP_CID_SECURITY_MANAGER_PROTOCOL 0x0006
78 
79 // L2CAP Configuration Result Codes
80 #define L2CAP_CONF_RESULT_UNKNOWN_OPTIONS   0x0003
81 
82 // L2CAP Reject Result Codes
83 #define L2CAP_REJ_CMD_UNKNOWN               0x0000
84 
85     // private structs
86 typedef enum {
87     L2CAP_STATE_CLOSED = 1,           // no baseband
88     L2CAP_STATE_WILL_SEND_CREATE_CONNECTION,
89     L2CAP_STATE_WAIT_CONNECTION_COMPLETE,
90     L2CAP_STATE_WAIT_CLIENT_ACCEPT_OR_REJECT,
91     L2CAP_STATE_WAIT_CONNECT_RSP, // from peer
92     L2CAP_STATE_CONFIG,
93     L2CAP_STATE_OPEN,
94     L2CAP_STATE_WAIT_DISCONNECT,  // from application
95     L2CAP_STATE_WILL_SEND_CONNECTION_REQUEST,
96     L2CAP_STATE_WILL_SEND_CONNECTION_RESPONSE_DECLINE,
97     L2CAP_STATE_WILL_SEND_CONNECTION_RESPONSE_ACCEPT,
98     L2CAP_STATE_WILL_SEND_DISCONNECT_REQUEST,
99     L2CAP_STATE_WILL_SEND_DISCONNECT_RESPONSE,
100 } L2CAP_STATE;
101 
102 typedef enum {
103     L2CAP_CHANNEL_STATE_VAR_NONE                  = 0,
104     L2CAP_CHANNEL_STATE_VAR_RCVD_CONF_REQ         = 1 << 0,
105     L2CAP_CHANNEL_STATE_VAR_RCVD_CONF_RSP         = 1 << 1,
106     L2CAP_CHANNEL_STATE_VAR_SEND_CONF_REQ         = 1 << 2,
107     L2CAP_CHANNEL_STATE_VAR_SEND_CONF_RSP         = 1 << 3,
108     L2CAP_CHANNEL_STATE_VAR_SENT_CONF_REQ         = 1 << 4,
109     L2CAP_CHANNEL_STATE_VAR_SENT_CONF_RSP         = 1 << 5,
110     L2CAP_CHANNEL_STATE_VAR_SEND_CONF_RSP_MTU     = 1 << 6,  // in CONF RSP, add MTU field
111     L2CAP_CHANNEL_STATE_VAR_SEND_CONF_RSP_CONT    = 1 << 7,  // in CONF RSP, set CONTINUE flag
112     L2CAP_CHANNEL_STATE_VAR_SEND_CONF_RSP_INVALID = 1 << 8,  // in CONF RSP, send UNKNOWN OPTIONS
113     L2CAP_CHANNEL_STATE_VAR_SEND_CMD_REJ_UNKNOWN  = 1 << 9,  // send CMD_REJ with reason unknown
114 } L2CAP_CHANNEL_STATE_VAR;
115 
116 // info regarding an actual coneection
117 typedef struct {
118     // linked list - assert: first field
119     linked_item_t    item;
120 
121     L2CAP_STATE state;
122     L2CAP_CHANNEL_STATE_VAR state_var;
123 
124     bd_addr_t address;
125     hci_con_handle_t handle;
126 
127     uint8_t   remote_sig_id;    // used by other side, needed for delayed response
128     uint8_t   local_sig_id;     // own signaling identifier
129 
130     uint16_t  local_cid;
131     uint16_t  remote_cid;
132 
133     uint16_t  local_mtu;
134     uint16_t  remote_mtu;
135 
136     uint16_t  psm;
137 
138     uint8_t   packets_granted;    // number of L2CAP/ACL packets client is allowed to send
139 
140     uint8_t   reason; // used in decline internal
141 
142     timer_source_t rtx; // also used for ertx
143 
144     // client connection
145     void * connection;
146 
147     // internal connection
148     btstack_packet_handler_t packet_handler;
149 
150 } l2cap_channel_t;
151 
152 // info regarding potential connections
153 typedef struct {
154     // linked list - assert: first field
155     linked_item_t    item;
156 
157     // service id
158     uint16_t  psm;
159 
160     // incoming MTU
161     uint16_t mtu;
162 
163     // client connection
164     void *connection;
165 
166     // internal connection
167     btstack_packet_handler_t packet_handler;
168 
169 } l2cap_service_t;
170 
171 
172 typedef struct l2cap_signaling_response {
173     hci_con_handle_t handle;
174     uint8_t  sig_id;
175     uint8_t  code;
176     uint16_t data; // infoType for INFORMATION REQUEST, result for CONNECTION request and command unknown
177 } l2cap_signaling_response_t;
178 
179 
180 void l2cap_block_new_credits(uint8_t blocked);
181 int  l2cap_can_send_packet_now(uint16_t local_cid);    // non-blocking UART write
182 
183 // get outgoing buffer and prepare data
184 uint8_t *l2cap_get_outgoing_buffer(void);
185 
186 int l2cap_send_prepared(uint16_t local_cid, uint16_t len);
187 
188 int l2cap_send_prepared_connectionless(uint16_t handle, uint16_t cid, uint16_t len);
189 
190 // Bluetooth 4.0 - allows to register handler for Attribute Protocol and Security Manager Protocol
191 void l2cap_register_fixed_channel(btstack_packet_handler_t packet_handler, uint16_t channel_id);
192 
193 uint16_t l2cap_max_mtu(void);
194 
195 int  l2cap_send_connectionless(uint16_t handle, uint16_t cid, uint8_t *data, uint16_t len);
196 
197 void l2cap_close_connection(void *connection);
198 
199 
200 /** Embedded API **/
201 
202 // Set up L2CAP and register L2CAP with HCI layer.
203 void l2cap_init(void);
204 
205 // Registers a packet handler that handles HCI and general BTstack events.
206 void l2cap_register_packet_handler(void (*handler)(void * connection, uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size));
207 
208 // Creates L2CAP channel to the PSM of a remote device with baseband address. A new baseband connection will be initiated if necessary.
209 void l2cap_create_channel_internal(void * connection, btstack_packet_handler_t packet_handler, bd_addr_t address, uint16_t psm, uint16_t mtu);
210 
211 // Disconencts L2CAP channel with given identifier.
212 void l2cap_disconnect_internal(uint16_t local_cid, uint8_t reason);
213 
214 // Queries the maximal transfer unit (MTU) for L2CAP channel with given identifier.
215 uint16_t l2cap_get_remote_mtu_for_local_cid(uint16_t local_cid);
216 
217 // Sends L2CAP data packet to the channel with given identifier.
218 int l2cap_send_internal(uint16_t local_cid, uint8_t *data, uint16_t len);
219 
220 // Registers L2CAP service with given PSM and MTU, and assigns a packet handler. On embedded systems, use NULL for connection parameter.
221 void l2cap_register_service_internal(void *connection, btstack_packet_handler_t packet_handler, uint16_t psm, uint16_t mtu);
222 
223 // Unregisters L2CAP service with given PSM.  On embedded systems, use NULL for connection parameter.
224 void l2cap_unregister_service_internal(void *connection, uint16_t psm);
225 
226 // Accepts/Deny incoming L2CAP connection.
227 void l2cap_accept_connection_internal(uint16_t local_cid);
228 void l2cap_decline_connection_internal(uint16_t local_cid, uint8_t reason);
229 
230 
231 #if defined __cplusplus
232 }
233 #endif
234