MdePkg/Include/Protocol/BluetoothIo.h

   1 /** @file
   2   EFI Bluetooth IO Service Binding Protocol as defined in UEFI 2.5.
   3   EFI Bluetooth IO Protocol as defined in UEFI 2.5.
   4   The EFI Bluetooth IO Service Binding Protocol is used to locate EFI Bluetooth IO Protocol drivers to
   5   create and destroy child of the driver to communicate with other Bluetooth device by using Bluetooth IO protocol.
   6
   7   Copyright (c) 2015 - 2017, Intel Corporation. All rights reserved.<BR>
   8   SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10   @par Revision Reference:
  11   This Protocol is introduced in UEFI Specification 2.5
  12
  13 **/
  14
  15 #ifndef __EFI_BLUETOOTH_IO_PROTOCOL_H__
  16 #define __EFI_BLUETOOTH_IO_PROTOCOL_H__
  17
  18 #include <IndustryStandard/Bluetooth.h>
  19
  20 #define EFI_BLUETOOTH_IO_SERVICE_BINDING_PROTOCOL_GUID \
  21   { \
  22     0x388278d3, 0x7b85, 0x42f0, { 0xab, 0xa9, 0xfb, 0x4b, 0xfd, 0x69, 0xf5, 0xab } \
  23   }
  24
  25 #define EFI_BLUETOOTH_IO_PROTOCOL_GUID \
  26   { \
  27     0x467313de, 0x4e30, 0x43f1, { 0x94, 0x3e, 0x32, 0x3f, 0x89, 0x84, 0x5d, 0xb5 } \
  28   }
  29
  30 typedef struct _EFI_BLUETOOTH_IO_PROTOCOL EFI_BLUETOOTH_IO_PROTOCOL;
  31
  32 ///
  33 /// EFI_BLUETOOTH_DEVICE_INFO
  34 ///
  35 typedef struct {
  36   ///
  37   /// The version of the structure
  38   ///
  39   UINT32                      Version;
  40   ///
  41   /// 48bit Bluetooth device address.
  42   ///
  43   BLUETOOTH_ADDRESS           BD_ADDR;
  44   ///
  45   /// Bluetooth PageScanRepetitionMode. See Bluetooth specification for detail.
  46   ///
  47   UINT8                       PageScanRepetitionMode;
  48   ///
  49   /// Bluetooth ClassOfDevice. See Bluetooth specification for detail.
  50   ///
  51   BLUETOOTH_CLASS_OF_DEVICE   ClassOfDevice;
  52   ///
  53   /// Bluetooth CloseOffset. See Bluetooth specification for detail.
  54   ///
  55   UINT16                      ClockOffset;
  56   ///
  57   /// Bluetooth RSSI. See Bluetooth specification for detail.
  58   ///
  59   UINT8                       RSSI;
  60   ///
  61   /// Bluetooth ExtendedInquiryResponse. See Bluetooth specification for detail.
  62   ///
  63   UINT8                       ExtendedInquiryResponse[240];
  64 } EFI_BLUETOOTH_DEVICE_INFO;
  65
  66 /**
  67   Get Bluetooth device information.
  68
  69   @param[in]   This               Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
  70   @param[out]  DeviceInfoSize     A pointer to the size, in bytes, of the DeviceInfo buffer.
  71   @param[out]  DeviceInfo         A pointer to a callee allocated buffer that returns Bluetooth device information.
  72
  73   @retval EFI_SUCCESS             The Bluetooth device information is returned successfully.
  74   @retval EFI_DEVICE_ERROR        A hardware error occurred trying to retrieve the Bluetooth device information.
  75
  76 **/
  77 typedef
  78 EFI_STATUS
  79 (EFIAPI *EFI_BLUETOOTH_IO_GET_DEVICE_INFO)(
  80   IN EFI_BLUETOOTH_IO_PROTOCOL    *This,
  81   OUT UINTN                       *DeviceInfoSize,
  82   OUT VOID                        **DeviceInfo
  83   );
  84
  85 /**
  86   Get Bluetooth SDP information.
  87
  88   @param[in]  This                Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
  89   @param[out] SdpInfoSize         A pointer to the size, in bytes, of the SdpInfo buffer.
  90   @param[out] SdpInfo             A pointer to a callee allocated buffer that returns Bluetooth SDP information.
  91
  92   @retval EFI_SUCCESS             The Bluetooth device information is returned successfully.
  93   @retval EFI_DEVICE_ERROR        A hardware error occurred trying to retrieve the Bluetooth SDP information.
  94
  95 **/
  96 typedef
  97 EFI_STATUS
  98 (EFIAPI *EFI_BLUETOOTH_IO_GET_SDP_INFO)(
  99   IN EFI_BLUETOOTH_IO_PROTOCOL    *This,
 100   OUT UINTN                       *SdpInfoSize,
 101   OUT VOID                        **SdpInfo
 102   );
 103
 104 /**
 105   Send L2CAP message (including L2CAP header).
 106
 107   @param[in]      This            Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
 108   @param[in, out] BufferSize      On input, indicates the size, in bytes, of the data buffer specified by Buffer.
 109                                   On output, indicates the amount of data actually transferred.
 110   @param[in]      Buffer          A pointer to the buffer of data that will be transmitted to Bluetooth L2CAP layer.
 111   @param[in]      Timeout         Indicating the transfer should be completed within this time frame. The units are in
 112                                   milliseconds. If Timeout is 0, then the caller must wait for the function to be completed
 113                                   until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 114
 115   @retval EFI_SUCCESS             The L2CAP message is sent successfully.
 116   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 117                                   - BufferSize is NULL.
 118                                   - *BufferSize is 0.
 119                                   - Buffer is NULL.
 120   @retval EFI_TIMEOUT             Sending L2CAP message fail due to timeout.
 121   @retval EFI_DEVICE_ERROR        Sending L2CAP message fail due to host controller or device error.
 122
 123 **/
 124 typedef
 125 EFI_STATUS
 126 (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_RAW_SEND)(
 127   IN EFI_BLUETOOTH_IO_PROTOCOL      *This,
 128   IN OUT UINTN                      *BufferSize,
 129   IN VOID                           *Buffer,
 130   IN UINTN                          Timeout
 131   );
 132
 133 /**
 134   Receive L2CAP message (including L2CAP header).
 135
 136   @param[in]  This                Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
 137   @param[in]  BufferSize          On input, indicates the size, in bytes, of the data buffer specified by Buffer.
 138                                   On output, indicates the amount of data actually transferred.
 139   @param[out] Buffer              A pointer to the buffer of data that will be received from Bluetooth L2CAP layer.
 140   @param[in]  Timeout             Indicating the transfer should be completed within this time frame. The units are in
 141                                   milliseconds. If Timeout is 0, then the caller must wait for the function to be completed
 142                                   until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 143
 144   @retval EFI_SUCCESS             The L2CAP message is received successfully.
 145   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 146                                   - BufferSize is NULL.
 147                                   - *BufferSize is 0.
 148                                   - Buffer is NULL.
 149   @retval EFI_TIMEOUT             Receiving L2CAP message fail due to timeout.
 150   @retval EFI_DEVICE_ERROR        Receiving L2CAP message fail due to host controller or device error.
 151
 152 **/
 153 typedef
 154 EFI_STATUS
 155 (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_RAW_RECEIVE)(
 156   IN EFI_BLUETOOTH_IO_PROTOCOL  *This,
 157   IN OUT UINTN                  *BufferSize,
 158   OUT VOID                      *Buffer,
 159   IN UINTN                      Timeout
 160   );
 161
 162 /**
 163   Callback function, it is called when asynchronous transfer is completed.
 164
 165   @param[in]  ChannelID         Bluetooth L2CAP message channel ID.
 166   @param[in]  Data              Data received via asynchronous transfer.
 167   @param[in]  DataLength        The length of Data in bytes, received via asynchronous transfer.
 168   @param[in]  Context           Context passed from asynchronous transfer request.
 169
 170   @retval EFI_SUCCESS           The callback function complete successfully.
 171
 172 **/
 173 typedef
 174 EFI_STATUS
 175 (EFIAPI *EFI_BLUETOOTH_IO_ASYNC_FUNC_CALLBACK) (
 176   IN UINT16                     ChannelID,
 177   IN VOID                       *Data,
 178   IN UINTN                      DataLength,
 179   IN VOID                       *Context
 180   );
 181
 182 /**
 183   Receive L2CAP message (including L2CAP header) in non-blocking way.
 184
 185   @param[in]  This                Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
 186   @param[in]  IsNewTransfer       If TRUE, a new transfer will be submitted. If FALSE, the request is deleted.
 187   @param[in]  PollingInterval     Indicates the periodic rate, in milliseconds, that the transfer is to be executed.
 188   @param[in]  DataLength          Specifies the length, in bytes, of the data to be received.
 189   @param[in]  Callback            The callback function. This function is called if the asynchronous transfer is
 190                                   completed.
 191   @param[in]  Context             Data passed into Callback function. This is optional parameter and may be NULL.
 192
 193   @retval EFI_SUCCESS             The L2CAP asynchronous receive request is submitted successfully.
 194   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 195                                   - DataLength is 0.
 196                                   - If IsNewTransfer is TRUE, and an asynchronous receive request already exists.
 197
 198 **/
 199 typedef
 200 EFI_STATUS
 201 (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_RAW_ASYNC_RECEIVE)(
 202   IN EFI_BLUETOOTH_IO_PROTOCOL              *This,
 203   IN BOOLEAN                                IsNewTransfer,
 204   IN UINTN                                  PollingInterval,
 205   IN UINTN                                  DataLength,
 206   IN EFI_BLUETOOTH_IO_ASYNC_FUNC_CALLBACK   Callback,
 207   IN VOID                                   *Context
 208   );
 209
 210 /**
 211   Send L2CAP message (excluding L2CAP header) to a specific channel.
 212
 213   @param[in]      This            Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
 214   @param[in]      Handle          A handle created by EFI_BLUETOOTH_IO_PROTOCOL.L2CapConnect indicates which channel to send.
 215   @param[in, out] BufferSize      On input, indicates the size, in bytes, of the data buffer specified by Buffer.
 216                                   On output, indicates the amount of data actually transferred.
 217   @param[in]      Buffer          A pointer to the buffer of data that will be transmitted to Bluetooth L2CAP layer.
 218   @param[in]      Timeout         Indicating the transfer should be completed within this time frame. The units are in
 219                                   milliseconds. If Timeout is 0, then the caller must wait for the function to be completed
 220                                   until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 221
 222   @retval EFI_SUCCESS             The L2CAP message is sent successfully.
 223   @retval EFI_NOT_FOUND           Handle is invalid or not found.
 224   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 225                                   - BufferSize is NULL.
 226                                   - *BufferSize is 0.
 227                                   - Buffer is NULL.
 228   @retval EFI_TIMEOUT             Sending L2CAP message fail due to timeout.
 229   @retval EFI_DEVICE_ERROR        Sending L2CAP message fail due to host controller or device error.
 230
 231 **/
 232 typedef
 233 EFI_STATUS
 234 (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_SEND)(
 235   IN EFI_BLUETOOTH_IO_PROTOCOL      *This,
 236   IN EFI_HANDLE                     Handle,
 237   IN OUT UINTN                      *BufferSize,
 238   IN VOID                           *Buffer,
 239   IN UINTN                          Timeout
 240   );
 241
 242 /**
 243   Receive L2CAP message (excluding L2CAP header) from a specific channel.
 244
 245   @param[in]  This                Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
 246   @param[in]  Handle              A handle created by EFI_BLUETOOTH_IO_PROTOCOL.L2CapConnect indicates which channel to receive.
 247   @param[out] BufferSize          Indicates the size, in bytes, of the data buffer specified by Buffer.
 248   @param[out] Buffer              A pointer to the buffer of data that will be received from Bluetooth L2CAP layer.
 249   @param[in]  Timeout             Indicating the transfer should be completed within this time frame. The units are in
 250                                   milliseconds. If Timeout is 0, then the caller must wait for the function to be completed
 251                                   until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 252
 253   @retval EFI_SUCCESS             The L2CAP message is received successfully.
 254   @retval EFI_NOT_FOUND           Handle is invalid or not found.
 255   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 256                                   - BufferSize is NULL.
 257                                   - *BufferSize is 0.
 258                                   - Buffer is NULL.
 259   @retval EFI_TIMEOUT             Receiving L2CAP message fail due to timeout.
 260   @retval EFI_DEVICE_ERROR        Receiving L2CAP message fail due to host controller or device error.
 261
 262 **/
 263 typedef
 264 EFI_STATUS
 265 (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_RECEIVE)(
 266   IN EFI_BLUETOOTH_IO_PROTOCOL    *This,
 267   IN EFI_HANDLE                   Handle,
 268   OUT UINTN                       *BufferSize,
 269   OUT VOID                        **Buffer,
 270   IN UINTN                        Timeout
 271   );
 272
 273 /**
 274   Callback function, it is called when asynchronous transfer is completed.
 275
 276   @param[in]  Data                Data received via asynchronous transfer.
 277   @param[in]  DataLength          The length of Data in bytes, received via asynchronous transfer.
 278   @param[in]  Context             Context passed from asynchronous transfer request.
 279
 280   @retval EFI_SUCCESS       The callback function complete successfully.
 281
 282 **/
 283 typedef
 284 EFI_STATUS
 285 (EFIAPI *EFI_BLUETOOTH_IO_CHANNEL_SERVICE_CALLBACK) (
 286   IN VOID                         *Data,
 287   IN UINTN                        DataLength,
 288   IN VOID                         *Context
 289   );
 290
 291 /**
 292   Receive L2CAP message (excluding L2CAP header) in non-blocking way from a specific channel.
 293
 294   @param[in]  This                Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
 295   @param[in]  Handel              A handle created by EFI_BLUETOOTH_IO_PROTOCOL.L2CapConnect indicates which channel
 296                                   to receive.
 297   @param[in]  Callback            The callback function. This function is called if the asynchronous transfer is
 298                                   completed.
 299   @param[in]  Context             Data passed into Callback function. This is optional parameter and may be NULL.
 300
 301   @retval EFI_SUCCESS             The L2CAP asynchronous receive request is submitted successfully.
 302   @retval EFI_NOT_FOUND           Handle is invalid or not found.
 303   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 304                                   - DataLength is 0.
 305                                   - If an asynchronous receive request already exists on same Handle.
 306
 307 **/
 308 typedef
 309 EFI_STATUS
 310 (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_ASYNC_RECEIVE)(
 311   IN  EFI_BLUETOOTH_IO_PROTOCOL                   *This,
 312   IN  EFI_HANDLE                                  Handle,
 313   IN  EFI_BLUETOOTH_IO_CHANNEL_SERVICE_CALLBACK   Callback,
 314   IN  VOID*                                       Context
 315   );
 316
 317 /**
 318   Do L2CAP connection.
 319
 320   @param[in]  This                Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
 321   @param[out] Handel              A handle to indicate this L2CAP connection.
 322   @param[in]  Psm                 Bluetooth PSM. See Bluetooth specification for detail.
 323   @param[in]  Mtu                 Bluetooth MTU. See Bluetooth specification for detail.
 324   @param[in]  Callback            The callback function. This function is called whenever there is message received
 325                                   in this channel.
 326   @param[in]  Context             Data passed into Callback function. This is optional parameter and may be NULL.
 327
 328   @retval EFI_SUCCESS             The Bluetooth L2CAP layer connection is created successfully.
 329   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 330                                   - Handle is NULL.
 331   @retval EFI_DEVICE_ERROR        A hardware error occurred trying to do Bluetooth L2CAP connection.
 332
 333 **/
 334 typedef
 335 EFI_STATUS
 336 (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_CONNECT)(
 337   IN EFI_BLUETOOTH_IO_PROTOCOL                    *This,
 338   OUT EFI_HANDLE                                  *Handle,
 339   IN UINT16                                       Psm,
 340   IN UINT16                                       Mtu,
 341   IN EFI_BLUETOOTH_IO_CHANNEL_SERVICE_CALLBACK    Callback,
 342   IN VOID                                         *Context
 343   );
 344
 345 /**
 346   Do L2CAP disconnection.
 347
 348   @param[in]  This                Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
 349   @param[in]  Handel              A handle to indicate this L2CAP connection.
 350
 351   @retval EFI_SUCCESS             The Bluetooth L2CAP layer is disconnected successfully.
 352   @retval EFI_NOT_FOUND           Handle is invalid or not found.
 353   @retval EFI_DEVICE_ERROR        A hardware error occurred trying to do Bluetooth L2CAP disconnection.
 354
 355 **/
 356 typedef
 357 EFI_STATUS
 358 (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_DISCONNECT)(
 359   IN EFI_BLUETOOTH_IO_PROTOCOL                    *This,
 360   IN EFI_HANDLE                                   Handle
 361   );
 362
 363 /**
 364   Register L2CAP callback function for special channel.
 365
 366   @param[in]  This                Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
 367   @param[out] Handel              A handle to indicate this L2CAP connection.
 368   @param[in]  Psm                 Bluetooth PSM. See Bluetooth specification for detail.
 369   @param[in]  Mtu                 Bluetooth MTU. See Bluetooth specification for detail.
 370   @param[in]  Callback            The callback function. This function is called whenever there is message received
 371                                   in this channel. NULL means unregister.
 372   @param[in]  Context             Data passed into Callback function. This is optional parameter and may be NULL.
 373
 374   @retval EFI_SUCCESS             The Bluetooth L2CAP callback function is registered successfully.
 375   @retval EFI_ALREADY_STARTED     The callback function already exists when register.
 376   @retval EFI_NOT_FOUND           The callback function does not exist when unregister.
 377
 378 **/
 379 typedef
 380 EFI_STATUS
 381 (EFIAPI *EFI_BLUETOOTH_IO_L2CAP_REGISTER_SERVICE)(
 382   IN EFI_BLUETOOTH_IO_PROTOCOL                    *This,
 383   OUT EFI_HANDLE                                  *Handle,
 384   IN UINT16                                       Psm,
 385   IN UINT16                                       Mtu,
 386   IN EFI_BLUETOOTH_IO_CHANNEL_SERVICE_CALLBACK    Callback,
 387   IN VOID                                         *Context
 388   );
 389
 390 ///
 391 /// This protocol provides service for Bluetooth L2CAP (Logical Link Control and Adaptation Protocol)
 392 /// and SDP (Service Discovery Protocol).
 393 ///
 394 struct _EFI_BLUETOOTH_IO_PROTOCOL {
 395   EFI_BLUETOOTH_IO_GET_DEVICE_INFO            GetDeviceInfo;
 396   EFI_BLUETOOTH_IO_GET_SDP_INFO               GetSdpInfo;
 397   EFI_BLUETOOTH_IO_L2CAP_RAW_SEND             L2CapRawSend;
 398   EFI_BLUETOOTH_IO_L2CAP_RAW_RECEIVE          L2CapRawReceive;
 399   EFI_BLUETOOTH_IO_L2CAP_RAW_ASYNC_RECEIVE    L2CapRawAsyncReceive;
 400   EFI_BLUETOOTH_IO_L2CAP_SEND                 L2CapSend;
 401   EFI_BLUETOOTH_IO_L2CAP_RECEIVE              L2CapReceive;
 402   EFI_BLUETOOTH_IO_L2CAP_ASYNC_RECEIVE        L2CapAsyncReceive;
 403   EFI_BLUETOOTH_IO_L2CAP_CONNECT              L2CapConnect;
 404   EFI_BLUETOOTH_IO_L2CAP_DISCONNECT           L2CapDisconnect;
 405   EFI_BLUETOOTH_IO_L2CAP_REGISTER_SERVICE     L2CapRegisterService;
 406 };
 407
 408 extern EFI_GUID gEfiBluetoothIoServiceBindingProtocolGuid;
 409 extern EFI_GUID gEfiBluetoothIoProtocolGuid;
 410
 411 #endif