MdePkg/Include/Protocol/BluetoothHc.h

   1 /** @file
   2   EFI Bluetooth Host Controller Protocol as defined in UEFI 2.5.
   3   This protocol abstracts the Bluetooth host controller layer message transmit and receive.
   4
   5   Copyright (c) 2015 - 2017, Intel Corporation. All rights reserved.<BR>
   6   This program and the accompanying materials are licensed and made available under
   7   the terms and conditions of the BSD License that accompanies this distribution.
   8   The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php.
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14   @par Revision Reference:
  15   This Protocol is introduced in UEFI Specification 2.5
  16
  17 **/
  18
  19 #ifndef __EFI_BLUETOOTH_HC_PROTOCOL_H__
  20 #define __EFI_BLUETOOTH_HC_PROTOCOL_H__
  21
  22 #define EFI_BLUETOOTH_HC_PROTOCOL_GUID \
  23   { \
  24     0xb3930571, 0xbeba, 0x4fc5, { 0x92, 0x3, 0x94, 0x27, 0x24, 0x2e, 0x6a, 0x43 } \
  25   }
  26
  27 typedef struct _EFI_BLUETOOTH_HC_PROTOCOL EFI_BLUETOOTH_HC_PROTOCOL;
  28
  29 /**
  30   Send HCI command packet.
  31
  32   The SendCommand() function sends HCI command packet. Buffer holds the whole HCI
  33   command packet, including OpCode, OCF, OGF, parameter length, and parameters. When
  34   this function is returned, it just means the HCI command packet is sent, it does not mean
  35   the command is success or complete. Caller might need to wait a command status event
  36   to know the command status, or wait a command complete event to know if the
  37   command is completed.
  38
  39   @param[in]      This              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
  40   @param[in,out]  BufferSize        On input, indicates the size, in bytes, of the data buffer
  41                                     specified by Buffer. On output, indicates the amount of
  42                                     data actually transferred.
  43   @param[in]      Buffer            A pointer to the buffer of data that will be transmitted to
  44                                     Bluetooth host controller.
  45   @param[in]      Timeout           Indicating the transfer should be completed within this
  46                                     time frame. The units are in milliseconds. If Timeout is 0,
  47                                     then the caller must wait for the function to be completed
  48                                     until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
  49
  50   @retval EFI_SUCCESS               The HCI command packet is sent successfully.
  51   @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:
  52                                       BufferSize is NULL.
  53                                       *BufferSize is 0.
  54                                       Buffer is NULL.
  55   @retval EFI_TIMEOUT               Sending HCI command packet fail due to timeout.
  56   @retval EFI_DEVICE_ERROR          Sending HCI command packet fail due to host controller or device
  57                                     error.
  58
  59 **/
  60 typedef
  61 EFI_STATUS
  62 (EFIAPI *EFI_BLUETOOTH_HC_SEND_COMMAND)(
  63   IN EFI_BLUETOOTH_HC_PROTOCOL      *This,
  64   IN OUT UINTN                      *BufferSize,
  65   IN VOID                           *Buffer,
  66   IN UINTN                          Timeout
  67   );
  68
  69 /**
  70   Receive HCI event packet.
  71
  72   The ReceiveEvent() function receives HCI event packet. Buffer holds the whole HCI event
  73   packet, including EventCode, parameter length, and parameters.
  74
  75   @param[in]      This              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
  76   @param[in,out]  BufferSize        On input, indicates the size, in bytes, of the data buffer
  77                                     specified by Buffer. On output, indicates the amount of
  78                                     data actually transferred.
  79   @param[out]     Buffer            A pointer to the buffer of data that will be received from
  80                                     Bluetooth host controller.
  81   @param[in]      Timeout           Indicating the transfer should be completed within this
  82                                     time frame. The units are in milliseconds. If Timeout is 0,
  83                                     then the caller must wait for the function to be completed
  84                                     until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
  85
  86   @retval EFI_SUCCESS               The HCI event packet is received successfully.
  87   @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:
  88                                       BufferSize is NULL.
  89                                       *BufferSize is 0.
  90                                       Buffer is NULL.
  91   @retval EFI_TIMEOUT               Receiving HCI event packet fail due to timeout.
  92   @retval EFI_DEVICE_ERROR          Receiving HCI event packet fail due to host controller or device
  93                                     error.
  94
  95 **/
  96 typedef
  97 EFI_STATUS
  98 (EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_EVENT)(
  99   IN EFI_BLUETOOTH_HC_PROTOCOL      *This,
 100   IN OUT UINTN                      *BufferSize,
 101   OUT VOID                          *Buffer,
 102   IN UINTN                          Timeout
 103   );
 104
 105 /**
 106   The async callback of AsyncReceiveEvent().
 107
 108   @param[in]  Data                  Data received via asynchronous transfer.
 109   @param[in]  DataLength            The length of Data in bytes, received via asynchronous
 110                                     transfer.
 111   @param[in]  Context               Context passed from asynchronous transfer request.
 112
 113   @retval EFI_SUCCESS               The callback does execute successfully.
 114   @retval Others                    The callback doesn't execute successfully.
 115
 116 **/
 117 typedef
 118 EFI_STATUS
 119 (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK) (
 120   IN VOID                           *Data,
 121   IN UINTN                          DataLength,
 122   IN VOID                           *Context
 123   );
 124
 125 /**
 126   Receive HCI event packet in non-blocking way.
 127
 128   The AsyncReceiveEvent() function receives HCI event packet in non-blocking way. Data
 129   in Callback function holds the whole HCI event packet, including EventCode, parameter
 130   length, and parameters.
 131
 132   @param[in]  This                  Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
 133   @param[in]  IsNewTransfer         If TRUE, a new transfer will be submitted. If FALSE, the
 134                                     request is deleted.
 135   @param[in]  PollingInterval       Indicates the periodic rate, in milliseconds, that the
 136                                     transfer is to be executed.
 137   @param[in]  DataLength            Specifies the length, in bytes, of the data to be received.
 138   @param[in]  Callback              The callback function. This function is called if the
 139                                     asynchronous transfer is completed.
 140   @param[in]  Context               Data passed into Callback function. This is optional
 141                                     parameter and may be NULL.
 142
 143   @retval EFI_SUCCESS               The HCI asynchronous receive request is submitted successfully.
 144   @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:
 145                                       DataLength is 0.
 146                                       If IsNewTransfer is TRUE, and an asynchronous receive
 147                                       request already exists.
 148 **/
 149 typedef
 150 EFI_STATUS
 151 (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT) (
 152   IN EFI_BLUETOOTH_HC_PROTOCOL              *This,
 153   IN BOOLEAN                                IsNewTransfer,
 154   IN UINTN                                  PollingInterval,
 155   IN UINTN                                  DataLength,
 156   IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK   Callback,
 157   IN VOID                                   *Context
 158   );
 159
 160 /**
 161   Send HCI ACL data packet.
 162
 163   The SendACLData() function sends HCI ACL data packet. Buffer holds the whole HCI ACL
 164   data packet, including Handle, PB flag, BC flag, data length, and data.
 165
 166   The SendACLData() function and ReceiveACLData() function just send and receive data
 167   payload from application layer. In order to protect the payload data, the Bluetooth bus is
 168   required to call HCI_Set_Connection_Encryption command to enable hardware based
 169   encryption after authentication completed, according to pairing mode and host
 170   capability.
 171
 172   @param[in]       This             Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
 173   @param[in, out]  BufferSize       On input, indicates the size, in bytes, of the data buffer
 174                                     specified by Buffer. On output, indicates the amount of
 175                                     data actually transferred.
 176   @param[in]       Buffer           A pointer to the buffer of data that will be transmitted to
 177                                     Bluetooth host controller.
 178   @param[in]       Timeout          Indicating the transfer should be completed within this
 179                                     time frame. The units are in milliseconds. If Timeout is 0,
 180                                     then the caller must wait for the function to be completed
 181                                     until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 182
 183   @retval EFI_SUCCESS               The HCI ACL data packet is sent successfully.
 184   @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:
 185                                       BufferSize is NULL.
 186                                       *BufferSize is 0.
 187                                       Buffer is NULL.
 188   @retval EFI_TIMEOUT               Sending HCI ACL data packet fail due to timeout.
 189   @retval EFI_DEVICE_ERROR          Sending HCI ACL data packet fail due to host controller or device
 190                                     error.
 191
 192 **/
 193 typedef
 194 EFI_STATUS
 195 (EFIAPI *EFI_BLUETOOTH_HC_SEND_ACL_DATA)(
 196   IN EFI_BLUETOOTH_HC_PROTOCOL      *This,
 197   IN OUT UINTN                      *BufferSize,
 198   IN VOID                           *Buffer,
 199   IN UINTN                          Timeout
 200   );
 201
 202 /**
 203   Receive HCI ACL data packet.
 204
 205   The ReceiveACLData() function receives HCI ACL data packet. Buffer holds the whole HCI
 206   ACL data packet, including Handle, PB flag, BC flag, data length, and data.
 207
 208   @param[in]       This             Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
 209   @param[in, out]  BufferSize       On input, indicates the size, in bytes, of the data buffer
 210                                     specified by Buffer. On output, indicates the amount of
 211                                     data actually transferred.
 212   @param[out]      Buffer           A pointer to the buffer of data that will be received from
 213                                     Bluetooth host controller.
 214   @param[in]       Timeout          Indicating the transfer should be completed within this
 215                                     time frame. The units are in milliseconds. If Timeout is 0,
 216                                     then the caller must wait for the function to be completed
 217                                     until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 218
 219   @retval EFI_SUCCESS               The HCI ACL data packet is received successfully.
 220   @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:
 221                                       BufferSize is NULL.
 222                                       *BufferSize is 0.
 223                                       Buffer is NULL.
 224   @retval EFI_TIMEOUT               Receiving HCI ACL data packet fail due to timeout.
 225   @retval EFI_DEVICE_ERROR          Receiving HCI ACL data packet fail due to host controller or device
 226                                     error.
 227
 228 **/
 229 typedef
 230 EFI_STATUS
 231 (EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA)(
 232   IN EFI_BLUETOOTH_HC_PROTOCOL      *This,
 233   IN OUT UINTN                      *BufferSize,
 234   OUT VOID                          *Buffer,
 235   IN UINTN                          Timeout
 236   );
 237
 238 /**
 239   Receive HCI ACL data packet in non-blocking way.
 240
 241   The AsyncReceiveACLData() function receives HCI ACL data packet in non-blocking way.
 242   Data in Callback holds the whole HCI ACL data packet, including Handle, PB flag, BC flag,
 243   data length, and data.
 244
 245   @param[in]  This                  Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
 246   @param[in]  IsNewTransfer         If TRUE, a new transfer will be submitted. If FALSE, the
 247                                     request is deleted.
 248   @param[in]  PollingInterval       Indicates the periodic rate, in milliseconds, that the
 249                                     transfer is to be executed.
 250   @param[in]  DataLength            Specifies the length, in bytes, of the data to be received.
 251   @param[in]  Callback              The callback function. This function is called if the
 252                                     asynchronous transfer is completed.
 253   @param[in]  Context               Data passed into Callback function. This is optional
 254                                     parameter and may be NULL.
 255
 256   @retval EFI_SUCCESS               The HCI asynchronous receive request is submitted successfully.
 257   @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:
 258                                       DataLength is 0.
 259                                       If IsNewTransfer is TRUE, and an asynchronous receive
 260                                       request already exists.
 261 **/
 262 typedef
 263 EFI_STATUS
 264 (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA) (
 265   IN EFI_BLUETOOTH_HC_PROTOCOL              *This,
 266   IN BOOLEAN                                IsNewTransfer,
 267   IN UINTN                                  PollingInterval,
 268   IN UINTN                                  DataLength,
 269   IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK   Callback,
 270   IN VOID                                   *Context
 271   );
 272
 273 /**
 274   Send HCI SCO data packet.
 275
 276   The SendSCOData() function sends HCI SCO data packet. Buffer holds the whole HCI SCO
 277   data packet, including ConnectionHandle, PacketStatus flag, data length, and data.
 278
 279   @param[in]      This              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
 280   @param[in,out]  BufferSize        On input, indicates the size, in bytes, of the data buffer
 281                                     specified by Buffer. On output, indicates the amount of
 282                                     data actually transferred.
 283   @param[in]      Buffer            A pointer to the buffer of data that will be transmitted to
 284                                     Bluetooth host controller.
 285   @param[in]      Timeout           Indicating the transfer should be completed within this
 286                                     time frame. The units are in milliseconds. If Timeout is 0,
 287                                     then the caller must wait for the function to be completed
 288                                     until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 289
 290   @retval EFI_SUCCESS               The HCI SCO data packet is sent successfully.
 291   @retval EFI_UNSUPPORTED           The implementation does not support HCI SCO transfer.
 292   @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:
 293                                       BufferSize is NULL.
 294                                       *BufferSize is 0.
 295                                       Buffer is NULL.
 296   @retval EFI_TIMEOUT               Sending HCI SCO data packet fail due to timeout.
 297   @retval EFI_DEVICE_ERROR          Sending HCI SCO data packet fail due to host controller or device
 298                                     error.
 299 **/
 300 typedef
 301 EFI_STATUS
 302 (EFIAPI *EFI_BLUETOOTH_HC_SEND_SCO_DATA)(
 303   IN EFI_BLUETOOTH_HC_PROTOCOL      *This,
 304   IN OUT UINTN                      *BufferSize,
 305   IN VOID                           *Buffer,
 306   IN UINTN                          Timeout
 307   );
 308
 309 /**
 310   Receive HCI SCO data packet.
 311
 312   The ReceiveSCOData() function receives HCI SCO data packet. Buffer holds the whole HCI
 313   SCO data packet, including ConnectionHandle, PacketStatus flag, data length, and data.
 314
 315   @param[in]      This              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
 316   @param[in,out]  BufferSize        On input, indicates the size, in bytes, of the data buffer
 317                                     specified by Buffer. On output, indicates the amount of
 318                                     data actually transferred.
 319   @param[out]     Buffer            A pointer to the buffer of data that will be received from
 320                                     Bluetooth host controller.
 321   @param[in]      Timeout           Indicating the transfer should be completed within this
 322                                     time frame. The units are in milliseconds. If Timeout is 0,
 323                                     then the caller must wait for the function to be completed
 324                                     until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 325
 326   @retval EFI_SUCCESS               The HCI SCO data packet is received successfully.
 327   @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:
 328                                       BufferSize is NULL.
 329                                       *BufferSize is 0.
 330                                       Buffer is NULL.
 331   @retval EFI_TIMEOUT               Receiving HCI SCO data packet fail due to timeout.
 332   @retval EFI_DEVICE_ERROR          Receiving HCI SCO data packet fail due to host controller or device
 333                                     error.
 334 **/
 335 typedef
 336 EFI_STATUS
 337 (EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA)(
 338   IN EFI_BLUETOOTH_HC_PROTOCOL      *This,
 339   IN OUT UINTN                      *BufferSize,
 340   OUT VOID                          *Buffer,
 341   IN UINTN                          Timeout
 342   );
 343
 344 /**
 345   Receive HCI SCO data packet in non-blocking way.
 346
 347   The AsyncReceiveSCOData() function receives HCI SCO data packet in non-blocking way.
 348   Data in Callback holds the whole HCI SCO data packet, including ConnectionHandle,
 349   PacketStatus flag, data length, and data.
 350
 351   @param[in]  This                  Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
 352   @param[in]  IsNewTransfer         If TRUE, a new transfer will be submitted. If FALSE, the
 353                                     request is deleted.
 354   @param[in]  PollingInterval       Indicates the periodic rate, in milliseconds, that the
 355                                     transfer is to be executed.
 356   @param[in]  DataLength            Specifies the length, in bytes, of the data to be received.
 357   @param[in]  Callback              The callback function. This function is called if the
 358                                     asynchronous transfer is completed.
 359   @param[in]  Context               Data passed into Callback function. This is optional
 360                                     parameter and may be NULL.
 361
 362   @retval EFI_SUCCESS               The HCI asynchronous receive request is submitted successfully.
 363   @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:
 364                                       DataLength is 0.
 365                                       If IsNewTransfer is TRUE, and an asynchronous receive
 366                                       request already exists.
 367 **/
 368 typedef
 369 EFI_STATUS
 370 (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA) (
 371   IN EFI_BLUETOOTH_HC_PROTOCOL              *This,
 372   IN BOOLEAN                                IsNewTransfer,
 373   IN UINTN                                  PollingInterval,
 374   IN UINTN                                  DataLength,
 375   IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK   Callback,
 376   IN VOID                                   *Context
 377   );
 378
 379 //
 380 // The EFI_BLUETOOTH_HC_PROTOCOL is used to transmit or receive HCI layer data packets.
 381 //
 382 struct _EFI_BLUETOOTH_HC_PROTOCOL {
 383   //
 384   // Send HCI command packet.
 385   //
 386   EFI_BLUETOOTH_HC_SEND_COMMAND               SendCommand;
 387   //
 388   // Receive HCI event packets.
 389   //
 390   EFI_BLUETOOTH_HC_RECEIVE_EVENT              ReceiveEvent;
 391   //
 392   // Non-blocking receive HCI event packets.
 393   //
 394   EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT        AsyncReceiveEvent;
 395   //
 396   // Send HCI ACL (asynchronous connection-oriented) data packets.
 397   //
 398   EFI_BLUETOOTH_HC_SEND_ACL_DATA              SendACLData;
 399   //
 400   // Receive HCI ACL data packets.
 401   //
 402   EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA           ReceiveACLData;
 403   //
 404   // Non-blocking receive HCI ACL data packets.
 405   //
 406   EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA     AsyncReceiveACLData;
 407   //
 408   // Send HCI synchronous (SCO and eSCO) data packets.
 409   //
 410   EFI_BLUETOOTH_HC_SEND_SCO_DATA              SendSCOData;
 411   //
 412   // Receive HCI synchronous data packets.
 413   //
 414   EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA           ReceiveSCOData;
 415   //
 416   // Non-blocking receive HCI synchronous data packets.
 417   //
 418   EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA     AsyncReceiveSCOData;
 419 };
 420
 421 extern EFI_GUID gEfiBluetoothHcProtocolGuid;
 422
 423 #endif
 424