1.\" $NetBSD: bluetooth.9,v 1.2 2007/04/21 06:15:22 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 April 10, 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 void 45.Fn hci_attach "struct hci_unit *unit" 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 79The Bluetooth Protocol Stack provides socket based access to Bluetooth 80Devices. This document describes device driver access to the stack from 81below, and also the general Bluetooth Protocol/Service API for layering 82above existing Bluetooth Protocols. 83.Sh DATA TYPES 84Device drivers attached to the Bluetooth Protocol Stack will make use of the 85.Fa struct hci_unit 86data type defined in 87.In netbt/hci.h 88.Pp 89This contains the following data items and function callbacks which 90should be initialised by the device before 91.Fn hci_attach 92is called: 93.Bd -literal 94 void *hci_softc; /* self reference */ 95 char *hci_devname; /* ->dv_xname */ 96 int hci_ipl; /* to block interrupts */ 97 int (*hci_enable)(struct hci_unit *); 98 void (*hci_disable)(struct hci_unit *); 99 void (*hci_start_cmd)(struct hci_unit *); 100 void (*hci_start_acl)(struct hci_unit *); 101 void (*hci_start_sco)(struct hci_unit *); 102.Ed 103.Pp 104and other items of interest that will be initialised by the protocol 105stack: 106.Bd -literal 107 uint16_t hci_flags; 108 MBUFQ_HEAD() hci_cmdq; 109 MBUFQ_HEAD() hci_acltxq; 110 MBUFQ_HEAD() hci_scotxq; 111 struct bt_stats hci_stats; 112.Ed 113.Pp 114Statistics counters should be updated by the device after packets have 115been transmitted or received, or when errors occur. 116.Bd -literal 117struct bt_stats { 118 uint32_t err_tx; 119 uint32_t err_rx; 120 uint32_t cmd_tx; 121 uint32_t evt_rx; 122 uint32_t acl_tx; 123 uint32_t acl_rx; 124 uint32_t sco_tx; 125 uint32_t sco_rx; 126 uint32_t byte_tx; 127 uint32_t byte_rx; 128}; 129.Ed 130.Pp 131Bluetooth Protocol layers attaching above the Bluetooth Protocol Stack 132will make use of the 133.Fa struct btproto 134data type, which is defined in 135.In netbt/bluetooth.h 136and contains the following function callbacks which 137should be initialised by the protocol layer before attaching to the 138protocol which it utilises: 139.Bd -literal 140struct btproto { 141 void (*connecting)(void *); 142 void (*connected)(void *); 143 void (*disconnected)(void *, int); 144 void *(*newconn)(void *, struct sockaddr_bt *, struct sockaddr_bt *); 145 void (*complete)(void *, int); 146 void (*linkmode)(void *, int); 147 void (*input)(void *, struct mbuf *); 148}; 149.Ed 150.Sh FUNCTIONS 151The following functions are related to the Bluetooth Device API. 152.Bl -tag -width XXXX 153.It Fn hci_attach "unit" 154Attach Bluetooth HCI device 155.Ar unit 156to the protocol stack. 157.It Fn hci_detach "unit" 158Detach Bluetooth HCI device 159.Ar unit 160from the protocol stack. 161.It Fn hci_input_event "unit" "mbuf" 162This function should be called by the device when it has an event 163packet to present to the protocol stack. It may be called from an 164interrupt routine at the 165.Fa hci_ipl 166value given above. 167.It Fn hci_input_acl "unit" "mbuf" 168This function should be called by the device when it has an ACL data 169packet to present to the protocol stack. It may be called from an 170interrupt routine at the 171.Fa hci_ipl 172value given above. 173.It Fn hci_input_sco "unit" "mbuf" 174This function should be called by the device when it has an SCO data 175packet to present to the protocol stack. It may be called from an 176interrupt routine at the 177.Fa hci_ipl 178value given above. 179.It Fn "(*hci_enable)" "unit" 180This will be called at the given 181.Fa hci_ipl 182level when the protocl stack wishes to enable the device. The driver should 183set the 184.Dv BTF_RUNNING 185flag in the unit structure. 186.It Fn "(*hci_disable)" "unit" 187This will be called at the given 188.Fa hci_ipl 189level when the protocol stack wishes to disable the device. The driver 190should clear the 191.Dv BTF_RUNNING 192flag in the unit structure. 193.It Fn "(*hci_start_cmd)" "unit" 194Will be called at the given 195.Fa hci_ipl 196level when command packets are available to be transmitted on the 197.Fa hci_cmdq 198queue in the 199.Fa hci_unit 200structure and the 201.Dv BTF_XMID_CMD 202flag is not set. The device should set 203.Dv BTF_XMIT_CMD 204and start sending command packets asyncrhonously until the queue 205is empty, then clear the 206.Dv BTF_XMIT_CMD 207flag and exit. 208.It Fn "(*hci_start_acl)" "unit" 209Will be called at the given 210.Fa hci_ipl 211level when ACL packets are available to be transmitted on the 212.Fa hci_acltxq 213queue in the 214.Fa hci_unit 215structure and the 216.Dv BTF_XMIT_ACL 217unit flag is not set. The device should set 218.Dv BTF_XMIT_ACL 219and start sending ACL packets asynchronously until the queue is empty, 220then clear the 221.Dv BTF_XMIT_ACL 222flag and exit. 223.It Fn "(*hci_start_sco)" "unit" 224Will be called at the given 225.Fa hci_ipl 226level when SCO packets are available to be transmitted on the 227.Fa hci_scotxq 228queue in the 229.Fa hci_unit 230structure and the 231.Dv BTF_XMIT_SCO 232flag is not set. The device should set the unit flag 233.Dv BTF_XMIT_SCO 234and start sending SCO packets asynchronously until the queue is empty, 235then clear the 236.Dv BTF_XMIT_SCO 237flag and exit. 238.El 239.Pp 240The following function definitions are related to the Bluetooth Protocol API. 241Note that the "btproto" prefix is representative only, the protocol being 242utilised will have a more specific prefix with prototypes being declared in 243the appropriate 244.In netbt/btproto.h 245file. 246.Bl -tag -width XXXX 247.It Fn btproto_attach "handle_ptr" "proto" "ref" 248Allocate and initialise a new protocol object at the 249.Ar handle_ptr 250address that should subsequently be passed into the other functions. 251.Ar proto 252is a pointer to the 253.Fa btproto 254structure as described above containing relevant callbacks, and 255.Ar ref 256is the argument that will be supplied to those calls. 257.It Fn btproto_bind "handle" "addr" 258Set the local address of the protocol object described by 259.Ar handle 260to 261.Ar addr . 262.It Fn btproto_sockaddr "handle" "addr" 263Copy the local address of the protocol object described by 264.Ar handle 265into 266.Ar addr 267.It Fn btproto_connect "handle" "addr" 268Initiate a connection by the protocol object described by 269.Ar handle 270to the remote device described by 271.Ar addr . 272This will result in a call to either 273.Fn proto->connected 274or 275.Fn proto->disconnected , 276and optionally 277.Fn proto->connecting 278with the appropriate reference as given to 279.Fn btproto_attach . 280.It Fn btproto_peeraddr "handle" "addr" 281Copy the remote address of the protocol object described by 282.Ar handle 283into 284.Ar addr . 285.It Fn btproto_disconnect "handle" "linger" 286Schedule a disconnection by the protocol object described by 287.Ar handle . 288This will result in a call to 289.Fn proto->disconnected 290with the appropriate reference when the connection is torn 291down. If linger is zero, the disconnection will be initiated 292immediately and any outstanding data may be lost. 293.It Fn btproto_detach "handle_ptr" 294Detach the protocol object described by the value in the location of 295.Ar handle_ptr , 296and free any related memory. The pointer in the location is cleared. 297.It Fn btproto_listen "handle" 298Utilise the protocol object described by 299.Ar handle 300as a listening post. This will result in calls to the 301.Fn proto->newconn 302function when incoming connections are detected. 303.It Fn btproto_send "handle" "mbuf" 304Send data on the connection described by the protocol object. 305.It Fn btproto_rcvd "handle" "space" 306Indicate to the protocol that 307.Ar space 308is now available in the input buffers so that flow control may be 309deasserted. This should also be called to indicate initial buffer 310space. Note that 311.Ar space 312is an absolute value. 313.It Fn btproto_setopt "handle" "optarg" "arg" 314Set options on the protocol object described by 315.Ar handle . 316.It Fn btproto_getopt "handle" "optarg" "arg" 317Get options for the protocol object described by 318.Ar handle . 319.It Fn "(*connecting)" "ref" 320This function will be called when the protocol receives information 321that the connection described by 322.Ar ref 323is pending. 324.It Fn "(*connected)" "ref" 325This function will be called when the connection described by 326.Ar ref 327is successful and indicates that data may now be sent. 328.It Fn "(*disconnected)" "ref" "error" 329This function will be called when the connection described by 330.Ar ref 331is disconnected. 332.It Fn "*(*newconn)" "ref" "laddr" "raddr" 333This function will be called when the protocol receives a new incoming 334connection on the local device described by 335.Ar laddr 336from the remote device described by 337.Ar raddr . 338The protocol should decide if it wishes to accept the connection and 339should attach and return a new instance of the relevant protocol handle 340or NULL. 341.It Fn "(*complete)" "ref" "count" 342This function will be called when the protocol has completed sending 343data. Complete will usually mean that the data has successfully left 344the device though for guaranteed protocols it can mean that the data 345has arrived at the other end and been acknowledged, and that 346.Ar count 347amount of data can be removed from the socket buffer. The units of the 348.Ar count 349value will be dependent on the protocol being used (eg RFCOMM is bytes, 350but L2CAP is packets) 351.It Fn "(*linkmode)" "ref" "mode" 352This function will be called for established connections, when the link mode 353of the baseband link has changed. 354.Ar mode 355is the new mode. 356.It Fn "(*input)" "ref" "mbuf" 357This function is called to supply new data on the connection described by 358.Ar ref . 359.El 360.Sh CODE REFERENCES 361This section describes places in the 362.Nx 363source tree where actual code implementing or using the 364Bluetooth Protocol Stack can be found. All pathnames are 365relative to 366.Pa /usr/src . 367.Pp 368The Bluetooth Protocol Stack is contained in the 369.Pa sys/netbt 370directory. 371.Pp 372The Bluetooth Device API as described above is contained 373in the 374.Pa sys/netbt/hci_unit.c 375file. 376.Pp 377For examples of the Bluetooth Protocol API see the interaction between 378the L2CAP upper layer in 379.Pa sys/netbt/l2cap_upper.c 380and either the L2CAP socket layer in 381.Pa sys/netbt/l2cap_socket.c 382or the 383.Xr bthidev 4 384pseudo-device in 385.Pa sys/dev/bluetooth/bthidev.c . 386.Pp 387Also, the RFCOMM upper layer in 388.Pa sys/netbt/rfcomm_upper.c 389and the RFCOMM socket layer in 390.Pa sys/netbt/rfcomm_socket.c . 391.Sh SEE ALSO 392.Xr bluetooth 4 , 393.Xr bt3c 4 , 394.Xr bthidev 4 , 395.Xr ubt 4 396.Sh HISTORY 397This Bluetooth Protocol Stack was written for 398.Nx 4.0 399by 400.An Iain Hibbert , 401under the sponsorship of Itronix, Inc. 402