From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga07.intel.com (mga07.intel.com [134.134.136.100]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id 482772095CC6F for ; Mon, 5 Jun 2017 20:26:55 -0700 (PDT) Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by orsmga105.jf.intel.com with ESMTP; 05 Jun 2017 20:27:59 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.39,304,1493708400"; d="scan'208";a="864935258" Received: from ray-dev.ccr.corp.intel.com ([10.239.9.1]) by FMSMGA003.fm.intel.com with ESMTP; 05 Jun 2017 20:27:57 -0700 From: Ruiyu Ni To: edk2-devel@lists.01.org Cc: Jiewen Yao Date: Tue, 6 Jun 2017 11:27:44 +0800 Message-Id: <20170606032746.238188-4-ruiyu.ni@intel.com> X-Mailer: git-send-email 2.12.2.windows.2 In-Reply-To: <20170606032746.238188-1-ruiyu.ni@intel.com> References: <20170606032746.238188-1-ruiyu.ni@intel.com> Subject: [PATCH 3/5] MdePkg/BluetoothHc: Add detailed function header comments X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.22 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 06 Jun 2017 03:26:55 -0000 Contributed-under: TianoCore Contribution Agreement 1.0 Signed-off-by: Ruiyu Ni Cc: Jiewen Yao --- 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.
- 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.
+ 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