ArmPlatformPkg/ArmVExpressFastBootDxe: clean up code and comments

[mirror_edk2.git] / ArmPlatformPkg / ArmVExpressPkg / ArmVExpressFastBootDxe / ArmVExpressFastBoot.c

diff --git a/ArmPlatformPkg/ArmVExpressPkg/ArmVExpressFastBootDxe/ArmVExpressFastBoot.c b/ArmPlatformPkg/ArmVExpressPkg/ArmVExpressFastBootDxe/ArmVExpressFastBoot.c
index 4d0811cc5eaf137e3253261b4e1ced52788934bf..fe4ade5c9fa8c7a254a14873abea6287cf57352d 100644 (file)
--- a/ArmPlatformPkg/ArmVExpressPkg/ArmVExpressFastBootDxe/ArmVExpressFastBoot.c
+++ b/ArmPlatformPkg/ArmVExpressPkg/ArmVExpressFastBootDxe/ArmVExpressFastBoot.c
@@ -1,6 +1,7 @@
 /** @file\r
 \r
   Copyright (c) 2014, ARM Ltd. All rights reserved.<BR>\r
+  Copyright (c) 2016, Linaro 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
@@ -135,11 +136,13 @@ ReadPartitionEntries (
 \r
 \r
 /*\r
-  Initialise: Open the Android NVM device and find the partitions on it. Save them in\r
-  a list along with the "PartitionName" fields for their GPT entries.\r
-  We will use these partition names as the key in\r
-  ArmFastbootPlatformFlashPartition.\r
+  Do any initialisation that needs to be done in order to be able to respond to\r
+  commands.\r
+\r
+  @retval EFI_SUCCESS   Initialised successfully.\r
+  @retval !EFI_SUCCESS  Error in initialisation.\r
 */\r
+STATIC\r
 EFI_STATUS\r
 ArmFastbootPlatformInit (\r
   VOID\r
@@ -164,6 +167,7 @@ ArmFastbootPlatformInit (
   //\r
   // Get EFI_HANDLES for all the partitions on the block devices pointed to by\r
   // PcdFastbootFlashDevicePath, also saving their GPT partition labels.\r
+  // We will use these labels as the key in ArmFastbootPlatformFlashPartition.\r
   // There's no way to find all of a device's children, so we get every handle\r
   // in the system supporting EFI_BLOCK_IO_PROTOCOL and then filter out ones\r
   // that don't represent partitions on the flash device.\r
@@ -296,6 +300,11 @@ Exit:
 \r
 }\r
 \r
+/*\r
+  To be called when Fastboot is finished and we aren't rebooting or booting an\r
+  image. Undo initialisation, free resrouces.\r
+*/\r
+STATIC\r
 VOID\r
 ArmFastbootPlatformUnInit (\r
   VOID\r
@@ -304,6 +313,18 @@ ArmFastbootPlatformUnInit (
   FreePartitionList ();\r
 }\r
 \r
+/*\r
+  Flash the partition named (according to a platform-specific scheme)\r
+  PartitionName, with the image pointed to by Buffer, whose size is BufferSize.\r
+\r
+  @param[in] PartitionName  Null-terminated name of partition to write.\r
+  @param[in] BufferSize     Size of Buffer in byets.\r
+  @param[in] Buffer         Data to write to partition.\r
+\r
+  @retval EFI_NOT_FOUND     No such partition.\r
+  @retval EFI_DEVICE_ERROR  Flashing failed.\r
+*/\r
+STATIC\r
 EFI_STATUS\r
 ArmFastbootPlatformFlashPartition (\r
   IN CHAR8  *PartitionName,\r
@@ -381,6 +402,15 @@ ArmFastbootPlatformFlashPartition (
   return Status;\r
 }\r
 \r
+/*\r
+  Erase the partition named PartitionName.\r
+\r
+  @param[in] PartitionName  Null-terminated name of partition to erase.\r
+\r
+  @retval EFI_NOT_FOUND     No such partition.\r
+  @retval EFI_DEVICE_ERROR  Erasing failed.\r
+*/\r
+STATIC\r
 EFI_STATUS\r
 ArmFastbootPlatformErasePartition (\r
   IN CHAR8 *Partition\r
@@ -389,6 +419,25 @@ ArmFastbootPlatformErasePartition (
   return EFI_SUCCESS;\r
 }\r
 \r
+/*\r
+  If the variable referred to by Name exists, copy it (as a null-terminated\r
+  string) into Value. If it doesn't exist, put the Empty string in Value.\r
+\r
+  Variable names and values may not be larger than 60 bytes, excluding the\r
+  terminal null character. This is a limitation of the Fastboot protocol.\r
+\r
+  The Fastboot application will handle platform-nonspecific variables\r
+  (Currently "version" is the only one of these.)\r
+\r
+  @param[in]  Name   Null-terminated name of Fastboot variable to retrieve.\r
+  @param[out] Value  Caller-allocated buffer for null-terminated value of\r
+                     variable.\r
+\r
+  @retval EFI_SUCCESS       The variable was retrieved, or it doesn't exist.\r
+  @retval EFI_DEVICE_ERROR  There was an error looking up the variable. This\r
+                            does _not_ include the variable not existing.\r
+*/\r
+STATIC\r
 EFI_STATUS\r
 ArmFastbootPlatformGetVar (\r
   IN  CHAR8   *Name,\r
@@ -403,6 +452,26 @@ ArmFastbootPlatformGetVar (
   return EFI_SUCCESS;\r
 }\r
 \r
+/*\r
+  React to an OEM-specific command.\r
+\r
+  Future versions of this function might want to allow the platform to do some\r
+  extra communication with the host. A way to do this would be to add a function\r
+  to the FASTBOOT_TRANSPORT_PROTOCOL that allows the implementation of\r
+  DoOemCommand to replace the ReceiveEvent with its own, and to restore the old\r
+  one when it's finished.\r
+\r
+  However at the moment although the specification allows it, the AOSP fastboot\r
+  host application doesn't handle receiving any data from the client, and it\r
+  doesn't support a data phase for OEM commands.\r
+\r
+  @param[in] Command    Null-terminated command string.\r
+\r
+  @retval EFI_SUCCESS       The command executed successfully.\r
+  @retval EFI_NOT_FOUND     The command wasn't recognised.\r
+  @retval EFI_DEVICE_ERROR  There was an error executing the command.\r
+*/\r
+STATIC\r
 EFI_STATUS\r
 ArmFastbootPlatformOemCommand (\r
   IN  CHAR8   *Command\r
@@ -424,7 +493,7 @@ ArmFastbootPlatformOemCommand (
   }\r
 }\r
 \r
-FASTBOOT_PLATFORM_PROTOCOL mPlatformProtocol = {\r
+STATIC FASTBOOT_PLATFORM_PROTOCOL mPlatformProtocol = {\r
   ArmFastbootPlatformInit,\r
   ArmFastbootPlatformUnInit,\r
   ArmFastbootPlatformFlashPartition,\r