| blob | 1b4e7cc153b880f7aa1d29a174cf4f49271aceeb |
1 .\" $NetBSD: bluetooth.9,v 1.3 2007/11/28 20:16:12 plunky Exp $
2 .\"
3 .\" Copyright (c) 2006 Itronix Inc.
4 .\" All rights reserved.
5 .\"
6 .\" Written by Iain Hibbert for Itronix Inc.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. The name of Itronix Inc. may not be used to endorse
17 .\" or promote products derived from this software without specific
18 .\" prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY ITRONIX INC. ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
22 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ITRONIX INC. BE LIABLE FOR ANY
24 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
25 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
27 .\" ON ANY THEORY OF LIABILITY, WHETHER IN
28 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30 .\" POSSIBILITY OF SUCH DAMAGE.
31 .\"
32 .\"
33 .Dd November 20, 2007
34 .Dt BLUETOOTH 9
35 .Os
36 .Sh NAME
37 .Nm BLUETOOTH
38 .Nd Bluetooth Device/Protocol API
39 .Sh SYNOPSIS
40 .In netbt/bluetooth.h
41 .In netbt/hci.h
42 .In netbt/l2cap.h
43 .In netbt/rfcomm.h
44 .Ft struct hci_unit *
45 .Fn hci_attach "const struct hci_if *hci_if" "device_t dev" "uint16_t flags"
46 .Ft void
47 .Fn hci_detach "struct hci_unit *unit"
48 .Ft void
49 .Fn hci_input_event "struct hci_unit *unit" "struct mbuf *m"
50 .Ft void
51 .Fn hci_input_acl "struct hci_unit *unit" "struct mbuf *m"
52 .Ft void
53 .Fn hci_input_sco "struct hci_unit *unit" "struct mbuf *m"
54 .Ft int
55 .Fn btproto_attach "btproto_handle *" "const struct btproto *proto" "void *ref"
56 .Ft int
57 .Fn btproto_bind "btproto_handle" "struct sockaddr_bt *addr"
58 .Ft int
59 .Fn btproto_sockaddr "btproto_handle" "struct sockaddr_bt *addr"
60 .Ft int
61 .Fn btproto_connect "btproto_handle" "struct sockaddr_bt *addr"
62 .Ft int
63 .Fn btproto_peeraddr "btproto_handle" "struct sockaddr_bt *addr"
64 .Ft int
65 .Fn btproto_disconnect "btproto_handle" "int linger"
66 .Ft int
67 .Fn btproto_detach "btproto_handle *"
68 .Ft int
69 .Fn btproto_listen "btproto_handle"
70 .Ft int
71 .Fn btproto_send "btproto_handle" "struct mbuf *mbuf"
72 .Ft int
73 .Fn btproto_rcvd "btproto_handle" "size_t space"
74 .Ft int
75 .Fn btproto_setopt "btproto_handle" "int optarg" "void *arg"
76 .Ft int
77 .Fn btproto_getopt "btproto_handle" "int optarg" "void *arg"
78 .Sh DESCRIPTION
79 The Bluetooth Protocol Stack provides socket based access to Bluetooth
80 Devices.
81 This document describes device driver access to the stack from
82 below, and also the general Bluetooth Protocol/Service API for layering
83 above existing Bluetooth Protocols.
84 .Sh DATA TYPES
85 Device drivers attaching to the Bluetooth Protocol Stack should pass a
86 pointer to a
87 .Fa struct hci_if
88 defined in
89 .In netbt/hci.h
90 containing the driver information as follows:
91 .Bd -literal
92 struct hci_if {
93 int (*enable)(device_t);
94 void (*disable)(device_t);
95 void (*output_cmd)(device_t, struct mbuf *);
96 void (*output_acl)(device_t, struct mbuf *);
97 void (*output_sco)(device_t, struct mbuf *);
98 void (*get_stats)(device_t, struct bt_stats *, int);
99 int ipl;
100 };
101 .Ed
102 .Pp
103 Statistics counters should be updated by the device after packets have
104 been transmitted or received, or when errors occur.
105 .Bd -literal
106 struct bt_stats {
107 uint32_t err_tx;
108 uint32_t err_rx;
109 uint32_t cmd_tx;
110 uint32_t evt_rx;
111 uint32_t acl_tx;
112 uint32_t acl_rx;
113 uint32_t sco_tx;
114 uint32_t sco_rx;
115 uint32_t byte_tx;
116 uint32_t byte_rx;
117 };
118 .Ed
119 .Pp
120 Bluetooth Protocol layers attaching above the Bluetooth Protocol Stack
121 will make use of the
122 .Fa struct btproto
123 data type, which is defined in
124 .In netbt/bluetooth.h
125 and contains the following function callbacks which
126 should be initialized by the protocol layer before attaching to the
127 protocol which it uses:
128 .Bd -literal
129 struct btproto {
130 void (*connecting)(void *);
131 void (*connected)(void *);
132 void (*disconnected)(void *, int);
133 void *(*newconn)(void *, struct sockaddr_bt *, struct sockaddr_bt *);
134 void (*complete)(void *, int);
135 void (*linkmode)(void *, int);
136 void (*input)(void *, struct mbuf *);
137 };
138 .Ed
139 .Sh FUNCTIONS
140 The following functions are related to the Bluetooth Device API.
141 .Bl -tag -width XXXX
142 .It Fn hci_attach "hci_if" "dev"
143 Attach Bluetooth HCI device
144 .Ar dev
145 to the protocol stack in the manner described by
146 .Ar hci_if .
147 Driver quirks may be registered by passing the corresponding
148 .Dv BTF_xxxx
149 flag in the
150 .Ar flags
151 argument.
152 .Pp
153 .Fn hci_attach
154 will return a
155 .Fa struct hci_unit
156 handle to be passed to the protocol stack in other calls.
157 .It Fn hci_detach "unit"
158 Detach Bluetooth HCI
159 .Ar unit
160 from the device.
161 .It Fn hci_input_event "unit" "mbuf"
162 This function should be called by the device when it has an event
163 packet to present to the protocol stack.
164 It may be called from an interrupt routine at the
165 .Fa ipl
166 value given in the
167 .Ar hci_if
168 descriptor.
169 .It Fn hci_input_acl "unit" "mbuf"
170 This function should be called by the device when it has an ACL data
171 packet to present to the protocol stack.
172 It may be called from an interrupt routine at the
173 .Fa ipl
174 value given in the
175 .Ar hci_if
176 descriptor.
177 .It Fn hci_input_sco "unit" "mbuf"
178 This function should be called by the device when it has an SCO data
179 packet to present to the protocol stack.
180 It may be called from an interrupt routine at the
181 .Fa ipl
182 value given in the
183 .Ar hci_if
184 descriptor.
185 .It Fn "(*enable)" "dev"
186 This will be called when the protocol stack wishes to enable the device.
187 .It Fn "(*disable)" "dev"
188 This will be called when the protocol stack wishes to disable the device.
189 .It Fn "(*output_cmd)" "dev" "mbuf"
190 Will be called to output command packets on the device.
191 The device is responsible for arbitrating access to the output queue, and
192 output commands should be sent asynchronously.
193 The device owns the
194 .Ar mbuf
195 and should release it when sent.
196 .It Fn "(*output_acl)" "dev" "mbuf"
197 Will be called to output ACL data packets on the device.
198 The device is responsible for arbitrating access to the output queue, and
199 ACL data packets should be sent asynchronously.
200 The device owns the
201 .Ar mbuf
202 and should release it when sent.
203 .It Fn "(*output_sco)" "dev" "mbuf"
204 Will be called to output SCO data packets on the device.
205 The device is responsible for arbitrating access to the output queue, and
206 SCO data packets should be sent asynchronously.
207 When the SCO data packet has been placed on the device and the
208 .Ar mbuf
209 is no longer required, it should be returned to the Bluetooth protocol
210 stack via the
211 .Fn hci_complete_sco
212 call.
213 .It Fn "(*get_stats)" "dev" "dest" "flush"
214 Will be called when IO statistics are requested.
215 The
216 .Fa bt_stats
217 structure
218 .Ar dest
219 should be filled in, and if the
220 .Ar flush
221 argument is true, statistics should be reset.
222 .El
223 .Pp
224 The following function definitions are related to the Bluetooth Protocol API.
225 Note that the "btproto" prefix is representative only, the protocol being
226 used will have a more specific prefix with prototypes being declared in
227 the appropriate
228 .In netbt/btproto.h
229 file.
230 .Bl -tag -width XXXX
231 .It Fn btproto_attach "handle_ptr" "proto" "ref"
232 Allocate and initialize a new protocol object at the
233 .Ar handle_ptr
234 address that should subsequently be passed into the other functions.
235 .Ar proto
236 is a pointer to the
237 .Fa btproto
238 structure as described above containing relevant callbacks, and
239 .Ar ref
240 is the argument that will be supplied to those calls.
241 .It Fn btproto_bind "handle" "addr"
242 Set the local address of the protocol object described by
243 .Ar handle
244 to
245 .Ar addr .
246 .It Fn btproto_sockaddr "handle" "addr"
247 Copy the local address of the protocol object described by
248 .Ar handle
249 into
250 .Ar addr
251 .It Fn btproto_connect "handle" "addr"
252 Initiate a connection by the protocol object described by
253 .Ar handle
254 to the remote device described by
255 .Ar addr .
256 This will result in a call to either
257 .Fn proto-\*[Gt]connected
258 or
259 .Fn proto-\*[Gt]disconnected ,
260 and optionally
261 .Fn proto-\*[Gt]connecting
262 with the appropriate reference as given to
263 .Fn btproto_attach .
264 .It Fn btproto_peeraddr "handle" "addr"
265 Copy the remote address of the protocol object described by
266 .Ar handle
267 into
268 .Ar addr .
269 .It Fn btproto_disconnect "handle" "linger"
270 Schedule a disconnection by the protocol object described by
271 .Ar handle .
272 This will result in a call to
273 .Fn proto-\*[Gt]disconnected
274 with the appropriate reference when the connection is torn
275 down.
276 If linger is zero, the disconnection will be initiated
277 immediately and any outstanding data may be lost.
278 .It Fn btproto_detach "handle_ptr"
279 Detach the protocol object described by the value in the location of
280 .Ar handle_ptr ,
281 and free any related memory.
282 The pointer in the location is cleared.
283 .It Fn btproto_listen "handle"
284 Use the protocol object described by
285 .Ar handle
286 as a listening post.
287 This will result in calls to the
288 .Fn proto-\*[Gt]newconn
289 function when incoming connections are detected.
290 .It Fn btproto_send "handle" "mbuf"
291 Send data on the connection described by the protocol object.
292 .It Fn btproto_rcvd "handle" "space"
293 Indicate to the protocol that
294 .Ar space
295 is now available in the input buffers so that flow control may be
296 deasserted.
297 This should also be called to indicate initial buffer space.
298 Note that
299 .Ar space
300 is an absolute value.
301 .It Fn btproto_setopt "handle" "optarg" "arg"
302 Set options on the protocol object described by
303 .Ar handle .
304 .It Fn btproto_getopt "handle" "optarg" "arg"
305 Get options for the protocol object described by
306 .Ar handle .
307 .It Fn "(*connecting)" "ref"
308 This function will be called when the protocol receives information
309 that the connection described by
310 .Ar ref
311 is pending.
312 .It Fn "(*connected)" "ref"
313 This function will be called when the connection described by
314 .Ar ref
315 is successful and indicates that data may now be sent.
316 .It Fn "(*disconnected)" "ref" "error"
317 This function will be called when the connection described by
318 .Ar ref
319 is disconnected.
320 .It Fn "*(*newconn)" "ref" "laddr" "raddr"
321 This function will be called when the protocol receives a new incoming
322 connection on the local device described by
323 .Ar laddr
324 from the remote device described by
325 .Ar raddr .
326 The protocol should decide if it wishes to accept the connection and
327 should attach and return a new instance of the relevant protocol handle
328 or NULL.
329 .It Fn "(*complete)" "ref" "count"
330 This function will be called when the protocol has completed sending
331 data.
332 Complete will usually mean that the data has successfully left
333 the device though for guaranteed protocols it can mean that the data
334 has arrived at the other end and been acknowledged, and that
335 .Ar count
336 amount of data can be removed from the socket buffer.
337 The units of the
338 .Ar count
339 value will be dependent on the protocol being used (e.g. RFCOMM is bytes,
340 but L2CAP is packets)
341 .It Fn "(*linkmode)" "ref" "mode"
342 This function will be called for established connections, when the link mode
343 of the baseband link has changed.
344 .Ar mode
345 is the new mode.
346 .It Fn "(*input)" "ref" "mbuf"
347 This function is called to supply new data on the connection described by
348 .Ar ref .
349 .El
350 .Sh CODE REFERENCES
351 This section describes places in the
352 .Nx
353 source tree where actual code implementing or using the
354 Bluetooth Protocol Stack can be found.
355 All pathnames are relative to
356 .Pa /usr/src .
357 .Pp
358 The Bluetooth Protocol Stack is contained in the
359 .Pa sys/netbt
360 directory.
361 .Pp
362 The Bluetooth Device API as described above is contained
363 in the
364 .Pa sys/netbt/hci_unit.c
365 file.
366 .Pp
367 For examples of the Bluetooth Protocol API see the interaction between
368 the L2CAP upper layer in
369 .Pa sys/netbt/l2cap_upper.c
370 and either the L2CAP socket layer in
371 .Pa sys/netbt/l2cap_socket.c
372 or the
373 .Xr bthidev 4
374 pseudo-device in
375 .Pa sys/dev/bluetooth/bthidev.c .
376 .Pp
377 Also, the RFCOMM upper layer in
378 .Pa sys/netbt/rfcomm_upper.c
379 and the RFCOMM socket layer in
380 .Pa sys/netbt/rfcomm_socket.c .
381 .Sh SEE ALSO
382 .Xr bluetooth 4 ,
383 .Xr bt3c 4 ,
384 .Xr bthidev 4 ,
385 .Xr ubt 4
386 .Sh HISTORY
387 This Bluetooth Protocol Stack was written for
388 .Nx 4.0
389 by
390 .An Iain Hibbert ,
391 under the sponsorship of Itronix, Inc.