ng_hci(4)

NAME

ng_hci - Netgraph node type that is also a Bluetooth Host

Controller
Interface (HCI) layer

SYNOPSIS

#include <sys/types.h>
#include <netgraph/bluetooth/include/ng_hci.h>

DESCRIPTION

The hci node type is a Netgraph node type that implements

Bluetooth Host
Controller Interface (HCI) layer as per chapter H1 of the

Bluetooth Specification Book v1.1.

INTRODUCTION TO BLUETOOTH

Bluetooth is a short-range radio link intended to replace

the cable(s)
connecting portable and/or fixed electronic devices. Blue

tooth operates
in the unlicensed ISM band at 2.4 GHz. The Bluetooth proto

col uses a
combination of circuit and packet switching. Bluetooth can

support an
asynchronous data channel, up to three simultaneous syn

chronous voice
channels, or a channel which simultaneously supports asyn

chronous data
and synchronous voice. Each voice channel supports a 64

kb/s synchronous
(voice) channel in each direction. The asynchronous channel

can support
maximal 723.2 kb/s asymmetric (and still up to 57.6 kb/s in

the return
direction), or 433.9 kb/s symmetric.

The Bluetooth system provides a point-to-point connection

(only two Bluetooth units involved), or a point-to-multipoint connection.

In the
point-to-multipoint connection, the channel is shared among

several Bluetooth units. Two or more units sharing the same channel

form a
``piconet''. One Bluetooth unit acts as the master of the

piconet,
whereas the other unit(s) acts as slave(s). Up to seven

slaves can be
active in the piconet. In addition, many more slaves can

remain locked
to the master in a so-called parked state. These parked

slaves cannot be
active on the channel, but remain synchronized to the mas

ter. Both for
active and parked slaves, the channel access is controlled

by the master.

Multiple piconets with overlapping coverage areas form a

``scatternet''.
Each piconet can only have a single master. However, slaves

can participate in different piconets on a time-division multiplex ba

sis. In addition, a master in one piconet can be a slave in another pi

conet. The
piconets shall not be frequency-synchronized. Each piconet

has its own
hopping channel.

Time Slots

The channel is divided into time slots, each 625 usec in

length. The
time slots are numbered according to the Bluetooth clock of

the piconet
master. The slot numbering ranges from 0 to 2^27 -1 and is

cyclic with a
cycle length of 2^27. In the time slots, master and slave

can transmit
packets.

SCO Link

The SCO link is a symmetric, point-to-point link between the

master and a
specific slave. The SCO link reserves slots and can there

fore be considered as a circuit-switched connection between the master and

the slave.
The SCO link typically supports time-bounded information

like voice. The
master can support up to three SCO links to the same slave

or to different slaves. A slave can support up to three SCO links from

the same master, or two SCO links if the links originate from different

masters. SCO
packets are never retransmitted.

ACL Link

In the slots not reserved for SCO links, the master can ex

change packets
with any slave on a per-slot basis. The ACL link provides a

packetswitched connection between the master and all active slaves

participating in the piconet. Both asynchronous and isochronous ser

vices are supported. Between a master and a slave only a single ACL link

can exist.
For most ACL packets, packet retransmission is applied to

assure data
integrity.

HOST CONTROLLER INTERFACE (HCI)

The HCI provides a command interface to the baseband con

troller and link
manager, and access to hardware status and control regis

ters. This
interface provides a uniform method of accessing the Blue

tooth baseband
capabilities.

The HCI layer on the Host exchanges data and commands with

the HCI
firmware on the Bluetooth hardware. The Host Controller

Transport Layer
(i.e., physical bus) driver provides both HCI layers with

the ability to
exchange information with each other.

The Host will receive asynchronous notifications of HCI

events independent of which Host Controller Transport Layer is used. HCI

events are
used for notifying the Host when something occurs. When the

Host discovers that an event has occurred it will then parse the re

ceived event
packet to determine which event occurred. The next sections

specify the
HCI packet formats.

HCI Command Packet

#define NG_HCI_CMD_PKT 0x01
typedef struct {

u_int8_t type; /* MUST be 0x1 */
u_int16_t opcode; /* OpCode */
u_int8_t length; /* parameter(s) length in

bytes */

} __attribute__ ((packed)) ng_hci_cmd_pkt_t;

The HCI command packet is used to send commands to the Host

Controller
from the Host. When the Host Controller completes most of

the commands,
a Command Complete event is sent to the Host. Some commands

do not
receive a Command Complete event when they have been com

pleted. Instead,
when the Host Controller receives one of these commands the

Host Controller sends a Command Status event back to the Host when

it has begun
to execute the command. Later on, when the actions associ

ated with the
command have finished, an event that is associated with the

sent command
will be sent by the Host Controller to the Host.

HCI Event Packet

#define NG_HCI_EVENT_PKT 0x04
typedef struct {

u_int8_t type; /* MUST be 0x4 */
u_int8_t event; /* event */
u_int8_t length; /* parameter(s) length in

bytes */

} __attribute__ ((packed)) ng_hci_event_pkt_t;

The HCI event packet is used by the Host Controller to noti

fy the Host
when events occur.

HCI ACL Data Packet

#define NG_HCI_ACL_DATA_PKT 0x02
typedef struct {

u_int8_t type; /* MUST be 0x2 */
u_int16_t con_handle; /* connection handle +

PB + BC flags */
u_int16_t length; /* payload length in

bytes */

} __attribute__ ((packed)) ng_hci_acldata_pkt_t;

HCI ACL data packets are used to exchange ACL data between

the Host and
Host Controller.

HCI SCO Data Packet

#define NG_HCI_SCO_DATA_PKT 0x03
typedef struct {

u_int8_t type; /* MUST be 0x3 */
u_int16_t con_handle; /* connection handle +

reserved bits */
u_int8_t length; /* payload length in

bytes */

} __attribute__ ((packed)) ng_hci_scodata_pkt_t;

HCI SCO data packets are used to exchange SCO data between

the Host and
Host Controller.

HCI INITIALIZATION

On initialization, HCI control application must issue the

following HCI
commands (in any order).

Read_BD_ADDR

To obtain BD_ADDR of the Bluetooth unit.

Read_Local_Supported_Features

To obtain the list of features supported by Blue

tooth unit.

Read_Buffer_Size

To determine the maximum size of HCI ACL and SCO HCI

data packets
(excluding header) that can be sent from the Host to

the Host
Controller. There are also two additional return

parameters that
specify the total number of HCI ACL and SCO data

packets that the
Host Controller can have waiting for transmission in

its buffers.

As soon as HCI initialization has been successfully per

formed, HCI control application must turn on ``inited'' bit for the node.

Once HCI node
has been initialized all upstream hooks will receive a

NGM_HCI_NODE_UP
Netgraph message defined as follows.

#define NGM_HCI_NODE_UP 112 /* HCI -> Upper */
typedef struct {

u_int16_t pkt_size; /* max. ACL/SCO packet

size (w/o hdr) */
u_int16_t num_pkts; /* ACL/SCO packet queue

size */
u_int16_t reserved; /* place holder */
bdaddr_t bdaddr; /* bdaddr */

} ng_hci_node_up_ep;

HCI FLOW CONTROL

HCI layer performs flow control on baseband connection basis

(i.e., ACL
and SCO link). Each baseband connection has ``connection

handle'' and
queue of outgoing data packets. Upper layers protocols are

allowed to
send up to (num_pkts - pending) packets at one time. HCI

layer will send
NGM_HCI_SYNC_CON_QUEUE Netgraph messages to inform upper

layers about
current queue state for each connection handle. The
NGM_HCI_SYNC_CON_QUEUE Netgraph message is defined as fol

lows.

#define NGM_HCI_SYNC_CON_QUEUE 113 /* HCI -> Upper */
typedef struct {

u_int16_t con_handle; /* connection handle */
u_int16_t completed; /* number of completed

packets */

} ng_hci_sync_con_queue_ep;

HOOKS

This node type supports the following hooks:

drv Bluetooth Host Controller Transport Layer hook.

Single HCI

packet contained in single mbuf structure.

acl Upper layer protocol/node is connected to the hook.

Single HCI

ACL data packet contained in single mbuf structure.

sco Upper layer protocol/node is connected to the hook.

Single HCI

SCO data packet contained in single mbuf structure.

raw Raw hook. Every HCI frame (including HCI command

frame) that

goes in or out will be delivered to the hook. Usu

ally the Bluetooth raw HCI socket layer is connected to the hook.

Single HCI
frame contained in single mbuf structure.

BLUETOOTH UPPER LAYER PROTOCOLS INTERFACE (LP CONTROL MESSAGES)

NGM_HCI_LP_CON_REQ

Requests the lower protocol to create a connection.

If a physical link to the remote device does not exist, this

message must
be sent to the lower protocol (baseband) to estab

lish the physical connection.

NGM_HCI_LP_DISCON_REQ

Requests the lower protocol (baseband) to terminate

a connection.

NGM_HCI_LP_CON_CFM

Confirms success or failure of the

NGM_HCI_LP_CON_REQ request to
establish a lower layer (baseband) connection. This

includes
passing the authentication challenge if authentica

tion is
required to establish the physical link.

NGM_HCI_LP_CON_IND

Indicates the lower protocol (baseband) has success

fully established incoming connection.

NGM_HCI_LP_CON_RSP

A response accepting or rejecting the previous con

nection indication request.

NGM_HCI_LP_DISCON_IND

Indicates the lower protocol (baseband) has termi

nated connection. This could be a response to NGM_HCI_LP_DIS

CON_REQ or a
timeout event.

NGM_HCI_LP_QOS_REQ

Requests the lower protocol (baseband) to accommo

date a particular QoS parameter set.

NGM_HCI_LP_QOS_CFM

Confirms success or failure of the request for a

given quality of
service.

NGM_HCI_LP_QOS_IND

Indicates the lower protocol (baseband) has detected

a violation
of the QoS agreement.

NETGRAPH CONTROL MESSAGES

This node type supports the generic control messages, plus

the following:

NGM_HCI_NODE_GET_STATE

Returns current state for the node.

NGM_HCI_NODE_INIT

Turn on ``inited'' bit for the node.

NGM_HCI_NODE_GET_DEBUG

Returns an integer containing the current debug lev

el for the
node.

NGM_HCI_NODE_SET_DEBUG

This command takes an integer argument and sets cur

rent debug
level for the node.

NGM_HCI_NODE_GET_BUFFER

Returns current state of data buffers.

NGM_HCI_NODE_GET_BDADDR

Returns BD_ADDR as cached in the node.

NGM_HCI_NODE_GET_FEATURES

Returns the list of features supported by hardware

(as cached by
the node).

NGM_HCI_NODE_GET_NEIGHBOR_CACHE

Returns content of the neighbor cache.

NGM_HCI_NODE_FLUSH_NEIGHBOR_CACHE

Remove all neighbor cache entries.

NGM_HCI_NODE_GET_CON_LIST

Returns list of active baseband connections (i.e.,

ACL and SCO
links).

NGM_HCI_NODE_GET_STAT

Returns various statistic counters.

NGM_HCI_NODE_RESET_STAT

Resets all statistic counters to zero.

NGM_HCI_NODE_SET_LINK_POLICY_SETTINGS_MASK

Sets current link policy settings mask. After the

new ACL connection is created the HCI node will try set link

policy for the
ACL connection. By default, every supported Link

Manager (LM)
mode will be enabled. User can override this by

setting link
policy settings mask which specifies LM modes to be

enabled.

NGM_HCI_NODE_GET_LINK_POLICY_SETTINGS_MASK

Returns current link policy settings mask.

NGM_HCI_NODE_SET_PACKET_MASK

Sets current packet mask. When new baseband (ACL or

SCO) connection is created the HCI node will specify every

packet type supported by the device. User can override this by

setting packet
mask which specifies packet types to be used for new

baseband
connections.

NGM_HCI_NODE_GET_PACKET_MASK

Returns current packet mask.

NGM_HCI_NODE_SET_ROLE_SWITCH

Sets the value of the role switch. Role switch is

enabled when
this value is not zero. This is the default state.

Note that
actual role switch at Bluetooth link level will only

be performed
if hardware supports role switch and it was enabled.

NGM_HCI_NODE_GET_ROLE_SWITCH

Returns the value of the role switch for the node.

SHUTDOWN

This node shuts down upon receipt of a NGM_SHUTDOWN control

message, or
when all hooks have been disconnected.

SEE ALSO

netgraph(4), hccontrol(8), ngctl(8)

HISTORY

The hci node type was implemented in FreeBSD 5.0.

AUTHORS

Maksim Yevmenkin <m_evmenkin@yahoo.com>

BUGS

Most likely. Please report if found.

BSD June 25, 2002

BSD