402 lines
12 KiB
Groff
402 lines
12 KiB
Groff
.\" $NetBSD: bluetooth.9,v 1.2 2007/04/21 06:15:22 plunky Exp $
|
|
.\"
|
|
.\" 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 April 10, 2007
|
|
.Dt BLUETOOTH 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm BLUETOOTH
|
|
.Nd Bluetooth Device/Protocol API
|
|
.Sh SYNOPSIS
|
|
.In netbt/bluetooth.h
|
|
.In netbt/hci.h
|
|
.In netbt/l2cap.h
|
|
.In netbt/rfcomm.h
|
|
.Ft void
|
|
.Fn hci_attach "struct hci_unit *unit"
|
|
.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 attached to the Bluetooth Protocol Stack will make use of the
|
|
.Fa struct hci_unit
|
|
data type defined in
|
|
.In netbt/hci.h
|
|
.Pp
|
|
This contains the following data items and function callbacks which
|
|
should be initialised by the device before
|
|
.Fn hci_attach
|
|
is called:
|
|
.Bd -literal
|
|
void *hci_softc; /* self reference */
|
|
char *hci_devname; /* ->dv_xname */
|
|
int hci_ipl; /* to block interrupts */
|
|
int (*hci_enable)(struct hci_unit *);
|
|
void (*hci_disable)(struct hci_unit *);
|
|
void (*hci_start_cmd)(struct hci_unit *);
|
|
void (*hci_start_acl)(struct hci_unit *);
|
|
void (*hci_start_sco)(struct hci_unit *);
|
|
.Ed
|
|
.Pp
|
|
and other items of interest that will be initialised by the protocol
|
|
stack:
|
|
.Bd -literal
|
|
uint16_t hci_flags;
|
|
MBUFQ_HEAD() hci_cmdq;
|
|
MBUFQ_HEAD() hci_acltxq;
|
|
MBUFQ_HEAD() hci_scotxq;
|
|
struct bt_stats hci_stats;
|
|
.Ed
|
|
.Pp
|
|
Statistics counters should be updated by the device after packets have
|
|
been transmitted or received, or when errors occur.
|
|
.Bd -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
|
|
.Pp
|
|
Bluetooth Protocol layers attaching above the Bluetooth Protocol Stack
|
|
will make use of the
|
|
.Fa struct btproto
|
|
data type, which is defined in
|
|
.In netbt/bluetooth.h
|
|
and contains the following function callbacks which
|
|
should be initialised by the protocol layer before attaching to the
|
|
protocol which it utilises:
|
|
.Bd -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.
|
|
.Bl -tag -width XXXX
|
|
.It Fn hci_attach "unit"
|
|
Attach Bluetooth HCI device
|
|
.Ar unit
|
|
to the protocol stack.
|
|
.It Fn hci_detach "unit"
|
|
Detach Bluetooth HCI device
|
|
.Ar unit
|
|
from the protocol stack.
|
|
.It 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 hci_ipl
|
|
value given above.
|
|
.It 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 hci_ipl
|
|
value given above.
|
|
.It 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 hci_ipl
|
|
value given above.
|
|
.It Fn "(*hci_enable)" "unit"
|
|
This will be called at the given
|
|
.Fa hci_ipl
|
|
level when the protocl stack wishes to enable the device. The driver should
|
|
set the
|
|
.Dv BTF_RUNNING
|
|
flag in the unit structure.
|
|
.It Fn "(*hci_disable)" "unit"
|
|
This will be called at the given
|
|
.Fa hci_ipl
|
|
level when the protocol stack wishes to disable the device. The driver
|
|
should clear the
|
|
.Dv BTF_RUNNING
|
|
flag in the unit structure.
|
|
.It Fn "(*hci_start_cmd)" "unit"
|
|
Will be called at the given
|
|
.Fa hci_ipl
|
|
level when command packets are available to be transmitted on the
|
|
.Fa hci_cmdq
|
|
queue in the
|
|
.Fa hci_unit
|
|
structure and the
|
|
.Dv BTF_XMID_CMD
|
|
flag is not set. The device should set
|
|
.Dv BTF_XMIT_CMD
|
|
and start sending command packets asyncrhonously until the queue
|
|
is empty, then clear the
|
|
.Dv BTF_XMIT_CMD
|
|
flag and exit.
|
|
.It Fn "(*hci_start_acl)" "unit"
|
|
Will be called at the given
|
|
.Fa hci_ipl
|
|
level when ACL packets are available to be transmitted on the
|
|
.Fa hci_acltxq
|
|
queue in the
|
|
.Fa hci_unit
|
|
structure and the
|
|
.Dv BTF_XMIT_ACL
|
|
unit flag is not set. The device should set
|
|
.Dv BTF_XMIT_ACL
|
|
and start sending ACL packets asynchronously until the queue is empty,
|
|
then clear the
|
|
.Dv BTF_XMIT_ACL
|
|
flag and exit.
|
|
.It Fn "(*hci_start_sco)" "unit"
|
|
Will be called at the given
|
|
.Fa hci_ipl
|
|
level when SCO packets are available to be transmitted on the
|
|
.Fa hci_scotxq
|
|
queue in the
|
|
.Fa hci_unit
|
|
structure and the
|
|
.Dv BTF_XMIT_SCO
|
|
flag is not set. The device should set the unit flag
|
|
.Dv BTF_XMIT_SCO
|
|
and start sending SCO packets asynchronously until the queue is empty,
|
|
then clear the
|
|
.Dv BTF_XMIT_SCO
|
|
flag and exit.
|
|
.El
|
|
.Pp
|
|
The following function definitions are related to the Bluetooth Protocol API.
|
|
Note that the "btproto" prefix is representative only, the protocol being
|
|
utilised will have a more specific prefix with prototypes being declared in
|
|
the appropriate
|
|
.In netbt/btproto.h
|
|
file.
|
|
.Bl -tag -width XXXX
|
|
.It Fn btproto_attach "handle_ptr" "proto" "ref"
|
|
Allocate and initialise 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.
|
|
.It Fn btproto_bind "handle" "addr"
|
|
Set the local address of the protocol object described by
|
|
.Ar handle
|
|
to
|
|
.Ar addr .
|
|
.It Fn btproto_sockaddr "handle" "addr"
|
|
Copy the local address of the protocol object described by
|
|
.Ar handle
|
|
into
|
|
.Ar addr
|
|
.It 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 .
|
|
.It Fn btproto_peeraddr "handle" "addr"
|
|
Copy the remote address of the protocol object described by
|
|
.Ar handle
|
|
into
|
|
.Ar addr .
|
|
.It 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.
|
|
.It 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.
|
|
.It Fn btproto_listen "handle"
|
|
Utilise 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.
|
|
.It Fn btproto_send "handle" "mbuf"
|
|
Send data on the connection described by the protocol object.
|
|
.It 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.
|
|
.It Fn btproto_setopt "handle" "optarg" "arg"
|
|
Set options on the protocol object described by
|
|
.Ar handle .
|
|
.It Fn btproto_getopt "handle" "optarg" "arg"
|
|
Get options for the protocol object described by
|
|
.Ar handle .
|
|
.It Fn "(*connecting)" "ref"
|
|
This function will be called when the protocol receives information
|
|
that the connection described by
|
|
.Ar ref
|
|
is pending.
|
|
.It 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.
|
|
.It Fn "(*disconnected)" "ref" "error"
|
|
This function will be called when the connection described by
|
|
.Ar ref
|
|
is disconnected.
|
|
.It 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.
|
|
.It 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 (eg RFCOMM is bytes,
|
|
but L2CAP is packets)
|
|
.It 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.
|
|
.It Fn "(*input)" "ref" "mbuf"
|
|
This function is called to supply new data on the connection described by
|
|
.Ar ref .
|
|
.El
|
|
.Sh CODE REFERENCES
|
|
This section describes places in the
|
|
.Nx
|
|
source tree where actual code implementing or using the
|
|
Bluetooth Protocol Stack can be found. All pathnames are
|
|
relative to
|
|
.Pa /usr/src .
|
|
.Pp
|
|
The Bluetooth Protocol Stack is contained in the
|
|
.Pa sys/netbt
|
|
directory.
|
|
.Pp
|
|
The Bluetooth Device API as described above is contained
|
|
in the
|
|
.Pa sys/netbt/hci_unit.c
|
|
file.
|
|
.Pp
|
|
For examples of the Bluetooth Protocol API see the interaction between
|
|
the L2CAP upper layer in
|
|
.Pa sys/netbt/l2cap_upper.c
|
|
and either the L2CAP socket layer in
|
|
.Pa sys/netbt/l2cap_socket.c
|
|
or the
|
|
.Xr bthidev 4
|
|
pseudo-device in
|
|
.Pa sys/dev/bluetooth/bthidev.c .
|
|
.Pp
|
|
Also, the RFCOMM upper layer in
|
|
.Pa sys/netbt/rfcomm_upper.c
|
|
and the RFCOMM socket layer in
|
|
.Pa 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.
|