From d8fd88626bc97303a423733fd0baa208e28728ec Mon Sep 17 00:00:00 2001 From: Olivier Martin Date: Wed, 5 Mar 2014 04:12:35 +0000 Subject: [PATCH] EmbeddedPkg/AndroidFastbootTransport.h: Introduced Android Fastboot Transport protocol Contributed-under: TianoCore Contribution Agreement 1.0 Signed-off-by: Olivier Martin git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@15310 6f19259b-4bc3-4df7-8a09-765794883524 --- EmbeddedPkg/EmbeddedPkg.dec | 2 + .../Protocol/AndroidFastbootTransport.h | 131 ++++++++++++++++++ 2 files changed, 133 insertions(+) create mode 100644 EmbeddedPkg/Include/Protocol/AndroidFastbootTransport.h diff --git a/EmbeddedPkg/EmbeddedPkg.dec b/EmbeddedPkg/EmbeddedPkg.dec index 1b8ef158af..a09b6d24d7 100644 --- a/EmbeddedPkg/EmbeddedPkg.dec +++ b/EmbeddedPkg/EmbeddedPkg.dec @@ -3,6 +3,7 @@ # # This Package provides headers and libraries that conform to EFI/PI Industry standards. # Copyright (c) 2007, Intel Corporation. All rights reserved.
+# Copyright (c) 2012-2014, ARM Ltd. All rights reserved.
# # This program and the accompanying materials are licensed and made available under # the terms and conditions of the BSD License which accompanies this distribution. @@ -57,6 +58,7 @@ gEmbeddedGpioProtocolGuid = { 0x17a0a3d7, 0xc0a5, 0x4635, { 0xbb, 0xd5, 0x07, 0x21, 0x87, 0xdf, 0xe2, 0xee }} gPeCoffLoaderProtocolGuid = { 0xB323179B, 0x97FB, 0x477E, { 0xB0, 0xFE, 0xD8, 0x85, 0x91, 0xFA, 0x11, 0xAB } } gEfiMmcHostProtocolGuid = { 0x3e591c00, 0x9e4a, 0x11df, {0x92, 0x44, 0x00, 0x02, 0xA5, 0xD5, 0xC5, 0x1B }} + gAndroidFastbootTransportProtocolGuid = { 0x74bd9fe0, 0x8902, 0x11e3, {0xb9, 0xd3, 0xf7, 0x22, 0x38, 0xfc, 0x9a, 0x31}} [PcdsFeatureFlag.common] gEmbeddedTokenSpaceGuid.PcdEmbeddedMacBoot|FALSE|BOOLEAN|0x00000001 diff --git a/EmbeddedPkg/Include/Protocol/AndroidFastbootTransport.h b/EmbeddedPkg/Include/Protocol/AndroidFastbootTransport.h new file mode 100644 index 0000000000..807068717e --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/AndroidFastbootTransport.h @@ -0,0 +1,131 @@ +/** @file + + Copyright (c) 2014, ARM Ltd. All rights reserved.
+ + This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which 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, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +**/ + +/* + Transport protocol over which Android Fastboot transactions can be made. + Fastboot is designed for USB, but this protocol is intended as an abstraction + so that it can be implemented over any transport mechanism. +*/ + +#ifndef __ANDROID_FASTBOOT_TRANSPORT_H__ +#define __ANDROID_FASTBOOT_TRANSPORT_H__ + +extern EFI_GUID gAndroidFastbootTransportProtocolGuid; + +/* + Set up the transport system for use by Fastboot. + e.g. For USB this probably means making the device enumerable. For TCP, + preparing to accept incoming connections. + + It is _not_ the responsibility of this protocol's implementer to unite the + data phase into a single buffer - that is handled by the Fastboot UEFI + application. As the Fastboot protocol spec says: "Short packets are always + acceptable and zero-length packets are ignored." + However the commands and responses must be in a single packet, and the order + of the packets must of course be maintained. + + If there is a fatal error in the receive channel, ReceiveEvent will be + signalled, and a subsequent call to Receive() will return an error. This + allows data transported prior to the error to be received. + + @param[in] ReceiveEvent Event to be Signalled when a packet has been received + and is ready to be retrieved via Receive(). + + @retval EFI_SUCCESS Initialised successfully. + @retval EFI_DEVICE_ERROR Error in initialising hardware + @retval (other) Error return from LocateProtocol functions. +*/ +typedef +EFI_STATUS +(*FASTBOOT_TRANSPORT_START) ( + IN EFI_EVENT ReceiveEvent + ); + +/* + Function to be called when all Fastboot transactions are finished, to + de-initialise the transport system. + e.g. A USB OTG system might want to get out of peripheral mode so it can be + a USB host. + + Note that this function will be called after an error is reported by Send or + Receive + + @retval EFI_SUCCESS De-initialised successfully. + @retval EFI_DEVICE_ERROR Error de-initialising hardware. +*/ +typedef +EFI_STATUS +(* FASTBOOT_TRANSPORT_STOP) ( + VOID + ); + +/* + Send data. This function can be used both for command responses like "OKAY" + and for the data phase (the protocol doesn't describe any situation when the + latter might be necessary, but does allow it) + + Transmission need not finish before the function returns. + If there is an error in transmission from which the transport system cannot + recover, FatalErrorEvent will be signalled. Otherwise, it is assumed that all + data was delivered successfully. + + @param[in] BufferSize Size in bytes of data to send. + @param[in] Buffer Data to send. + @param[in] FatalErrorEvent Event to signal if there was an error in + transmission from which the transport system + cannot recover. + + @retval EFI_SUCCESS The data was sent or queued for send. + @retval EFI_DEVICE_ERROR There was an error preparing to send the data. + */ +typedef +EFI_STATUS +(*FASTBOOT_TRANSPORT_SEND) ( + IN UINTN BufferSize, + IN CONST VOID *Buffer, + IN EFI_EVENT *FatalErrorEvent + ); + +/* + When the event has been Signalled to say data is available from the host, + this function is used to get data. In order to handle the case where several + packets are received before ReceiveEvent's notify function is called, packets + received are queued, and each call to this function returns the next packet in + the queue. It should therefore be called in a loop, the exit condition being a + return of EFI_NOT_READY. + + @param[out] Buffer Pointer to received data. Callee allocated - the + caller must free it with FreePool. + @param[out] BufferSize The size of received data in bytes + + @retval EFI_NOT_READY There is no data available + @retval EFI_DEVICE_ERROR There was a fatal error in the receive channel. + e.g. for USB the cable was unplugged or for TCP the + connection was closed by the remote host.. +*/ +typedef +EFI_STATUS +(*FASTBOOT_TRANSPORT_RECEIVE) ( + OUT UINTN *BufferSize, + OUT VOID **Buffer + ); + +typedef struct _FASTBOOT_TRANSPORT_PROTOCOL { + FASTBOOT_TRANSPORT_START Start; + FASTBOOT_TRANSPORT_STOP Stop; + FASTBOOT_TRANSPORT_SEND Send; + FASTBOOT_TRANSPORT_RECEIVE Receive; +} FASTBOOT_TRANSPORT_PROTOCOL; + +#endif -- 2.39.2