.\"	$NetBSD: bluetooth.9,v 1.1 2006/06/19 15:44:44 gdamore 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 March 4, 2006
.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 (*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 "(*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.