1.\" $NetBSD: bluetooth.9,v 1.6 2017/07/03 21:28:48 wiz 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 79The Bluetooth Protocol Stack provides socket based access to Bluetooth 80Devices. 81This document describes device driver access to the stack from 82below, and also the general Bluetooth Protocol/Service API for layering 83above existing Bluetooth Protocols. 84.Sh DATA TYPES 85Device drivers attaching to the Bluetooth Protocol Stack should pass a 86pointer to a 87.Fa struct hci_if 88defined in 89.In netbt/hci.h 90containing the driver information as follows: 91.Bd -literal 92struct 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 103Statistics counters should be updated by the device after packets have 104been transmitted or received, or when errors occur. 105.Bd -literal 106struct 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 120Bluetooth Protocol layers attaching above the Bluetooth Protocol Stack 121will make use of the 122.Fa struct btproto 123data type, which is defined in 124.In netbt/bluetooth.h 125and contains the following function callbacks which 126should be initialized by the protocol layer before attaching to the 127protocol which it uses: 128.Bd -literal 129struct 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 140The following functions are related to the Bluetooth Device API. 141.Bl -tag -width XXXX 142.It Fn hci_attach "hci_if" "dev" 143Attach Bluetooth HCI device 144.Ar dev 145to the protocol stack in the manner described by 146.Ar hci_if . 147Driver quirks may be registered by passing the corresponding 148.Dv BTF_xxxx 149flag in the 150.Ar flags 151argument. 152.Pp 153.Fn hci_attach 154will return a 155.Fa struct hci_unit 156handle to be passed to the protocol stack in other calls. 157.It Fn hci_detach "unit" 158Detach Bluetooth HCI 159.Ar unit 160from the device. 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. 164It may be called from an interrupt routine at the 165.Fa ipl 166value given in the 167.Ar hci_if 168descriptor. 169.It Fn hci_input_acl "unit" "mbuf" 170This function should be called by the device when it has an ACL data 171packet to present to the protocol stack. 172It may be called from an interrupt routine at the 173.Fa ipl 174value given in the 175.Ar hci_if 176descriptor. 177.It Fn hci_input_sco "unit" "mbuf" 178This function should be called by the device when it has an SCO data 179packet to present to the protocol stack. 180It may be called from an interrupt routine at the 181.Fa ipl 182value given in the 183.Ar hci_if 184descriptor. 185.It Fn "(*enable)" "dev" 186This will be called when the protocol stack wishes to enable the device. 187.It Fn "(*disable)" "dev" 188This will be called when the protocol stack wishes to disable the device. 189.It Fn "(*output_cmd)" "dev" "mbuf" 190Will be called to output command packets on the device. 191The device is responsible for arbitrating access to the output queue, and 192output commands should be sent asynchronously. 193The device owns the 194.Ar mbuf 195and should release it when sent. 196.It Fn "(*output_acl)" "dev" "mbuf" 197Will be called to output ACL data packets on the device. 198The device is responsible for arbitrating access to the output queue, and 199ACL data packets should be sent asynchronously. 200The device owns the 201.Ar mbuf 202and should release it when sent. 203.It Fn "(*output_sco)" "dev" "mbuf" 204Will be called to output SCO data packets on the device. 205The device is responsible for arbitrating access to the output queue, and 206SCO data packets should be sent asynchronously. 207When the SCO data packet has been placed on the device and the 208.Ar mbuf 209is no longer required, it should be returned to the Bluetooth protocol 210stack via the 211.Fn hci_complete_sco 212call. 213.It Fn "(*get_stats)" "dev" "dest" "flush" 214Will be called when IO statistics are requested. 215The 216.Fa bt_stats 217structure 218.Ar dest 219should be filled in, and if the 220.Ar flush 221argument is true, statistics should be reset. 222.El 223.Pp 224The following function definitions are related to the Bluetooth Protocol API. 225Note that the "btproto" prefix is representative only, the protocol being 226used will have a more specific prefix with prototypes being declared in 227the appropriate 228.In netbt/btproto.h 229file. 230.Bl -tag -width XXXX 231.It Fn btproto_attach "handle_ptr" "proto" "ref" 232Allocate and initialize a new protocol object at the 233.Ar handle_ptr 234address that should subsequently be passed into the other functions. 235.Ar proto 236is a pointer to the 237.Fa btproto 238structure as described above containing relevant callbacks, and 239.Ar ref 240is the argument that will be supplied to those calls. 241.It Fn btproto_bind "handle" "addr" 242Set the local address of the protocol object described by 243.Ar handle 244to 245.Ar addr . 246.It Fn btproto_sockaddr "handle" "addr" 247Copy the local address of the protocol object described by 248.Ar handle 249into 250.Ar addr 251.It Fn btproto_connect "handle" "addr" 252Initiate a connection by the protocol object described by 253.Ar handle 254to the remote device described by 255.Ar addr . 256This will result in a call to either 257.Fn proto->connected 258or 259.Fn proto->disconnected , 260and optionally 261.Fn proto->connecting 262with the appropriate reference as given to 263.Fn btproto_attach . 264.It Fn btproto_peeraddr "handle" "addr" 265Copy the remote address of the protocol object described by 266.Ar handle 267into 268.Ar addr . 269.It Fn btproto_disconnect "handle" "linger" 270Schedule a disconnection by the protocol object described by 271.Ar handle . 272This will result in a call to 273.Fn proto->disconnected 274with the appropriate reference when the connection is torn 275down. 276If linger is zero, the disconnection will be initiated 277immediately and any outstanding data may be lost. 278.It Fn btproto_detach "handle_ptr" 279Detach the protocol object described by the value in the location of 280.Ar handle_ptr , 281and free any related memory. 282The pointer in the location is cleared. 283.It Fn btproto_listen "handle" 284Use the protocol object described by 285.Ar handle 286as a listening post. 287This will result in calls to the 288.Fn proto->newconn 289function when incoming connections are detected. 290.It Fn btproto_send "handle" "mbuf" 291Send data on the connection described by the protocol object. 292.It Fn btproto_rcvd "handle" "space" 293Indicate to the protocol that 294.Ar space 295is now available in the input buffers so that flow control may be 296deasserted. 297This should also be called to indicate initial buffer space. 298Note that 299.Ar space 300is an absolute value. 301.It Fn btproto_setopt "handle" "optarg" "arg" 302Set options on the protocol object described by 303.Ar handle . 304.It Fn btproto_getopt "handle" "optarg" "arg" 305Get options for the protocol object described by 306.Ar handle . 307.It Fn "(*connecting)" "ref" 308This function will be called when the protocol receives information 309that the connection described by 310.Ar ref 311is pending. 312.It Fn "(*connected)" "ref" 313This function will be called when the connection described by 314.Ar ref 315is successful and indicates that data may now be sent. 316.It Fn "(*disconnected)" "ref" "error" 317This function will be called when the connection described by 318.Ar ref 319is disconnected. 320.It Fn "*(*newconn)" "ref" "laddr" "raddr" 321This function will be called when the protocol receives a new incoming 322connection on the local device described by 323.Ar laddr 324from the remote device described by 325.Ar raddr . 326The protocol should decide if it wishes to accept the connection and 327should attach and return a new instance of the relevant protocol handle 328or NULL. 329.It Fn "(*complete)" "ref" "count" 330This function will be called when the protocol has completed sending 331data. 332Complete will usually mean that the data has successfully left 333the device though for guaranteed protocols it can mean that the data 334has arrived at the other end and been acknowledged, and that 335.Ar count 336amount of data can be removed from the socket buffer. 337The units of the 338.Ar count 339value will be dependent on the protocol being used (e.g. RFCOMM is bytes, 340but L2CAP is packets) 341.It Fn "(*linkmode)" "ref" "mode" 342This function will be called for established connections, when the link mode 343of the baseband link has changed. 344.Ar mode 345is the new mode. 346.It Fn "(*input)" "ref" "mbuf" 347This function is called to supply new data on the connection described by 348.Ar ref . 349.El 350.Sh CODE REFERENCES 351The Bluetooth Protocol Stack is contained in the 352.Pa sys/netbt 353directory. 354.Pp 355The Bluetooth Device API as described above is contained 356in the 357.Pa sys/netbt/hci_unit.c 358file. 359.Pp 360For examples of the Bluetooth Protocol API see the interaction between 361the L2CAP upper layer in 362.Pa sys/netbt/l2cap_upper.c 363and either the L2CAP socket layer in 364.Pa sys/netbt/l2cap_socket.c 365or the 366.Xr bthidev 4 367pseudo-device in 368.Pa sys/dev/bluetooth/bthidev.c . 369.Pp 370Also, the RFCOMM upper layer in 371.Pa sys/netbt/rfcomm_upper.c 372and the RFCOMM socket layer in 373.Pa sys/netbt/rfcomm_socket.c . 374.Sh SEE ALSO 375.Xr bluetooth 4 , 376.Xr bt3c 4 , 377.Xr bthidev 4 , 378.Xr ubt 4 379.Sh HISTORY 380This Bluetooth Protocol Stack was written for 381.Nx 4.0 382by 383.An Iain Hibbert , 384under the sponsorship of Itronix, Inc. 385