PageRenderTime 18ms CodeModel.GetById 8ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 1ms

/share/man/man4/ng_hci.4

https://bitbucket.org/freebsd/freebsd-head/
Forth | 387 lines | 385 code | 0 blank | 2 comment | 20 complexity | 399160f77ee50211a8a5d5b5ddb0ab67 MD5 | raw file
  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.