From: Ruiyu Ni <ruiyu.ni@intel.com>
To: edk2-devel@lists.01.org
Cc: Jiewen Yao <jiewen.yao@intel.com>
Subject: [PATCH 3/5] MdePkg/BluetoothHc: Add detailed function header comments
Date: Tue, 6 Jun 2017 11:27:44 +0800 [thread overview]
Message-ID: <20170606032746.238188-4-ruiyu.ni@intel.com> (raw)
In-Reply-To: <20170606032746.238188-1-ruiyu.ni@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Ruiyu Ni <ruiyu.ni@intel.com>
Cc: Jiewen Yao <jiewen.yao@intel.com>
---
MdePkg/Include/Protocol/BluetoothHc.h | 510 ++++++++++++++++++++--------------
1 file changed, 303 insertions(+), 207 deletions(-)
diff --git a/MdePkg/Include/Protocol/BluetoothHc.h b/MdePkg/Include/Protocol/BluetoothHc.h
index 37b7602679..b82c3285a0 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
+
--
2.12.2.windows.2
next prev parent reply other threads:[~2017-06-06 3:26 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-06-06 3:27 [PATCH 0/5] Add Bluetooth LE definitions per UEFI Spec 2.7 Ruiyu Ni
2017-06-06 3:27 ` [PATCH 1/5] MdePkg/DevicePath: Add BluetoothLe device path node support Ruiyu Ni
2017-06-06 3:27 ` [PATCH 2/5] MdePkg/BluetoothConfig: Add new EFI_BLUETOOTH_CONFIG_DATA_TYPE types Ruiyu Ni
2017-06-06 3:27 ` Ruiyu Ni [this message]
2017-06-06 3:27 ` [PATCH 4/5] MdePkg/BluetoothIo: Formalize function header comments Ruiyu Ni
2017-06-06 3:27 ` [PATCH 5/5] MdePkg: Add BluetoothAttribute.h and BluetoothLeConfig.h Ruiyu Ni
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-list from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20170606032746.238188-4-ruiyu.ni@intel.com \
--to=devel@edk2.groups.io \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox