HCI Extensions bcore-sp-009P

Introduction1 IntroductionThe Host Computer Interface specification [HCI] defines a set of common commands and events that passbetween a Bluetooth host and Bluetooth module. Although these handle the majority of functionality required tocontrol a Bluetooth module, the specification’s authors foresaw the need to include (module)manufacturer-specific extensions.This document describes the use of these HCI manufacturer-specific extensions on CSR’s Bluetooth chips.bcore-sp-009Pa© Copyright CSR 2001-2003This material is subject to CSR’s non-disclosure agreement.Page 3 of 13

Context2 ContextThe HCI interface, defined in [HCI], specifies a functional interface between the Bluetooth host and the Bluetoothhost controller (the Bluetooth module).The specification defines a set of “commands” that flow from the host to the module, and a set of “events” thatflow in the reverse direction. Each of the commands and events has an identifying number.The specification provides a set of command identity numbers for “manufacturer-specific” commands to alloweach module manufacturer to extend its implementation of HCI to permit access to module-specific functionality.For example, a module manufacturer may provide commands to test its radio. The HCI specification alsoprovides a single “manufacturer-specific” event identifier.StandardHCICommandsManufacturer-specificHCICommandsHCIHCICommandsHCIEventsStandardHCIEventsHostBluetooth ModuleManufacturer-specificHCIEventFigure 2.1: Manufacturer-specific HCI Extensions for BlueCoreThis document describes the use of these two manufacturer-specific HCI extensions for a BlueCore chip.BlueCore HCI Extensionsbcore-sp-009Pa© Copyright CSR 2001-2003This material is subject to CSR’s non-disclosure agreement.Page 4 of 13

Manufacturer-Specific HCI Commands and Events3 Manufacturer-Specific HCI Commands and EventsThe Bluetooth HCI specification effectively multiplexes a set of parallel protocol streams over a single physicalconnection: ACL (asynchronous connection-less), SCO (synchronous connection-oriented) and Command/Event.The BlueCore firmware uses a single manufacturer-specific HCI command and the single manufacturer-specificHCI event to form a reliable bi-directional datagram service. Upon this datagram service it runs the HCI_EXTNprotocol, described in this document.The HCI_EXTN protocol tunnels through this single reliable manufacturer-specific HCI command/event service toprovide 64 parallel bi-directional reliable datagram streams. The protocol supports datagram fragmentation andreassembly on the 64 streams.The full set of HCI streams may be viewed as shown in Figure 3.1.SCOStreamsACLStreamsStandardHCICmd/EvtTunnelledProtocolsSCOvariablenumberACLvariablenumberHCIFigure 3.1: HCI Streams3.1 Data From the Host: HCI CommandHCI Cmd/Evtup to64HCI_EXTNThe structure of HCI_EXTN data packets from the host fits the standard HCI command pattern as shown inFigure 3.2.Bytes0x000xfcParameterTotal LengthPayloadDescriptor0 1 2 3 4 ...PacketPay................loadParameter Total LengthBlueCore HCI ExtensionsFigure 3.2: Structure of HCI_EXTN Data Packets from HostAs with a normal HCI command, the packet is an integer number of bytes in length. The packet can be between4 and 258 bytes long.The first two bytes, {0x00, 0xfc} are identical to HCI command:{OGF = 0x3f, OCF = 0x00}The opcode group field (OGF) of 0x3f implies a manufacturer-specific HCI command.The “Parameter Total Length” byte is as for a normal HCI command packet. Its value is always 3 less than thetotal number of bytes in the packet.The “Payload Descriptor” byte defines the Payload’s logical channel through HCI and includes fragmentationinformation. This is described below.bcore-sp-009Pa© Copyright CSR 2001-2003This material is subject to CSR’s non-disclosure agreement.Page 5 of 13

Manufacturer-Specific HCI Commands and EventsThe Payload field carries the packet or packet fragment being tunnelled through HCI. This can be between 0 and254 bytes long.3.2 Data to the Host: HCI EventThe structure of HCI_EXTN data packets to the host fits the standard HCI event pattern as shown in Figure 3.3.0xffParameterTotal LengthPayloadDescriptorPay................loadParameter Total LengthBytes0 1 2 3 ...PacketFigure 3.3: Structure of HCI_EXTN Data Packets to HostAs with a normal HCI event, the packet is an integer number of bytes in length. The packet can be between 3 and257 bytes long.The first byte, 0xff, implies the manufacturer-specific HCI event.The “Parameter Total Length” byte is as for a normal HCI event packet. Its value will always be 2 less than thetotal number of bytes in the packet.The “Payload Descriptor” byte defines the Payload’s logical channel through HCI and includes fragmentationinformation. This is described in section 3.3.The Payload field carries the packet being tunnelled through HCI. This can be between 0 and 254 bytes long.3.3 Payload DescriptorThe two types of HCI_EXTN packet each include a “Payload Descriptor” byte. These have the following structure:BitsLastFragmentFirstFragment(msb)7 6 5Channel ID4 321 0Figure 3.4: Payload Descriptor Byte(lsb)BlueCore HCI ExtensionsThe six bit Channel ID field describes the logical data channel being tunnelled through HCI.If the First Fragment bit is 1, then the Payload field carries the first fragment of a packet being passed throughthe channel, else it is a continuation fragment.If the Last Fragment bit is 1, then the Payload field carries the last fragment of a packet being passed throughthe channel, else it is not the last fragment.If the Payload field holds a complete (unfragmented) packet, then both fragmentation bits are set to 1.bcore-sp-009Pa© Copyright CSR 2001-2003This material is subject to CSR’s non-disclosure agreement.Page 6 of 13

Fragmentation4 FragmentationEach HCI_EXTN packet has a maximum payload of 254 bytes. This is too small for some tunnelled protocols, soHCI_EXTN supports fragmentation.Any packet trying to pass through the hci_extn channel may be fragmented and sent as an ordered sequence offragments, each sized to fit HCI_EXTN Payload fields.The Payload Descriptor field provides two Fragment bits:• The first fragment of the ordered sequence must have its Start Fragment bit set to 1.• The last fragment of the ordered sequence must have its End Fragment bit set to 1.• If the original packet is passed through hci_extn as three or more fragments, then fragments betweenthe first and last must have both Fragment bits set to 0.• If the original packet is passed through hci_extn as a single fragment, then both Fragment bits are setto 1.For each hci_extn direction (host-to-chip and chip-to-host), once the first fragment of a packet has been passedinto hci_extn all of the remaining fragments of that packet must be passed before fragments of any other packet.(i.e., fragments from different tunnelled channels must not interleave.)Fragmentation may be used for packets that are smaller than 254 bytes.BlueCore HCI Extensionsbcore-sp-009Pa© Copyright CSR 2001-2003This material is subject to CSR’s non-disclosure agreement.Page 7 of 13

Flow Control5 Flow ControlUnder normal circumstances HCI_EXTN is not concerned with flow control: HCI_EXTN provides a set of parallelreliable bi-directional datagram channels, and assumes each of these channels will handle its own flow control.This is the default case.Under unfortunate circumstances, manufacturer-specific HCI commands may be subject to conventional HCIcommand flow control. In this case, for each HCI_EXTN packet that flows from the host to the chip (HCIcommand packet) a corresponding HCI Command Complete event with the following structure must be sent inthe reverse direction:Num_HCI_Command_PacketsAs for normal HCI Command Complete messagesCommand_Opcode {OGF = 0x3f, OCF = 0x00}Return_ParametersNoneTable 5.1: Flow Control Command Complete EventUse of this flow control mechanism will be enabled by local configuration.BlueCore HCI Extensionsbcore-sp-009Pa© Copyright CSR 2001-2003This material is subject to CSR’s non-disclosure agreement.Page 8 of 13

Tunnelled Channels6 Tunnelled ChannelsThe HCI commands and events defined in section 3 provide up to 64 reliable bi-directional datagram channelsthrough the extended HCI.Each channel has an identifier. The same identifier is used in HCI commands and events for a given channel.Some of the channel identifiers have been allocated as shown in Table 6.1.Channel ID Allocation Notes(a)(b)(c)0, 1 Not available2 BCCMD Defined in [BCCMD]3 HQ Defined in [HQ]4 Device Mgr Lib5, 6, 7 Not available8 L2CAP Lib9 RFCOMM Lib10 SDP Lib11 Not available12 DFU Defined in [DFUPROT]13 VM14 → 19 Unallocated20 LM debug21 → 63 UnallocatedTable 6.1: Channel IdentifiersSome BlueCore firmware builds provide a resource-limited Bluetooth stack on the chip including L2CAP,RFCOMM and SDP. Communication to the tops of these stack elements can pass through this protocol.CCL define these channels’ protocols in [BSTK] and [BCCODE]. The Device Manager channel is CCLproprietary(effectively it is CCL’s “private channel”).Currently used to carry debugging information from the chip. This is for CSR development only, anddetails of this channel will not be published.Channel for communication to/from application code in the VM. Protocol currently undocumented. Thiswill carry application and debug information using multiplexing.(a)(a)(a)(a)(b)(c)(b)BlueCore HCI Extensionsbcore-sp-009Pa© Copyright CSR 2001-2003This material is subject to CSR’s non-disclosure agreement.Page 9 of 13

Notes7 NotesThis section provides some observations on the protocol described above. This section does not form part of thespecification.Most of the standard HCI commands are associated with a Command Complete event, and optionally a set ofCommand Status events. By default, the protocol described above does not follow this convention: an HCI_EXTNHCI Command has no implied related Command Complete event. This means the tunnelled protocols mustprovide their own flow control.The section on Flow Control describes the use of a Command Complete event packet. The description ofCommand Complete event packets in section 5.2.14 of [HCI] does not describe its use with manufacturer-specificHCI commands. It is neither allowed nor prohibited.The section on Flow Control above describes an HCI Command Complete flow control mechanism. This isprovided for systems where the host applies conventional HCI Command flow control to all HCI traffic (includinghci_extn traffic). This is likely to give poor performance,as it effectively imposes a window size of 1 for host tochip traffic (assuming the default maximum Num_HCI_Command_Packets). In BlueCore firmware, this iscurrently controlled by PS Key PSKEY_HOSTIO_USE_HCI_EXTN_CCFC.The protocol allows a maximum packet payload of 254 bytes, but implementations may need to limit packets tosmaller maximum sizes, e.g., to allow low latency on HCI SCO packets.The channel identifiers mirror those used in BCSP, described in [BCSPCHAN].If a BlueCore chip uses a BCSP host interface, the protocol described in this document effectively provides asecond route for the non-standard HostModule channels. It will normally make sense to use only one of theseroutes in a given application, and it may be better to use the BCSP channels. This configuration isapplication-specific. In BlueCore firmware this is currently controlled by PS KeyPSKEY_HOSTIO_USE_HCI_EXTN.Section 5.2.12 of [HCI] suggests (but does not imply) that the first HCI message is a Command Status event,used to indicate that the module is ready to receive HCI commands. The protocol described in this documentmay violate this notion. This will be important if module initialisation is performed over BCCMD, which shouldoccur before standard HCI traffic.Ericsson’s manufacturer-specific HCI extensions continue the standard HCI theme of HCI commands provokingactions on the module and returning HCI events. HCI_EXTN clearly follows a different model. Thecommand/response model does not suit tunnelled protocols that carry bulk data, e.g., to the on-chipimplementation of RFCOMM.BlueCore HCI Extensionsbcore-sp-009Pa© Copyright CSR 2001-2003This material is subject to CSR’s non-disclosure agreement.Page 10 of 13

Document References8 Document ReferencesReferenceDocument[BCCMD][DFUPROT][BCSPCHAN][HCI][HQ][BCCODE]BCCMD Protocol; CSR document bcore-sp-002PBlue Core Device Firmware Upgrade Protocol Specification; CSR document bc01-an-095BCSP Channel Allocation; CSR document bcore-sp-007PHost Computer Interface specification; Section H:1 of [BT]HQ Protocol; CSR document bcore-sp-011PPacket coding procedure on CCL-defined BCSP channels; CCL document AN-002 "Usingthe BlueStack API over BCSP”[BSTK] BlueStack User Manual; CCL document C6066-UM-001 v1.6[BT] Specification of the Bluetooth System, Volume 1, Core, v1.1, 22 February 2001Further ReferencesCSR’s Implementation of HCI on BlueCore; CSR document bcore-me-007PBCCMD Test Commands; CSR document bcore-sp-001PBlueCore HCI Extensionsbcore-sp-009Pa© Copyright CSR 2001-2003This material is subject to CSR’s non-disclosure agreement.Page 11 of 13

Acronyms and DefinitionsAcronyms and DefinitionsBlueCoreBlueLabBlueStackBluetoothACLBCCMDBCSPCCLCSRDFUHCIHCI_EXTNHQL2CAPLSBMSBOCFOGFRFCOMMSCOVMGroup term for CSR’s range of Bluetooth chipsCSR’s software development kit for applications running in BlueCore’s VMCCL’s implementation of the “higher layers” of a Bluetooth stack: L2CAP, SDP andRFCOMMA set of technologies providing audio and data transfer over short-range radioconnectionsAsynchronous Connection-Less. Bluetooth-defined reliable datagram serviceBlueCore Command Protocol, described in [BCCMD].BlueCore Serial ProtocolCambridge Consultants LtdCambridge Silicon Radio LtdDevice Firmware UpgradeHost Controller Interface; part of the Bluetooth specification [BT]The protocol described in this document, providing a set of reliable datagram streamstunnelled through HCI manufacturer-specific extensionsHost Query Protocol; a “private channel” protocol allowing the BlueCore firmware toaccess services on its hostBluetooth-defined reliable datagram serviceLeast Significant BitMost Significant BitOpcode Command FieldOpcode Group FieldBluetooth-defined serial port emulation serviceSynchronous Connection-Oriented. Bluetooth-defined unreliable audio sample streamserviceVirtual Machine; environment in BlueCore firmware for running application-specific codeBlueCore HCI Extensionsbcore-sp-009Pa© Copyright CSR 2001-2003This material is subject to CSR’s non-disclosure agreement.Page 12 of 13

Record of ChangesRecord of ChangesDate Revision Comment08 JAN 03 aDocument originally published as CSR reference bc01-an-067 (revisions athrough c, versions through HCIStack1.1v15.x builds).New revision control number allocated to align with HCIStack1.1v16.x builds.HCI Extensionsbcore-sp-009PaJanuary 2003BlueCore HCI ExtensionsBluetooth and the Bluetooth logos are trademarks owned by Bluetooth SIG Inc, USA and licensed to CSR.BlueCore is a trademark of CSR.All other product, service and company names are trademarks, registered trademarks or service marks of theirrespective owners.CSR’s products are not authorised for use in life-support or safety-critical applications.bcore-sp-009Pa© Copyright CSR 2001-2003This material is subject to CSR’s non-disclosure agreement.Page 13 of 13