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