Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


BLUETOOTH(9)               Kernel Developer's Manual              BLUETOOTH(9)

NAME
     BLUETOOTH - Bluetooth Device/Protocol API

SYNOPSIS
     #include <netbt/bluetooth.h>
     #include <netbt/hci.h>
     #include <netbt/l2cap.h>
     #include <netbt/rfcomm.h>

     struct hci_unit *
     hci_attach(const struct hci_if *hci_if, device_t dev, uint16_t flags);

     void
     hci_detach(struct hci_unit *unit);

     void
     hci_input_event(struct hci_unit *unit, struct mbuf *m);

     void
     hci_input_acl(struct hci_unit *unit, struct mbuf *m);

     void
     hci_input_sco(struct hci_unit *unit, struct mbuf *m);

     int
     btproto_attach(btproto_handle *, const struct btproto *proto, void *ref);

     int
     btproto_bind(btproto_handle, struct sockaddr_bt *addr);

     int
     btproto_sockaddr(btproto_handle, struct sockaddr_bt *addr);

     int
     btproto_connect(btproto_handle, struct sockaddr_bt *addr);

     int
     btproto_peeraddr(btproto_handle, struct sockaddr_bt *addr);

     int
     btproto_disconnect(btproto_handle, int linger);

     int
     btproto_detach(btproto_handle *);

     int
     btproto_listen(btproto_handle);

     int
     btproto_send(btproto_handle, struct mbuf *mbuf);

     int
     btproto_rcvd(btproto_handle, size_t space);

     int
     btproto_setopt(btproto_handle, int optarg, void *arg);

     int
     btproto_getopt(btproto_handle, int optarg, void *arg);

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.

DATA TYPES
     Device drivers attaching to the Bluetooth Protocol Stack should pass a
     pointer to a struct hci_if defined in <netbt/hci.h> containing the driver
     information as follows:

     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;
     };

     Statistics counters should be updated by the device after packets have
     been transmitted or received, or when errors occur.

     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;
     };

     Bluetooth Protocol layers attaching above the Bluetooth Protocol Stack
     will make use of the struct btproto data type, which is defined 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:

     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 *);
     };

FUNCTIONS
     The following functions are related to the Bluetooth Device API.

     hci_attach(hci_if, dev)
           Attach Bluetooth HCI device dev to the protocol stack in the manner
           described by hci_if.  Driver quirks may be registered by passing
           the corresponding BTF_xxxx flag in the flags argument.

           hci_attach() will return a struct hci_unit handle to be passed to
           the protocol stack in other calls.

     hci_detach(unit)
           Detach Bluetooth HCI unit from the device.

     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 ipl value given in the hci_if descriptor.

     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 ipl value given in the hci_if
           descriptor.

     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 ipl value given in the hci_if
           descriptor.

     (*enable)(dev)
           This will be called when the protocol stack wishes to enable the
           device.

     (*disable)(dev)
           This will be called when the protocol stack wishes to disable the
           device.

     (*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
           mbuf and should release it when sent.

     (*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 mbuf and should release it when sent.

     (*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 mbuf is no longer
           required, it should be returned to the Bluetooth protocol stack via
           the hci_complete_sco() call.

     (*get_stats)(dev, dest, flush)
           Will be called when IO statistics are requested.  The bt_stats
           structure dest should be filled in, and if the flush argument is
           true, statistics should be reset.

     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 <netbt/btproto.h> file.

     btproto_attach(handle_ptr, proto, ref)
           Allocate and initialize a new protocol object at the handle_ptr
           address that should subsequently be passed into the other
           functions.  proto is a pointer to the btproto structure as
           described above containing relevant callbacks, and ref is the
           argument that will be supplied to those calls.

     btproto_bind(handle, addr)
           Set the local address of the protocol object described by handle to
           addr.

     btproto_sockaddr(handle, addr)
           Copy the local address of the protocol object described by handle
           into addr

     btproto_connect(handle, addr)
           Initiate a connection by the protocol object described by handle to
           the remote device described by addr.  This will result in a call to
           either proto->connected() or proto->disconnected(), and optionally
           proto->connecting() with the appropriate reference as given to
           btproto_attach().

     btproto_peeraddr(handle, addr)
           Copy the remote address of the protocol object described by handle
           into addr.

     btproto_disconnect(handle, linger)
           Schedule a disconnection by the protocol object described by
           handle.  This will result in a call to 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.

     btproto_detach(handle_ptr)
           Detach the protocol object described by the value in the location
           of handle_ptr, and free any related memory.  The pointer in the
           location is cleared.

     btproto_listen(handle)
           Use the protocol object described by handle as a listening post.
           This will result in calls to the proto->newconn() function when
           incoming connections are detected.

     btproto_send(handle, mbuf)
           Send data on the connection described by the protocol object.

     btproto_rcvd(handle, space)
           Indicate to the protocol that 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 space is an
           absolute value.

     btproto_setopt(handle, optarg, arg)
           Set options on the protocol object described by handle.

     btproto_getopt(handle, optarg, arg)
           Get options for the protocol object described by handle.

     (*connecting)(ref)
           This function will be called when the protocol receives information
           that the connection described by ref is pending.

     (*connected)(ref)
           This function will be called when the connection described by ref
           is successful and indicates that data may now be sent.

     (*disconnected)(ref, error)
           This function will be called when the connection described by ref
           is disconnected.

     *(*newconn)(ref, laddr, raddr)
           This function will be called when the protocol receives a new
           incoming connection on the local device described by laddr from the
           remote device described by 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.

     (*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 count amount of data can be removed from the
           socket buffer.  The units of the count value will be dependent on
           the protocol being used (e.g. RFCOMM is bytes, but L2CAP is
           packets)

     (*linkmode)(ref, mode)
           This function will be called for established connections, when the
           link mode of the baseband link has changed.  mode is the new mode.

     (*input)(ref, mbuf)
           This function is called to supply new data on the connection
           described by ref.

CODE REFERENCES
     The Bluetooth Protocol Stack is contained in the sys/netbt directory.

     The Bluetooth Device API as described above is contained in the
     sys/netbt/hci_unit.c file.

     For examples of the Bluetooth Protocol API see the interaction between
     the L2CAP upper layer in sys/netbt/l2cap_upper.c and either the L2CAP
     socket layer in sys/netbt/l2cap_socket.c or the bthidev(4) pseudo-device
     in sys/dev/bluetooth/bthidev.c.

     Also, the RFCOMM upper layer in sys/netbt/rfcomm_upper.c and the RFCOMM
     socket layer in sys/netbt/rfcomm_socket.c.

SEE ALSO
     bluetooth(4), bt3c(4), bthidev(4), ubt(4)

HISTORY
     This Bluetooth Protocol Stack was written for NetBSD 4.0 by Iain Hibbert,
     under the sponsorship of Itronix, Inc.

NetBSD 10.99                   November 20, 2007                  NetBSD 10.99