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