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 inbytes */- } __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 inbytes */- } __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 inbytes */- } __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 inbytes */- } __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 packetsize (w/o hdr) */
u_int16_t num_pkts; /* ACL/SCO packet queuesize */
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 completedpackets */- } 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