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, 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   @param  This          Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
  33   @param  BufferSize    On input, indicates the size, in bytes, of the data buffer specified by Buffer.
  34                         On output, indicates the amount of data actually transferred.
  35   @param  Buffer        A pointer to the buffer of data that will be transmitted to Bluetooth host
  36                         controller.
  37   @param  Timeout       Indicating the transfer should be completed within this time frame. The units are
  38                         in milliseconds. If Timeout is 0, then the caller must wait for the function to
  39                         be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
  40
  41   @retval EFI_SUCCESS           The HCI command packet is sent successfully.
  42   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
  43                                 - BufferSize is NULL.
  44                                 - *BufferSize is 0.
  45                                 - Buffer is NULL.
  46   @retval EFI_TIMEOUT           Sending HCI command packet fail due to timeout.
  47   @retval EFI_DEVICE_ERROR      Sending HCI command packet fail due to host controller or device error.
  48
  49 **/
  50 typedef
  51 EFI_STATUS
  52 (EFIAPI *EFI_BLUETOOTH_HC_SEND_COMMAND)(
  53   IN EFI_BLUETOOTH_HC_PROTOCOL  *This,
  54   IN OUT UINTN                  *BufferSize,
  55   IN VOID                       *Buffer,
  56   IN UINTN                      Timeout
  57   );
  58
  59
  60 /**
  61   Receive HCI event packet.
  62
  63   @param  This          Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
  64   @param  BufferSize    On input, indicates the size, in bytes, of the data buffer specified by Buffer.
  65                         On output, indicates the amount of data actually transferred.
  66   @param  Buffer        A pointer to the buffer of data that will be received from Bluetooth host controller.
  67   @param  Timeout       Indicating the transfer should be completed within this time frame. The units are
  68                         in milliseconds. If Timeout is 0, then the caller must wait for the function to
  69                         be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
  70
  71   @retval EFI_SUCCESS           The HCI event packet is received successfully.
  72   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
  73                                 - BufferSize is NULL.
  74                                 - *BufferSize is 0.
  75                                 - Buffer is NULL.
  76   @retval EFI_TIMEOUT           Receiving HCI event packet fail due to timeout.
  77   @retval EFI_DEVICE_ERROR      Receiving HCI event packet fail due to host controller or device error.
  78
  79 **/
  80 typedef
  81 EFI_STATUS
  82 (EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_EVENT)(
  83   IN EFI_BLUETOOTH_HC_PROTOCOL  *This,
  84   IN OUT UINTN                  *BufferSize,
  85   OUT VOID                      *Buffer,
  86   IN UINTN                      Timeout
  87   );
  88
  89 /**
  90   Callback function, it is called when asynchronous transfer is completed.
  91
  92   @param  Data              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
  93   @param  DataLength        Specifies the length, in bytes, of the data to be received.
  94   @param  Context           Data passed into Callback function. This is optional parameter and may be NULL.
  95
  96   @retval EFI_SUCCESS             The callback function complete successfully.
  97
  98 **/
  99 typedef
 100 EFI_STATUS
 101 (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK) (
 102   IN VOID                       *Data,
 103   IN UINTN                      DataLength,
 104   IN VOID                       *Context
 105   );
 106
 107 /**
 108   Receive HCI event packet in non-blocking way.
 109
 110   @param  This              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
 111   @param  IsNewTransfer     If TRUE, a new transfer will be submitted. If FALSE, the request is deleted.
 112   @param  PollingInterval   Indicates the periodic rate, in milliseconds, that the transfer is to be executed.
 113   @param  DataLength        Specifies the length, in bytes, of the data to be received.
 114   @param  Callback          The callback function. This function is called if the asynchronous transfer is
 115                             completed.
 116   @param  Context           Data passed into Callback function. This is optional parameter and may be NULL.
 117
 118   @retval EFI_SUCCESS           The HCI asynchronous receive request is submitted successfully.
 119   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 120                                 - DataLength is 0.
 121                                 - If IsNewTransfer is TRUE, and an asynchronous receive request already exists.
 122
 123 **/
 124 typedef
 125 EFI_STATUS
 126 (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT)(
 127   IN EFI_BLUETOOTH_HC_PROTOCOL            *This,
 128   IN BOOLEAN                              IsNewTransfer,
 129   IN UINTN                                PollingInterval,
 130   IN UINTN                                DataLength,
 131   IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,
 132   IN VOID                                 *Context
 133   );
 134
 135 /**
 136   Send HCI ACL data packet.
 137
 138   @param  This          Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
 139   @param  BufferSize    On input, indicates the size, in bytes, of the data buffer specified by Buffer.
 140                         On output, indicates the amount of data actually transferred.
 141   @param  Buffer        A pointer to the buffer of data that will be transmitted to Bluetooth host
 142                         controller.
 143   @param  Timeout       Indicating the transfer should be completed within this time frame. The units are
 144                         in milliseconds. If Timeout is 0, then the caller must wait for the function to
 145                         be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 146
 147   @retval EFI_SUCCESS           The HCI ACL data packet is sent successfully.
 148   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 149                                 - BufferSize is NULL.
 150                                 - *BufferSize is 0.
 151                                 - Buffer is NULL.
 152   @retval EFI_TIMEOUT           Sending HCI ACL data packet fail due to timeout.
 153   @retval EFI_DEVICE_ERROR      Sending HCI ACL data packet fail due to host controller or device error.
 154
 155 **/
 156 typedef
 157 EFI_STATUS
 158 (EFIAPI *EFI_BLUETOOTH_HC_SEND_ACL_DATA)(
 159   IN EFI_BLUETOOTH_HC_PROTOCOL  *This,
 160   IN OUT UINTN                  *BufferSize,
 161   IN VOID                       *Buffer,
 162   IN UINTN                      Timeout
 163   );
 164
 165 /**
 166   Receive HCI ACL data packet.
 167
 168   @param  This          Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
 169   @param  BufferSize    On input, indicates the size, in bytes, of the data buffer specified by Buffer.
 170                         On output, indicates the amount of data actually transferred.
 171   @param  Buffer        A pointer to the buffer of data that will be received from Bluetooth host controller.
 172   @param  Timeout       Indicating the transfer should be completed within this time frame. The units are
 173                         in milliseconds. If Timeout is 0, then the caller must wait for the function to
 174                         be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 175
 176   @retval EFI_SUCCESS           The HCI ACL data packet is received successfully.
 177   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 178                                 - BufferSize is NULL.
 179                                 - *BufferSize is 0.
 180                                 - Buffer is NULL.
 181   @retval EFI_TIMEOUT           Receiving HCI ACL data packet fail due to timeout.
 182   @retval EFI_DEVICE_ERROR      Receiving HCI ACL data packet fail due to host controller or device error.
 183
 184 **/
 185 typedef
 186 EFI_STATUS
 187 (EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA)(
 188   IN EFI_BLUETOOTH_HC_PROTOCOL  *This,
 189   IN OUT UINTN                  *BufferSize,
 190   OUT VOID                      *Buffer,
 191   IN UINTN                      Timeout
 192   );
 193
 194
 195 /**
 196   Receive HCI ACL data packet in non-blocking way.
 197
 198   @param  This              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
 199   @param  IsNewTransfer     If TRUE, a new transfer will be submitted. If FALSE, the request is deleted.
 200   @param  PollingInterval   Indicates the periodic rate, in milliseconds, that the transfer is to be executed.
 201   @param  DataLength        Specifies the length, in bytes, of the data to be received.
 202   @param  Callback          The callback function. This function is called if the asynchronous transfer is
 203                             completed.
 204   @param  Context           Data passed into Callback function. This is optional parameter and may be NULL.
 205
 206   @retval EFI_SUCCESS           The HCI asynchronous receive request is submitted successfully.
 207   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 208                                 - DataLength is 0.
 209                                 - If IsNewTransfer is TRUE, and an asynchronous receive request already exists.
 210
 211 **/
 212 typedef
 213 EFI_STATUS
 214 (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA) (
 215   IN EFI_BLUETOOTH_HC_PROTOCOL            *This,
 216   IN BOOLEAN                              IsNewTransfer,
 217   IN UINTN                                PollingInterval,
 218   IN UINTN                                DataLength,
 219   IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,
 220   IN VOID                                 *Context
 221   );
 222
 223 /**
 224   Send HCI SCO data packet.
 225
 226   @param  This          Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
 227   @param  BufferSize    On input, indicates the size, in bytes, of the data buffer specified by Buffer.
 228                         On output, indicates the amount of data actually transferred.
 229   @param  Buffer        A pointer to the buffer of data that will be transmitted to Bluetooth host
 230                         controller.
 231   @param  Timeout       Indicating the transfer should be completed within this time frame. The units are
 232                         in milliseconds. If Timeout is 0, then the caller must wait for the function to
 233                         be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 234
 235   @retval EFI_SUCCESS           The HCI SCO data packet is sent successfully.
 236   @retval EFI_UNSUPPORTED       The implementation does not support HCI SCO transfer.
 237   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 238                                 - BufferSize is NULL.
 239                                 - *BufferSize is 0.
 240                                 - Buffer is NULL.
 241   @retval EFI_TIMEOUT           Sending HCI SCO data packet fail due to timeout.
 242   @retval EFI_DEVICE_ERROR      Sending HCI SCO data packet fail due to host controller or device error.
 243
 244 **/
 245 typedef
 246 EFI_STATUS
 247 (EFIAPI *EFI_BLUETOOTH_HC_SEND_SCO_DATA)(
 248   IN EFI_BLUETOOTH_HC_PROTOCOL  *This,
 249   IN OUT UINTN                  *BufferSize,
 250   IN VOID                       *Buffer,
 251   IN UINTN                      Timeout
 252   );
 253
 254 /**
 255   Receive HCI SCO data packet.
 256
 257   @param  This          Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
 258   @param  BufferSize    On input, indicates the size, in bytes, of the data buffer specified by Buffer.
 259                         On output, indicates the amount of data actually transferred.
 260   @param  Buffer        A pointer to the buffer of data that will be received from Bluetooth host controller.
 261   @param  Timeout       Indicating the transfer should be completed within this time frame. The units are
 262                         in milliseconds. If Timeout is 0, then the caller must wait for the function to
 263                         be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 264
 265   @retval EFI_SUCCESS           The HCI SCO data packet is received successfully.
 266   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 267                                 - BufferSize is NULL.
 268                                 - *BufferSize is 0.
 269                                 - Buffer is NULL.
 270   @retval EFI_TIMEOUT           Receiving HCI SCO data packet fail due to timeout
 271   @retval EFI_DEVICE_ERROR      Receiving HCI SCO data packet fail due to host controller or device error.
 272
 273 **/
 274 typedef
 275 EFI_STATUS
 276 (EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA)(
 277   IN EFI_BLUETOOTH_HC_PROTOCOL  *This,
 278   IN OUT UINTN                  *BufferSize,
 279   OUT VOID                      *Buffer,
 280   IN UINTN                      Timeout
 281   );
 282
 283 /**
 284   Receive HCI SCO data packet in non-blocking way.
 285
 286   @param  This              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
 287   @param  IsNewTransfer     If TRUE, a new transfer will be submitted. If FALSE, the request is deleted.
 288   @param  PollingInterval   Indicates the periodic rate, in milliseconds, that the transfer is to be executed.
 289   @param  DataLength        Specifies the length, in bytes, of the data to be received.
 290   @param  Callback          The callback function. This function is called if the asynchronous transfer is
 291                             completed.
 292   @param  Context           Data passed into Callback function. This is optional parameter and may be NULL.
 293
 294   @retval EFI_SUCCESS           The HCI asynchronous receive request is submitted successfully.
 295   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 296                                 - DataLength is 0.
 297                                 - If IsNewTransfer is TRUE, and an asynchronous receive request already exists.
 298
 299 **/
 300 typedef
 301 EFI_STATUS
 302 (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA) (
 303   IN EFI_BLUETOOTH_HC_PROTOCOL            *This,
 304   IN BOOLEAN                              IsNewTransfer,
 305   IN UINTN                                PollingInterval,
 306   IN UINTN                                DataLength,
 307   IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,
 308   IN VOID                                 *Context
 309   );
 310
 311 ///
 312 /// This protocol abstracts the Bluetooth host controller layer message transmit and receive.
 313 ///
 314 struct _EFI_BLUETOOTH_HC_PROTOCOL {
 315   EFI_BLUETOOTH_HC_SEND_COMMAND               SendCommand;
 316   EFI_BLUETOOTH_HC_RECEIVE_EVENT              ReceiveEvent;
 317   EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT        AsyncReceiveEvent;
 318   EFI_BLUETOOTH_HC_SEND_ACL_DATA              SendACLData;
 319   EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA           ReceiveACLData;
 320   EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA     AsyncReceiveACLData;
 321   EFI_BLUETOOTH_HC_SEND_SCO_DATA              SendSCOData;
 322   EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA           ReceiveSCOData;
 323   EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA     AsyncReceiveSCOData;
 324 };
 325
 326 extern EFI_GUID gEfiBluetoothHcProtocolGuid;
 327
 328 #endif