Copyright (c) 2006 Itronix Inc.
All rights reserved.
Written by Iain Hibbert for Itronix Inc.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. The name of Itronix Inc. may not be used to endorse
or promote products derived from this software without specific
prior written permission.
THIS SOFTWARE IS PROVIDED BY ITRONIX INC. ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ITRONIX INC. BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd November 20, 2007 .Dt BLUETOOTH 9 .Os .Sh NAME .Nm BLUETOOTH .Nd Bluetooth Device/Protocol API .Sh SYNOPSIS n netbt/bluetooth.h n netbt/hci.h n netbt/l2cap.h n netbt/rfcomm.h .Ft struct hci_unit * .Fn hci_attach "const struct hci_if *hci_if" "device_t dev" "uint16_t flags" .Ft void .Fn hci_detach "struct hci_unit *unit" .Ft void .Fn hci_input_event "struct hci_unit *unit" "struct mbuf *m" .Ft void .Fn hci_input_acl "struct hci_unit *unit" "struct mbuf *m" .Ft void .Fn hci_input_sco "struct hci_unit *unit" "struct mbuf *m" .Ft int .Fn btproto_attach "btproto_handle *" "const struct btproto *proto" "void *ref" .Ft int .Fn btproto_bind "btproto_handle" "struct sockaddr_bt *addr" .Ft int .Fn btproto_sockaddr "btproto_handle" "struct sockaddr_bt *addr" .Ft int .Fn btproto_connect "btproto_handle" "struct sockaddr_bt *addr" .Ft int .Fn btproto_peeraddr "btproto_handle" "struct sockaddr_bt *addr" .Ft int .Fn btproto_disconnect "btproto_handle" "int linger" .Ft int .Fn btproto_detach "btproto_handle *" .Ft int .Fn btproto_listen "btproto_handle" .Ft int .Fn btproto_send "btproto_handle" "struct mbuf *mbuf" .Ft int .Fn btproto_rcvd "btproto_handle" "size_t space" .Ft int .Fn btproto_setopt "btproto_handle" "int optarg" "void *arg" .Ft int .Fn btproto_getopt "btproto_handle" "int optarg" "void *arg" .Sh DESCRIPTION The Bluetooth Protocol Stack provides socket based access to Bluetooth Devices. This document describes device driver access to the stack from below, and also the general Bluetooth Protocol/Service API for layering above existing Bluetooth Protocols. .Sh DATA TYPES Device drivers attaching to the Bluetooth Protocol Stack should pass a pointer to a .Fa struct hci_if defined in n netbt/hci.h containing the driver information as follows: d -literal struct hci_if { int (*enable)(device_t); void (*disable)(device_t); void (*output_cmd)(device_t, struct mbuf *); void (*output_acl)(device_t, struct mbuf *); void (*output_sco)(device_t, struct mbuf *); void (*get_stats)(device_t, struct bt_stats *, int); int ipl; }; .Ed
p Statistics counters should be updated by the device after packets have been transmitted or received, or when errors occur. d -literal struct bt_stats { uint32_t err_tx; uint32_t err_rx; uint32_t cmd_tx; uint32_t evt_rx; uint32_t acl_tx; uint32_t acl_rx; uint32_t sco_tx; uint32_t sco_rx; uint32_t byte_tx; uint32_t byte_rx; }; .Ed
p Bluetooth Protocol layers attaching above the Bluetooth Protocol Stack will make use of the .Fa struct btproto data type, which is defined in n netbt/bluetooth.h and contains the following function callbacks which should be initialized by the protocol layer before attaching to the protocol which it uses: d -literal struct btproto { void (*connecting)(void *); void (*connected)(void *); void (*disconnected)(void *, int); void *(*newconn)(void *, struct sockaddr_bt *, struct sockaddr_bt *); void (*complete)(void *, int); void (*linkmode)(void *, int); void (*input)(void *, struct mbuf *); }; .Ed .Sh FUNCTIONS The following functions are related to the Bluetooth Device API. l -tag -width XXXX t Fn hci_attach "hci_if" "dev" Attach Bluetooth HCI device .Ar dev to the protocol stack in the manner described by .Ar hci_if . Driver quirks may be registered by passing the corresponding .Dv BTF_xxxx flag in the .Ar flags argument.
p .Fn hci_attach will return a .Fa struct hci_unit handle to be passed to the protocol stack in other calls. t Fn hci_detach "unit" Detach Bluetooth HCI .Ar unit from the device. t Fn hci_input_event "unit" "mbuf" This function should be called by the device when it has an event packet to present to the protocol stack. It may be called from an interrupt routine at the .Fa ipl value given in the .Ar hci_if descriptor. t Fn hci_input_acl "unit" "mbuf" This function should be called by the device when it has an ACL data packet to present to the protocol stack. It may be called from an interrupt routine at the .Fa ipl value given in the .Ar hci_if descriptor. t Fn hci_input_sco "unit" "mbuf" This function should be called by the device when it has an SCO data packet to present to the protocol stack. It may be called from an interrupt routine at the .Fa ipl value given in the .Ar hci_if descriptor. t Fn "(*enable)" "dev" This will be called when the protocol stack wishes to enable the device. t Fn "(*disable)" "dev" This will be called when the protocol stack wishes to disable the device. t Fn "(*output_cmd)" "dev" "mbuf" Will be called to output command packets on the device. The device is responsible for arbitrating access to the output queue, and output commands should be sent asynchronously. The device owns the .Ar mbuf and should release it when sent. t Fn "(*output_acl)" "dev" "mbuf" Will be called to output ACL data packets on the device. The device is responsible for arbitrating access to the output queue, and ACL data packets should be sent asynchronously. The device owns the .Ar mbuf and should release it when sent. t Fn "(*output_sco)" "dev" "mbuf" Will be called to output SCO data packets on the device. The device is responsible for arbitrating access to the output queue, and SCO data packets should be sent asynchronously. When the SCO data packet has been placed on the device and the .Ar mbuf is no longer required, it should be returned to the Bluetooth protocol stack via the .Fn hci_complete_sco call. t Fn "(*get_stats)" "dev" "dest" "flush" Will be called when IO statistics are requested. The .Fa bt_stats structure .Ar dest should be filled in, and if the .Ar flush argument is true, statistics should be reset. .El
p The following function definitions are related to the Bluetooth Protocol API. Note that the "btproto" prefix is representative only, the protocol being used will have a more specific prefix with prototypes being declared in the appropriate n netbt/btproto.h file. l -tag -width XXXX t Fn btproto_attach "handle_ptr" "proto" "ref" Allocate and initialize a new protocol object at the .Ar handle_ptr address that should subsequently be passed into the other functions. .Ar proto is a pointer to the .Fa btproto structure as described above containing relevant callbacks, and .Ar ref is the argument that will be supplied to those calls. t Fn btproto_bind "handle" "addr" Set the local address of the protocol object described by .Ar handle to .Ar addr . t Fn btproto_sockaddr "handle" "addr" Copy the local address of the protocol object described by .Ar handle into .Ar addr t Fn btproto_connect "handle" "addr" Initiate a connection by the protocol object described by .Ar handle to the remote device described by .Ar addr . This will result in a call to either .Fn proto->connected or .Fn proto->disconnected , and optionally .Fn proto->connecting with the appropriate reference as given to .Fn btproto_attach . t Fn btproto_peeraddr "handle" "addr" Copy the remote address of the protocol object described by .Ar handle into .Ar addr . t Fn btproto_disconnect "handle" "linger" Schedule a disconnection by the protocol object described by .Ar handle . This will result in a call to .Fn proto->disconnected with the appropriate reference when the connection is torn down. If linger is zero, the disconnection will be initiated immediately and any outstanding data may be lost. t Fn btproto_detach "handle_ptr" Detach the protocol object described by the value in the location of .Ar handle_ptr , and free any related memory. The pointer in the location is cleared. t Fn btproto_listen "handle" Use the protocol object described by .Ar handle as a listening post. This will result in calls to the .Fn proto->newconn function when incoming connections are detected. t Fn btproto_send "handle" "mbuf" Send data on the connection described by the protocol object. t Fn btproto_rcvd "handle" "space" Indicate to the protocol that .Ar space is now available in the input buffers so that flow control may be deasserted. This should also be called to indicate initial buffer space. Note that .Ar space is an absolute value. t Fn btproto_setopt "handle" "optarg" "arg" Set options on the protocol object described by .Ar handle . t Fn btproto_getopt "handle" "optarg" "arg" Get options for the protocol object described by .Ar handle . t Fn "(*connecting)" "ref" This function will be called when the protocol receives information that the connection described by .Ar ref is pending. t Fn "(*connected)" "ref" This function will be called when the connection described by .Ar ref is successful and indicates that data may now be sent. t Fn "(*disconnected)" "ref" "error" This function will be called when the connection described by .Ar ref is disconnected. t Fn "*(*newconn)" "ref" "laddr" "raddr" This function will be called when the protocol receives a new incoming connection on the local device described by .Ar laddr from the remote device described by .Ar raddr . The protocol should decide if it wishes to accept the connection and should attach and return a new instance of the relevant protocol handle or NULL. t Fn "(*complete)" "ref" "count" This function will be called when the protocol has completed sending data. Complete will usually mean that the data has successfully left the device though for guaranteed protocols it can mean that the data has arrived at the other end and been acknowledged, and that .Ar count amount of data can be removed from the socket buffer. The units of the .Ar count value will be dependent on the protocol being used (e.g. RFCOMM is bytes, but L2CAP is packets) t Fn "(*linkmode)" "ref" "mode" This function will be called for established connections, when the link mode of the baseband link has changed. .Ar mode is the new mode. t Fn "(*input)" "ref" "mbuf" This function is called to supply new data on the connection described by .Ar ref . .El .Sh CODE REFERENCES The Bluetooth Protocol Stack is contained in the
p The Bluetooth Device API as described above is contained in the
a sys/netbt/hci_unit.c file.
p For examples of the Bluetooth Protocol API see the interaction between the L2CAP upper layer in
a sys/netbt/l2cap_upper.c and either the L2CAP socket layer in
a sys/netbt/l2cap_socket.c or the .Xr bthidev 4 pseudo-device in
a sys/dev/bluetooth/bthidev.c .
p Also, the RFCOMM upper layer in
a sys/netbt/rfcomm_upper.c and the RFCOMM socket layer in
a sys/netbt/rfcomm_socket.c . .Sh SEE ALSO .Xr bluetooth 4 , .Xr bt3c 4 , .Xr bthidev 4 , .Xr ubt 4 .Sh HISTORY This Bluetooth Protocol Stack was written for .Nx 4.0 by .An Iain Hibbert , under the sponsorship of Itronix, Inc.
Indexes created Wed Sep 24 05:09:52 GMT 2025