Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
NG_HCI(4)	       FreeBSD Kernel Interfaces Manual		     NG_HCI(4)

NAME
     ng_hci -- Netgraph	node type that is also a Bluetooth Host	Controller
     Interface (HCI) layer

SYNOPSIS
     #include <sys/types.h>
     #include <netgraph/bluetooth/include/ng_hci.h>

DESCRIPTION
     The hci node type is a Netgraph node type that implements Bluetooth Host
     Controller	Interface (HCI)	layer as per chapter H1	of the Bluetooth Spec-
     ification Book v1.1.

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
     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
     direction), or 433.9 kb/s symmetric.

     The Bluetooth system provides a point-to-point connection (only two Blue-
     tooth units involved), or a point-to-multipoint connection.  In the
     point-to-multipoint connection, the channel is shared among several Blue-
     tooth units.  Two or more units sharing the same channel form a
     ``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 access is controlled	by the master.

     Multiple piconets with overlapping	coverage areas form a ``scatternet''.
     Each piconet can only have	a single master.  However, slaves can partici-
     pate in different piconets	on a time-division multiplex basis.  In	addi-
     tion, 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.

   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.

   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 consid-
     ered 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 differ-
     ent slaves.  A slave can support up to three SCO links from the same mas-
     ter, or two SCO links if the links	originate from different masters.  SCO
     packets are never retransmitted.

   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 participat-
     ing in the	piconet.  Both asynchronous and	isochronous services are sup-
     ported.  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.

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 provides	a uniform method of accessing the Bluetooth baseband
     capabilities.

     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 bus) driver provides both HCI layers with the ability to
     exchange information with each other.

     The Host will receive asynchronous	notifications of HCI events indepen-
     dent of which Host	Controller Transport Layer is used.  HCI events	are
     used for notifying	the Host when something	occurs.	 When the Host discov-
     ers 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.

   HCI Command Packet
	   #define NG_HCI_CMD_PKT 0x01
	   typedef struct {
		   uint8_t  type;   /* MUST be 0x1 */
		   uint16_t opcode; /* OpCode */
		   uint8_t  length; /* parameter(s) length in bytes */
	   } __attribute__ ((packed)) ng_hci_cmd_pkt_t;

     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 Con-
     troller 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.

   HCI Event Packet
	   #define NG_HCI_EVENT_PKT 0x04
	   typedef struct {
		   uint8_t type;   /* MUST be 0x4 */
		   uint8_t event;  /* event */
		   uint8_t length; /* parameter(s) length in bytes */
	   } __attribute__ ((packed)) ng_hci_event_pkt_t;

     The HCI event packet is used by the Host Controller to notify the Host
     when events occur.

   HCI ACL Data	Packet
	   #define NG_HCI_ACL_DATA_PKT 0x02
	   typedef struct {
		   uint8_t  type;	/* MUST	be 0x2 */
		   uint16_t con_handle;	/* connection handle + PB + BC flags */
		   uint16_t length;	/* payload length in bytes */
	   } __attribute__ ((packed)) ng_hci_acldata_pkt_t;

     HCI ACL data packets are used to exchange ACL data	between	the Host and
     Host Controller.

   HCI SCO Data	Packet
	   #define NG_HCI_SCO_DATA_PKT 0x03
	   typedef struct {
		   uint8_t  type;	/* MUST	be 0x3 */
		   uint16_t con_handle;	/* connection handle + reserved	bits */
		   uint8_t  length;	/* payload length in bytes */
	   } __attribute__ ((packed)) ng_hci_scodata_pkt_t;

     HCI SCO data packets are used to exchange SCO data	between	the Host and
     Host Controller.

HCI INITIALIZATION
     On	initialization,	HCI control application	must issue the following HCI
     commands (in any order).

     Read_BD_ADDR
	  To obtain BD_ADDR of the Bluetooth unit.

     Read_Local_Supported_Features
	  To obtain the	list of	features supported by Bluetooth	unit.

     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	Con-
	  troller.  There are also two additional return parameters that spec-
	  ify the total	number of HCI ACL and SCO data packets that the	Host
	  Controller can have waiting for transmission in its buffers.

     As	soon as	HCI initialization has been successfully performed, HCI	con-
     trol application must turn	on ``inited'' bit for the node.	 Once HCI node
     has been initialized all upstream hooks will receive a NGM_HCI_NODE_UP
     Netgraph message defined as follows.

	   #define NGM_HCI_NODE_UP 112 /* HCI -> Upper */
	   typedef struct {
		   uint16_t  pkt_size; /* max. ACL/SCO packet size (w/o	hdr) */
		   uint16_t  num_pkts; /* ACL/SCO packet queue size */
		   uint16_t  reserved; /* place	holder */
		   bdaddr_t  bdaddr;   /* bdaddr */
	   } ng_hci_node_up_ep;

HCI FLOW CONTROL
     HCI layer performs	flow control on	baseband connection basis (i.e., ACL
     and SCO link).  Each baseband connection has ``connection handle''	and
     queue of outgoing data packets.  Upper layers protocols are allowed to
     send up to	(num_pkts - pending) packets at	one time.  HCI layer will send
     NGM_HCI_SYNC_CON_QUEUE Netgraph messages to inform	upper layers about
     current queue state for each connection handle.  The
     NGM_HCI_SYNC_CON_QUEUE Netgraph message is	defined	as follows.

	   #define NGM_HCI_SYNC_CON_QUEUE 113 /* HCI ->	Upper */
	   typedef struct {
		   uint16_t con_handle;	/* connection handle */
		   uint16_t completed;	/* number of completed packets */
	   } ng_hci_sync_con_queue_ep;

HOOKS
     This node type supports the following hooks:

     drv  Bluetooth Host Controller Transport Layer hook.  Single HCI packet
	  contained in single mbuf structure.

     acl  Upper	layer protocol/node is connected to the	hook.  Single HCI ACL
	  data packet contained	in single mbuf structure.

     sco  Upper	layer protocol/node is connected to the	hook.  Single HCI SCO
	  data packet contained	in single mbuf structure.

     raw  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 con-
	  tained in single mbuf	structure.

BLUETOOTH UPPER	LAYER PROTOCOLS	INTERFACE (LP CONTROL MESSAGES)
     NGM_HCI_LP_CON_REQ
	  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 connec-
	  tion.

     NGM_HCI_LP_DISCON_REQ
	  Requests the lower protocol (baseband) to terminate a	connection.

     NGM_HCI_LP_CON_CFM
	  Confirms success or failure of the NGM_HCI_LP_CON_REQ	request	to
	  establish a lower layer (baseband) connection.  This includes	pass-
	  ing the authentication challenge if authentication is	required to
	  establish the	physical link.

     NGM_HCI_LP_CON_IND
	  Indicates the	lower protocol (baseband) has successfully established
	  incoming connection.

     NGM_HCI_LP_CON_RSP
	  A response accepting or rejecting the	previous connection indication
	  request.

     NGM_HCI_LP_DISCON_IND
	  Indicates the	lower protocol (baseband) has terminated connection.
	  This could be	a response to NGM_HCI_LP_DISCON_REQ or a timeout
	  event.

     NGM_HCI_LP_QOS_REQ
	  Requests the lower protocol (baseband) to accommodate	a particular
	  QoS parameter	set.

     NGM_HCI_LP_QOS_CFM
	  Confirms success or failure of the request for a given quality of
	  service.

     NGM_HCI_LP_QOS_IND
	  Indicates the	lower protocol (baseband) has detected a violation of
	  the QoS agreement.

NETGRAPH CONTROL MESSAGES
     This node type supports the generic control messages, plus	the following:

     NGM_HCI_NODE_GET_STATE
	  Returns current state	for the	node.

     NGM_HCI_NODE_INIT
	  Turn on ``inited'' bit for the node.

     NGM_HCI_NODE_GET_DEBUG
	  Returns an integer containing	the current debug level	for the	node.

     NGM_HCI_NODE_SET_DEBUG
	  This command takes an	integer	argument and sets current debug	level
	  for the node.

     NGM_HCI_NODE_GET_BUFFER
	  Returns current state	of data	buffers.

     NGM_HCI_NODE_GET_BDADDR
	  Returns BD_ADDR as cached in the node.

     NGM_HCI_NODE_GET_FEATURES
	  Returns the list of features supported by hardware (as cached	by the
	  node).

     NGM_HCI_NODE_GET_NEIGHBOR_CACHE
	  Returns content of the neighbor cache.

     NGM_HCI_NODE_FLUSH_NEIGHBOR_CACHE
	  Remove all neighbor cache entries.

     NGM_HCI_NODE_GET_CON_LIST
	  Returns list of active baseband connections (i.e., ACL and SCO
	  links).

     NGM_HCI_NODE_GET_STAT
	  Returns various statistic counters.

     NGM_HCI_NODE_RESET_STAT
	  Resets all statistic counters	to zero.

     NGM_HCI_NODE_SET_LINK_POLICY_SETTINGS_MASK
	  Sets current link policy settings mask.  After the new ACL connec-
	  tion 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.

     NGM_HCI_NODE_GET_LINK_POLICY_SETTINGS_MASK
	  Returns current link policy settings mask.

     NGM_HCI_NODE_SET_PACKET_MASK
	  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.

     NGM_HCI_NODE_GET_PACKET_MASK
	  Returns current packet mask.

     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 performed if	hard-
	  ware supports	role switch and	it was enabled.

     NGM_HCI_NODE_GET_ROLE_SWITCH
	  Returns the value of the role	switch for the node.

SHUTDOWN
     This node shuts down upon receipt of a NGM_SHUTDOWN control message, or
     when all hooks have been disconnected.

SEE ALSO
     netgraph(4), hccontrol(8),	ngctl(8)

HISTORY
     The hci node type was implemented in FreeBSD 5.0.

AUTHORS
     Maksim Yevmenkin <m_evmenkin@yahoo.com>

BUGS
     Most likely.  Please report if found.

FreeBSD	10.1			 June 25, 2002			  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | INTRODUCTION TO BLUETOOTH | HOST CONTROLLER INTERFACE (HCI) | HCI INITIALIZATION | HCI FLOW CONTROL | HOOKS | BLUETOOTH UPPER LAYER PROTOCOLS INTERFACE (LP CONTROL MESSAGES) | NETGRAPH CONTROL MESSAGES | SHUTDOWN | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=ng_hci&manpath=FreeBSD+10.0-RELEASE>

home | help