385 lines
12 KiB
Groff
385 lines
12 KiB
Groff
.\" $NetBSD: bluetooth.9,v 1.6 2017/07/03 21:28:48 wiz 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 November 20, 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 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
|
|
.In netbt/hci.h
|
|
containing the driver information as follows:
|
|
.Bd -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
|
|
.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 initialized by the protocol layer before attaching to the
|
|
protocol which it uses:
|
|
.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 "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.
|
|
.Pp
|
|
.Fn hci_attach
|
|
will return a
|
|
.Fa struct hci_unit
|
|
handle to be passed to the protocol stack in other calls.
|
|
.It Fn hci_detach "unit"
|
|
Detach Bluetooth HCI
|
|
.Ar unit
|
|
from the device.
|
|
.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 ipl
|
|
value given in the
|
|
.Ar hci_if
|
|
descriptor.
|
|
.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 ipl
|
|
value given in the
|
|
.Ar hci_if
|
|
descriptor.
|
|
.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 ipl
|
|
value given in the
|
|
.Ar hci_if
|
|
descriptor.
|
|
.It Fn "(*enable)" "dev"
|
|
This will be called when the protocol stack wishes to enable the device.
|
|
.It Fn "(*disable)" "dev"
|
|
This will be called when the protocol stack wishes to disable the device.
|
|
.It 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.
|
|
.It 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.
|
|
.It 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.
|
|
.It 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
|
|
.Pp
|
|
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
|
|
.In netbt/btproto.h
|
|
file.
|
|
.Bl -tag -width XXXX
|
|
.It 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.
|
|
.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"
|
|
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.
|
|
.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 (e.g. 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
|
|
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.
|