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