diff options
author | ru <ru@FreeBSD.org> | 2003-05-20 21:01:21 +0000 |
---|---|---|
committer | ru <ru@FreeBSD.org> | 2003-05-20 21:01:21 +0000 |
commit | 638a31a3e24744379ca4274722cebfb783cb3acd (patch) | |
tree | cc71fbdbb548ae9fb5856beadc19f74dae54e77b /share/man/man4/ng_hci.4 | |
parent | a808871f563c1b6300be2d520e5420fc534e7de7 (diff) | |
download | FreeBSD-src-638a31a3e24744379ca4274722cebfb783cb3acd.zip FreeBSD-src-638a31a3e24744379ca4274722cebfb783cb3acd.tar.gz |
Reapply mdoc(7) fixes that got accidentally lost in the last
Bluetooth update, and fix a few more issues.
Submitted by: Maksim Yevmenkin <m_evmenkin@yahoo.com>, ru
Approved by: re (blanket)
Diffstat (limited to 'share/man/man4/ng_hci.4')
-rw-r--r-- | share/man/man4/ng_hci.4 | 312 |
1 files changed, 176 insertions, 136 deletions
diff --git a/share/man/man4/ng_hci.4 b/share/man/man4/ng_hci.4 index bc5e11e..b0b791f 100644 --- a/share/man/man4/ng_hci.4 +++ b/share/man/man4/ng_hci.4 @@ -1,8 +1,6 @@ -.\" ng_hci.4 -.\" .\" Copyright (c) 2001-2002 Maksim Yevmenkin <m_evmenkin@yahoo.com> .\" All rights reserved. -.\" +.\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: @@ -11,7 +9,7 @@ .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. -.\" +.\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE @@ -23,15 +21,16 @@ .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. -.\" +.\" .\" $Id: ng_hci.4,v 1.2 2003/03/18 00:09:34 max Exp $ .\" $FreeBSD$ +.\" .Dd June 25, 2002 .Dt NG_HCI 4 .Os .Sh NAME -.Nm hci -.Nd Netgraph node type that is also a Bluetooth Host Controller Interface +.Nm ng_hci +.Nd Netgraph node type that is also a Bluetooth Host Controller Interface (HCI) layer .Sh SYNOPSIS .In sys/types.h @@ -40,78 +39,99 @@ .In netgraph/ng_hci.h .Sh DESCRIPTION The -.Nm +.Nm hci node type is a Netgraph node type that implements Bluetooth Host Controller -Interface (HCI) layer as per chapter H1 of the Bluetooth Specification Book +Interface (HCI) layer as per chapter H1 of the Bluetooth Specification Book v1.1. .Sh INTRODUCTION TO BLUETOOTH -Bluetooth is a short-range radio link intended to replace the cable(s) -connecting portable and/or fixed electronic devices. Bluetooth operates -in the unlicensed ISM band at 2.4 GHz. The Bluetooth protocol uses a -combination of circuit and packet switching. Bluetooth can support an +Bluetooth is a short-range radio link intended to replace the cable(s) +connecting portable and/or fixed electronic devices. +Bluetooth operates in the unlicensed ISM band at 2.4 GHz. +The Bluetooth protocol uses a +combination of circuit and packet switching. +Bluetooth can support an asynchronous data channel, up to three simultaneous synchronous voice -channels, or a channel which simultaneously supports asynchronous data -and synchronous voice. Each voice channel supports a 64 kb/s synchronous -(voice) channel in each direction. The asynchronous channel can support -maximal 723.2 kb/s asymmetric (and still up to 57.6 kb/s in the return +channels, or a channel which simultaneously supports asynchronous data +and synchronous voice. +Each voice channel supports a 64 kb/s synchronous +(voice) channel in each direction. +The asynchronous channel can support +maximal 723.2 kb/s asymmetric (and still up to 57.6 kb/s in the return direction), or 433.9 kb/s symmetric. .Pp -The Bluetooth system provides a point-to-point connection (only two -Bluetooth units involved), or a point-to-multipoint connection. In the -point-to-multipoint connection, the channel is shared among several -Bluetooth units. Two or more units sharing the same channel form a -.Em piconet . -One Bluetooth unit acts as the master of the piconet, whereas the other -unit(s) acts as slave(s). Up to seven slaves can be active in the piconet. +The Bluetooth system provides a point-to-point connection (only two +Bluetooth units involved), or a point-to-multipoint connection. +In the point-to-multipoint connection, +the channel is shared among several Bluetooth units. +Two or more units sharing the same channel form a +.Dq piconet . +One Bluetooth unit acts as the master of the piconet, whereas the other +unit(s) acts as slave(s). +Up to seven slaves can be active in the piconet. In addition, many more slaves can remain locked to the master in a so-called -parked state. These parked slaves cannot be active on the channel, but remain -synchronized to the master. Both for active and parked slaves, the channel +parked state. +These parked slaves cannot be active on the channel, but remain +synchronized to the master. +Both for active and parked slaves, the channel access is controlled by the master. -.Pp -Multiple piconets with overlapping coverage areas form a -.Em scatternet . -Each piconet can only have a single master. However, slaves can participate -in different piconets on a time-division multiplex basis. In addition, a -master in one piconet can be a slave in another piconet. The piconets shall -not be frequency-synchronized. Each piconet has its own hopping channel. -.Ss Time slots -The channel is divided into time slots, each 625 usec in length. The time -slots are numbered according to the Bluetooth clock of the piconet master. -The slot numbering ranges from 0 to 2^27 -1 and is cyclic with a cycle length -of 2^27. In the time slots, master and slave can transmit packets. -.Ss SCO link -The SCO link is a symmetric, point-to-point link between the master and a -specific slave. The SCO link reserves slots and can therefore be considered -as a circuit-switched connection between the master and the slave. The SCO -link typically supports time-bounded information like voice. The master can -support up to three SCO links to the same slave or to different slaves. A -slave can support up to three SCO links from the same master, or two SCO -links if the links originate from different masters. SCO packets are never -retransmitted. -.Ss ACL link -In the slots not reserved for SCO links, the master can exchange packets -with any slave on a per-slot basis. The ACL link provides a packet-switched -connection between the master and all active slaves participating in the -piconet. Both asynchronous and isochronous services are supported. Between -a master and a slave only a single ACL link can exist. For most ACL packets, +.Pp +Multiple piconets with overlapping coverage areas form a +.Dq scatternet . +Each piconet can only have a single master. +However, slaves can participate +in different piconets on a time-division multiplex basis. +In addition, a master in one piconet can be a slave in another piconet. +The piconets shall not be frequency-synchronized. +Each piconet has its own hopping channel. +.Ss Time Slots +The channel is divided into time slots, each 625 usec in length. +The time +slots are numbered according to the Bluetooth clock of the piconet master. +The slot numbering ranges from 0 to 2^27 -1 and is cyclic with a cycle length +of 2^27. +In the time slots, master and slave can transmit packets. +.Ss SCO Link +The SCO link is a symmetric, point-to-point link between the master and a +specific slave. +The SCO link reserves slots and can therefore be considered +as a circuit-switched connection between the master and the slave. +The SCO link typically supports time-bounded information like voice. +The master can +support up to three SCO links to the same slave or to different slaves. +A slave can support up to three SCO links from the same master, or two SCO +links if the links originate from different masters. +SCO packets are never retransmitted. +.Ss ACL Link +In the slots not reserved for SCO links, the master can exchange packets +with any slave on a per-slot basis. +The ACL link provides a packet-switched +connection between the master and all active slaves participating in the +piconet. +Both asynchronous and isochronous services are supported. +Between a master and a slave only a single ACL link can exist. +For most ACL packets, packet retransmission is applied to assure data integrity. .Sh HOST CONTROLLER INTERFACE (HCI) -The HCI provides a command interface to the baseband controller and link -manager, and access to hardware status and control registers. This interface +The HCI provides a command interface to the baseband controller and link +manager, and access to hardware status and control registers. +This interface provides a uniform method of accessing the Bluetooth baseband capabilities. .Pp The HCI layer on the Host exchanges data and commands with the HCI firmware -on the Bluetooth hardware. The Host Controller Transport Layer (i.e. physical +on the Bluetooth hardware. +The Host Controller Transport Layer (i.e. physical bus) driver provides both HCI layers with the ability to exchange information with each other. .Pp -The Host will receive asynchronous notifications of HCI events independent -of which Host Controller Transport Layer is used. HCI events are used for -notifying the Host when something occurs. When the Host discovers that an -event has occurred it will then parse the received event packet to determine +The Host will receive asynchronous notifications of HCI events independent +of which Host Controller Transport Layer is used. +HCI events are used for +notifying the Host when something occurs. +When the Host discovers that an +event has occurred it will then parse the received event packet to determine which event occurred. The next sections specify the HCI packet formats. -.Ss HCI command packet +.Ss HCI Command Packet .Bd -literal -offset indent #define NG_HCI_CMD_PKT 0x01 typedef struct { @@ -122,15 +142,19 @@ typedef struct { .Ed .Pp The HCI command packet is used to send commands to the Host Controller -from the Host. When the Host Controller completes most of the commands, -a Command Complete event is sent to the Host. Some commands do not receive -a Command Complete event when they have been completed. Instead, when the -Host Controller receives one of these commands the Host Controller sends -a Command Status event back to the Host when it has begun to execute the -command. Later on, when the actions associated with the command have finished, -an event that is associated with the sent command will be sent by the Host +from the Host. +When the Host Controller completes most of the commands, +a Command Complete event is sent to the Host. +Some commands do not receive +a Command Complete event when they have been completed. +Instead, when the +Host Controller receives one of these commands the Host Controller sends +a Command Status event back to the Host when it has begun to execute the +command. +Later on, when the actions associated with the command have finished, +an event that is associated with the sent command will be sent by the Host Controller to the Host. -.Ss HCI event packet +.Ss HCI Event Packet .Bd -literal -offset indent #define NG_HCI_EVENT_PKT 0x04 typedef struct { @@ -140,9 +164,9 @@ typedef struct { } __attribute__ ((packed)) ng_hci_event_pkt_t; .Ed .Pp -The HCI event packet is used by the Host Controller to notify the Host +The HCI event packet is used by the Host Controller to notify the Host when events occur. -.Ss HCI ACL data packet +.Ss HCI ACL Data Packet .Bd -literal -offset indent #define NG_HCI_ACL_DATA_PKT 0x02 typedef struct { @@ -152,9 +176,9 @@ typedef struct { } __attribute__ ((packed)) ng_hci_acldata_pkt_t; .Ed .Pp -HCI ACL data packets are used to exchange ACL data between the Host and +HCI ACL data packets are used to exchange ACL data between the Host and Host Controller. -.Ss HCI SCO data packet +.Ss HCI SCO Data Packet .Bd -literal -offset indent #define NG_HCI_SCO_DATA_PKT 0x03 typedef struct { @@ -164,29 +188,31 @@ typedef struct { } __attribute__ ((packed)) ng_hci_scodata_pkt_t; .Ed .Pp -HCI SCO data packets are used to exchange SCO data between the Host and +HCI SCO data packets are used to exchange SCO data between the Host and Host Controller. .Sh HCI INITIALIZATION On initialization, HCI control application must issue the following HCI commands (in any order). -.Bl -tag -width foobar +.Bl -tag -width indent .It Dv Read_BD_ADDR To obtain BD_ADDR of the Bluetooth unit. .It Dv Read_Local_Supported_Features To obtain the list of features supported by Bluetooth unit. .It Dv Read_Buffer_Size -To determine the maximum size of HCI ACL and SCO HCI data packets (excluding -header) that can be sent from the Host to the Host Controller. There are also -two additional return parameters that specify the total number of HCI ACL and -SCO data packets that the Host Controller can have waiting for transmission in -its buffers. +To determine the maximum size of HCI ACL and SCO HCI data packets (excluding +header) that can be sent from the Host to the Host Controller. +There are also +two additional return parameters that specify the total number of HCI ACL and +SCO data packets that the Host Controller can have waiting for transmission in +its buffers. .El .Pp -As soon as HCI initialization has been successfuly performed, HCI control +As soon as HCI initialization has been successfully performed, HCI control application must turn on .Dq inited -bit for the node. Once HCI node has been initialized all upsteam hooks -will receive a +bit for the node. +Once HCI node has been initialized all upsteam hooks +will receive a .Dv NGM_HCI_NODE_UP Netgraph message defined as follows. .Bd -literal -offset indent @@ -200,17 +226,22 @@ typedef struct { .Ed .Sh HCI FLOW CONTROL HCI layer performs flow control on baseband connection basis (i.e. ACL and -SCO link). Each baseband connection has -.Em connection handle -and queue of outgoing data packets. Upper layers protocols are allowed to -send up to ( -.Dv num_pkts - +SCO link). +Each baseband connection has +.Dq "connection handle" +and queue of outgoing data packets. +Upper layers protocols are allowed to +send up to +.Dv ( num_pkts +\- .Dv pending ) -packets at one time. HCI layer will send -.Dv NGM_HCI_SYNC_CON_QUEUE -Netgraph messages to inform upper layers about current queue state for each -connection handle. The -.Dv NGM_HCI_SYNC_CON_QUEUE +packets at one time. +HCI layer will send +.Dv NGM_HCI_SYNC_CON_QUEUE +Netgraph messages to inform upper layers about current queue state for each +connection handle. +The +.Dv NGM_HCI_SYNC_CON_QUEUE Netgraph message is defined as follows. .Bd -literal -offset indent #define NGM_HCI_SYNC_CON_QUEUE 113 /* HCI -> Upper */ @@ -221,71 +252,73 @@ typedef struct { .Ed .Sh HOOKS This node type supports the following hooks: -.Pp -.Bl -tag -width foobar +.Bl -tag -width indent .It Dv drv -Bluetooth Host Controller Transport Layer hook. Single HCI packet contained in -single -.Dv mbuf +Bluetooth Host Controller Transport Layer hook. +Single HCI packet contained in single +.Vt mbuf structure. .It Dv acl -Upper layer protocol/node is connected to the hook. Single HCI ACL -data packet contained in single -.Dv mbuf +Upper layer protocol/node is connected to the hook. +Single HCI ACL data packet contained in single +.Vt mbuf structure. .It Dv sco -Upper layer protocol/node is connected to the hook. Single HCI SCO -data packet contained in single -.Dv mbuf +Upper layer protocol/node is connected to the hook. +Single HCI SCO data packet contained in single +.Vt mbuf structure. .It Dv raw -Raw hook. Every HCI frame (including HCI command frame) that goes in -or out will be delivired to the hook. Usually Bluetooth raw HCI sockets -layer is connected to the hook. Single HCI frame contained in single -. Dv mbuf +Raw hook. +Every HCI frame (including HCI command frame) that goes in +or out will be delivered to the hook. +Usually the Bluetooth raw HCI socket layer is connected to the hook. +Single HCI frame contained in single +.Vt mbuf structure. .El .Sh BLUETOOTH UPPER LAYER PROTOCOLS INTERFACE (LP CONTROL MESSAGES) -.Bl -tag -width foo +.Bl -tag -width indent .It Dv NGM_HCI_LP_CON_REQ -Requests the lower protocol to create a connection. If a physical link +Requests the lower protocol to create a connection. +If a physical link to the remote device does not exist, this message must be sent to the lower protocol (baseband) to establish the physical connection. .It Dv NGM_HCI_LP_DISCON_REQ -Requests the lower protocol (baseband) to terminate a connection. +Requests the lower protocol (baseband) to terminate a connection. .It Dv NGM_HCI_LP_CON_CFM Confirms success or failure of the -.Dv -NGM_HCI_LP_CON_REQ request to establish a lower layer (baseband) connection. -This includes passing the authentication challenge if authentication is +.Dv NGM_HCI_LP_CON_REQ +request to establish a lower layer (baseband) connection. +This includes passing the authentication challenge if authentication is required to establish the physical link. .It Dv NGM_HCI_LP_CON_IND -Indicates the lower protocol (baseband) has successfully established -incoming connection. +Indicates the lower protocol (baseband) has successfully established +incoming connection. .It Dv NGM_HCI_LP_CON_RSP A response accepting or rejecting the previous connection indication request. .It Dv NGM_HCI_LP_DISCON_IND -Indicates the lower protocol (baseband) has terminated connection. This -could be a response to +Indicates the lower protocol (baseband) has terminated connection. +This could be a response to .Dv NGM_HCI_LP_DISCON_REQ or a timeout event. .It Dv NGM_HCI_LP_QOS_REQ -Requests the lower protocol (baseband) to accommodate a particular QoS +Requests the lower protocol (baseband) to accommodate a particular QoS parameter set. .It Dv NGM_HCI_LP_QOS_CFM Confirms success or failure of the request for a given quality of service. .It Dv NGM_HCI_LP_QOS_IND -Indicates the lower protocol (baseband) has detected a violation of the QoS +Indicates the lower protocol (baseband) has detected a violation of the QoS agreement. .El .Sh NETGRAPH CONTROL MESSAGES This node type supports the generic control messages, plus the following: -.Bl -tag -width foo +.Bl -tag -width indent .It Dv NGM_HCI_NODE_GET_STATE Returns current state for the node. .It Dv NGM_HCI_NODE_INIT Turn on -.Dq inited +.Dq inited bit for the node. .It Dv NGM_HCI_NODE_GET_DEBUG Returns an integer containing the current debug level for the node. @@ -309,40 +342,47 @@ Returns various statistic counters. .It Dv NGM_HCI_NODE_RESET_STAT Resets all statistic counters to zero. .It NGM_HCI_NODE_SET_LINK_POLICY_SETTINGS_MASK -Sets current link policy settings mask. After the new ACL connection is -created the HCI node will try set link policy for the ACL connection. By -default every supported Link Manager (LM) mode will be enabled. User can -override this by setting link policy settings mask which specifies LM +Sets current link policy settings mask. +After the new ACL connection is +created the HCI node will try set link policy for the ACL connection. +By default, every supported Link Manager (LM) mode will be enabled. +User can +override this by setting link policy settings mask which specifies LM modes to be enabled. .It NGM_HCI_NODE_GET_LINK_POLICY_SETTINGS_MASK Returns current link policy settings mask. .It NGM_HCI_NODE_SET_PACKET_MASK -Sets current packet mask. When new baseband (ACL or SCO) connection is +Sets current packet mask. +When new baseband (ACL or SCO) connection is created the HCI node will specify every packet type supported by the device. User can override this by setting packet mask which specifies packet types to be used for new baseband connections. .It NGM_HCI_NODE_GET_PACKET_MASK Returns current packet mask. .It NGM_HCI_NODE_SET_ROLE_SWITCH -Sets the value of the role switch. Role switch is enabled when this value is -not zero. This is the default state. Note that actual role switch at Bluetooth -link level will only be perfomed if hardware supports role switch and it was -enabled. +Sets the value of the role switch. +Role switch is enabled when this value is not zero. +This is the default state. +Note that actual role switch at Bluetooth link level will only be perfomed if +hardware supports role switch and it was enabled. .It NGM_HCI_NODE_GET_ROLE_SWITCH Returns the value of the role switch for the node. .El .Sh SHUTDOWN -This node shuts down upon receipt of a NGM_SHUTDOWN control message, or +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. .Sh BUGS -Most likely. Please report if found. +Most likely. +Please report if found. .Sh SEE ALSO .Xr netgraph 4 , -.Xr ngctl 8 , -.Xr hccontrol 8 +.Xr hccontrol 8 , +.Xr ngctl 8 .Sh HISTORY The -.Nm +.Nm hci node type was implemented in .Fx 5.0 . .Sh AUTHORS |