1.\" ng_hci.4 2.\" 3.\" Copyright (c) 2001-2002 Maksim Yevmenkin <m_evmenkin@yahoo.com> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $Id: ng_hci.4,v 1.2 2003/03/18 00:09:34 max Exp $ 28.\" $FreeBSD$ 29.Dd June 25, 2002 30.Dt NG_HCI 4 31.Os 32.Sh NAME 33.Nm hci 34.Nd Netgraph node type that is also a Bluetooth Host Controller Interface 35(HCI) layer 36.Sh SYNOPSIS 37.In sys/types.h 38.In netgraph/ng_message.h 39.In netgraph/netgraph.h 40.In netgraph/ng_hci.h 41.Sh DESCRIPTION 42The 43.Nm 44node type is a Netgraph node type that implements Bluetooth Host Controller 45Interface (HCI) layer as per chapter H1 of the Bluetooth Specification Book 46v1.1. 47.Sh INTRODUCTION TO BLUETOOTH 48Bluetooth is a short-range radio link intended to replace the cable(s) 49connecting portable and/or fixed electronic devices. Bluetooth operates 50in the unlicensed ISM band at 2.4 GHz. The Bluetooth protocol uses a 51combination of circuit and packet switching. Bluetooth can support an 52asynchronous data channel, up to three simultaneous synchronous voice 53channels, or a channel which simultaneously supports asynchronous data 54and synchronous voice. Each voice channel supports a 64 kb/s synchronous 55(voice) channel in each direction. The asynchronous channel can support 56maximal 723.2 kb/s asymmetric (and still up to 57.6 kb/s in the return 57direction), or 433.9 kb/s symmetric. 58.Pp 59The Bluetooth system provides a point-to-point connection (only two 60Bluetooth units involved), or a point-to-multipoint connection. In the 61point-to-multipoint connection, the channel is shared among several 62Bluetooth units. Two or more units sharing the same channel form a 63.Em piconet . 64One Bluetooth unit acts as the master of the piconet, whereas the other 65unit(s) acts as slave(s). Up to seven slaves can be active in the piconet. 66In addition, many more slaves can remain locked to the master in a so-called 67parked state. These parked slaves cannot be active on the channel, but remain 68synchronized to the master. Both for active and parked slaves, the channel 69access is controlled by the master. 70.Pp 71Multiple piconets with overlapping coverage areas form a 72.Em scatternet . 73Each piconet can only have a single master. However, slaves can participate 74in different piconets on a time-division multiplex basis. In addition, a 75master in one piconet can be a slave in another piconet. The piconets shall 76not be frequency-synchronized. Each piconet has its own hopping channel. 77.Ss Time slots 78The channel is divided into time slots, each 625 usec in length. The time 79slots are numbered according to the Bluetooth clock of the piconet master. 80The slot numbering ranges from 0 to 2^27 -1 and is cyclic with a cycle length 81of 2^27. In the time slots, master and slave can transmit packets. 82.Ss SCO link 83The SCO link is a symmetric, point-to-point link between the master and a 84specific slave. The SCO link reserves slots and can therefore be considered 85as a circuit-switched connection between the master and the slave. The SCO 86link typically supports time-bounded information like voice. The master can 87support up to three SCO links to the same slave or to different slaves. A 88slave can support up to three SCO links from the same master, or two SCO 89links if the links originate from different masters. SCO packets are never 90retransmitted. 91.Ss ACL link 92In the slots not reserved for SCO links, the master can exchange packets 93with any slave on a per-slot basis. The ACL link provides a packet-switched 94connection between the master and all active slaves participating in the 95piconet. Both asynchronous and isochronous services are supported. Between 96a master and a slave only a single ACL link can exist. For most ACL packets, 97packet retransmission is applied to assure data integrity. 98.Sh HOST CONTROLLER INTERFACE (HCI) 99The HCI provides a command interface to the baseband controller and link 100manager, and access to hardware status and control registers. This interface 101provides a uniform method of accessing the Bluetooth baseband capabilities. 102.Pp 103The HCI layer on the Host exchanges data and commands with the HCI firmware 104on the Bluetooth hardware. The Host Controller Transport Layer (i.e. physical 105bus) driver provides both HCI layers with the ability to exchange information 106with each other. 107.Pp 108The Host will receive asynchronous notifications of HCI events independent 109of which Host Controller Transport Layer is used. HCI events are used for 110notifying the Host when something occurs. When the Host discovers that an 111event has occurred it will then parse the received event packet to determine 112which event occurred. 113The next sections specify the HCI packet formats. 114.Ss HCI command packet 115.Bd -literal -offset indent 116#define NG_HCI_CMD_PKT 0x01 117typedef struct { 118 u_int8_t type; /* MUST be 0x1 */ 119 u_int16_t opcode; /* OpCode */ 120 u_int8_t length; /* parameter(s) length in bytes */ 121} __attribute__ ((packed)) ng_hci_cmd_pkt_t; 122.Ed 123.Pp 124The HCI command packet is used to send commands to the Host Controller 125from the Host. When the Host Controller completes most of the commands, 126a Command Complete event is sent to the Host. Some commands do not receive 127a Command Complete event when they have been completed. Instead, when the 128Host Controller receives one of these commands the Host Controller sends 129a Command Status event back to the Host when it has begun to execute the 130command. Later on, when the actions associated with the command have finished, 131an event that is associated with the sent command will be sent by the Host 132Controller to the Host. 133.Ss HCI event packet 134.Bd -literal -offset indent 135#define NG_HCI_EVENT_PKT 0x04 136typedef struct { 137 u_int8_t type; /* MUST be 0x4 */ 138 u_int8_t event; /* event */ 139 u_int8_t length; /* parameter(s) length in bytes */ 140} __attribute__ ((packed)) ng_hci_event_pkt_t; 141.Ed 142.Pp 143The HCI event packet is used by the Host Controller to notify the Host 144when events occur. 145.Ss HCI ACL data packet 146.Bd -literal -offset indent 147#define NG_HCI_ACL_DATA_PKT 0x02 148typedef struct { 149 u_int8_t type; /* MUST be 0x2 */ 150 u_int16_t con_handle; /* connection handle + PB + BC flags */ 151 u_int16_t length; /* payload length in bytes */ 152} __attribute__ ((packed)) ng_hci_acldata_pkt_t; 153.Ed 154.Pp 155HCI ACL data packets are used to exchange ACL data between the Host and 156Host Controller. 157.Ss HCI SCO data packet 158.Bd -literal -offset indent 159#define NG_HCI_SCO_DATA_PKT 0x03 160typedef struct { 161 u_int8_t type; /* MUST be 0x3 */ 162 u_int16_t con_handle; /* connection handle + reserved bits */ 163 u_int8_t length; /* payload length in bytes */ 164} __attribute__ ((packed)) ng_hci_scodata_pkt_t; 165.Ed 166.Pp 167HCI SCO data packets are used to exchange SCO data between the Host and 168Host Controller. 169.Sh HCI INITIALIZATION 170On initialization, HCI control application must issue the following HCI 171commands (in any order). 172.Bl -tag -width foobar 173.It Dv Read_BD_ADDR 174To obtain BD_ADDR of the Bluetooth unit. 175.It Dv Read_Local_Supported_Features 176To obtain the list of features supported by Bluetooth unit. 177.It Dv Read_Buffer_Size 178To determine the maximum size of HCI ACL and SCO HCI data packets (excluding 179header) that can be sent from the Host to the Host Controller. There are also 180two additional return parameters that specify the total number of HCI ACL and 181SCO data packets that the Host Controller can have waiting for transmission in 182its buffers. 183.El 184.Pp 185As soon as HCI initialization has been successfuly performed, HCI control 186application must turn on 187.Dq inited 188bit for the node. Once HCI node has been initialized all upsteam hooks 189will receive a 190.Dv NGM_HCI_NODE_UP 191Netgraph message defined as follows. 192.Bd -literal -offset indent 193#define NGM_HCI_NODE_UP 112 /* HCI -> Upper */ 194typedef struct { 195 u_int16_t pkt_size; /* max. ACL/SCO packet size (w/o hdr) */ 196 u_int16_t num_pkts; /* ACL/SCO packet queue size */ 197 u_int16_t reserved; /* place holder */ 198 bdaddr_t bdaddr; /* bdaddr */ 199} ng_hci_node_up_ep; 200.Ed 201.Sh HCI FLOW CONTROL 202HCI layer performs flow control on baseband connection basis (i.e. ACL and 203SCO link). Each baseband connection has 204.Em connection handle 205and queue of outgoing data packets. Upper layers protocols are allowed to 206send up to ( 207.Dv num_pkts - 208.Dv pending ) 209packets at one time. HCI layer will send 210.Dv NGM_HCI_SYNC_CON_QUEUE 211Netgraph messages to inform upper layers about current queue state for each 212connection handle. The 213.Dv NGM_HCI_SYNC_CON_QUEUE 214Netgraph message is defined as follows. 215.Bd -literal -offset indent 216#define NGM_HCI_SYNC_CON_QUEUE 113 /* HCI -> Upper */ 217typedef struct { 218 u_int16_t con_handle; /* connection handle */ 219 u_int16_t completed; /* number of completed packets */ 220} ng_hci_sync_con_queue_ep; 221.Ed 222.Sh HOOKS 223This node type supports the following hooks: 224.Pp 225.Bl -tag -width foobar 226.It Dv drv 227Bluetooth Host Controller Transport Layer hook. Single HCI packet contained in 228single 229.Dv mbuf 230structure. 231.It Dv acl 232Upper layer protocol/node is connected to the hook. Single HCI ACL 233data packet contained in single 234.Dv mbuf 235structure. 236.It Dv sco 237Upper layer protocol/node is connected to the hook. Single HCI SCO 238data packet contained in single 239.Dv mbuf 240structure. 241.It Dv raw 242Raw hook. Every HCI frame (including HCI command frame) that goes in 243or out will be delivired to the hook. Usually Bluetooth raw HCI sockets 244layer is connected to the hook. Single HCI frame contained in single 245. Dv mbuf 246structure. 247.El 248.Sh BLUETOOTH UPPER LAYER PROTOCOLS INTERFACE (LP CONTROL MESSAGES) 249.Bl -tag -width foo 250.It Dv NGM_HCI_LP_CON_REQ 251Requests the lower protocol to create a connection. If a physical link 252to the remote device does not exist, this message must be sent to the lower 253protocol (baseband) to establish the physical connection. 254.It Dv NGM_HCI_LP_DISCON_REQ 255Requests the lower protocol (baseband) to terminate a connection. 256.It Dv NGM_HCI_LP_CON_CFM 257Confirms success or failure of the 258.Dv 259NGM_HCI_LP_CON_REQ request to establish a lower layer (baseband) connection. 260This includes passing the authentication challenge if authentication is 261required to establish the physical link. 262.It Dv NGM_HCI_LP_CON_IND 263Indicates the lower protocol (baseband) has successfully established 264incoming connection. 265.It Dv NGM_HCI_LP_CON_RSP 266A response accepting or rejecting the previous connection indication request. 267.It Dv NGM_HCI_LP_DISCON_IND 268Indicates the lower protocol (baseband) has terminated connection. This 269could be a response to 270.Dv NGM_HCI_LP_DISCON_REQ 271or a timeout event. 272.It Dv NGM_HCI_LP_QOS_REQ 273Requests the lower protocol (baseband) to accommodate a particular QoS 274parameter set. 275.It Dv NGM_HCI_LP_QOS_CFM 276Confirms success or failure of the request for a given quality of service. 277.It Dv NGM_HCI_LP_QOS_IND 278Indicates the lower protocol (baseband) has detected a violation of the QoS 279agreement. 280.El 281.Sh NETGRAPH CONTROL MESSAGES 282This node type supports the generic control messages, plus the following: 283.Bl -tag -width foo 284.It Dv NGM_HCI_NODE_GET_STATE 285Returns current state for the node. 286.It Dv NGM_HCI_NODE_INIT 287Turn on 288.Dq inited 289bit for the node. 290.It Dv NGM_HCI_NODE_GET_DEBUG 291Returns an integer containing the current debug level for the node. 292.It Dv NGM_HCI_NODE_SET_DEBUG 293This command takes an integer argument and sets current debug level 294for the node. 295.It Dv NGM_HCI_NODE_GET_BUFFER 296Returns current state of data buffers. 297.It Dv NGM_HCI_NODE_GET_BDADDR 298Returns BD_ADDR as cached in the node. 299.It Dv NGM_HCI_NODE_GET_FEATURES 300Returns the list of features supported by hardware (as cached by the node). 301.It Dv NGM_HCI_NODE_GET_NEIGHBOR_CACHE 302Returns content of the neighbor cache. 303.It Dv NGM_HCI_NODE_FLUSH_NEIGHBOR_CACHE 304Remove all neighbor cache entries. 305.It Dv NGM_HCI_NODE_GET_CON_LIST 306Returns list of active baseband connections (i.e. ACL and SCO links). 307.It Dv NGM_HCI_NODE_GET_STAT 308Returns various statistic counters. 309.It Dv NGM_HCI_NODE_RESET_STAT 310Resets all statistic counters to zero. 311.It NGM_HCI_NODE_SET_LINK_POLICY_SETTINGS_MASK 312Sets current link policy settings mask. After the new ACL connection is 313created the HCI node will try set link policy for the ACL connection. By 314default every supported Link Manager (LM) mode will be enabled. User can 315override this by setting link policy settings mask which specifies LM 316modes to be enabled. 317.It NGM_HCI_NODE_GET_LINK_POLICY_SETTINGS_MASK 318Returns current link policy settings mask. 319.It NGM_HCI_NODE_SET_PACKET_MASK 320Sets current packet mask. When new baseband (ACL or SCO) connection is 321created the HCI node will specify every packet type supported by the device. 322User can override this by setting packet mask which specifies packet types 323to be used for new baseband connections. 324.It NGM_HCI_NODE_GET_PACKET_MASK 325Returns current packet mask. 326.It NGM_HCI_NODE_SET_ROLE_SWITCH 327Sets the value of the role switch. Role switch is enabled when this value is 328not zero. This is the default state. Note that actual role switch at Bluetooth 329link level will only be perfomed if hardware supports role switch and it was 330enabled. 331.It NGM_HCI_NODE_GET_ROLE_SWITCH 332Returns the value of the role switch for the node. 333.El 334.Sh SHUTDOWN 335This node shuts down upon receipt of a NGM_SHUTDOWN control message, or 336when all hooks have been disconnected. 337.Sh BUGS 338Most likely. Please report if found. 339.Sh SEE ALSO 340.Xr netgraph 4 , 341.Xr ngctl 8 , 342.Xr hccontrol 8 343.Sh HISTORY 344The 345.Nm 346node type was implemented in 347.Fx 5.0 . 348.Sh AUTHORS 349.An Maksim Yevmenkin Aq m_evmenkin@yahoo.com 350