NAME

SYNOPSIS

DESCRIPTION

INTRODUCTION TO BLUETOOTH

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

HOST CONTROLLER INTERFACE (HCI)

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

#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;

#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;

#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;

#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 INITIALIZATION

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

As soon as HCI initialization has been successfully performed, HCI control 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

#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

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 contained 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 connection.

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 passing 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

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

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 hardware supports role switch and it was enabled.

NGM_HCI_NODE_GET_ROLE_SWITCH

Returns the value of the role switch for the node.

SHUTDOWN

SEE ALSO

HISTORY

AUTHORS

BUGS