BlueStack User Manual

Transcription

1 BlueStack User Manual

2 General Information General Information Ownership of Information Mezoe 2001 (Mezoe is a division of Cambridge Consultants Ltd) All information contained in this document is owned by Mezoe and should not be copied or reused for any purpose. Trademarks BlueStack is a trademark of Mezoe that is registered in the United Kingdom StackPrimer is a trademark of Mezoe Proto Developer is a trademark of Mezoe Interface Express is a trademark of Mezoe Mezoe is a trademark of Cambridge Consultants Ltd. CCL is a trademark of Cambridge Consultants Ltd that is registered in the United Kingdom and Germany Bluetooth is a trademark owned by the Bluetooth SIG, Inc. and used by Mezoe under license Bluecore is a trademark of Cambridge Silicon Radio All other trademarks are acknowledged as owned by their respective proprietors Confidentiality This document contains confidential information that is proprietary to Mezoe. This information must only be used for its intended purpose and should not be disclosed to third parties. Fitness for Purpose and Liability Mezoe makes no warranty of any kind with regard to the information contained in this document, expressed or implied, including but not limited to implied warranties of fitness for purpose or satisfactory quality. Mezoe does not warrant that the Software to which this document refers or this document itself is error free or suitable for use in safety-critical applications. The user shall take full responsibility for ensuring that the Software and the document is suitable for the user s intended purposes and for its subsequent use. Mezoe does not accept any liability for any loss or damage arising from the use of this document or the information within it, howsoever caused, including but not limited to direct, indirect, unforeseen or consequential loss or damage, other than death or personal injury resulting from Mezoe s proven negligence. Contact Mezoe Mezoe, Cambridge Consultants Ltd Science park Milton Road Cambridge CB4 0DW UK Tel. +44 (0) Fax. +44 (0) bluetooth@mezoe.com

3 Contents Contents Contents 3 List of Figures 11 List of Tables 12 1 Introduction Audience In This Document About this Manual Finding Your Way Around Conventions Getting More Information 17 2 Overview Introducing BlueStack BlueStack as a Software Component Standard Two-Processor Solution Embedded Two-Processor Solution Wholly Embedded Solution The Application Interface to BlueStack Scheduler and BlueStack Initialisation Memory Management Functions HCI Transport Driver Configuration Scheduler Services BlueStack Layers Link Manager L2CAP Device Manager Service Discovery RFCOMM TCS Binary Host Controller Interface Internal Communications Model Adopted for BlueStack Interface Library Functions Registration and phandles Error Handling and Debug Facilities Management Entity Partitioning Porting and Building 36 3 BlueStack Application Interface Overview Key Concepts The Scheduler Inter-process Communication, Messaging and Events Communications Services Timed Events Configurability and Tuners Application Interface Functions Initialisation BST_InitScheduler BST_ConfigureStack BST_StartScheduler BST_sched_protect_tasks BST_ReconfigurePool

4 Contents BST_InitHCIdrv BST_HCIdrv_enum_drivers BST_HCIdrv_select_driver BST_HCIdrv_get_current_driver BST_HCIdrv_query_driver_available BST_HCIdrv_get_driver_name BST_HCIdrv_get_driver_description BST_HCIdrv_get_driver_id Application Interface Functions Scheduler Services BST_putMessage BST_getMessage BST_put_message_at BST_put_message_in BST_cancel_timed_message BST_timed_event_at BST_timed_event_in BST_cancel_timed_event BST_get_time BST_sched_claim_task_mutex BST_sched_release_task_mutex BST_CallbackOnPanic Application Interface Functions Memory Management BST_pmalloc BST_pfree BST_zpmalloc BST_xpmalloc BST_xzpmalloc BST_RFC_DLC_malloc BST_prealloc BST_xprealloc BST_pcopy BST_xpcopy BST_pstrdup BST_xpstrdup Application Interface Functions Utilities bd_addr_copy bd_addr_zero bd_addr_eq BST_ReportPoolStats BST_ReportPoolUsage BST_SendWatchText BST_send_watch_text BST_get_config_string BST_get_scheduler_identifier Usage Scenarios and Examples Scheduler and BlueStack Initialisation Sending Messages Getting Messages Callback on Panic 71 4 RFCOMM Overview Key Concepts Mux ID Local Server Channel

5 Contents RFCOMM Flow Control Configurability and Tuners RFCOMM API Primitives RFC_INIT RFC_REGISTER RFC_START RFC_STARTCMP RFC_CLOSE RFC_PARNEG RFC_ESTABLISH RFC_RELEASE RFC_CONTROL RFC_PORTNEG RFC_FCON RFC_FCOFF RFC_DATA RFC_DATAWRITE RFC_LINESTATUS RFC_TEST RFC_NSC Usage Scenarios and Examples Starting and Configuring a Multiplexer Session As an Initiator Starting and Configuring a Multiplexer Session As a Recipient Opening a Server Channel and Negotiating Service Discovery Protocol Overview of SDP and its API Service Discovery Client (SDC) Interface Service Discovery Server (SDS) Interface Key Concepts within SDP Service Record Formats Configurability and Tuners SDP API Primitives SDC SDC_SERVICE_SEARCH SDC_SERVICE_ATTRIBUTE SDC_SERVICE_SEARCH_ATTRIBUTE SDC_TERMINATE_PRIMITIVE SDC_OPEN_SEARCH SDC_CLOSE_SEARCH SDC_CONFIG SDP API Primitives SDS SDS_REGISTER SDS_UNREGISTER SDS_CONFIG Usage Scenarios and Examples Service Registration Service Search Request Service Attribute Request TCS Overview Key Concepts Attach SCO Bearer Call Management Connectionless Call Management

6 Contents Group Management Memory Management TCS Constraints Race Conditions / Multiple Resources Configurability and Tuners TCS API Primitives TCS_REGISTER TCS_UNREGISTER TCS_ATTACH TCS_PREATTACH TCS_DETACH TCS_SETUP TCS_CL_SETUP TCS_INFO TCS_CALL_PROCEEDING TCS_ALERTING TCS_OPEN_SCO TCS_CONNECT TCS_PROGRESS TCS_DISCONNECT TCS_RELEASING TCS_RELEASED TCS_CL_RELEASE TCS_CL_RELEASED TCS_START_DTMF TCS_STOP_DTMF TCS_ACCESS_RIGHTS TCS_WUG_INFO TCS_LISTEN_REQUEST TCS_LISTEN_SUGGEST TCS_LISTEN_QUERY TCS_CL_INFO L2CAP Overview of L2CAP and its API Key Concepts PSM CID MTU RTX ERTX Configurability and Tuners L2CAP API Primitives L2CA_REGISTER L2CA_CONNECT L2CA_CONFIG L2CA_DATAWRITE L2CA_DATAREAD L2CA_DISCONNECT L2CA_TIMEOUT L2CA_QOSVIOLATION L2CA_PING L2CA_GETINFO L2CA_GROUP_CREATE L2CA_GROUP_CLOSE

7 Contents L2CA_ENABLE_CONNECTIONLESS L2CA_DISABLE_CONNECTIONLESS Usage Scenarios and Examples Registration Connection Establishment and Configuration Outgoing Connection Establishment and Configuration Incoming Data Transfer Disconnection Local Initiation Disconnection Remote Initiation Device Manager Overview Key Concepts Device Discoverability and Inquiry Security Manager Link Policy ACL Link Management SCO Flow Control Local Name Parameter Caching Configurability and Tuners Device Manager API Primitives General Device Manager API Primitives Application Manager Related DM_AM_REGISTER DM_WRITE_CACHED_PAGE_MODE DM_WRITE_CACHED_CLOCK_OFFSET DM_CLEAR_PARAM_CACHE Device Manager API Primitives Link Control DM_HCI_INQUIRY DM_HCI_INQUIRY_RESULT DM_HCI_INQUIRY_COMPLETE DM_HCI_INQUIRY_CANCEL DM_HCI_INQUIRY_CANCEL_COMPLETE DM_HCI_CHANGE_PACKET_TYPE DM_HCI_CHANGE_LINK_KEY DM_HCI_MASTER_LINK_KEY DM_HCI_REMOTE_NAME_REQUEST DM_HCI_READ_REMOTE_FEATURES DM_HCI_READ_REMOTE_VERSION DM_HCI_READ_CLOCK_OFFSET DM_HCI_REMOTE_NAME_COMPLETE Device Manager API Primitives Link Policy DM_SET_DEFAULT_LINK_POLICY DM_HCI_WRITE_LP_SETTINGS DM_HCI_WRITE_LP_SETTINGS_COMPLETE DM_HCI_READ_LP_SETTINGS DM_HCI_READ_LP_SETTINGS_COMPLETE DM_HCI_PARK_MODE DM_HCI_EXIT_PARK_MODE DM_HCI_HOLD_MODE DM_HCI_SNIFF_MODE DM_HCI_EXIT_SNIFF_MODE DM_HCI_ROLE_DISCOVERY DM_HCI_SWITCH_ROLE

8 Contents 8.8 Device Manager API Primitives Host Controller and Baseband DM_HCI_CHANGE_LOCAL_NAME DM_HCI_CHANGE_LOCAL_NAME_COMPLETE DM_HCI_WRITE_SCAN_ENABLE DM_HCI_WRITE_CURRENT_IAC_LAP DM_HCI_FLUSH DM_HCI_READ_AUTO_FLUSH_TIMEOUT DM_HCI_WRITE_AUTO_FLUSH_TIMEOUT DM_HCI_READ_TX_POWER_LEVEL DM_HCI_READ_SCO_FLOW_CONTROL_ENABLE DM_HCI_WRITE_SCO_FLOW_CONTROL_ENABLE DM_HCI_READ_LINK_SUPERV_TIMEOUT DM_HCI_WRITE_LINK_SUPERV_TIMEOUT Device Manager API Primitives Status DM_HCI_FAILED_CONTACT_COUNTER DM_HCI_RESET_CONTACT_COUNTER DM_HCI_GET_LINK_QUALITY DM_HCI_READ_RSSI Device Manager API Primitives SCO Control Related DM_SCO_INCOMING_REGISTER DM_SCO_INCOMING_UNREGISTER DM_SCO_CONNECT DM_SCO_DISCONNECT DM_SCO_BUFFER_SIZE DM_SCO_ DATA_SENT Device Manager API Primitives Security Manager Related DM_SM_PIN_REQUEST DM_SM_LINK_KEY_REQUEST DM_SM_SET_DEFAULT_SECURITY DM_SM_REGISTER DM_SM_REGISTER_OUTGOING DM_SM_UNREGISTER DM_SM_UNREGISTER_OUTGOING DM_SM_ACCESS DM_SM_SET_SEC_MODE_REQ DM_SM_ADD_DEVICE_REQ DM_SM_REMOVE_DEVICE DM_SM_AUTHORISE DM_SM_AUTHENTICATE DM_SM_ENCRYPT DM_SM_ENCRYPTION_CHANGE ACL link management and monitoring DM_ACL_OPEN DM_ACL_OPENED_IND DM_ACL_CLOSED_IND Usage Scenarios and Examples Registration SCO Connection Establishment Inquiry Limited Discoverability Mode HCI Transport HCI Top Interface Overview

9 Contents 9.2 Downstream SCO Data Interface HCI_Send_SCO_Data_Packet Example Upstream SCO Data Interface HCI_SCO_DATA_PACKET Example SCO data application management UART Driver Function Interface and USB Interface 301 Annex A Writing a Port Entity 302 A.1 Overview 302 A.2 Example Action Functions 308 Send_Start_Req 308 Send_ParNeg_Req 309 Send_Establish_Req 310 Send_Close_Req 310 Send_Established_ok 310 Send_Data 310 Read_Data 311 Store_Data 311 Close_Connection 311 Annex B Error Codes 313 B.1 GENERAL_ERROR 313 B.2 RFCOMM_ERROR 313 B.3 L2CAP_ERROR 313 B.4 DM_ERROR 314 B.5 HCI_ERROR 314 B.6 LM_ERROR 314 B.7 SDP_ERROR 314 B.8 CS_ERROR 314 Annex C Changes in this version 315 C.1 General 315 C.2 Introduction 315 C.3 Overview 315 C.4 BlueStack Application Interface 315 C.5 RFCOMM 315 C.6 SDP 315 C.7 TCS 316 C.8 L2CAP 316 C.9 Device Manager 316 C.10 HCI Transport 317 C.11 Annex A Writing a port entity 317 C.12 Annex B Error Codes 317 Glossary 318 event 318 Big Endian 318 downstream 318 host 318 host controller 318 phandle 318 server channel 318 upstream

10 Contents Acronyms

11 Contents List of Figures Figure 2-1: Bluetooth Protocol Stack as Specified by the Bluetooth SIG...18 Figure 2-2: BlueStack Protocols Layers...19 Figure 2-3: Layers Required in an Application Running over Bluetooth...20 Figure 2-4: Showing the relationship between the Application Interface to BlueStack (bluestack.h) and the Interface Library Functions Figure 2-5: Three Integration Approaches Illustrated...22 Figure 2-6: RFCOMM Devices Type 1 and Type Figure 2-7: HCI showing physical split between Host and Host Controller...29 Figure 2-8: Use of Primitives with Layered Protocols...30 Figure 2-9: Protocol Message Construction Within a Layered Architecture...30 Figure 2-10: Management Entity in the Integrated Application...35 Figure 3-1: The Application Interface to BlueStack Figure 3-2: Illustration of Event Handling and Message Passing...40 Figure 3-3: Primitive Definition Format...41 Figure 4-1: RFCOMM Overview Architecture...73 Figure 4-2: MUX and Service Channel Relationship Example...74 Figure 4-3: RFCOMM Credit-based Flow Control, successful negotiation...75 Figure 4-4: RFCOMM Credit-based Flow Control, unsuccessful negotiation...76 Figure 4-5: Updating flow control with no user data...77 Figure 4-6: Starting a Multiplexer Session As an Initiator Figure 4-7: Starting a Multiplexer Session As a Recipient Figure 4-8: Opening a Server Channel and Negotiating Figure 5-1: Service Record Attribute List Figure 5-2: Service Record Structure Figure 5-3: Service Registration Figure 5-4: COM1 Service Record Example Figure 5-5: Service Search Request Figure 5-6: Service Attribute Request Figure 6-1: TCS Binary Relationship to Other Entities Figure 6-2: Cordless Telephony Application supporting multiple profiles Figure 6-3: Cordless Telephony Scenario Figure 7-1: Registration Figure 7-2: Connection Establishment Outgoing Figure 7-3: Connection Establishment Incoming Figure 7-4: Data Transfer Figure 7-5: Disconnection Local Initiation Figure 7-6: Disconnection Remote Initiation Figure 8-1: Device Manager Interfaces Figure 8-2: SCO Control Entity Credit Counter Figure 8-3: Registration Example Figure 8-4: SCO Connection Establishment Figure 8-5: Inquiry Figure 8-6: Inquiry Flowchart Figure 9-1: HCI Transport Component Relationship Figure 9-2: SCO Control and Data Flows Figure 9-3: Layers Required in an Application Running over Bluetooth Figure 9-4: Differences in Data Transfer Figure 9-5: Port Entity Phases Figure 9-6: Port Entity Application to RFCOMM Calls Figure 9-7: Message Exchange Figure 9-8: Basic Flow Control

12 Contents List of Tables Table 2-1: Allowable BlueStack Partitioning Combinations...36 Table 4-1: RFC_INIT Primitives...79 Table 4-2: RFC_REGISTER Primitives...80 Table 4-3: RFC_START Primitives...81 Table 4-4: RFC_STARTCMP Primitive...83 Table 4-5: RFC_CLOSE Primitives...85 Table 4-6: RFC_PARNEG Primitives...86 Table 4-7: RFC_ESTABLISH Primitives...88 Table 4-8: RFC_RELEASE Primitive...90 Table 4-9: RFC_CONTROL Primitives...91 Table 4-10: Mapping From the Control Signal Octet by a Receiving Entity...92 Table 4-11: Mapping To the Control Signal Octet by a Sending Entity...92 Table 4-12: RFC_PORTNEG Primitives...93 Table 4-13: RFC_FCON Primitives...96 Table 4-14: RFC_FCOFF Primitives...97 Table 4-15: RFC_DATA Primitives...98 Table 4-16: RFC_DATAWRITE Primitives...99 Table 4-17: RFC_LINESTATUS Primitives Table 4-18: RFC_TEST Primitives Table 4-19: RFC_NSC Primitive Table 5-1: Data Types from Bluetooth Specification Table 5-2: Size Indexes from Bluetooth Specification Table 5-3: SDC_SERVICE_SEARCH Primitives Table 5-4: SDC_SERVICE_ATTRIBUTE Primitives Table 5-5: SDC_SERVICE_SEARCH_ATTRIBUTE Primitives Table 5-6: SDC_TERMINATE_PRIMITIVE Primitives Table 5-7: SDC_OPEN_SEARCH Primitives Table 5-8: SDC_CLOSE_SEARCH Primitive Table 5-9: SDC_CONFIG Primitive Table 5-10: SDS_REGISTER Primitives Table 5-11: SDS_UNREGISTER Primitives Table 5-12: SDS_CONFIG Primitive Table 5-13: Serial Port Profile Service Database Entries Table 6-1: TCS Primitives and wug_master Flag Relationship Table 6-2: TCS_REGISTER Primitives Table 6-3: TCS_UNREGISTER Primitives Table 6-4: TCS_ATTACH Primitives Table 6-5: TCS_ PRE_ATTACH Primitives Table 6-6: TCS_DETACH Primitives Table 6-7: TCS_SETUP Primitives Table 6-8: TCS_CL_SETUP Primitives Table 6-9: TCS_INFO Primitives Table 6-10: TCS_CALL_PROCEEDING Primitives Table 6-11: TCS_ALERTING Primitives Table 6-12: TCS_OPEN_SCO Primitives Table 6-13: TCS_CONNECT Primitives Table 6-14: TCS_PROGRESS Primitives Table 6-15: TCS_DISCONNECT Primitives Table 6-16: TCS_RELEASING Primitives Table 6-17: TCS_RELEASED Primitives Table 6-18: TCS_CL_RELEASE Primitive Table 6-19: TCS_CL_RELEASED Primitive

13 Contents Table 6-20: TCS_START_DTMF Primitives Table 6-21: TCS_STOP_DTMF Primitives Table 6-22: TCS_ACCESS_RIGHTS Primitives Table 6-23: TCS_WUG_INFO Primitives Table 6-24: TCS_LISTEN_REQUEST Primitives Table 6-25: TCS_LISTEN_SUGGEST Primitives Table 6-26: TCS_LISTEN_QUERY Primitives Table 6-27: TCS_CL_INFO Primitives Table 7-1: L2CA_REGISTER Primitives Table 7-2: L2CA_CONNECT Primitives Table 7-3: L2CA_CONFIG Primitives Table 7-4: L2CA_DATAWRITE Primitives Table 7-5: L2CA_DATAREAD Primitives Table 7-6: L2CA_DISCONNECT Primitives Table 7-7: L2CA_TIMEOUT Primitives Table 7-8: L2CA_QOSVIOLATION Primitives Table 7-9: L2CA_PING Primitives Table 7-10: L2CA_GETINFO Primitives Table 7-11: L2CA_GROUP_CREATE Primitives Table 7-12: L2CA_GROUP_CLOSE Primitives Table 7-13: L2CA_ENABLE_CONNECTIONLESS Primitives Table 7-14: L2CA_DISABLE_CONNECTIONLESS Primitives Table 8-1: DM_AM_REGISTER Primitives Table 8-2: DM_WRITE_CACHED_PAGE_MODE Primitives Table 8-3: DM_WRITE_CACHED_CLOCK_OFFSET Primitives Table 8-4: DM_CLEAR_PARAM_CACHE Primitives Table 8-5: DM_HCI_INQUIRY Primitive Table 8-6: DM_HCI_INQUIRY_RESULT Primitive Table 8-7: DM_HCI_INQUIRY_COMPLETE Primitive Table 8-8: DM_HCI_INQUIRY_CANCEL Primitive Table 8-9: DM_HCI_INQUIRY_CANCEL_COMPLETE Primitive Table 8-10: DM_HCI_CHANGE_PACKET_TYPE Primitive Table 8-11: DM_HCI_CHANGE_LINK_KEY Primitive Table 8-12: DM_HCI_MASTER_LINK_KEY Primitive Table 8-13: DM_HCI_REMOTE_NAME_REQUEST Primitive Table 8-14: DM_HCI_READ_REMOTE_FEATURES Primitive Table 8-15: DM_HCI_READ_REMOTE_VERSION Primitive Table 8-16: DM_HCI_READ_CLOCK_OFFSET Primitive Table 8-17: DM_HCI_REMOTE_NAME_COMPLETE Primitive Table 8-18: DM_SET_DEFAULT_LINK_POLICY Primitive Table 8-19: DM_HCI_WRITE_LP_SETTINGS Primitive Table 8-20: DM_HCI_WRITE_LP_SETTINGS_COMPLETE Primitive Table 8-21: DM_HCI_READ_LP_SETTINGS Primitive Table 8-22: DM_HCI_READ_LP_SETTINGS_COMPLETE Primitive Table 8-23: DM_HCI_PARK_MODE Primitive Table 8-24: DM_HCI_EXIT_PARK_MODE Primitive Table 8-25: DM_HCI_HOLD_MODE Primitive Table 8-26: DM_HCI_SNIFF_MODE Primitive Table 8-27: DM_HCI_EXIT_SNIFF_MODE Primitive Table 8-28: DM_HCI_ROLE_DISCOVERY Primitive Table 8-29: DM_HCI_SWITCH_ROLE Primitive Table 8-30: DM_HCI_CHANGE_LOCAL_NAME Primitive Table 8-31: DM_HCI_CHANGE_LOCAL_NAME_COMPLETE Primitive Table 8-32: DM_HCI_WRITE_SCAN_ENABLE Primitive Table 8-33: DM_HCI_WRITE_CURRENT_IAC_LAP Primitive

14 Contents Table 8-34: DM_HCI_FLUSH Primitive Table 8-35: DM_HCI_READ_AUTO_FLUSH_TIMEOUT Primitive Table 8-36: DM_HCI WRITE_AUTO_FLUSH_TIMEOUT Primitive Table 8-37: DM_HCI_READ_TX_POWER_LEVEL Primitive Table 8-38: DM_HCI_READ_SCO_FLOW_CONTROL_ENABLE Primitive Table 8-39: DM_HCI_WRITE_SCO_FLOW_CONTROL_ENABLE Primitive Table 8-40: DM_HCI_READ_LINK_SUPERV_TIMEOUT Primitive Table 8-41: DM_HCI_WRITE_LINK_SUPERV_TIMEOUT Primitive Table 8-42: DM_HCI_FAILED_CONTACT_COUNTER Primitive Table 8-43: DM_HCI_RESET_CONTACT_COUNTER Primitive Table 8-44: DM_HCI_GET_LINK_QUALITY Primitive Table 8-45: DM_HCI_READ_RSSI Primitive Table 8-46: DM_SCO_INCOMING_REGISTER primitive Table 8-47: DM_SCO_INCOMING_UNREGISTER primitive Table 8-48: DM_SCO_CONNECT Primitive Table 8-49: DM_SCO_DISCONNECT Primitives Table 8-50: DM_SCO_BUFFER_SIZE Primitive Table 8-51: DM_SCO_DATA_SENT Primitive Table 8-52: DM_SM_PIN_REQUEST Primitive Table 8-53: DM_SM_LINK_KEY_REQUEST Primitive Table 8-54: DM_SM_SET_DEFAULT_SECURITY Primitives Table 8-55: DM_SM_REGISTER Primitives Table 8-56: DM_SM_REGISTER_OUTGOING_REQ Primitives Table 8-57: DM_SM_UNREGISTER Primitives Table 8-58: DM_SM_UNREGISTER_OUTGOING Primitives Table 8-59: DM_SM_ACCESS Primitives Table 8-60: DM_SM_SET_SEC_MODE Primitives Table 8-61: DM_SM_ADD_DEVICE Primitives Table 8-62: DM_SM_REMOVE_DEVICE Primitives Table 8-63: DM_SM_AUTHORISE Primitive Table 8-64: DM_AUTHENTICATE Primitive Table 8-65: DM_SM_ENCRYPT Primitive Table 8-66: DM_SM_ENCRYPTION_CHANGE Primitive Table 8-67: DM_ACL_OPEN Primitives Table 8-68: DM_ACL_OPENED_IND Primitive Table 8-69: DM_ACL_CLOSED_IND Primitive Table 9-1: HCI_SCO_DATA_PACKET Table 9-2: Message Exchange State Table

15 Introduction 1 Introduction This chapter describes the BlueStack User Guide and the conventions used within. It contains the following sections: ΠAudience on page 15 ΠIn This Document on page 15 ΠConventions on page Audience This User Guide is written for systems and product developers who want to incorporate BlueStack as a software component into their designs. The Guide assumes that the reader is familiar with C, the language BlueStack is written in. It is assumed that the reader is familiar with the basic Bluetooth concepts; it is possible to apply BlueStack without a need for a detailed understanding of the Bluetooth specification. Different sections of the manual are applicable to different application areas. Consequently, product developers can omit sections that are not relevant to them. 1.2 In This Document This document is the user s guide to BlueStack, the Bluetooth protocol software developed by Mezoe. It provides an overview of BlueStack that covers the design philosophy of the software and the Application Programming Interfaces (APIs). It does not provide a detailed description of the design of the individual software sub-systems that comprise BlueStack, nor does it describe the operation of Bluetooth About this Manual Each of the API s is described in detail. The information provided for the API primitives is illustrated with individual examples. Examples are also included for more complicated scenarios. This User Guide does not describe in detail how to design a Bluetooth system, nor does it provide any sample applications. Sample applications are included with Proto Developer for BlueStack (the BlueStack software development toolkit) Finding Your Way Around We have provided some guideposts within the document concerning the relevancy of sections - see Conventions on page 16 for details. It is suggested that you begin by reading the Overview on page 18 if you are new to BlueStack. Once you become familiar with the overall philosophy, you can concentrate on those detailed sections that are of direct relevance

16 Introduction The BlueStack User Guide contains the following sections: Introduction on page 15 An overview of the BlueStack User Guide Overview on page 18 An overview of BlueStack and its various components. BlueStack Application Interface on page 37 RFCOMM on page 72 Service Discovery Protocol on page 111 TCS on page 136 L2CAP on page 194 Device Manager on page 219 HCI Transport on page 293 Annex A Writing a Port Entity on page 302 Annex B Error Codes on page 313 Annex C Changes in this version on page 315 Glossary on page 315 An overview of the BlueStack Application Interface and an introduction to the API. An overview of RFCOMM - a protocol that provides serial port emulation over the L2CAP protocol - and an introduction to its API. An overview of SDP and an introduction to its API. An overview of TCS the Telephony Control Specification (also know as TCS binary) - and an introduction to its API. An overview of L2CAP - the Logical Link Control and Adaptation Protocol - and an introduction to its API. An overview of the Device Manager - the management functions that relate to the Management aspects of Bluetooth. An introduction to the DM API is also provided. An overview of the HCI transport function and an introduction to its associated APIs. A description of the process of writing a Port Entity, along with a simple model. A list of the error codes that BlueStack can return at its API s A list of the changes made to this document since its last formal release. A list of terms and acronyms associated with BlueStack, which have been used throughout this document. 1.3 Conventions The following conventions are used in the BlueStack User Guide: Narrative text is always in the Arial font. Example C code is in the Courier New font. Note: Where possible, the example C code can be compiled and executed. The Times New Roman font is used for illustrative text, for example pseudo code. This text is also indented. Italicized text is used to indicate a note of explanation and is accompanied with the note symbol. The warning symbol is used to draw to the reader s attention where a situation could occur that could result in an undesirable side effect. This is accompanied by text in bold

17 Introduction The light bulb symbol is used to indicate an idea or hint that the reader may find useful. This text is also italicized. The C code includes both source code (.c) and header (.h) files. The header files: ΠΠdeclare all the necessary information to provide the interface to the functionality provided by an identically named.c file. define the interface parameters ( primitives ) of a protocol layer interface. For all files there is a naming convention adopted whereby the file is preceded with an identifier that shows the owning layer. For example l2cap_prim.h is the primitive header file for L2CAP. Common files are not preceded with an identifier. There are a number of different product s that can be realised using BlueStack. Within the manual the following symbols are used to identify sections that are of particular relevance to product designers Getting More Information The Bluetooth website, contains the Bluetooth specification, profiles and other documents relevant to Bluetooth. General information regarding BlueStack, Proto Developer for BlueStack 1, Interface Express 2 and other Bluetooth products from Mezoe can be found on the Mezoe website Technical support is available to licensees of BlueStack. The address is bluetooth@mezoe.com. Cambridge Consultants Ltd. can provide design services on a contract basis to those people requiring professional assistance with the design and/or development of Bluetooth products. For further information, visit the CCL website: Further information on the BlueCore single-chip solution, which is used in some examples in this manual, can be obtained from Cambridge Silicon Radio, 1 Proto Developer is a software toolkit to assist you developing with BlueStack. 2 Interface Express provides an application abstraction for BlueStack tailored to the Bluetooth profiles. It also provides Bluetooth management functions that expand the capability of the BlueStack Device Manager

18 Overview 2 Overview This chapter introduces the Bluetooth protocol stack and the BlueStack layers. The different s of products that can incorporate BlueStack as a component are also discussed. It contains the following sections: ΠIntroducing BlueStack on page 18 ΠBlueStack as a Software Component on page 19 ΠThe Application Interface to BlueStack on page 23 ΠBlueStack Layers on page 26 ΠInternal Communications Model Adopted for BlueStack on page 29 ΠError Handling and Debug Facilities on page 34 ΠRegistration and phandles on page 33 ΠManagement Entity on page 34 ΠPartitioning on page 36 ΠPorting and Building on page Introducing BlueStack The layered model proposed by the Bluetooth Special Interest Group (SIG) is shown in Figure 2-1. The shaded boxes indicate the layers defined in version 1.1 of the Bluetooth specification. Figure 2-1: Bluetooth Protocol Stack as Specified by the Bluetooth SIG

19 Overview BlueStack is a software implementation in C of the Bluetooth protocol stack, as shown in Figure 2-2 on page 19. It has been designed to be applicable to a wide range of Bluetooth applications. It does not include Obex 1, WAP, VCal or VCard. TCS Binary RFCOMM SDP L2CAP Device Mgr HCI Top HCI Upper driver HCI lower driver HCI bottom Link Manager Baseband and RF Figure 2-2: BlueStack Protocols Layers BlueStack introduces the Device Manager. This provides a number of stack management functions, such as security management, and allows access to the HCI command and event interface. 2.2 BlueStack as a Software Component BlueStack is a software component that is designed to allow product developers to incorporate Bluetooth functionality within their products. BlueStack is supplied with the following elements: Device Manager (DM) SDP RFCOMM TCS L2CAP HCI Top HCI Upper Driver (H:4 or BCSP) Scheduler services 1 Supplied as part of Interface Express from Mezoe

20 Overview BlueStack is intended to be used in conjunction with Bluetooth hardware. Since the HCI is a standard interface, BlueStack works with Bluetooth hardware from a range of silicon vendors. The BlueStack HCI Bottom and Link Manager are not supplied as standard as part of BlueStack. HCI Bottom and the Link Manager have been implemented for the BlueCore 1 single chip device from Cambridge Silicon Radio, however they can be ported to other silicon vendors host controller devices please contact Mezoe at Bluetooth@mezoe.com for further information if you need to incorporate the BlueStack Link Manager in your design and wish to purchase it. See also page 26. As a software component, BlueStack requires integrating with other software to realise a complete product. Typically, this software is some form of application. It may be an existing application, or a completely new application. The integration model adopted for BlueStack is based on integrating the stack with an application. The integration can be carried out in an integration layer, which sits between the application and BlueStack. An example of such an integration layer is defined in the serial port profile, the Port Entity. This sits between the Application and RFCOMM. Application Layer Application BT App Integration Layer Port Entity Application Management Entity Profile Specific Layer RFCOMM Bluetooth Generic Stack Layers SDP L2CAP and Device Manager HCI Link Manager Baseband and Link Control Figure 2-3: Layers Required in an Application Running over Bluetooth RFCOMM is a profile specific layer. For example, when developing a Bluetooth cordless telephone that meets the interoperability requirements laid down in the Cordless Telephony profile, TCS binary would be used as the profile specific layer, and not RFCOMM. The examples in this User Guide use applications that run over RFCOMM. In Figure 2-3 RFCOMM is the Port Entity - this is the integration layer between RFCOMM and the application. When the application is wholly new, the application could be designed to interface directly to the RFCOMM API. However, in many cases the application already exists, 1 BlueCore is a Trademark of Cambridge Silicon Radio Ltd

21 Overview so the Port Entity is introduced to adapt the RFCOMM API to the form required by the application. The integration layer can also provide the adaptation between the application s environment and the BlueStack operating environment. BlueStack is designed to be portable. Part of the porting decision that a designer must make is whether to wholly integrate each of the host-resident software subsystems ( layers ) into the host operating system. However, an easier alternative is to take the environment of BlueStack - the scheduler and memory manager - and to port them with the host layers onto the host. Porting is dealt with in detail in the document BlueStack Porting Guide. Access to the BlueStack operating environment services, and hence to the BlueStack APIs, is via the interface defined in the file bluestack.h. This is referred to as the Application Interface to BlueStack and is further described in the section The Application Interface to BlueStack on page 23. Application and Integration Layer RFCOMM Lib SDP Lib DM Lib bluestack.h RFCOMM SDP BlueStack Operating Environment L2CAP Device Mgr HCI Top Figure 2-4: Showing the relationship between the Application Interface to BlueStack (bluestack.h) and the Interface Library Functions. The application can access the APIs directly, using the operating environment services provided by bluestack.h, or can access the APIs using the Interface Library Functions. The relationship between the Application Interface and the Interface Library Functions is shown in Figure 2-4. The Interface Library Functions are described further on page 32. The exact integration approach taken also depends on the of product being developed. For example, performance will be different depending on the integration approach adopted. Broadly speaking, there are three categories of products that designers might consider: ΠΠtwo-processor standard solutions involving a host and host controller, where the higher layers have to be ported to and implemented on the host, the physical split at the Bluetooth - defined HCI (for example, a PC-based application) two-processor embedded solutions where the split between host and embedded (host) controller does not take place at the HCI (for example, an embedded host with limited resources, such as a mobile phone)

22 Overview Πwholly embedded single processor solutions, where there is no external host, for example, a wireless headset The protocol layer models for the different categories can be represented as shown in Figure 2-5. Application Port Entity RFCOMM Service Discovery L2CAP HCI Device Manager Application Port Entity Application APPLICATION INTERFACE RFCOMM SDP RFCOMM SDP L2CAP Device Manager L2CAP Device Manager HCI HCI HCI LINK MANAGER LINK MANAGER Drivers LINK MANAGER BASEBAND and RF BASEBAND and RF Hardware BASEBAND and RF Standard Two-Processor Architecture Embedded Two-Processor Architecture Wholly-Embedded Single- Processor Architecture Figure 2-5: Three Integration Approaches Illustrated Standard Two-Processor Solution For the standard two-processor solution, where the split between higher and lower layers of the stack takes place at the HCI, it is assumed that the host is a personal computer of some description. However, in general this category can include any computing platform with communications capability that is not resource limited Embedded Two-Processor Solution The embedded two-processor category is a feature of BlueStack demonstrated by BlueCore. This allows products to be designed that incorporate Bluetooth, where the host is resource limited and cannot readily support the addition of the Bluetooth functionality. One such example is a mobile phone; not all mobile phones have the spare resources to readily implement additional protocol stacks Wholly Embedded Solution The wholly embedded solution, for example a single chip Bluetooth product, also shows where the additional hardware drivers sit within the architecture. One example is of a cordless headset, however the model is equally applicable to any small wireless device that would benefit from a single processor solution

23 Overview 2.3 The Application Interface to BlueStack The application interface to BlueStack is defined in the file bluestack.h. This file #includes all the header files required to define the application interfaces that are needed to access the individual layer APIs. An overview of the individual layers is given in the section BlueStack Layers that starts on page 26. The services provided via this interface allow the application to: initialise the scheduler and BlueStack access the memory management functions configure the driver for the HCI transport layer use the scheduler services such as message passing and timed events. This section provides an overview for each of these services. A full description of the functions that comprise this interface can be found in the section BlueStack Application Interface that starts on page 37. The same application interface is used both for the portable code of BlueStack, and the BlueStack library supplied with Proto Developer. This allows users to develop code using Proto Developer, in conjunction with the Microsoft Developer Studio and Visual C++ tools. Developing products using Proto Developer is described in the Proto Developer User Guide Scheduler and BlueStack Initialisation The scheduler and BlueStack initialisation services allow the application to control the start up of the scheduler and BlueStack. Specifically, the application: initialises the scheduler initialises the HCI transport driver configures BlueStack and starts the scheduler running. The configuration of BlueStack controls which BlueStack layers have been implemented on the host. This configuration code does NOT control the configuration of any higher layers that are implemented in firmware on the host controller device. Hence the configuration of the layers on the host must reflect the configuration of the firmware on the host controller. If there is a mis-match in the configuration code between the host and the host controller then the protocol software may behave in a unpredictable manner. Configuring BlueStack via the Application Interface does not control which layers are present within the build, and which are absent. For example, if an application requires RFCOMM and not TCS Binary, then it is possible to build BlueStack without TCS Binary, thus saving memory. In this case, if any configuration settings are made for TCS Binary via the Application Interface, then they will be ignored. Additionally, the dynamic configuration of the resources assigned to the memory manager can be selected, provided that this option has been set up by use of the compiler flag PMALLOC_DYNAMIC_LINK. Further configuration options allow the protection of tasks using mutex

24 Overview The function calls are described in detail in the section BlueStack Application Interface on page 37. Within that section is an example scenario for Scheduler and BlueStack Initialisation on page Memory Management Functions The memory manager is a library that provides a pool of memory blocks that are available for the dynamic allocation of storage. The memory management functions primarily allow the application to access the same memory management services that the BlueStack protocol software uses. Thus an application can allocate, using pmalloc(), and free memory blocks, using pfree(); typically allocating memory blocks for downstream messages and freeing the memory blocks of received upstream messages once the data has been dealt with (consumed). The memory manager services also include a number of utility functions that: allocate memory and set the contents to zero, and report the memory pool status. Optionally, the memory pool configuration can be modified dynamically during BlueStack initialisation as described on page 44. With the source code portable version of BlueStack, this task is normally carried out by editing the appropriate files prior to building the code. Further details are given in the document BlueStack Porting Guide. The memory manager library is not a true malloc()-style memory allocator - it does not obtain memory from any underlying operating system nor does it perform defragmentation of returned memory HCI Transport Driver Configuration The HCI Transport driver configuration allows the application to set up the driver for the HCI Transport. The functions available via the Application Interface allow the application to: find the identifier for the next available driver, select a driver, initialise the selected driver, find the identifier of any installed drivers, then query for a specific driver, obtain the driver s name and its description and obtain the identifier of a driver from its name. The HCI Transport itself is described in the section HCI Transport on page

25 Overview Scheduler Services Tbe BlueStack protocol software uses a lightweight scheduler to co-ordinate the execution of the stack layers. The scheduler has many similarities to a STREAMS 1 scheduler and is therefore well suited for use with protocol stacks. The scheduler is designed to be portable. There are two options for the porting of the scheduler, either as the sole operating system or as an adaptation layer to work within another operating system environment. The scheduler provides a single-threaded co-operative non pre-emptive multi-tasking environment. This places a requirement on the programmers to ensure that the length of any single task execution time is as short as possible so that control is returned to the scheduler as soon as possible. If tasks take too long to execute, it results in buffer overflows, which could cause the stack to miss events. Where there is a possibility that a single task may take too long to execute, it can usually be broken down into several shorter tasks. In this case, the software module posts a message back to itself via the scheduler queue, to ensure that the scheduler calls it again to continue the execution later. A direct consequence of the use of this simple scheduler is that there can be no blocking calls. These cause the stack to halt. The BlueStack interface philosophy follows on from the use of the scheduler; the APIs to the layers cannot block. A message passing method is used where a message is sent to a particular task via the scheduler, using a queue identifier as the destination. Queue identifiers are set up for the tasks at build time and are part of the scheduler configuration. The protocol stack layer queues are pre-assigned to tasks at build time. Queue identifiers are also referred to within the software as protocol handles, or phandles. For the higher layers of BlueStack, a registration procedure is used whereby the phandle of the upper layer is registered with the lower layer before communication starts. This is to allow the dynamic configuration of protocol stacks. Phandles are dealt with in detail in Registration and phandles on page 33. The scheduler executes the tasks that have messages pending. It is up to the software module to pull the message or messages from the queue and to act on them. The result of this is that the BlueStack protocol stack is message driven. The scheduler provides timer support. Timer support is hardware dependent and any port to a different platform needs to take this fact into consideration. 1 STREAMS was originally developed as a framework for communications services under Unix

26 Overview 2.4 BlueStack Layers This section provides an overview for each of the BlueStack layers. Within BlueStack, the protocol layers above the HCI: L2CAP, SDP, RFCOMM and Device Manager, are referred to as the Higher Layers and the layers below the HCI: Link Manager and Link Controller, are referred to as the Lower Layers Link Manager The Link Manager implements the Link Management Protocol (LMP) as defined by the Bluetooth SIG. The Link Manager is not supplied as standard with BlueStack and is included here only for completeness. The Link Manager is responsible for the establishment of Asynchronous ConnectionLess (ACL) and Synchronous Connection Oriented (SCO) links and as a consequence, is also responsible for both Paging and Page Scanning. Similarly, it is responsible for the initiation and control of Inquiry and Inquiry Scanning, plus Hold, Sniff and Park modes. Authentication and encryption is controlled by the Link Manager, which includes the implementation of the authentication algorithms. The Link Manager also implements the event filters. Event filters are mechanisms specified by the Bluetooth SIG to allow automatic link establishment without reference to the higher layers. The event filters constrain which links can be established without higher layer intervention. There is no direct API provided for the control of the Link Manager from the application. Control of the Link Manager from the application may be achieved indirectly using the HCI calls that are available via the Device Manager API. The Link Manager layer is not covered in detail in this User Guide L2CAP L2CAP implements the Logical Link Control and Adaptation Protocol (L2CAP) as defined by the Bluetooth SIG. The purpose of L2CAP is to provide connection oriented and connectionless data services to higher layer protocols. In order to do this, it provides: ΠΠΠmultiplexing of higher layer protocols segmentation and re-assembly of large data packets establishment and maintenance of logical connections between L2CAP entities Although the L2CAP protocol layer is used by both SDP and RFCOMM, it can also support other services above it. Therefore, there is an API defined to allow developers to use L2CAP with transport services other than RFCOMM applications. L2CAP is probably of little interest to developers who are developing applications that only use RFCOMM and SDP Device Manager For BlueStack, the Bluetooth protocol model has been expanded to include the Device Manager. This is part of the management entity, which is discussed in more detail later in this overview (Management Entity on page 34). The Device Manager is a collection of functions that relate to the management aspects of Bluetooth. These functions include resource management, which is responsible for ensuring that the available resources (typically at the air interface) are not over-allocated to the different applications, which can all make service requests independently of each other

27 Overview Device specific (silicon vendor dependent) management is not a function of the Device Manager. However the HCI interface can be readily extended to incorporate the required functionality and the Management Entity may interface directly to the extension. The Device Manager API is provided to allow more sophisticated control of the Bluetooth stack. This is an API that allows Bluetooth-aware applications to exploit the full capabilities of Bluetooth. For example, Bluetooth Inquiries should be handled via this API. It is not necessary to write an integration layer that explicitly uses the HCI commands via the Device Manager interface much of the service provision is managed by the Device Manager in response to requests made to L2CAP Service Discovery SDP is the implementation of the Service Discovery Protocol, as defined by the Bluetooth SIG. It consists of the Service Discovery Database for the device and subsequently, the Service Discovery Server and the Service Discovery Client. The Service Discovery API provides both Server and Client interfaces. The Server interface is used for the registration of services in the Service Discovery Database. The local Client interface allows an application, sometimes referred to as the Service Discovery Application, to browse for services on a remote device. SDP does not include this application RFCOMM RFCOMM implements the RFCOMM protocol as defined by the Bluetooth SIG. RFCOMM is a protocol that provides an emulation of serial ports over the L2CAP protocol, including the transfer of the state of non-data circuits, for example RS-232 Clear to Send (CTS). The RFCOMM architecture supports two device s (see Figure 2-6): ΠΠType 1 is a communication end point, such as a computer. Type 2 is a device that is part of a communication segment such as a modem. The Port Emulation Entity (PEE) maps a system specific communication interface (API) to the RFCOMM services. The Port Proxy Entity (PPE) relays data from RFCOMM to an external serial interface, for example RS-232, linked to a Data Communication Equipment (DCE), such as a modem