EmbeddedPkg/AndroidFastbootTransport.h: Introduced Android Fastboot Transport protocol

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Olivier Martin <olivier.martin@arm.com>
git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@15310 6f19259b-4bc3-4df7-8a09-765794883524

diff --git a/EmbeddedPkg/EmbeddedPkg.dec b/EmbeddedPkg/EmbeddedPkg.dec
index 1b8ef158afe4f1571885ced0629f49297aefb2a6..a09b6d24d776b732f488c3ab15635be442801e8b 100644 (file)
--- a/EmbeddedPkg/EmbeddedPkg.dec
+++ b/EmbeddedPkg/EmbeddedPkg.dec
@@ -3,6 +3,7 @@
 #\r
 # This Package provides headers and libraries that conform to EFI/PI Industry standards.\r
 # Copyright (c) 2007, Intel Corporation. All rights reserved.<BR>\r
 #\r
 # This Package provides headers and libraries that conform to EFI/PI Industry standards.\r
 # Copyright (c) 2007, Intel Corporation. All rights reserved.<BR>\r

+# Copyright (c) 2012-2014, ARM Ltd. All rights reserved.<BR>\r

 #\r
 #    This program and the accompanying materials are licensed and made available under\r
 #    the terms and conditions of the BSD License which accompanies this distribution.\r
 #\r
 #    This program and the accompanying materials are licensed and made available under\r
 #    the terms and conditions of the BSD License which accompanies this distribution.\r


@@ -57,6 +58,7 @@
   gEmbeddedGpioProtocolGuid           = { 0x17a0a3d7, 0xc0a5, 0x4635, { 0xbb, 0xd5, 0x07, 0x21, 0x87, 0xdf, 0xe2, 0xee }}\r
   gPeCoffLoaderProtocolGuid =  { 0xB323179B, 0x97FB, 0x477E, { 0xB0, 0xFE, 0xD8, 0x85, 0x91, 0xFA, 0x11, 0xAB } }\r
   gEfiMmcHostProtocolGuid              = { 0x3e591c00, 0x9e4a, 0x11df, {0x92, 0x44, 0x00, 0x02, 0xA5, 0xD5, 0xC5, 0x1B }}\r
   gEmbeddedGpioProtocolGuid           = { 0x17a0a3d7, 0xc0a5, 0x4635, { 0xbb, 0xd5, 0x07, 0x21, 0x87, 0xdf, 0xe2, 0xee }}\r
   gPeCoffLoaderProtocolGuid =  { 0xB323179B, 0x97FB, 0x477E, { 0xB0, 0xFE, 0xD8, 0x85, 0x91, 0xFA, 0x11, 0xAB } }\r
   gEfiMmcHostProtocolGuid              = { 0x3e591c00, 0x9e4a, 0x11df, {0x92, 0x44, 0x00, 0x02, 0xA5, 0xD5, 0xC5, 0x1B }}\r

+  gAndroidFastbootTransportProtocolGuid = { 0x74bd9fe0, 0x8902, 0x11e3, {0xb9, 0xd3, 0xf7, 0x22, 0x38, 0xfc, 0x9a, 0x31}}\r

 \r
 [PcdsFeatureFlag.common]\r
   gEmbeddedTokenSpaceGuid.PcdEmbeddedMacBoot|FALSE|BOOLEAN|0x00000001\r
 \r
 [PcdsFeatureFlag.common]\r
   gEmbeddedTokenSpaceGuid.PcdEmbeddedMacBoot|FALSE|BOOLEAN|0x00000001\r

diff --git a/EmbeddedPkg/Include/Protocol/AndroidFastbootTransport.h b/EmbeddedPkg/Include/Protocol/AndroidFastbootTransport.h
new file mode 100644 (file)
index 0000000..8070687
--- /dev/null
+++ b/EmbeddedPkg/Include/Protocol/AndroidFastbootTransport.h
@@ -0,0 +1,131 @@
+/** @file\r
+\r
+  Copyright (c) 2014, ARM Ltd. All rights reserved.<BR>\r
+\r
+  This program and the accompanying materials\r
+  are licensed and made available under the terms and conditions of the BSD License\r
+  which accompanies this distribution.  The full text of the license may be found at\r
+  http://opensource.org/licenses/bsd-license.php\r
+\r
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+**/\r
+\r
+/*\r
+  Transport protocol over which Android Fastboot transactions can be made.\r
+  Fastboot is designed for USB, but this protocol is intended as an abstraction\r
+   so that it can be implemented over any transport mechanism.\r
+*/\r
+\r
+#ifndef __ANDROID_FASTBOOT_TRANSPORT_H__\r
+#define __ANDROID_FASTBOOT_TRANSPORT_H__\r
+\r
+extern EFI_GUID gAndroidFastbootTransportProtocolGuid;\r
+\r
+/*\r
+  Set up the transport system for use by Fastboot.\r
+  e.g. For USB this probably means making the device enumerable. For TCP,\r
+       preparing to accept incoming connections.\r
+\r
+  It is _not_ the responsibility of this protocol's implementer to unite the\r
+  data phase into a single buffer - that is handled by the Fastboot UEFI\r
+  application. As the Fastboot protocol spec says: "Short packets are always\r
+   acceptable and zero-length packets are ignored."\r
+  However the commands and responses must be in a single packet, and the order\r
+  of the packets must of course be maintained.\r
+\r
+  If there is a fatal error in the receive channel, ReceiveEvent will be\r
+  signalled, and a subsequent call to Receive() will return an error. This\r
+  allows data transported prior to the error to be received.\r
+\r
+  @param[in] ReceiveEvent  Event to be Signalled when a packet has been received\r
+                           and is ready to be retrieved via Receive().\r
+\r
+  @retval EFI_SUCCESS       Initialised successfully.\r
+  @retval EFI_DEVICE_ERROR  Error in initialising hardware\r
+  @retval (other)           Error return from LocateProtocol functions.\r
+*/\r
+typedef\r
+EFI_STATUS\r
+(*FASTBOOT_TRANSPORT_START) (\r
+  IN EFI_EVENT ReceiveEvent\r
+  );\r
+\r
+/*\r
+  Function to be called when all Fastboot transactions are finished, to\r
+  de-initialise the transport system.\r
+  e.g. A USB OTG system might want to get out of peripheral mode so it can be\r
+       a USB host.\r
+\r
+  Note that this function will be called after an error is reported by Send or\r
+  Receive\r
+\r
+  @retval EFI_SUCCESS       De-initialised successfully.\r
+  @retval EFI_DEVICE_ERROR  Error de-initialising hardware.\r
+*/\r
+typedef\r
+EFI_STATUS\r
+(* FASTBOOT_TRANSPORT_STOP) (\r
+  VOID\r
+  );\r
+\r
+/*\r
+  Send data. This function can be used both for command responses like "OKAY"\r
+  and for the data phase (the protocol doesn't describe any situation when the\r
+   latter might be necessary, but does allow it)\r
+\r
+  Transmission need not finish before the function returns.\r
+  If there is an error in transmission from which the transport system cannot\r
+  recover, FatalErrorEvent will be signalled. Otherwise, it is assumed that all\r
+  data was delivered successfully.\r
+\r
+  @param[in] BufferSize       Size in bytes of data to send.\r
+  @param[in] Buffer           Data to send.\r
+  @param[in] FatalErrorEvent  Event to signal if there was an error in\r
+                              transmission from which the transport system\r
+                              cannot recover.\r
+\r
+  @retval EFI_SUCCESS       The data was sent or queued for send.\r
+  @retval EFI_DEVICE_ERROR  There was an error preparing to send the data.\r
+ */\r
+typedef\r
+EFI_STATUS\r
+(*FASTBOOT_TRANSPORT_SEND) (\r
+  IN        UINTN      BufferSize,\r
+  IN  CONST VOID      *Buffer,\r
+  IN        EFI_EVENT *FatalErrorEvent\r
+  );\r
+\r
+/*\r
+  When the event has been Signalled to say data is available from the host,\r
+  this function is used to get data. In order to handle the case where several\r
+  packets are received before ReceiveEvent's notify function is called, packets\r
+  received are queued, and each call to this function returns the next packet in\r
+  the queue. It should therefore be called in a loop, the exit condition being a\r
+  return of EFI_NOT_READY.\r
+\r
+  @param[out]  Buffer       Pointer to received data. Callee allocated - the\r
+                            caller must free it with FreePool.\r
+  @param[out]  BufferSize   The size of received data in bytes\r
+\r
+  @retval EFI_NOT_READY     There is no data available\r
+  @retval EFI_DEVICE_ERROR  There was a fatal error in the receive channel.\r
+                            e.g. for USB the cable was unplugged or for TCP the\r
+                            connection was closed by the remote host..\r
+*/\r
+typedef\r
+EFI_STATUS\r
+(*FASTBOOT_TRANSPORT_RECEIVE) (\r
+  OUT UINTN  *BufferSize,\r
+  OUT VOID  **Buffer\r
+  );\r
+\r
+typedef struct _FASTBOOT_TRANSPORT_PROTOCOL {\r
+  FASTBOOT_TRANSPORT_START                     Start;\r
+  FASTBOOT_TRANSPORT_STOP                      Stop;\r
+  FASTBOOT_TRANSPORT_SEND                      Send;\r
+  FASTBOOT_TRANSPORT_RECEIVE                   Receive;\r
+} FASTBOOT_TRANSPORT_PROTOCOL;\r
+\r
+#endif\r