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>
This commit is contained in:
Ruiyu Ni 2017-06-06 11:01:15 +08:00
parent 0cbd5830b4
commit 5a39f404f3

View File

@ -2,7 +2,7 @@
EFI Bluetooth Host Controller Protocol as defined in UEFI 2.5. EFI Bluetooth Host Controller Protocol as defined in UEFI 2.5.
This protocol abstracts the Bluetooth host controller layer message transmit and receive. This protocol abstracts the Bluetooth host controller layer message transmit and receive.
Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> Copyright (c) 2015 - 2017, Intel Corporation. All rights reserved.<BR>
This program and the accompanying materials are licensed and made available under 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 terms and conditions of the BSD License that accompanies this distribution.
The full text of the license may be found at The full text of the license may be found at
@ -29,22 +29,32 @@ typedef struct _EFI_BLUETOOTH_HC_PROTOCOL EFI_BLUETOOTH_HC_PROTOCOL;
/** /**
Send HCI command packet. Send HCI command packet.
@param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. The SendCommand() function sends HCI command packet. Buffer holds the whole HCI
@param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. command packet, including OpCode, OCF, OGF, parameter length, and parameters. When
On output, indicates the amount of data actually transferred. this function is returned, it just means the HCI command packet is sent, it does not mean
@param Buffer A pointer to the buffer of data that will be transmitted to Bluetooth host the command is success or complete. Caller might need to wait a command status event
controller. to know the command status, or wait a command complete event to know if the
@param Timeout Indicating the transfer should be completed within this time frame. The units are command is completed.
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. @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_SUCCESS The HCI command packet is sent successfully.
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- BufferSize is NULL. BufferSize is NULL.
- *BufferSize is 0. *BufferSize is 0.
- Buffer is NULL. Buffer is NULL.
@retval EFI_TIMEOUT Sending HCI command packet fail due to timeout. @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. @retval EFI_DEVICE_ERROR Sending HCI command packet fail due to host controller or device
error.
**/ **/
typedef typedef
@ -56,25 +66,31 @@ EFI_STATUS
IN UINTN Timeout IN UINTN Timeout
); );
/** /**
Receive HCI event packet. Receive HCI event packet.
@param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. The ReceiveEvent() function receives HCI event packet. Buffer holds the whole HCI event
@param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. packet, including EventCode, parameter length, and parameters.
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[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
@param Timeout Indicating the transfer should be completed within this time frame. The units are @param[in,out] BufferSize On input, indicates the size, in bytes, of the data buffer
in milliseconds. If Timeout is 0, then the caller must wait for the function to specified by Buffer. On output, indicates the amount of
be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. 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_SUCCESS The HCI event packet is received successfully.
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- BufferSize is NULL. BufferSize is NULL.
- *BufferSize is 0. *BufferSize is 0.
- Buffer is NULL. Buffer is NULL.
@retval EFI_TIMEOUT Receiving HCI event packet fail due to timeout. @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. @retval EFI_DEVICE_ERROR Receiving HCI event packet fail due to host controller or device
error.
**/ **/
typedef typedef
@ -87,13 +103,15 @@ EFI_STATUS
); );
/** /**
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[in] Data Data received via asynchronous transfer.
@param DataLength Specifies the length, in bytes, of the data to be received. @param[in] DataLength The length of Data in bytes, received via asynchronous
@param Context Data passed into Callback function. This is optional parameter and may be NULL. 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 typedef
@ -107,19 +125,26 @@ EFI_STATUS
/** /**
Receive HCI event packet in non-blocking way. Receive HCI event packet in non-blocking way.
@param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. The AsyncReceiveEvent() function receives HCI event packet in non-blocking way. Data
@param IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the request is deleted. in Callback function holds the whole HCI event packet, including EventCode, parameter
@param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be executed. length, and parameters.
@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 @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
completed. @param[in] IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the
@param Context Data passed into Callback function. This is optional parameter and may be NULL. 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_SUCCESS The HCI asynchronous receive request is submitted successfully.
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- DataLength is 0. DataLength is 0.
- If IsNewTransfer is TRUE, and an asynchronous receive request already exists. If IsNewTransfer is TRUE, and an asynchronous receive
request already exists.
**/ **/
typedef typedef
EFI_STATUS EFI_STATUS
@ -135,22 +160,34 @@ EFI_STATUS
/** /**
Send HCI ACL data packet. Send HCI ACL data packet.
@param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. The SendACLData() function sends HCI ACL data packet. Buffer holds the whole HCI ACL
@param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. data packet, including Handle, PB flag, BC flag, data length, and data.
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 The SendACLData() function and ReceiveACLData() function just send and receive data
controller. payload from application layer. In order to protect the payload data, the Bluetooth bus is
@param Timeout Indicating the transfer should be completed within this time frame. The units are required to call HCI_Set_Connection_Encryption command to enable hardware based
in milliseconds. If Timeout is 0, then the caller must wait for the function to encryption after authentication completed, according to pairing mode and host
be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. 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_SUCCESS The HCI ACL data packet is sent successfully.
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- BufferSize is NULL. BufferSize is NULL.
- *BufferSize is 0. *BufferSize is 0.
- Buffer is NULL. Buffer is NULL.
@retval EFI_TIMEOUT Sending HCI ACL data packet fail due to timeout. @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. @retval EFI_DEVICE_ERROR Sending HCI ACL data packet fail due to host controller or device
error.
**/ **/
typedef typedef
@ -165,21 +202,28 @@ EFI_STATUS
/** /**
Receive HCI ACL data packet. Receive HCI ACL data packet.
@param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. The ReceiveACLData() function receives HCI ACL data packet. Buffer holds the whole HCI
@param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. ACL data packet, including Handle, PB flag, BC flag, data length, and data.
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[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
@param Timeout Indicating the transfer should be completed within this time frame. The units are @param[in, out] BufferSize On input, indicates the size, in bytes, of the data buffer
in milliseconds. If Timeout is 0, then the caller must wait for the function to specified by Buffer. On output, indicates the amount of
be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. 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_SUCCESS The HCI ACL data packet is received successfully.
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- BufferSize is NULL. BufferSize is NULL.
- *BufferSize is 0. *BufferSize is 0.
- Buffer is NULL. Buffer is NULL.
@retval EFI_TIMEOUT Receiving HCI ACL data packet fail due to timeout. @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. @retval EFI_DEVICE_ERROR Receiving HCI ACL data packet fail due to host controller or device
error.
**/ **/
typedef typedef
@ -191,23 +235,29 @@ EFI_STATUS
IN UINTN Timeout IN UINTN Timeout
); );
/** /**
Receive HCI ACL data packet in non-blocking way. Receive HCI ACL data packet in non-blocking way.
@param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. The AsyncReceiveACLData() function receives HCI ACL data packet in non-blocking way.
@param IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the request is deleted. Data in Callback holds the whole HCI ACL data packet, including Handle, PB flag, BC flag,
@param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be executed. data length, and data.
@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 @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
completed. @param[in] IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the
@param Context Data passed into Callback function. This is optional parameter and may be NULL. 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_SUCCESS The HCI asynchronous receive request is submitted successfully.
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- DataLength is 0. DataLength is 0.
- If IsNewTransfer is TRUE, and an asynchronous receive request already exists. If IsNewTransfer is TRUE, and an asynchronous receive
request already exists.
**/ **/
typedef typedef
EFI_STATUS EFI_STATUS
@ -223,24 +273,29 @@ EFI_STATUS
/** /**
Send HCI SCO data packet. Send HCI SCO data packet.
@param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. The SendSCOData() function sends HCI SCO data packet. Buffer holds the whole HCI SCO
@param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. data packet, including ConnectionHandle, PacketStatus flag, data length, and data.
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 @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
controller. @param[in,out] BufferSize On input, indicates the size, in bytes, of the data buffer
@param Timeout Indicating the transfer should be completed within this time frame. The units are specified by Buffer. On output, indicates the amount of
in milliseconds. If Timeout is 0, then the caller must wait for the function to data actually transferred.
be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. @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_SUCCESS The HCI SCO data packet is sent successfully.
@retval EFI_UNSUPPORTED The implementation does not support HCI SCO transfer. @retval EFI_UNSUPPORTED The implementation does not support HCI SCO transfer.
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- BufferSize is NULL. BufferSize is NULL.
- *BufferSize is 0. *BufferSize is 0.
- Buffer is NULL. Buffer is NULL.
@retval EFI_TIMEOUT Sending HCI SCO data packet fail due to timeout. @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. @retval EFI_DEVICE_ERROR Sending HCI SCO data packet fail due to host controller or device
error.
**/ **/
typedef typedef
EFI_STATUS EFI_STATUS
@ -254,22 +309,28 @@ EFI_STATUS
/** /**
Receive HCI SCO data packet. Receive HCI SCO data packet.
@param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. The ReceiveSCOData() function receives HCI SCO data packet. Buffer holds the whole HCI
@param BufferSize On input, indicates the size, in bytes, of the data buffer specified by Buffer. SCO data packet, including ConnectionHandle, PacketStatus flag, data length, and data.
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[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
@param Timeout Indicating the transfer should be completed within this time frame. The units are @param[in,out] BufferSize On input, indicates the size, in bytes, of the data buffer
in milliseconds. If Timeout is 0, then the caller must wait for the function to specified by Buffer. On output, indicates the amount of
be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. 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_SUCCESS The HCI SCO data packet is received successfully.
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- BufferSize is NULL. BufferSize is NULL.
- *BufferSize is 0. *BufferSize is 0.
- Buffer is NULL. Buffer is NULL.
@retval EFI_TIMEOUT Receiving HCI SCO data packet fail due to timeout @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. @retval EFI_DEVICE_ERROR Receiving HCI SCO data packet fail due to host controller or device
error.
**/ **/
typedef typedef
EFI_STATUS EFI_STATUS
@ -283,19 +344,26 @@ EFI_STATUS
/** /**
Receive HCI SCO data packet in non-blocking way. Receive HCI SCO data packet in non-blocking way.
@param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. The AsyncReceiveSCOData() function receives HCI SCO data packet in non-blocking way.
@param IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the request is deleted. Data in Callback holds the whole HCI SCO data packet, including ConnectionHandle,
@param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be executed. PacketStatus flag, data length, and data.
@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 @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
completed. @param[in] IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the
@param Context Data passed into Callback function. This is optional parameter and may be NULL. 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_SUCCESS The HCI asynchronous receive request is submitted successfully.
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- DataLength is 0. DataLength is 0.
- If IsNewTransfer is TRUE, and an asynchronous receive request already exists. If IsNewTransfer is TRUE, and an asynchronous receive
request already exists.
**/ **/
typedef typedef
EFI_STATUS EFI_STATUS
@ -308,21 +376,49 @@ EFI_STATUS
IN VOID *Context 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 { struct _EFI_BLUETOOTH_HC_PROTOCOL {
//
// Send HCI command packet.
//
EFI_BLUETOOTH_HC_SEND_COMMAND SendCommand; EFI_BLUETOOTH_HC_SEND_COMMAND SendCommand;
//
// Receive HCI event packets.
//
EFI_BLUETOOTH_HC_RECEIVE_EVENT ReceiveEvent; EFI_BLUETOOTH_HC_RECEIVE_EVENT ReceiveEvent;
//
// Non-blocking receive HCI event packets.
//
EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT AsyncReceiveEvent; EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT AsyncReceiveEvent;
//
// Send HCI ACL (asynchronous connection-oriented) data packets.
//
EFI_BLUETOOTH_HC_SEND_ACL_DATA SendACLData; EFI_BLUETOOTH_HC_SEND_ACL_DATA SendACLData;
//
// Receive HCI ACL data packets.
//
EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA ReceiveACLData; EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA ReceiveACLData;
//
// Non-blocking receive HCI ACL data packets.
//
EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA AsyncReceiveACLData; EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA AsyncReceiveACLData;
//
// Send HCI synchronous (SCO and eSCO) data packets.
//
EFI_BLUETOOTH_HC_SEND_SCO_DATA SendSCOData; EFI_BLUETOOTH_HC_SEND_SCO_DATA SendSCOData;
//
// Receive HCI synchronous data packets.
//
EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA ReceiveSCOData; EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA ReceiveSCOData;
//
// Non-blocking receive HCI synchronous data packets.
//
EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA AsyncReceiveSCOData; EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA AsyncReceiveSCOData;
}; };
extern EFI_GUID gEfiBluetoothHcProtocolGuid; extern EFI_GUID gEfiBluetoothHcProtocolGuid;
#endif #endif