1.\" $NetBSD: bluetooth.9,v 1.1 2006/06/19 15:44:44 gdamore 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 March 4, 2006 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 (*input)(void *, struct mbuf *); 147}; 148.Ed 149.Sh FUNCTIONS 150The following functions are related to the Bluetooth Device API. 151.Bl -tag -width XXXX 152.It Fn hci_attach "unit" 153Attach Bluetooth HCI device 154.Ar unit 155to the protocol stack. 156.It Fn hci_detach "unit" 157Detach Bluetooth HCI device 158.Ar unit 159from the protocol stack. 160.It Fn hci_input_event "unit" "mbuf" 161This function should be called by the device when it has an event 162packet to present to the protocol stack. It may be called from an 163interrupt routine at the 164.Fa hci_ipl 165value given above. 166.It Fn hci_input_acl "unit" "mbuf" 167This function should be called by the device when it has an ACL data 168packet to present to the protocol stack. It may be called from an 169interrupt routine at the 170.Fa hci_ipl 171value given above. 172.It Fn hci_input_sco "unit" "mbuf" 173This function should be called by the device when it has an SCO data 174packet to present to the protocol stack. It may be called from an 175interrupt routine at the 176.Fa hci_ipl 177value given above. 178.It Fn "(*hci_enable)" "unit" 179This will be called at the given 180.Fa hci_ipl 181level when the protocl stack wishes to enable the device. The driver should 182set the 183.Dv BTF_RUNNING 184flag in the unit structure. 185.It Fn "(*hci_disable)" "unit" 186This will be called at the given 187.Fa hci_ipl 188level when the protocol stack wishes to disable the device. The driver 189should clear the 190.Dv BTF_RUNNING 191flag in the unit structure. 192.It Fn "(*hci_start_cmd)" "unit" 193Will be called at the given 194.Fa hci_ipl 195level when command packets are available to be transmitted on the 196.Fa hci_cmdq 197queue in the 198.Fa hci_unit 199structure and the 200.Dv BTF_XMID_CMD 201flag is not set. The device should set 202.Dv BTF_XMIT_CMD 203and start sending command packets asyncrhonously until the queue 204is empty, then clear the 205.Dv BTF_XMIT_CMD 206flag and exit. 207.It Fn "(*hci_start_acl)" "unit" 208Will be called at the given 209.Fa hci_ipl 210level when ACL packets are available to be transmitted on the 211.Fa hci_acltxq 212queue in the 213.Fa hci_unit 214structure and the 215.Dv BTF_XMIT_ACL 216unit flag is not set. The device should set 217.Dv BTF_XMIT_ACL 218and start sending ACL packets asynchronously until the queue is empty, 219then clear the 220.Dv BTF_XMIT_ACL 221flag and exit. 222.It Fn "(*hci_start_sco)" "unit" 223Will be called at the given 224.Fa hci_ipl 225level when SCO packets are available to be transmitted on the 226.Fa hci_scotxq 227queue in the 228.Fa hci_unit 229structure and the 230.Dv BTF_XMIT_SCO 231flag is not set. The device should set the unit flag 232.Dv BTF_XMIT_SCO 233and start sending SCO packets asynchronously until the queue is empty, 234then clear the 235.Dv BTF_XMIT_SCO 236flag and exit. 237.El 238.Pp 239The following function definitions are related to the Bluetooth Protocol API. 240Note that the "btproto" prefix is representative only, the protocol being 241utilised will have a more specific prefix with prototypes being declared in 242the appropriate 243.In netbt/btproto.h 244file. 245.Bl -tag -width XXXX 246.It Fn btproto_attach "handle_ptr" "proto" "ref" 247Allocate and initialise a new protocol object at the 248.Ar handle_ptr 249address that should subsequently be passed into the other functions. 250.Ar proto 251is a pointer to the 252.Fa btproto 253structure as described above containing relevant callbacks, and 254.Ar ref 255is the argument that will be supplied to those calls. 256.It Fn btproto_bind "handle" "addr" 257Set the local address of the protocol object described by 258.Ar handle 259to 260.Ar addr . 261.It Fn btproto_sockaddr "handle" "addr" 262Copy the local address of the protocol object described by 263.Ar handle 264into 265.Ar addr 266.It Fn btproto_connect "handle" "addr" 267Initiate a connection by the protocol object described by 268.Ar handle 269to the remote device described by 270.Ar addr . 271This will result in a call to either 272.Fn proto->connected 273or 274.Fn proto->disconnected , 275and optionally 276.Fn proto->connecting 277with the appropriate reference as given to 278.Fn btproto_attach . 279.It Fn btproto_peeraddr "handle" "addr" 280Copy the remote address of the protocol object described by 281.Ar handle 282into 283.Ar addr . 284.It Fn btproto_disconnect "handle" "linger" 285Schedule a disconnection by the protocol object described by 286.Ar handle . 287This will result in a call to 288.Fn proto->disconnected 289with the appropriate reference when the connection is torn 290down. If linger is zero, the disconnection will be initiated 291immediately and any outstanding data may be lost. 292.It Fn btproto_detach "handle_ptr" 293Detach the protocol object described by the value in the location of 294.Ar handle_ptr , 295and free any related memory. The pointer in the location is cleared. 296.It Fn btproto_listen "handle" 297Utilise the protocol object described by 298.Ar handle 299as a listening post. This will result in calls to the 300.Fn proto->newconn 301function when incoming connections are detected. 302.It Fn btproto_send "handle" "mbuf" 303Send data on the connection described by the protocol object. 304.It Fn btproto_rcvd "handle" "space" 305Indicate to the protocol that 306.Ar space 307is now available in the input buffers so that flow control may be 308deasserted. This should also be called to indicate initial buffer 309space. Note that 310.Ar space 311is an absolute value. 312.It Fn btproto_setopt "handle" "optarg" "arg" 313Set options on the protocol object described by 314.Ar handle . 315.It Fn btproto_getopt "handle" "optarg" "arg" 316Get options for the protocol object described by 317.Ar handle . 318.It Fn "(*connecting)" "ref" 319This function will be called when the protocol receives information 320that the connection described by 321.Ar ref 322is pending. 323.It Fn "(*connected)" "ref" 324This function will be called when the connection described by 325.Ar ref 326is successful and indicates that data may now be sent. 327.It Fn "(*disconnected)" "ref" "error" 328This function will be called when the connection described by 329.Ar ref 330is disconnected. 331.It Fn "*(*newconn)" "ref" "laddr" "raddr" 332This function will be called when the protocol receives a new incoming 333connection on the local device described by 334.Ar laddr 335from the remote device described by 336.Ar raddr . 337The protocol should decide if it wishes to accept the connection and 338should attach and return a new instance of the relevant protocol handle 339or NULL. 340.It Fn "(*complete)" "ref" "count" 341This function will be called when the protocol has completed sending 342data. Complete will usually mean that the data has successfully left 343the device though for guaranteed protocols it can mean that the data 344has arrived at the other end and been acknowledged, and that 345.Ar count 346amount of data can be removed from the socket buffer. The units of the 347.Ar count 348value will be dependent on the protocol being used (eg RFCOMM is bytes, 349but L2CAP is packets) 350.It Fn "(*input)" "ref" "mbuf" 351This function is called to supply new data on the connection described by 352.Ar ref . 353.El 354.Sh CODE REFERENCES 355This section describes places in the 356.Nx 357source tree where actual code implementing or using the 358Bluetooth Protocol Stack can be found. All pathnames are 359relative to 360.Pa /usr/src . 361.Pp 362The Bluetooth Protocol Stack is contained in the 363.Pa sys/netbt 364directory. 365.Pp 366The Bluetooth Device API as described above is contained 367in the 368.Pa sys/netbt/hci_unit.c 369file. 370.Pp 371For examples of the Bluetooth Protocol API see the interaction between 372the L2CAP upper layer in 373.Pa sys/netbt/l2cap_upper.c 374and either the L2CAP socket layer in 375.Pa sys/netbt/l2cap_socket.c 376or the 377.Xr bthidev 4 378pseudo-device in 379.Pa sys/dev/bluetooth/bthidev.c . 380.Pp 381Also, the RFCOMM upper layer in 382.Pa sys/netbt/rfcomm_upper.c 383and the RFCOMM socket layer in 384.Pa sys/netbt/rfcomm_socket.c . 385.Sh SEE ALSO 386.Xr bluetooth 4 , 387.Xr bt3c 4 , 388.Xr bthidev 4 , 389.Xr ubt 4 390.Sh HISTORY 391This Bluetooth Protocol Stack was written for 392.Nx 4.0 393by 394.An Iain Hibbert , 395under the sponsorship of Itronix, Inc. 396