EmbeddedPkg/Include/Protocol/AndroidFastbootPlatform.h

   1 /** @file
   2
   3   Copyright (c) 2014, ARM Ltd. All rights reserved.<BR>
   4
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef __ANDROID_FASTBOOT_PLATFORM_H__
  16 #define __ANDROID_FASTBOOT_PLATFORM_H__
  17
  18 extern EFI_GUID gAndroidFastbootPlatformProtocolGuid;
  19
  20 /*
  21   Protocol for platform-specific operations initiated by Android Fastboot.
  22
  23   Based on Fastboot Protocol version 0.4. See
  24   system/core/fastboot/fastboot_protocol.txt in the AOSP source tree for more
  25   info.
  26
  27   Doesn't support image verification.
  28 */
  29
  30 /*
  31   Do any initialisation that needs to be done in order to be able to respond to
  32   commands.
  33
  34   @retval EFI_SUCCESS   Initialised successfully.
  35   @retval !EFI_SUCCESS  Error in initialisation.
  36 */
  37 typedef
  38 EFI_STATUS
  39 (*FASTBOOT_PLATFORM_INIT) (
  40   VOID
  41   );
  42
  43 /*
  44   To be called when Fastboot is finished and we aren't rebooting or booting an
  45   image. Undo initialisation, free resrouces.
  46 */
  47 typedef
  48 VOID
  49 (*FASTBOOT_PLATFORM_UN_INIT) (
  50   VOID
  51   );
  52
  53 /*
  54   Flash the partition named (according to a platform-specific scheme)
  55   PartitionName, with the image pointed to by Buffer, whose size is BufferSize.
  56
  57   @param[in] PartitionName  Null-terminated name of partition to write.
  58   @param[in] BufferSize     Size of Buffer in byets.
  59   @param[in] Buffer         Data to write to partition.
  60
  61   @retval EFI_NOT_FOUND     No such partition.
  62   @retval EFI_DEVICE_ERROR  Flashing failed.
  63 */
  64 typedef
  65 EFI_STATUS
  66 (*FASTBOOT_PLATFORM_FLASH) (
  67   IN CHAR8   *PartitionName,
  68   IN UINTN    BufferSize,
  69   IN VOID    *Buffer
  70   );
  71
  72 /*
  73   Erase the partition named PartitionName.
  74
  75   @param[in] PartitionName  Null-terminated name of partition to erase.
  76
  77   @retval EFI_NOT_FOUND     No such partition.
  78   @retval EFI_DEVICE_ERROR  Erasing failed.
  79 */
  80 typedef
  81 EFI_STATUS
  82 (*FASTBOOT_PLATFORM_ERASE) (
  83   IN CHAR8   *PartitionName
  84   );
  85
  86 /*
  87   If the variable referred to by Name exists, copy it (as a null-terminated
  88   string) into Value. If it doesn't exist, put the Empty string in Value.
  89
  90   Variable names and values may not be larger than 60 bytes, excluding the
  91   terminal null character. This is a limitation of the Fastboot protocol.
  92
  93   The Fastboot application will handle platform-nonspecific variables
  94   (Currently "version" is the only one of these.)
  95
  96   @param[in]  Name   Null-terminated name of Fastboot variable to retrieve.
  97   @param[out] Value  Caller-allocated buffer for null-terminated value of
  98                      variable.
  99
 100   @retval EFI_SUCCESS       The variable was retrieved, or it doesn't exist.
 101   @retval EFI_DEVICE_ERROR  There was an error looking up the variable. This
 102                             does _not_ include the variable not existing.
 103 */
 104 typedef
 105 EFI_STATUS
 106 (*FASTBOOT_PLATFORM_GETVAR) (
 107   IN  CHAR8   *Name,
 108   OUT CHAR8   *Value
 109   );
 110
 111 /*
 112   React to an OEM-specific command.
 113
 114   Future versions of this function might want to allow the platform to do some
 115   extra communication with the host. A way to do this would be to add a function
 116   to the FASTBOOT_TRANSPORT_PROTOCOL that allows the implementation of
 117   DoOemCommand to replace the ReceiveEvent with its own, and to restore the old
 118   one when it's finished.
 119
 120   However at the moment although the specification allows it, the AOSP fastboot
 121   host application doesn't handle receiving any data from the client, and it
 122   doesn't support a data phase for OEM commands.
 123
 124   @param[in] Command    Null-terminated command string.
 125
 126   @retval EFI_SUCCESS       The command executed successfully.
 127   @retval EFI_NOT_FOUND     The command wasn't recognised.
 128   @retval EFI_DEVICE_ERROR  There was an error executing the command.
 129 */
 130 typedef
 131 EFI_STATUS
 132 (*FASTBOOT_PLATFORM_OEM_COMMAND) (
 133   IN  CHAR8   *Command
 134   );
 135
 136 typedef struct _FASTBOOT_PLATFORM_PROTOCOL {
 137   FASTBOOT_PLATFORM_INIT          Init;
 138   FASTBOOT_PLATFORM_UN_INIT       UnInit;
 139   FASTBOOT_PLATFORM_FLASH         FlashPartition;
 140   FASTBOOT_PLATFORM_ERASE         ErasePartition;
 141   FASTBOOT_PLATFORM_GETVAR        GetVar;
 142   FASTBOOT_PLATFORM_OEM_COMMAND   DoOemCommand;
 143 } FASTBOOT_PLATFORM_PROTOCOL;
 144
 145 #endif