From nobody Sat Dec 28 12:03:30 2024 Delivered-To: importer@patchew.org Received-SPF: none (zoho.com: 198.145.21.10 is neither permitted nor denied by domain of lists.01.org) client-ip=198.145.21.10; envelope-from=edk2-devel-bounces@lists.01.org; helo=ml01.01.org; Authentication-Results: mx.zoho.com; spf=none (zoho.com: 198.145.21.10 is neither permitted nor denied by domain of lists.01.org) smtp.mailfrom=edk2-devel-bounces@lists.01.org; Return-Path: Received: from ml01.01.org (ml01.01.org [198.145.21.10]) by mx.zohomail.com with SMTPS id 1496720157559612.8710546247107; Mon, 5 Jun 2017 20:35:57 -0700 (PDT) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 8884321959CB3; Mon, 5 Jun 2017 20:34:44 -0700 (PDT) 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 D96B821959CAC for ; Mon, 5 Jun 2017 20:34:42 -0700 (PDT) Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by orsmga105.jf.intel.com with ESMTP; 05 Jun 2017 20:35:49 -0700 Received: from ray-dev.ccr.corp.intel.com ([10.239.9.1]) by FMSMGA003.fm.intel.com with ESMTP; 05 Jun 2017 20:35:48 -0700 X-Original-To: edk2-devel@lists.01.org X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.39,304,1493708400"; d="scan'208";a="864937065" From: Ruiyu Ni To: edk2-devel@lists.01.org Date: Tue, 6 Jun 2017 11:35:41 +0800 Message-Id: <20170606033543.254936-4-ruiyu.ni@intel.com> X-Mailer: git-send-email 2.12.2.windows.2 In-Reply-To: <20170606033543.254936-1-ruiyu.ni@intel.com> References: <20170606033543.254936-1-ruiyu.ni@intel.com> Subject: [edk2] [PATCH v2 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: , Cc: Jiewen Yao MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Errors-To: edk2-devel-bounces@lists.01.org Sender: "edk2-devel" X-ZohoMail: RSF_4 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" 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/Protoco= l/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 tran= smit and receive. =20 - Copyright (c) 2015, Intel Corporation. All rights reserved.
- This program and the accompanying materials are licensed and made availa= ble under=20 - the terms and conditions of the BSD License that accompanies this distri= bution. =20 + Copyright (c) 2015 - 2017, Intel Corporation. All rights reserved.
+ This program and the accompanying materials are licensed and made availa= ble under + the terms and conditions of the BSD License that accompanies this distri= bution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php. = =20 - =20 - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, = =20 + 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 IMP= LIED. =20 - @par Revision Reference: =20 + @par Revision Reference: This Protocol is introduced in UEFI Specification 2.5 =20 **/ @@ -29,300 +29,396 @@ typedef struct _EFI_BLUETOOTH_HC_PROTOCOL EFI_BLUETOO= TH_HC_PROTOCOL; /** Send HCI command packet. =20 - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param BufferSize On input, indicates the size, in bytes, of the dat= a buffer specified by Buffer.=20 - On output, indicates the amount of data actually t= ransferred. - @param Buffer A pointer to the buffer of data that will be trans= mitted to Bluetooth host=20 - controller. - @param Timeout Indicating the transfer should be completed within= this time frame. The units are=20 - in milliseconds. If Timeout is 0, then the caller = must wait for the function to=20 - be completed until EFI_SUCCESS or EFI_DEVICE_ERROR= is returned. - - @retval EFI_SUCCESS The HCI command packet is sent successfull= y. - @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 tim= eout. - @retval EFI_DEVICE_ERROR Sending HCI command packet fail due to hos= t controller or device error. + The SendCommand() function sends HCI command packet. Buffer holds the wh= ole HCI + command packet, including OpCode, OCF, OGF, parameter length, and parame= ters. 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_PROTOC= OL instance. + @param[in,out] BufferSize On input, indicates the size, in bytes= , of the data buffer + specified by Buffer. On output, indica= tes the amount of + data actually transferred. + @param[in] Buffer A pointer to the buffer of data that w= ill be transmitted to + Bluetooth host controller. + @param[in] Timeout Indicating the transfer should be comp= leted within this + time frame. The units are in milliseco= nds. If Timeout is 0, + then the caller must wait for the func= tion to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR = is returned. + + @retval EFI_SUCCESS The HCI command packet is sent success= fully. + @retval EFI_INVALID_PARAMETER One or more of the following condition= s 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. =20 **/ -typedef=20 +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 ); - =20 =20 /** Receive HCI event packet. =20 - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param BufferSize On input, indicates the size, in bytes, of the dat= a buffer specified by Buffer.=20 - On output, indicates the amount of data actually t= ransferred. - @param Buffer A pointer to the buffer of data that will be recei= ved from Bluetooth host controller. - @param Timeout Indicating the transfer should be completed within= this time frame. The units are=20 - in milliseconds. If Timeout is 0, then the caller = must wait for the function to=20 - be completed until EFI_SUCCESS or EFI_DEVICE_ERROR= is returned. - - @retval EFI_SUCCESS The HCI event packet is received successfu= lly. - @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 tim= eout. - @retval EFI_DEVICE_ERROR Receiving HCI event packet fail due to hos= t 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_PROTOC= OL instance. + @param[in,out] BufferSize On input, indicates the size, in bytes= , of the data buffer + specified by Buffer. On output, indica= tes the amount of + data actually transferred. + @param[out] Buffer A pointer to the buffer of data that w= ill be received from + Bluetooth host controller. + @param[in] Timeout Indicating the transfer should be comp= leted within this + time frame. The units are in milliseco= nds. If Timeout is 0, + then the caller must wait for the func= tion to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR = is returned. + + @retval EFI_SUCCESS The HCI event packet is received succe= ssfully. + @retval EFI_INVALID_PARAMETER One or more of the following condition= s 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. =20 **/ 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 ); - =20 + /** - Callback function, it is called when asynchronous transfer is completed. + The async callback of AsyncReceiveEvent(). =20 - @param Data Pointer to the EFI_BLUETOOTH_HC_PROTOCOL insta= nce. - @param DataLength Specifies the length, in bytes, of the data to= be received. - @param Context Data passed into Callback function. This is op= tional parameter and may be NULL. + @param[in] Data Data received via asynchronous transfe= r. + @param[in] DataLength The length of Data in bytes, received = via asynchronous + transfer. + @param[in] Context Context passed from asynchronous trans= fer request. =20 - @retval EFI_SUCCESS The callback function complete successfu= lly. + @retval EFI_SUCCESS The callback does execute successfully. + @retval Others The callback doesn't execute successfu= lly. =20 **/ 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 ); - =20 + /** Receive HCI event packet in non-blocking way. =20 - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL insta= nce. - @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=20 - completed. - @param Context Data passed into Callback function. This is op= tional parameter and may be NULL. - - @retval EFI_SUCCESS The HCI asynchronous receive request is su= bmitted successfully. - @retval EFI_INVALID_PARAMETER One or more of the following conditions is= TRUE: - - DataLength is 0. - - If IsNewTransfer is TRUE, and an asynchr= onous receive request already exists. - + The AsyncReceiveEvent() function receives HCI event packet in non-blocki= ng way. Data + in Callback function holds the whole HCI event packet, including EventCo= de, parameter + length, and parameters. + + @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOC= OL instance. + @param[in] IsNewTransfer If TRUE, a new transfer will be submit= ted. If FALSE, the + request is deleted. + @param[in] PollingInterval Indicates the periodic rate, in millis= econds, 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 i= s called if the + asynchronous transfer is completed. + @param[in] Context Data passed into Callback function. Th= is is optional + parameter and may be NULL. + + @retval EFI_SUCCESS The HCI asynchronous receive request i= s submitted successfully. + @retval EFI_INVALID_PARAMETER One or more of the following condition= s is TRUE: + DataLength is 0. + If IsNewTransfer is TRUE, and an asy= nchronous 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 ); - =20 + /** Send HCI ACL data packet. =20 - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param BufferSize On input, indicates the size, in bytes, of the dat= a buffer specified by Buffer.=20 - On output, indicates the amount of data actually t= ransferred. - @param Buffer A pointer to the buffer of data that will be trans= mitted to Bluetooth host=20 - controller. - @param Timeout Indicating the transfer should be completed within= this time frame. The units are=20 - in milliseconds. If Timeout is 0, then the caller = must wait for the function to=20 - be completed until EFI_SUCCESS or EFI_DEVICE_ERROR= is returned. - - @retval EFI_SUCCESS The HCI ACL data packet is sent successful= ly. - @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 ti= meout. - @retval EFI_DEVICE_ERROR Sending HCI ACL data packet fail due to ho= st controller or device error. + The SendACLData() function sends HCI ACL data packet. Buffer holds the w= hole HCI ACL + data packet, including Handle, PB flag, BC flag, data length, and data. + + The SendACLData() function and ReceiveACLData() function just send and r= eceive data + payload from application layer. In order to protect the payload data, th= e Bluetooth bus is + required to call HCI_Set_Connection_Encryption command to enable hardwar= e based + encryption after authentication completed, according to pairing mode and= host + capability. + + @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOC= OL instance. + @param[in, out] BufferSize On input, indicates the size, in bytes= , of the data buffer + specified by Buffer. On output, indica= tes the amount of + data actually transferred. + @param[in] Buffer A pointer to the buffer of data that w= ill be transmitted to + Bluetooth host controller. + @param[in] Timeout Indicating the transfer should be comp= leted within this + time frame. The units are in milliseco= nds. If Timeout is 0, + then the caller must wait for the func= tion to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR = is returned. + + @retval EFI_SUCCESS The HCI ACL data packet is sent succes= sfully. + @retval EFI_INVALID_PARAMETER One or more of the following condition= s is TRUE: + BufferSize is NULL. + *BufferSize is 0. + Buffer is NULL. + @retval EFI_TIMEOUT Sending HCI ACL data packet fail due t= o timeout. + @retval EFI_DEVICE_ERROR Sending HCI ACL data packet fail due t= o host controller or device + error. =20 **/ 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 ); - =20 + /** Receive HCI ACL data packet. =20 - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param BufferSize On input, indicates the size, in bytes, of the dat= a buffer specified by Buffer.=20 - On output, indicates the amount of data actually t= ransferred. - @param Buffer A pointer to the buffer of data that will be recei= ved from Bluetooth host controller. - @param Timeout Indicating the transfer should be completed within= this time frame. The units are=20 - in milliseconds. If Timeout is 0, then the caller = must wait for the function to=20 - be completed until EFI_SUCCESS or EFI_DEVICE_ERROR= is returned. - - @retval EFI_SUCCESS The HCI ACL data packet is received succes= sfully. - @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 da= ta. + + @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOC= OL instance. + @param[in, out] BufferSize On input, indicates the size, in bytes= , of the data buffer + specified by Buffer. On output, indica= tes the amount of + data actually transferred. + @param[out] Buffer A pointer to the buffer of data that w= ill be received from + Bluetooth host controller. + @param[in] Timeout Indicating the transfer should be comp= leted within this + time frame. The units are in milliseco= nds. If Timeout is 0, + then the caller must wait for the func= tion to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR = is returned. + + @retval EFI_SUCCESS The HCI ACL data packet is received su= ccessfully. + @retval EFI_INVALID_PARAMETER One or more of the following condition= s 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. =20 **/ 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 ); - =20 =20 /** Receive HCI ACL data packet in non-blocking way. =20 - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL insta= nce. - @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=20 - completed. - @param Context Data passed into Callback function. This is op= tional parameter and may be NULL. - - @retval EFI_SUCCESS The HCI asynchronous receive request is su= bmitted successfully. - @retval EFI_INVALID_PARAMETER One or more of the following conditions is= TRUE: - - DataLength is 0. - - If IsNewTransfer is TRUE, and an asynchr= onous receive request already exists. - + The AsyncReceiveACLData() function receives HCI ACL data packet in non-b= locking 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_PROTOC= OL instance. + @param[in] IsNewTransfer If TRUE, a new transfer will be submit= ted. If FALSE, the + request is deleted. + @param[in] PollingInterval Indicates the periodic rate, in millis= econds, 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 i= s called if the + asynchronous transfer is completed. + @param[in] Context Data passed into Callback function. Th= is is optional + parameter and may be NULL. + + @retval EFI_SUCCESS The HCI asynchronous receive request i= s submitted successfully. + @retval EFI_INVALID_PARAMETER One or more of the following condition= s is TRUE: + DataLength is 0. + If IsNewTransfer is TRUE, and an asy= nchronous 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 ); - =20 + /** Send HCI SCO data packet. =20 - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param BufferSize On input, indicates the size, in bytes, of the dat= a buffer specified by Buffer.=20 - On output, indicates the amount of data actually t= ransferred. - @param Buffer A pointer to the buffer of data that will be trans= mitted to Bluetooth host=20 - controller. - @param Timeout Indicating the transfer should be completed within= this time frame. The units are=20 - in milliseconds. If Timeout is 0, then the caller = must wait for the function to=20 - be completed until EFI_SUCCESS or EFI_DEVICE_ERROR= is returned. - - @retval EFI_SUCCESS The HCI SCO data packet is sent successful= ly. - @retval EFI_UNSUPPORTED The implementation does not support HCI SC= O 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 ti= meout. - @retval EFI_DEVICE_ERROR Sending HCI SCO data packet fail due to ho= st controller or device error. - + The SendSCOData() function sends HCI SCO data packet. Buffer holds the w= hole HCI SCO + data packet, including ConnectionHandle, PacketStatus flag, data length,= and data. + + @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOC= OL instance. + @param[in,out] BufferSize On input, indicates the size, in bytes= , of the data buffer + specified by Buffer. On output, indica= tes the amount of + data actually transferred. + @param[in] Buffer A pointer to the buffer of data that w= ill be transmitted to + Bluetooth host controller. + @param[in] Timeout Indicating the transfer should be comp= leted within this + time frame. The units are in milliseco= nds. If Timeout is 0, + then the caller must wait for the func= tion to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR = is returned. + + @retval EFI_SUCCESS The HCI SCO data packet is sent succes= sfully. + @retval EFI_UNSUPPORTED The implementation does not support HC= I SCO transfer. + @retval EFI_INVALID_PARAMETER One or more of the following condition= s is TRUE: + BufferSize is NULL. + *BufferSize is 0. + Buffer is NULL. + @retval EFI_TIMEOUT Sending HCI SCO data packet fail due t= o timeout. + @retval EFI_DEVICE_ERROR Sending HCI SCO data packet fail due t= o 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 ); - =20 + /** Receive HCI SCO data packet. =20 - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance. - @param BufferSize On input, indicates the size, in bytes, of the dat= a buffer specified by Buffer.=20 - On output, indicates the amount of data actually t= ransferred. - @param Buffer A pointer to the buffer of data that will be recei= ved from Bluetooth host controller. - @param Timeout Indicating the transfer should be completed within= this time frame. The units are=20 - in milliseconds. If Timeout is 0, then the caller = must wait for the function to=20 - be completed until EFI_SUCCESS or EFI_DEVICE_ERROR= is returned. - - @retval EFI_SUCCESS The HCI SCO data packet is received succes= sfully. - @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 len= gth, and data. + + @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOC= OL instance. + @param[in,out] BufferSize On input, indicates the size, in bytes= , of the data buffer + specified by Buffer. On output, indica= tes the amount of + data actually transferred. + @param[out] Buffer A pointer to the buffer of data that w= ill be received from + Bluetooth host controller. + @param[in] Timeout Indicating the transfer should be comp= leted within this + time frame. The units are in milliseco= nds. If Timeout is 0, + then the caller must wait for the func= tion to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR = is returned. + + @retval EFI_SUCCESS The HCI SCO data packet is received su= ccessfully. + @retval EFI_INVALID_PARAMETER One or more of the following condition= s 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 ); =20 /** Receive HCI SCO data packet in non-blocking way. =20 - @param This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL insta= nce. - @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=20 - completed. - @param Context Data passed into Callback function. This is op= tional parameter and may be NULL. - - @retval EFI_SUCCESS The HCI asynchronous receive request is su= bmitted successfully. - @retval EFI_INVALID_PARAMETER One or more of the following conditions is= TRUE: - - DataLength is 0. - - If IsNewTransfer is TRUE, and an asynchr= onous receive request already exists. - + The AsyncReceiveSCOData() function receives HCI SCO data packet in non-b= locking way. + Data in Callback holds the whole HCI SCO data packet, including Connecti= onHandle, + PacketStatus flag, data length, and data. + + @param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOC= OL instance. + @param[in] IsNewTransfer If TRUE, a new transfer will be submit= ted. If FALSE, the + request is deleted. + @param[in] PollingInterval Indicates the periodic rate, in millis= econds, 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 i= s called if the + asynchronous transfer is completed. + @param[in] Context Data passed into Callback function. Th= is is optional + parameter and may be NULL. + + @retval EFI_SUCCESS The HCI asynchronous receive request i= s submitted successfully. + @retval EFI_INVALID_PARAMETER One or more of the following condition= s is TRUE: + DataLength is 0. + If IsNewTransfer is TRUE, and an asy= nchronous 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 ); - =20 -/// -/// This protocol abstracts the Bluetooth host controller layer message tr= ansmit 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; }; - =20 + extern EFI_GUID gEfiBluetoothHcProtocolGuid; =20 #endif + --=20 2.12.2.windows.2 _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel