MdePkg/BluetoothHc: Add detailed function header comments
authorRuiyu Ni <ruiyu.ni@intel.com>
Tue, 6 Jun 2017 03:01:15 +0000 (11:01 +0800)
committerRuiyu Ni <ruiyu.ni@intel.com>
Wed, 7 Jun 2017 00:46:21 +0000 (08:46 +0800)
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Ruiyu Ni <ruiyu.ni@intel.com>
Reviewed-by: Jiewen Yao <jiewen.yao@intel.com>
MdePkg/Include/Protocol/BluetoothHc.h

index 37b760267953dbe8dc5bcdb24644835d6859ddc3..b82c3285a09eb60d72007d9e5efe5e8379b77d31 100644 (file)
@@ -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
-  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
-  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
-  @par Revision Reference:          \r
+  @par Revision Reference:\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
-  @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
-typedef \r
+typedef\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
   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
-  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
-  Callback function, it is called when asynchronous transfer is completed.\r
+  The async callback of AsyncReceiveEvent().\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
-  @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
-  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
   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
-(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
   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
-  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
   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
-  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
   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
-  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
   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
-  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
   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
-  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
-  @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
-  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
-/// 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
+  //\r
+  // Send HCI command packet.\r
+  //\r
   EFI_BLUETOOTH_HC_SEND_COMMAND               SendCommand;\r
+  //\r
+  // Receive HCI event packets.\r
+  //\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
+  //\r
+  // Send HCI ACL (asynchronous connection-oriented) data packets.\r
+  //\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
+  //\r
+  // Non-blocking receive HCI ACL data packets.\r
+  //\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
+  //\r
+  // Receive HCI synchronous data packets.\r
+  //\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
-  \r
+\r
 extern EFI_GUID gEfiBluetoothHcProtocolGuid;\r
 \r
 #endif\r
+\r