share/man/man4/ng_hci.4

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