diff options
author | Ruiyu Ni <ruiyu.ni@intel.com> | 2017-06-06 11:01:15 +0800 |
---|---|---|
committer | Ruiyu Ni <ruiyu.ni@intel.com> | 2017-06-07 08:46:21 +0800 |
commit | 5a39f404f3b870fd27d0127b864d82c90704fde6 (patch) | |
tree | 2d248098d24c774ed39a0c3e57ec161e341e5b18 /MdePkg | |
parent | 0cbd5830b48a97cd8a8089d2830c3d30fc3e7a63 (diff) | |
download | edk2-5a39f404f3b870fd27d0127b864d82c90704fde6.zip edk2-5a39f404f3b870fd27d0127b864d82c90704fde6.tar.gz edk2-5a39f404f3b870fd27d0127b864d82c90704fde6.tar.bz2 |
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>
Diffstat (limited to 'MdePkg')
-rw-r--r-- | MdePkg/Include/Protocol/BluetoothHc.h | 510 |
1 files changed, 303 insertions, 207 deletions
diff --git a/MdePkg/Include/Protocol/BluetoothHc.h b/MdePkg/Include/Protocol/BluetoothHc.h index 37b7602..b82c328 100644 --- 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.
This protocol abstracts the Bluetooth host controller layer message transmit and receive.
- Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>
- This program and the accompanying materials are licensed and made available under
- the terms and conditions of the BSD License that accompanies this distribution.
+ Copyright (c) 2015 - 2017, Intel Corporation. All rights reserved.<BR>
+ This program and the accompanying materials are licensed and made available under
+ the terms and conditions of the BSD License that accompanies this distribution.
The full text of the license may be found at
- http://opensource.org/licenses/bsd-license.php.
-
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+ http://opensource.org/licenses/bsd-license.php.
+
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
- @par Revision Reference:
+ @par Revision Reference:
This Protocol is introduced in UEFI Specification 2.5
**/
@@ -29,300 +29,396 @@ typedef struct _EFI_BLUETOOTH_HC_PROTOCOL EFI_BLUETOOTH_HC_PROTOCOL; /**
Send HCI command packet.
- @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- @param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer.
- On output, indicates the amount of data actually transferred.
- @param Buffer A pointer to the buffer of data that will be transmitted to Bluetooth host
- controller.
- @param Timeout Indicating the transfer should be completed within this time frame. The units are
- in milliseconds. If Timeout is 0, then the caller must wait for the function to
- be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
-
- @retval EFI_SUCCESS The HCI command packet is sent successfully.
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- - BufferSize is NULL.
- - *BufferSize is 0.
- - Buffer is NULL.
- @retval EFI_TIMEOUT Sending HCI command packet fail due to timeout.
- @retval EFI_DEVICE_ERROR Sending HCI command packet fail due to host controller or device error.
+ The SendCommand() function sends HCI command packet. Buffer holds the whole HCI
+ command packet, including OpCode, OCF, OGF, parameter length, and parameters. When
+ this function is returned, it just means the HCI command packet is sent, it does not mean
+ the command is success or complete. Caller might need to wait a command status event
+ to know the command status, or wait a command complete event to know if the
+ command is completed.
+
+ @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
+ @param[in,out] BufferSize On input, indicates the size, in bytes, of the data buffer
+ specified by Buffer. On output, indicates the amount of
+ data actually transferred.
+ @param[in] Buffer A pointer to the buffer of data that will be transmitted to
+ Bluetooth host controller.
+ @param[in] Timeout Indicating the transfer should be completed within this
+ time frame. The units are in milliseconds. If Timeout is 0,
+ then the caller must wait for the function to be completed
+ until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
+
+ @retval EFI_SUCCESS The HCI command packet is sent successfully.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ BufferSize is NULL.
+ *BufferSize is 0.
+ Buffer is NULL.
+ @retval EFI_TIMEOUT Sending HCI command packet fail due to timeout.
+ @retval EFI_DEVICE_ERROR Sending HCI command packet fail due to host controller or device
+ error.
**/
-typedef
+typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_SEND_COMMAND)(
- IN EFI_BLUETOOTH_HC_PROTOCOL *This,
- IN OUT UINTN *BufferSize,
- IN VOID *Buffer,
- IN UINTN Timeout
+ IN EFI_BLUETOOTH_HC_PROTOCOL *This,
+ IN OUT UINTN *BufferSize,
+ IN VOID *Buffer,
+ IN UINTN Timeout
);
-
/**
Receive HCI event packet.
- @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- @param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer.
- On output, indicates the amount of data actually transferred.
- @param Buffer A pointer to the buffer of data that will be received from Bluetooth host controller.
- @param Timeout Indicating the transfer should be completed within this time frame. The units are
- in milliseconds. If Timeout is 0, then the caller must wait for the function to
- be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
-
- @retval EFI_SUCCESS The HCI event packet is received successfully.
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- - BufferSize is NULL.
- - *BufferSize is 0.
- - Buffer is NULL.
- @retval EFI_TIMEOUT Receiving HCI event packet fail due to timeout.
- @retval EFI_DEVICE_ERROR Receiving HCI event packet fail due to host controller or device error.
+ The ReceiveEvent() function receives HCI event packet. Buffer holds the whole HCI event
+ packet, including EventCode, parameter length, and parameters.
+
+ @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
+ @param[in,out] BufferSize On input, indicates the size, in bytes, of the data buffer
+ specified by Buffer. On output, indicates the amount of
+ data actually transferred.
+ @param[out] Buffer A pointer to the buffer of data that will be received from
+ Bluetooth host controller.
+ @param[in] Timeout Indicating the transfer should be completed within this
+ time frame. The units are in milliseconds. If Timeout is 0,
+ then the caller must wait for the function to be completed
+ until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
+
+ @retval EFI_SUCCESS The HCI event packet is received successfully.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ BufferSize is NULL.
+ *BufferSize is 0.
+ Buffer is NULL.
+ @retval EFI_TIMEOUT Receiving HCI event packet fail due to timeout.
+ @retval EFI_DEVICE_ERROR Receiving HCI event packet fail due to host controller or device
+ error.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_EVENT)(
- IN EFI_BLUETOOTH_HC_PROTOCOL *This,
- IN OUT UINTN *BufferSize,
- OUT VOID *Buffer,
- IN UINTN Timeout
+ IN EFI_BLUETOOTH_HC_PROTOCOL *This,
+ IN OUT UINTN *BufferSize,
+ OUT VOID *Buffer,
+ IN UINTN Timeout
);
-
+
/**
- Callback function, it is called when asynchronous transfer is completed.
+ The async callback of AsyncReceiveEvent().
- @param Data Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- @param DataLength Specifies the length, in bytes, of the data to be received.
- @param Context Data passed into Callback function. This is optional parameter and may be NULL.
+ @param[in] Data Data received via asynchronous transfer.
+ @param[in] DataLength The length of Data in bytes, received via asynchronous
+ transfer.
+ @param[in] Context Context passed from asynchronous transfer request.
- @retval EFI_SUCCESS The callback function complete successfully.
+ @retval EFI_SUCCESS The callback does execute successfully.
+ @retval Others The callback doesn't execute successfully.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK) (
- IN VOID *Data,
- IN UINTN DataLength,
- IN VOID *Context
+ IN VOID *Data,
+ IN UINTN DataLength,
+ IN VOID *Context
);
-
+
/**
Receive HCI event packet in non-blocking way.
- @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- @param IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the request is deleted.
- @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be executed.
- @param DataLength Specifies the length, in bytes, of the data to be received.
- @param Callback The callback function. This function is called if the asynchronous transfer is
- completed.
- @param Context Data passed into Callback function. This is optional parameter and may be NULL.
-
- @retval EFI_SUCCESS The HCI asynchronous receive request is submitted successfully.
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- - DataLength is 0.
- - If IsNewTransfer is TRUE, and an asynchronous receive request already exists.
-
+ The AsyncReceiveEvent() function receives HCI event packet in non-blocking way. Data
+ in Callback function holds the whole HCI event packet, including EventCode, parameter
+ length, and parameters.
+
+ @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
+ @param[in] IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the
+ request is deleted.
+ @param[in] PollingInterval Indicates the periodic rate, in milliseconds, that the
+ transfer is to be executed.
+ @param[in] DataLength Specifies the length, in bytes, of the data to be received.
+ @param[in] Callback The callback function. This function is called if the
+ asynchronous transfer is completed.
+ @param[in] Context Data passed into Callback function. This is optional
+ parameter and may be NULL.
+
+ @retval EFI_SUCCESS The HCI asynchronous receive request is submitted successfully.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ DataLength is 0.
+ If IsNewTransfer is TRUE, and an asynchronous receive
+ request already exists.
**/
typedef
EFI_STATUS
-(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT)(
- IN EFI_BLUETOOTH_HC_PROTOCOL *This,
- IN BOOLEAN IsNewTransfer,
- IN UINTN PollingInterval,
- IN UINTN DataLength,
- IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,
- IN VOID *Context
+(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT) (
+ IN EFI_BLUETOOTH_HC_PROTOCOL *This,
+ IN BOOLEAN IsNewTransfer,
+ IN UINTN PollingInterval,
+ IN UINTN DataLength,
+ IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,
+ IN VOID *Context
);
-
+
/**
Send HCI ACL data packet.
- @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- @param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer.
- On output, indicates the amount of data actually transferred.
- @param Buffer A pointer to the buffer of data that will be transmitted to Bluetooth host
- controller.
- @param Timeout Indicating the transfer should be completed within this time frame. The units are
- in milliseconds. If Timeout is 0, then the caller must wait for the function to
- be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
-
- @retval EFI_SUCCESS The HCI ACL data packet is sent successfully.
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- - BufferSize is NULL.
- - *BufferSize is 0.
- - Buffer is NULL.
- @retval EFI_TIMEOUT Sending HCI ACL data packet fail due to timeout.
- @retval EFI_DEVICE_ERROR Sending HCI ACL data packet fail due to host controller or device error.
+ The SendACLData() function sends HCI ACL data packet. Buffer holds the whole HCI ACL
+ data packet, including Handle, PB flag, BC flag, data length, and data.
+
+ The SendACLData() function and ReceiveACLData() function just send and receive data
+ payload from application layer. In order to protect the payload data, the Bluetooth bus is
+ required to call HCI_Set_Connection_Encryption command to enable hardware based
+ encryption after authentication completed, according to pairing mode and host
+ capability.
+
+ @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
+ @param[in, out] BufferSize On input, indicates the size, in bytes, of the data buffer
+ specified by Buffer. On output, indicates the amount of
+ data actually transferred.
+ @param[in] Buffer A pointer to the buffer of data that will be transmitted to
+ Bluetooth host controller.
+ @param[in] Timeout Indicating the transfer should be completed within this
+ time frame. The units are in milliseconds. If Timeout is 0,
+ then the caller must wait for the function to be completed
+ until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
+
+ @retval EFI_SUCCESS The HCI ACL data packet is sent successfully.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ BufferSize is NULL.
+ *BufferSize is 0.
+ Buffer is NULL.
+ @retval EFI_TIMEOUT Sending HCI ACL data packet fail due to timeout.
+ @retval EFI_DEVICE_ERROR Sending HCI ACL data packet fail due to host controller or device
+ error.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_SEND_ACL_DATA)(
- IN EFI_BLUETOOTH_HC_PROTOCOL *This,
- IN OUT UINTN *BufferSize,
- IN VOID *Buffer,
- IN UINTN Timeout
+ IN EFI_BLUETOOTH_HC_PROTOCOL *This,
+ IN OUT UINTN *BufferSize,
+ IN VOID *Buffer,
+ IN UINTN Timeout
);
-
+
/**
Receive HCI ACL data packet.
- @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- @param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer.
- On output, indicates the amount of data actually transferred.
- @param Buffer A pointer to the buffer of data that will be received from Bluetooth host controller.
- @param Timeout Indicating the transfer should be completed within this time frame. The units are
- in milliseconds. If Timeout is 0, then the caller must wait for the function to
- be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
-
- @retval EFI_SUCCESS The HCI ACL data packet is received successfully.
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- - BufferSize is NULL.
- - *BufferSize is 0.
- - Buffer is NULL.
- @retval EFI_TIMEOUT Receiving HCI ACL data packet fail due to timeout.
- @retval EFI_DEVICE_ERROR Receiving HCI ACL data packet fail due to host controller or device error.
+ The ReceiveACLData() function receives HCI ACL data packet. Buffer holds the whole HCI
+ ACL data packet, including Handle, PB flag, BC flag, data length, and data.
+
+ @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
+ @param[in, out] BufferSize On input, indicates the size, in bytes, of the data buffer
+ specified by Buffer. On output, indicates the amount of
+ data actually transferred.
+ @param[out] Buffer A pointer to the buffer of data that will be received from
+ Bluetooth host controller.
+ @param[in] Timeout Indicating the transfer should be completed within this
+ time frame. The units are in milliseconds. If Timeout is 0,
+ then the caller must wait for the function to be completed
+ until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
+
+ @retval EFI_SUCCESS The HCI ACL data packet is received successfully.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ BufferSize is NULL.
+ *BufferSize is 0.
+ Buffer is NULL.
+ @retval EFI_TIMEOUT Receiving HCI ACL data packet fail due to timeout.
+ @retval EFI_DEVICE_ERROR Receiving HCI ACL data packet fail due to host controller or device
+ error.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA)(
- IN EFI_BLUETOOTH_HC_PROTOCOL *This,
- IN OUT UINTN *BufferSize,
- OUT VOID *Buffer,
- IN UINTN Timeout
+ IN EFI_BLUETOOTH_HC_PROTOCOL *This,
+ IN OUT UINTN *BufferSize,
+ OUT VOID *Buffer,
+ IN UINTN Timeout
);
-
/**
Receive HCI ACL data packet in non-blocking way.
- @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- @param IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the request is deleted.
- @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be executed.
- @param DataLength Specifies the length, in bytes, of the data to be received.
- @param Callback The callback function. This function is called if the asynchronous transfer is
- completed.
- @param Context Data passed into Callback function. This is optional parameter and may be NULL.
-
- @retval EFI_SUCCESS The HCI asynchronous receive request is submitted successfully.
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- - DataLength is 0.
- - If IsNewTransfer is TRUE, and an asynchronous receive request already exists.
-
+ The AsyncReceiveACLData() function receives HCI ACL data packet in non-blocking way.
+ Data in Callback holds the whole HCI ACL data packet, including Handle, PB flag, BC flag,
+ data length, and data.
+
+ @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
+ @param[in] IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the
+ request is deleted.
+ @param[in] PollingInterval Indicates the periodic rate, in milliseconds, that the
+ transfer is to be executed.
+ @param[in] DataLength Specifies the length, in bytes, of the data to be received.
+ @param[in] Callback The callback function. This function is called if the
+ asynchronous transfer is completed.
+ @param[in] Context Data passed into Callback function. This is optional
+ parameter and may be NULL.
+
+ @retval EFI_SUCCESS The HCI asynchronous receive request is submitted successfully.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ DataLength is 0.
+ If IsNewTransfer is TRUE, and an asynchronous receive
+ request already exists.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA) (
- IN EFI_BLUETOOTH_HC_PROTOCOL *This,
- IN BOOLEAN IsNewTransfer,
- IN UINTN PollingInterval,
- IN UINTN DataLength,
- IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,
- IN VOID *Context
+ IN EFI_BLUETOOTH_HC_PROTOCOL *This,
+ IN BOOLEAN IsNewTransfer,
+ IN UINTN PollingInterval,
+ IN UINTN DataLength,
+ IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,
+ IN VOID *Context
);
-
+
/**
Send HCI SCO data packet.
- @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- @param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer.
- On output, indicates the amount of data actually transferred.
- @param Buffer A pointer to the buffer of data that will be transmitted to Bluetooth host
- controller.
- @param Timeout Indicating the transfer should be completed within this time frame. The units are
- in milliseconds. If Timeout is 0, then the caller must wait for the function to
- be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
-
- @retval EFI_SUCCESS The HCI SCO data packet is sent successfully.
- @retval EFI_UNSUPPORTED The implementation does not support HCI SCO transfer.
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- - BufferSize is NULL.
- - *BufferSize is 0.
- - Buffer is NULL.
- @retval EFI_TIMEOUT Sending HCI SCO data packet fail due to timeout.
- @retval EFI_DEVICE_ERROR Sending HCI SCO data packet fail due to host controller or device error.
-
+ The SendSCOData() function sends HCI SCO data packet. Buffer holds the whole HCI SCO
+ data packet, including ConnectionHandle, PacketStatus flag, data length, and data.
+
+ @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
+ @param[in,out] BufferSize On input, indicates the size, in bytes, of the data buffer
+ specified by Buffer. On output, indicates the amount of
+ data actually transferred.
+ @param[in] Buffer A pointer to the buffer of data that will be transmitted to
+ Bluetooth host controller.
+ @param[in] Timeout Indicating the transfer should be completed within this
+ time frame. The units are in milliseconds. If Timeout is 0,
+ then the caller must wait for the function to be completed
+ until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
+
+ @retval EFI_SUCCESS The HCI SCO data packet is sent successfully.
+ @retval EFI_UNSUPPORTED The implementation does not support HCI SCO transfer.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ BufferSize is NULL.
+ *BufferSize is 0.
+ Buffer is NULL.
+ @retval EFI_TIMEOUT Sending HCI SCO data packet fail due to timeout.
+ @retval EFI_DEVICE_ERROR Sending HCI SCO data packet fail due to host controller or device
+ error.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_SEND_SCO_DATA)(
- IN EFI_BLUETOOTH_HC_PROTOCOL *This,
- IN OUT UINTN *BufferSize,
- IN VOID *Buffer,
- IN UINTN Timeout
+ IN EFI_BLUETOOTH_HC_PROTOCOL *This,
+ IN OUT UINTN *BufferSize,
+ IN VOID *Buffer,
+ IN UINTN Timeout
);
-
+
/**
Receive HCI SCO data packet.
- @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- @param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer.
- On output, indicates the amount of data actually transferred.
- @param Buffer A pointer to the buffer of data that will be received from Bluetooth host controller.
- @param Timeout Indicating the transfer should be completed within this time frame. The units are
- in milliseconds. If Timeout is 0, then the caller must wait for the function to
- be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
-
- @retval EFI_SUCCESS The HCI SCO data packet is received successfully.
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- - BufferSize is NULL.
- - *BufferSize is 0.
- - Buffer is NULL.
- @retval EFI_TIMEOUT Receiving HCI SCO data packet fail due to timeout
- @retval EFI_DEVICE_ERROR Receiving HCI SCO data packet fail due to host controller or device error.
-
+ The ReceiveSCOData() function receives HCI SCO data packet. Buffer holds the whole HCI
+ SCO data packet, including ConnectionHandle, PacketStatus flag, data length, and data.
+
+ @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
+ @param[in,out] BufferSize On input, indicates the size, in bytes, of the data buffer
+ specified by Buffer. On output, indicates the amount of
+ data actually transferred.
+ @param[out] Buffer A pointer to the buffer of data that will be received from
+ Bluetooth host controller.
+ @param[in] Timeout Indicating the transfer should be completed within this
+ time frame. The units are in milliseconds. If Timeout is 0,
+ then the caller must wait for the function to be completed
+ until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
+
+ @retval EFI_SUCCESS The HCI SCO data packet is received successfully.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ BufferSize is NULL.
+ *BufferSize is 0.
+ Buffer is NULL.
+ @retval EFI_TIMEOUT Receiving HCI SCO data packet fail due to timeout.
+ @retval EFI_DEVICE_ERROR Receiving HCI SCO data packet fail due to host controller or device
+ error.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA)(
- IN EFI_BLUETOOTH_HC_PROTOCOL *This,
- IN OUT UINTN *BufferSize,
- OUT VOID *Buffer,
- IN UINTN Timeout
+ IN EFI_BLUETOOTH_HC_PROTOCOL *This,
+ IN OUT UINTN *BufferSize,
+ OUT VOID *Buffer,
+ IN UINTN Timeout
);
/**
Receive HCI SCO data packet in non-blocking way.
- @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- @param IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the request is deleted.
- @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be executed.
- @param DataLength Specifies the length, in bytes, of the data to be received.
- @param Callback The callback function. This function is called if the asynchronous transfer is
- completed.
- @param Context Data passed into Callback function. This is optional parameter and may be NULL.
-
- @retval EFI_SUCCESS The HCI asynchronous receive request is submitted successfully.
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- - DataLength is 0.
- - If IsNewTransfer is TRUE, and an asynchronous receive request already exists.
-
+ The AsyncReceiveSCOData() function receives HCI SCO data packet in non-blocking way.
+ Data in Callback holds the whole HCI SCO data packet, including ConnectionHandle,
+ PacketStatus flag, data length, and data.
+
+ @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
+ @param[in] IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the
+ request is deleted.
+ @param[in] PollingInterval Indicates the periodic rate, in milliseconds, that the
+ transfer is to be executed.
+ @param[in] DataLength Specifies the length, in bytes, of the data to be received.
+ @param[in] Callback The callback function. This function is called if the
+ asynchronous transfer is completed.
+ @param[in] Context Data passed into Callback function. This is optional
+ parameter and may be NULL.
+
+ @retval EFI_SUCCESS The HCI asynchronous receive request is submitted successfully.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ DataLength is 0.
+ If IsNewTransfer is TRUE, and an asynchronous receive
+ request already exists.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA) (
- IN EFI_BLUETOOTH_HC_PROTOCOL *This,
- IN BOOLEAN IsNewTransfer,
- IN UINTN PollingInterval,
- IN UINTN DataLength,
- IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,
- IN VOID *Context
+ IN EFI_BLUETOOTH_HC_PROTOCOL *This,
+ IN BOOLEAN IsNewTransfer,
+ IN UINTN PollingInterval,
+ IN UINTN DataLength,
+ IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,
+ IN VOID *Context
);
-
-///
-/// This protocol abstracts the Bluetooth host controller layer message transmit and receive.
-///
+
+//
+// The EFI_BLUETOOTH_HC_PROTOCOL is used to transmit or receive HCI layer data packets.
+//
struct _EFI_BLUETOOTH_HC_PROTOCOL {
+ //
+ // Send HCI command packet.
+ //
EFI_BLUETOOTH_HC_SEND_COMMAND SendCommand;
+ //
+ // Receive HCI event packets.
+ //
EFI_BLUETOOTH_HC_RECEIVE_EVENT ReceiveEvent;
+ //
+ // Non-blocking receive HCI event packets.
+ //
EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT AsyncReceiveEvent;
+ //
+ // Send HCI ACL (asynchronous connection-oriented) data packets.
+ //
EFI_BLUETOOTH_HC_SEND_ACL_DATA SendACLData;
+ //
+ // Receive HCI ACL data packets.
+ //
EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA ReceiveACLData;
+ //
+ // Non-blocking receive HCI ACL data packets.
+ //
EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA AsyncReceiveACLData;
+ //
+ // Send HCI synchronous (SCO and eSCO) data packets.
+ //
EFI_BLUETOOTH_HC_SEND_SCO_DATA SendSCOData;
+ //
+ // Receive HCI synchronous data packets.
+ //
EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA ReceiveSCOData;
+ //
+ // Non-blocking receive HCI synchronous data packets.
+ //
EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA AsyncReceiveSCOData;
};
-
+
extern EFI_GUID gEfiBluetoothHcProtocolGuid;
#endif
+
|