MdePkg/BluetoothHc: Add detailed function header comments

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Ruiyu Ni <ruiyu.ni@intel.com>
Reviewed-by: Jiewen Yao <jiewen.yao@intel.com>

diff --git a/MdePkg/Include/Protocol/BluetoothHc.h b/MdePkg/Include/Protocol/BluetoothHc.h
index 37b760267953dbe8dc5bcdb24644835d6859ddc3..b82c3285a09eb60d72007d9e5efe5e8379b77d31 100644 (file)
--- a/MdePkg/Include/Protocol/BluetoothHc.h
+++ b/MdePkg/Include/Protocol/BluetoothHc.h
@@ -2,16 +2,16 @@
   EFI Bluetooth Host Controller Protocol as defined in UEFI 2.5.\r
   This protocol abstracts the Bluetooth host controller layer message transmit and receive.\r
 \r
   EFI Bluetooth Host Controller Protocol as defined in UEFI 2.5.\r
   This protocol abstracts the Bluetooth host controller layer message transmit and receive.\r
 \r

-  Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>\r
-  This program and the accompanying materials are licensed and made available under \r
-  the terms and conditions of the BSD License that accompanies this distribution.  \r
+  Copyright (c) 2015 - 2017, Intel Corporation. All rights reserved.<BR>\r
+  This program and the accompanying materials are licensed and made available under\r
+  the terms and conditions of the BSD License that accompanies this distribution.\r

   The full text of the license may be found at\r
   The full text of the license may be found at\r

-  http://opensource.org/licenses/bsd-license.php.                                          \r
-    \r
-  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     \r
+  http://opensource.org/licenses/bsd-license.php.\r
+\r
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
 \r
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
 \r

-  @par Revision Reference:          \r
+  @par Revision Reference:\r

   This Protocol is introduced in UEFI Specification 2.5\r
 \r
 **/\r
   This Protocol is introduced in UEFI Specification 2.5\r
 \r
 **/\r


@@ -29,300 +29,396 @@ typedef struct _EFI_BLUETOOTH_HC_PROTOCOL EFI_BLUETOOTH_HC_PROTOCOL;
 /**\r
   Send HCI command packet.\r
 \r
 /**\r
   Send HCI command packet.\r
 \r

-  @param  This          Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
-  @param  BufferSize    On input, indicates the size, in bytes, of the data buffer specified by Buffer. \r
-                        On output, indicates the amount of data actually transferred.\r
-  @param  Buffer        A pointer to the buffer of data that will be transmitted to Bluetooth host \r
-                        controller.\r
-  @param  Timeout       Indicating the transfer should be completed within this time frame. The units are \r
-                        in milliseconds. If Timeout is 0, then the caller must wait for the function to \r
-                        be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.\r
-\r
-  @retval EFI_SUCCESS           The HCI command packet is sent successfully.\r
-  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
-                                - BufferSize is NULL.\r
-                                - *BufferSize is 0.\r
-                                - Buffer is NULL.\r
-  @retval EFI_TIMEOUT           Sending HCI command packet fail due to timeout.\r
-  @retval EFI_DEVICE_ERROR      Sending HCI command packet fail due to host controller or device error.\r
+  The SendCommand() function sends HCI command packet. Buffer holds the whole HCI\r
+  command packet, including OpCode, OCF, OGF, parameter length, and parameters. When\r
+  this function is returned, it just means the HCI command packet is sent, it does not mean\r
+  the command is success or complete. Caller might need to wait a command status event\r
+  to know the command status, or wait a command complete event to know if the\r
+  command is completed.\r
+\r
+  @param[in]      This              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
+  @param[in,out]  BufferSize        On input, indicates the size, in bytes, of the data buffer\r
+                                    specified by Buffer. On output, indicates the amount of\r
+                                    data actually transferred.\r
+  @param[in]      Buffer            A pointer to the buffer of data that will be transmitted to\r
+                                    Bluetooth host controller.\r
+  @param[in]      Timeout           Indicating the transfer should be completed within this\r
+                                    time frame. The units are in milliseconds. If Timeout is 0,\r
+                                    then the caller must wait for the function to be completed\r
+                                    until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.\r
+\r
+  @retval EFI_SUCCESS               The HCI command packet is sent successfully.\r
+  @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:\r
+                                      BufferSize is NULL.\r
+                                      *BufferSize is 0.\r
+                                      Buffer is NULL.\r
+  @retval EFI_TIMEOUT               Sending HCI command packet fail due to timeout.\r
+  @retval EFI_DEVICE_ERROR          Sending HCI command packet fail due to host controller or device\r
+                                    error.\r

 \r
 **/\r
 \r
 **/\r

-typedef \r
+typedef\r

 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_SEND_COMMAND)(\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_SEND_COMMAND)(\r

-  IN EFI_BLUETOOTH_HC_PROTOCOL  *This,\r
-  IN OUT UINTN                  *BufferSize,\r
-  IN VOID                       *Buffer,\r
-  IN UINTN                      Timeout\r
+  IN EFI_BLUETOOTH_HC_PROTOCOL      *This,\r
+  IN OUT UINTN                      *BufferSize,\r
+  IN VOID                           *Buffer,\r
+  IN UINTN                          Timeout\r

   );\r
   );\r

-  \r

 \r
 /**\r
   Receive HCI event packet.\r
 \r
 \r
 /**\r
   Receive HCI event packet.\r
 \r

-  @param  This          Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
-  @param  BufferSize    On input, indicates the size, in bytes, of the data buffer specified by Buffer. \r
-                        On output, indicates the amount of data actually transferred.\r
-  @param  Buffer        A pointer to the buffer of data that will be received from Bluetooth host controller.\r
-  @param  Timeout       Indicating the transfer should be completed within this time frame. The units are \r
-                        in milliseconds. If Timeout is 0, then the caller must wait for the function to \r
-                        be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.\r
-\r
-  @retval EFI_SUCCESS           The HCI event packet is received successfully.\r
-  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
-                                - BufferSize is NULL.\r
-                                - *BufferSize is 0.\r
-                                - Buffer is NULL.\r
-  @retval EFI_TIMEOUT           Receiving HCI event packet fail due to timeout.\r
-  @retval EFI_DEVICE_ERROR      Receiving HCI event packet fail due to host controller or device error.\r
+  The ReceiveEvent() function receives HCI event packet. Buffer holds the whole HCI event\r
+  packet, including EventCode, parameter length, and parameters.\r
+\r
+  @param[in]      This              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
+  @param[in,out]  BufferSize        On input, indicates the size, in bytes, of the data buffer\r
+                                    specified by Buffer. On output, indicates the amount of\r
+                                    data actually transferred.\r
+  @param[out]     Buffer            A pointer to the buffer of data that will be received from\r
+                                    Bluetooth host controller.\r
+  @param[in]      Timeout           Indicating the transfer should be completed within this\r
+                                    time frame. The units are in milliseconds. If Timeout is 0,\r
+                                    then the caller must wait for the function to be completed\r
+                                    until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.\r
+\r
+  @retval EFI_SUCCESS               The HCI event packet is received successfully.\r
+  @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:\r
+                                      BufferSize is NULL.\r
+                                      *BufferSize is 0.\r
+                                      Buffer is NULL.\r
+  @retval EFI_TIMEOUT               Receiving HCI event packet fail due to timeout.\r
+  @retval EFI_DEVICE_ERROR          Receiving HCI event packet fail due to host controller or device\r
+                                    error.\r

 \r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_EVENT)(\r
 \r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_EVENT)(\r

-  IN EFI_BLUETOOTH_HC_PROTOCOL  *This,\r
-  IN OUT UINTN                  *BufferSize,\r
-  OUT VOID                      *Buffer,\r
-  IN UINTN                      Timeout\r
+  IN EFI_BLUETOOTH_HC_PROTOCOL      *This,\r
+  IN OUT UINTN                      *BufferSize,\r
+  OUT VOID                          *Buffer,\r
+  IN UINTN                          Timeout\r

   );\r
   );\r

-  \r
+\r

 /**\r
 /**\r

-  Callback function, it is called when asynchronous transfer is completed.\r
+  The async callback of AsyncReceiveEvent().\r

 \r
 \r

-  @param  Data              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
-  @param  DataLength        Specifies the length, in bytes, of the data to be received.\r
-  @param  Context           Data passed into Callback function. This is optional parameter and may be NULL.\r
+  @param[in]  Data                  Data received via asynchronous transfer.\r
+  @param[in]  DataLength            The length of Data in bytes, received via asynchronous\r
+                                    transfer.\r
+  @param[in]  Context               Context passed from asynchronous transfer request.\r

 \r
 \r

-  @retval EFI_SUCCESS             The callback function complete successfully.\r
+  @retval EFI_SUCCESS               The callback does execute successfully.\r
+  @retval Others                    The callback doesn't execute successfully.\r

 \r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK) (\r
 \r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK) (\r

-  IN VOID                       *Data,\r
-  IN UINTN                      DataLength,\r
-  IN VOID                       *Context\r
+  IN VOID                           *Data,\r
+  IN UINTN                          DataLength,\r
+  IN VOID                           *Context\r

   );\r
   );\r

-  \r
+\r

 /**\r
   Receive HCI event packet in non-blocking way.\r
 \r
 /**\r
   Receive HCI event packet in non-blocking way.\r
 \r

-  @param  This              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
-  @param  IsNewTransfer     If TRUE, a new transfer will be submitted. If FALSE, the request is deleted.\r
-  @param  PollingInterval   Indicates the periodic rate, in milliseconds, that the transfer is to be executed.\r
-  @param  DataLength        Specifies the length, in bytes, of the data to be received.\r
-  @param  Callback          The callback function. This function is called if the asynchronous transfer is \r
-                            completed.\r
-  @param  Context           Data passed into Callback function. This is optional parameter and may be NULL.\r
-\r
-  @retval EFI_SUCCESS           The HCI asynchronous receive request is submitted successfully.\r
-  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
-                                - DataLength is 0.\r
-                                - If IsNewTransfer is TRUE, and an asynchronous receive request already exists.\r
-\r
+  The AsyncReceiveEvent() function receives HCI event packet in non-blocking way. Data\r
+  in Callback function holds the whole HCI event packet, including EventCode, parameter\r
+  length, and parameters.\r
+\r
+  @param[in]  This                  Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
+  @param[in]  IsNewTransfer         If TRUE, a new transfer will be submitted. If FALSE, the\r
+                                    request is deleted.\r
+  @param[in]  PollingInterval       Indicates the periodic rate, in milliseconds, that the\r
+                                    transfer is to be executed.\r
+  @param[in]  DataLength            Specifies the length, in bytes, of the data to be received.\r
+  @param[in]  Callback              The callback function. This function is called if the\r
+                                    asynchronous transfer is completed.\r
+  @param[in]  Context               Data passed into Callback function. This is optional\r
+                                    parameter and may be NULL.\r
+\r
+  @retval EFI_SUCCESS               The HCI asynchronous receive request is submitted successfully.\r
+  @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:\r
+                                      DataLength is 0.\r
+                                      If IsNewTransfer is TRUE, and an asynchronous receive\r
+                                      request already exists.\r

 **/\r
 typedef\r
 EFI_STATUS\r
 **/\r
 typedef\r
 EFI_STATUS\r

-(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT)(\r
-  IN EFI_BLUETOOTH_HC_PROTOCOL            *This,\r
-  IN BOOLEAN                              IsNewTransfer,\r
-  IN UINTN                                PollingInterval,\r
-  IN UINTN                                DataLength,\r
-  IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,\r
-  IN VOID                                 *Context\r
+(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT) (\r
+  IN EFI_BLUETOOTH_HC_PROTOCOL              *This,\r
+  IN BOOLEAN                                IsNewTransfer,\r
+  IN UINTN                                  PollingInterval,\r
+  IN UINTN                                  DataLength,\r
+  IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK   Callback,\r
+  IN VOID                                   *Context\r

   );\r
   );\r

-  \r
+\r

 /**\r
   Send HCI ACL data packet.\r
 \r
 /**\r
   Send HCI ACL data packet.\r
 \r

-  @param  This          Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
-  @param  BufferSize    On input, indicates the size, in bytes, of the data buffer specified by Buffer. \r
-                        On output, indicates the amount of data actually transferred.\r
-  @param  Buffer        A pointer to the buffer of data that will be transmitted to Bluetooth host \r
-                        controller.\r
-  @param  Timeout       Indicating the transfer should be completed within this time frame. The units are \r
-                        in milliseconds. If Timeout is 0, then the caller must wait for the function to \r
-                        be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.\r
-\r
-  @retval EFI_SUCCESS           The HCI ACL data packet is sent successfully.\r
-  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
-                                - BufferSize is NULL.\r
-                                - *BufferSize is 0.\r
-                                - Buffer is NULL.\r
-  @retval EFI_TIMEOUT           Sending HCI ACL data packet fail due to timeout.\r
-  @retval EFI_DEVICE_ERROR      Sending HCI ACL data packet fail due to host controller or device error.\r
+  The SendACLData() function sends HCI ACL data packet. Buffer holds the whole HCI ACL\r
+  data packet, including Handle, PB flag, BC flag, data length, and data.\r
+\r
+  The SendACLData() function and ReceiveACLData() function just send and receive data\r
+  payload from application layer. In order to protect the payload data, the Bluetooth bus is\r
+  required to call HCI_Set_Connection_Encryption command to enable hardware based\r
+  encryption after authentication completed, according to pairing mode and host\r
+  capability.\r
+\r
+  @param[in]       This             Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
+  @param[in, out]  BufferSize       On input, indicates the size, in bytes, of the data buffer\r
+                                    specified by Buffer. On output, indicates the amount of\r
+                                    data actually transferred.\r
+  @param[in]       Buffer           A pointer to the buffer of data that will be transmitted to\r
+                                    Bluetooth host controller.\r
+  @param[in]       Timeout          Indicating the transfer should be completed within this\r
+                                    time frame. The units are in milliseconds. If Timeout is 0,\r
+                                    then the caller must wait for the function to be completed\r
+                                    until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.\r
+\r
+  @retval EFI_SUCCESS               The HCI ACL data packet is sent successfully.\r
+  @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:\r
+                                      BufferSize is NULL.\r
+                                      *BufferSize is 0.\r
+                                      Buffer is NULL.\r
+  @retval EFI_TIMEOUT               Sending HCI ACL data packet fail due to timeout.\r
+  @retval EFI_DEVICE_ERROR          Sending HCI ACL data packet fail due to host controller or device\r
+                                    error.\r

 \r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_SEND_ACL_DATA)(\r
 \r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_SEND_ACL_DATA)(\r

-  IN EFI_BLUETOOTH_HC_PROTOCOL  *This,\r
-  IN OUT UINTN                  *BufferSize,\r
-  IN VOID                       *Buffer,\r
-  IN UINTN                      Timeout\r
+  IN EFI_BLUETOOTH_HC_PROTOCOL      *This,\r
+  IN OUT UINTN                      *BufferSize,\r
+  IN VOID                           *Buffer,\r
+  IN UINTN                          Timeout\r

   );\r
   );\r

-  \r
+\r

 /**\r
   Receive HCI ACL data packet.\r
 \r
 /**\r
   Receive HCI ACL data packet.\r
 \r

-  @param  This          Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
-  @param  BufferSize    On input, indicates the size, in bytes, of the data buffer specified by Buffer. \r
-                        On output, indicates the amount of data actually transferred.\r
-  @param  Buffer        A pointer to the buffer of data that will be received from Bluetooth host controller.\r
-  @param  Timeout       Indicating the transfer should be completed within this time frame. The units are \r
-                        in milliseconds. If Timeout is 0, then the caller must wait for the function to \r
-                        be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.\r
-\r
-  @retval EFI_SUCCESS           The HCI ACL data packet is received successfully.\r
-  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
-                                - BufferSize is NULL.\r
-                                - *BufferSize is 0.\r
-                                - Buffer is NULL.\r
-  @retval EFI_TIMEOUT           Receiving HCI ACL data packet fail due to timeout.\r
-  @retval EFI_DEVICE_ERROR      Receiving HCI ACL data packet fail due to host controller or device error.\r
+  The ReceiveACLData() function receives HCI ACL data packet. Buffer holds the whole HCI\r
+  ACL data packet, including Handle, PB flag, BC flag, data length, and data.\r
+\r
+  @param[in]       This             Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
+  @param[in, out]  BufferSize       On input, indicates the size, in bytes, of the data buffer\r
+                                    specified by Buffer. On output, indicates the amount of\r
+                                    data actually transferred.\r
+  @param[out]      Buffer           A pointer to the buffer of data that will be received from\r
+                                    Bluetooth host controller.\r
+  @param[in]       Timeout          Indicating the transfer should be completed within this\r
+                                    time frame. The units are in milliseconds. If Timeout is 0,\r
+                                    then the caller must wait for the function to be completed\r
+                                    until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.\r
+\r
+  @retval EFI_SUCCESS               The HCI ACL data packet is received successfully.\r
+  @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:\r
+                                      BufferSize is NULL.\r
+                                      *BufferSize is 0.\r
+                                      Buffer is NULL.\r
+  @retval EFI_TIMEOUT               Receiving HCI ACL data packet fail due to timeout.\r
+  @retval EFI_DEVICE_ERROR          Receiving HCI ACL data packet fail due to host controller or device\r
+                                    error.\r

 \r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA)(\r
 \r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA)(\r

-  IN EFI_BLUETOOTH_HC_PROTOCOL  *This,\r
-  IN OUT UINTN                  *BufferSize,\r
-  OUT VOID                      *Buffer,\r
-  IN UINTN                      Timeout\r
+  IN EFI_BLUETOOTH_HC_PROTOCOL      *This,\r
+  IN OUT UINTN                      *BufferSize,\r
+  OUT VOID                          *Buffer,\r
+  IN UINTN                          Timeout\r

   );\r
   );\r

-  \r

 \r
 /**\r
   Receive HCI ACL data packet in non-blocking way.\r
 \r
 \r
 /**\r
   Receive HCI ACL data packet in non-blocking way.\r
 \r

-  @param  This              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
-  @param  IsNewTransfer     If TRUE, a new transfer will be submitted. If FALSE, the request is deleted.\r
-  @param  PollingInterval   Indicates the periodic rate, in milliseconds, that the transfer is to be executed.\r
-  @param  DataLength        Specifies the length, in bytes, of the data to be received.\r
-  @param  Callback          The callback function. This function is called if the asynchronous transfer is \r
-                            completed.\r
-  @param  Context           Data passed into Callback function. This is optional parameter and may be NULL.\r
-\r
-  @retval EFI_SUCCESS           The HCI asynchronous receive request is submitted successfully.\r
-  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
-                                - DataLength is 0.\r
-                                - If IsNewTransfer is TRUE, and an asynchronous receive request already exists.\r
-\r
+  The AsyncReceiveACLData() function receives HCI ACL data packet in non-blocking way.\r
+  Data in Callback holds the whole HCI ACL data packet, including Handle, PB flag, BC flag,\r
+  data length, and data.\r
+\r
+  @param[in]  This                  Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
+  @param[in]  IsNewTransfer         If TRUE, a new transfer will be submitted. If FALSE, the\r
+                                    request is deleted.\r
+  @param[in]  PollingInterval       Indicates the periodic rate, in milliseconds, that the\r
+                                    transfer is to be executed.\r
+  @param[in]  DataLength            Specifies the length, in bytes, of the data to be received.\r
+  @param[in]  Callback              The callback function. This function is called if the\r
+                                    asynchronous transfer is completed.\r
+  @param[in]  Context               Data passed into Callback function. This is optional\r
+                                    parameter and may be NULL.\r
+\r
+  @retval EFI_SUCCESS               The HCI asynchronous receive request is submitted successfully.\r
+  @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:\r
+                                      DataLength is 0.\r
+                                      If IsNewTransfer is TRUE, and an asynchronous receive\r
+                                      request already exists.\r

 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA) (\r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA) (\r

-  IN EFI_BLUETOOTH_HC_PROTOCOL            *This,\r
-  IN BOOLEAN                              IsNewTransfer,\r
-  IN UINTN                                PollingInterval,\r
-  IN UINTN                                DataLength,\r
-  IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,\r
-  IN VOID                                 *Context\r
+  IN EFI_BLUETOOTH_HC_PROTOCOL              *This,\r
+  IN BOOLEAN                                IsNewTransfer,\r
+  IN UINTN                                  PollingInterval,\r
+  IN UINTN                                  DataLength,\r
+  IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK   Callback,\r
+  IN VOID                                   *Context\r

   );\r
   );\r

-  \r
+\r

 /**\r
   Send HCI SCO data packet.\r
 \r
 /**\r
   Send HCI SCO data packet.\r
 \r

-  @param  This          Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
-  @param  BufferSize    On input, indicates the size, in bytes, of the data buffer specified by Buffer. \r
-                        On output, indicates the amount of data actually transferred.\r
-  @param  Buffer        A pointer to the buffer of data that will be transmitted to Bluetooth host \r
-                        controller.\r
-  @param  Timeout       Indicating the transfer should be completed within this time frame. The units are \r
-                        in milliseconds. If Timeout is 0, then the caller must wait for the function to \r
-                        be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.\r
-\r
-  @retval EFI_SUCCESS           The HCI SCO data packet is sent successfully.\r
-  @retval EFI_UNSUPPORTED       The implementation does not support HCI SCO transfer.\r
-  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
-                                - BufferSize is NULL.\r
-                                - *BufferSize is 0.\r
-                                - Buffer is NULL.\r
-  @retval EFI_TIMEOUT           Sending HCI SCO data packet fail due to timeout.\r
-  @retval EFI_DEVICE_ERROR      Sending HCI SCO data packet fail due to host controller or device error.\r
-\r
+  The SendSCOData() function sends HCI SCO data packet. Buffer holds the whole HCI SCO\r
+  data packet, including ConnectionHandle, PacketStatus flag, data length, and data.\r
+\r
+  @param[in]      This              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
+  @param[in,out]  BufferSize        On input, indicates the size, in bytes, of the data buffer\r
+                                    specified by Buffer. On output, indicates the amount of\r
+                                    data actually transferred.\r
+  @param[in]      Buffer            A pointer to the buffer of data that will be transmitted to\r
+                                    Bluetooth host controller.\r
+  @param[in]      Timeout           Indicating the transfer should be completed within this\r
+                                    time frame. The units are in milliseconds. If Timeout is 0,\r
+                                    then the caller must wait for the function to be completed\r
+                                    until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.\r
+\r
+  @retval EFI_SUCCESS               The HCI SCO data packet is sent successfully.\r
+  @retval EFI_UNSUPPORTED           The implementation does not support HCI SCO transfer.\r
+  @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:\r
+                                      BufferSize is NULL.\r
+                                      *BufferSize is 0.\r
+                                      Buffer is NULL.\r
+  @retval EFI_TIMEOUT               Sending HCI SCO data packet fail due to timeout.\r
+  @retval EFI_DEVICE_ERROR          Sending HCI SCO data packet fail due to host controller or device\r
+                                    error.\r

 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_SEND_SCO_DATA)(\r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_SEND_SCO_DATA)(\r

-  IN EFI_BLUETOOTH_HC_PROTOCOL  *This,\r
-  IN OUT UINTN                  *BufferSize,\r
-  IN VOID                       *Buffer,\r
-  IN UINTN                      Timeout\r
+  IN EFI_BLUETOOTH_HC_PROTOCOL      *This,\r
+  IN OUT UINTN                      *BufferSize,\r
+  IN VOID                           *Buffer,\r
+  IN UINTN                          Timeout\r

   );\r
   );\r

-  \r
+\r

 /**\r
   Receive HCI SCO data packet.\r
 \r
 /**\r
   Receive HCI SCO data packet.\r
 \r

-  @param  This          Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
-  @param  BufferSize    On input, indicates the size, in bytes, of the data buffer specified by Buffer. \r
-                        On output, indicates the amount of data actually transferred.\r
-  @param  Buffer        A pointer to the buffer of data that will be received from Bluetooth host controller.\r
-  @param  Timeout       Indicating the transfer should be completed within this time frame. The units are \r
-                        in milliseconds. If Timeout is 0, then the caller must wait for the function to \r
-                        be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.\r
-\r
-  @retval EFI_SUCCESS           The HCI SCO data packet is received successfully.\r
-  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
-                                - BufferSize is NULL.\r
-                                - *BufferSize is 0.\r
-                                - Buffer is NULL.\r
-  @retval EFI_TIMEOUT           Receiving HCI SCO data packet fail due to timeout\r
-  @retval EFI_DEVICE_ERROR      Receiving HCI SCO data packet fail due to host controller or device error.\r
-\r
+  The ReceiveSCOData() function receives HCI SCO data packet. Buffer holds the whole HCI\r
+  SCO data packet, including ConnectionHandle, PacketStatus flag, data length, and data.\r
+\r
+  @param[in]      This              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
+  @param[in,out]  BufferSize        On input, indicates the size, in bytes, of the data buffer\r
+                                    specified by Buffer. On output, indicates the amount of\r
+                                    data actually transferred.\r
+  @param[out]     Buffer            A pointer to the buffer of data that will be received from\r
+                                    Bluetooth host controller.\r
+  @param[in]      Timeout           Indicating the transfer should be completed within this\r
+                                    time frame. The units are in milliseconds. If Timeout is 0,\r
+                                    then the caller must wait for the function to be completed\r
+                                    until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.\r
+\r
+  @retval EFI_SUCCESS               The HCI SCO data packet is received successfully.\r
+  @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:\r
+                                      BufferSize is NULL.\r
+                                      *BufferSize is 0.\r
+                                      Buffer is NULL.\r
+  @retval EFI_TIMEOUT               Receiving HCI SCO data packet fail due to timeout.\r
+  @retval EFI_DEVICE_ERROR          Receiving HCI SCO data packet fail due to host controller or device\r
+                                    error.\r

 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA)(\r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA)(\r

-  IN EFI_BLUETOOTH_HC_PROTOCOL  *This,\r
-  IN OUT UINTN                  *BufferSize,\r
-  OUT VOID                      *Buffer,\r
-  IN UINTN                      Timeout\r
+  IN EFI_BLUETOOTH_HC_PROTOCOL      *This,\r
+  IN OUT UINTN                      *BufferSize,\r
+  OUT VOID                          *Buffer,\r
+  IN UINTN                          Timeout\r

   );\r
 \r
 /**\r
   Receive HCI SCO data packet in non-blocking way.\r
 \r
   );\r
 \r
 /**\r
   Receive HCI SCO data packet in non-blocking way.\r
 \r

-  @param  This              Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
-  @param  IsNewTransfer     If TRUE, a new transfer will be submitted. If FALSE, the request is deleted.\r
-  @param  PollingInterval   Indicates the periodic rate, in milliseconds, that the transfer is to be executed.\r
-  @param  DataLength        Specifies the length, in bytes, of the data to be received.\r
-  @param  Callback          The callback function. This function is called if the asynchronous transfer is \r
-                            completed.\r
-  @param  Context           Data passed into Callback function. This is optional parameter and may be NULL.\r
-\r
-  @retval EFI_SUCCESS           The HCI asynchronous receive request is submitted successfully.\r
-  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
-                                - DataLength is 0.\r
-                                - If IsNewTransfer is TRUE, and an asynchronous receive request already exists.\r
-\r
+  The AsyncReceiveSCOData() function receives HCI SCO data packet in non-blocking way.\r
+  Data in Callback holds the whole HCI SCO data packet, including ConnectionHandle,\r
+  PacketStatus flag, data length, and data.\r
+\r
+  @param[in]  This                  Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.\r
+  @param[in]  IsNewTransfer         If TRUE, a new transfer will be submitted. If FALSE, the\r
+                                    request is deleted.\r
+  @param[in]  PollingInterval       Indicates the periodic rate, in milliseconds, that the\r
+                                    transfer is to be executed.\r
+  @param[in]  DataLength            Specifies the length, in bytes, of the data to be received.\r
+  @param[in]  Callback              The callback function. This function is called if the\r
+                                    asynchronous transfer is completed.\r
+  @param[in]  Context               Data passed into Callback function. This is optional\r
+                                    parameter and may be NULL.\r
+\r
+  @retval EFI_SUCCESS               The HCI asynchronous receive request is submitted successfully.\r
+  @retval EFI_INVALID_PARAMETER     One or more of the following conditions is TRUE:\r
+                                      DataLength is 0.\r
+                                      If IsNewTransfer is TRUE, and an asynchronous receive\r
+                                      request already exists.\r

 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA) (\r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA) (\r

-  IN EFI_BLUETOOTH_HC_PROTOCOL            *This,\r
-  IN BOOLEAN                              IsNewTransfer,\r
-  IN UINTN                                PollingInterval,\r
-  IN UINTN                                DataLength,\r
-  IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,\r
-  IN VOID                                 *Context\r
+  IN EFI_BLUETOOTH_HC_PROTOCOL              *This,\r
+  IN BOOLEAN                                IsNewTransfer,\r
+  IN UINTN                                  PollingInterval,\r
+  IN UINTN                                  DataLength,\r
+  IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK   Callback,\r
+  IN VOID                                   *Context\r

   );\r
   );\r

-  \r
-///\r
-/// This protocol abstracts the Bluetooth host controller layer message transmit and receive.\r
-///\r
+\r
+//\r
+// The EFI_BLUETOOTH_HC_PROTOCOL is used to transmit or receive HCI layer data packets.\r
+//\r

 struct _EFI_BLUETOOTH_HC_PROTOCOL {\r
 struct _EFI_BLUETOOTH_HC_PROTOCOL {\r

+  //\r
+  // Send HCI command packet.\r
+  //\r

   EFI_BLUETOOTH_HC_SEND_COMMAND               SendCommand;\r
   EFI_BLUETOOTH_HC_SEND_COMMAND               SendCommand;\r

+  //\r
+  // Receive HCI event packets.\r
+  //\r

   EFI_BLUETOOTH_HC_RECEIVE_EVENT              ReceiveEvent;\r
   EFI_BLUETOOTH_HC_RECEIVE_EVENT              ReceiveEvent;\r

+  //\r
+  // Non-blocking receive HCI event packets.\r
+  //\r

   EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT        AsyncReceiveEvent;\r
   EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT        AsyncReceiveEvent;\r

+  //\r
+  // Send HCI ACL (asynchronous connection-oriented) data packets.\r
+  //\r

   EFI_BLUETOOTH_HC_SEND_ACL_DATA              SendACLData;\r
   EFI_BLUETOOTH_HC_SEND_ACL_DATA              SendACLData;\r

+  //\r
+  // Receive HCI ACL data packets.\r
+  //\r

   EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA           ReceiveACLData;\r
   EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA           ReceiveACLData;\r

+  //\r
+  // Non-blocking receive HCI ACL data packets.\r
+  //\r

   EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA     AsyncReceiveACLData;\r
   EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA     AsyncReceiveACLData;\r

+  //\r
+  // Send HCI synchronous (SCO and eSCO) data packets.\r
+  //\r

   EFI_BLUETOOTH_HC_SEND_SCO_DATA              SendSCOData;\r
   EFI_BLUETOOTH_HC_SEND_SCO_DATA              SendSCOData;\r

+  //\r
+  // Receive HCI synchronous data packets.\r
+  //\r

   EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA           ReceiveSCOData;\r
   EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA           ReceiveSCOData;\r

+  //\r
+  // Non-blocking receive HCI synchronous data packets.\r
+  //\r

   EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA     AsyncReceiveSCOData;\r
 };\r
   EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA     AsyncReceiveSCOData;\r
 };\r

-  \r
+\r

 extern EFI_GUID gEfiBluetoothHcProtocolGuid;\r
 \r
 #endif\r
 extern EFI_GUID gEfiBluetoothHcProtocolGuid;\r
 \r
 #endif\r

+\r