ArmPlatformPkg/FileSystem/BootMonFs/BootMonFsApi.h

   1 /** @file
   2 *
   3 *  Copyright (c) 2012-2014, ARM Limited. All rights reserved.
   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 __BOOTMON_FS_API_H
  16 #define __BOOTMON_FS_API_H
  17
  18 #include <Protocol/SimpleFileSystem.h>
  19
  20 EFI_STATUS
  21 BootMonFsInitialize (
  22   IN BOOTMON_FS_INSTANCE *Instance
  23   );
  24
  25 UINT32
  26 BootMonFsChecksum (
  27   IN VOID   *Data,
  28   IN UINT32 Size
  29   );
  30
  31 EFI_STATUS
  32 BootMonFsComputeFooterChecksum (
  33   IN OUT HW_IMAGE_DESCRIPTION *Footer
  34   );
  35
  36 EFIAPI
  37 EFI_STATUS
  38 OpenBootMonFsOpenVolume (
  39   IN EFI_SIMPLE_FILE_SYSTEM_PROTOCOL *This,
  40   OUT EFI_FILE_PROTOCOL              **Root
  41   );
  42
  43 UINT32
  44 BootMonFsGetImageLength (
  45   IN BOOTMON_FS_FILE      *File
  46   );
  47
  48 UINTN
  49 BootMonFsGetPhysicalSize (
  50   IN BOOTMON_FS_FILE* File
  51   );
  52
  53 EFI_STATUS
  54 BootMonFsCreateFile (
  55   IN  BOOTMON_FS_INSTANCE *Instance,
  56   OUT BOOTMON_FS_FILE     **File
  57   );
  58
  59 EFIAPI
  60 EFI_STATUS
  61 BootMonFsGetInfo (
  62   IN EFI_FILE_PROTOCOL  *This,
  63   IN EFI_GUID           *InformationType,
  64   IN OUT UINTN          *BufferSize,
  65   OUT VOID              *Buffer
  66   );
  67
  68 EFIAPI
  69 EFI_STATUS
  70 BootMonFsReadDirectory (
  71   IN EFI_FILE_PROTOCOL    *This,
  72   IN OUT UINTN            *BufferSize,
  73   OUT VOID                *Buffer
  74   );
  75
  76 EFIAPI
  77 EFI_STATUS
  78 BootMonFsFlushDirectory (
  79   IN EFI_FILE_PROTOCOL  *This
  80   );
  81
  82 /**
  83   Flush all modified data associated with a file to a device.
  84
  85   @param[in]  This  A pointer to the EFI_FILE_PROTOCOL instance that is the
  86                     file handle to flush.
  87
  88   @retval  EFI_SUCCESS            The data was flushed.
  89   @retval  EFI_ACCESS_DENIED      The file was opened read-only.
  90   @retval  EFI_DEVICE_ERROR       The device reported an error.
  91   @retval  EFI_VOLUME_FULL        The volume is full.
  92   @retval  EFI_OUT_OF_RESOURCES   Not enough resources were available to flush the data.
  93   @retval  EFI_INVALID_PARAMETER  At least one of the parameters is invalid.
  94
  95 **/
  96 EFIAPI
  97 EFI_STATUS
  98 BootMonFsFlushFile (
  99   IN EFI_FILE_PROTOCOL  *This
 100   );
 101
 102 /**
 103   Close a specified file handle.
 104
 105   @param[in]  This  A pointer to the EFI_FILE_PROTOCOL instance that is the file
 106                     handle to close.
 107
 108   @retval  EFI_SUCCESS            The file was closed.
 109   @retval  EFI_INVALID_PARAMETER  The parameter "This" is NULL or is not an open
 110                                   file handle.
 111
 112 **/
 113 EFIAPI
 114 EFI_STATUS
 115 BootMonFsCloseFile (
 116   IN EFI_FILE_PROTOCOL  *This
 117   );
 118
 119 /**
 120   Open a file on the boot monitor file system.
 121
 122   The boot monitor file system does not allow for sub-directories. There is only
 123   one directory, the root one. On any attempt to create a directory, the function
 124   returns in error with the EFI_WRITE_PROTECTED error code.
 125
 126   @param[in]   This        A pointer to the EFI_FILE_PROTOCOL instance that is
 127                            the file handle to source location.
 128   @param[out]  NewHandle   A pointer to the location to return the opened
 129                            handle for the new file.
 130   @param[in]   FileName    The Null-terminated string of the name of the file
 131                            to be opened.
 132   @param[in]   OpenMode    The mode to open the file : Read or Read/Write or
 133                            Read/Write/Create
 134   @param[in]   Attributes  Attributes of the file in case of a file creation
 135
 136   @retval  EFI_SUCCESS            The file was open.
 137   @retval  EFI_NOT_FOUND          The specified file could not be found or the specified
 138                                   directory in which to create a file could not be found.
 139   @retval  EFI_DEVICE_ERROR       The device reported an error.
 140   @retval  EFI_WRITE_PROTECTED    Attempt to create a directory. This is not possible
 141                                   with the Boot Monitor file system.
 142   @retval  EFI_OUT_OF_RESOURCES   Not enough resources were available to open the file.
 143   @retval  EFI_INVALID_PARAMETER  At least one of the parameters is invalid.
 144
 145 **/
 146 EFIAPI
 147 EFI_STATUS
 148 BootMonFsOpenFile (
 149   IN EFI_FILE_PROTOCOL  *This,
 150   OUT EFI_FILE_PROTOCOL **NewHandle,
 151   IN CHAR16             *FileName,
 152   IN UINT64             OpenMode,
 153   IN UINT64             Attributes
 154   );
 155
 156 /**
 157   Read data from an open file.
 158
 159   @param[in]      This        A pointer to the EFI_FILE_PROTOCOL instance that
 160                               is the file handle to read data from.
 161   @param[in out]  BufferSize  On input, the size of the Buffer. On output, the
 162                               amount of data returned in Buffer. In both cases,
 163                               the size is measured in bytes.
 164   @param[out]     Buffer      The buffer into which the data is read.
 165
 166   @retval  EFI_SUCCESS            The data was read.
 167   @retval  EFI_DEVICE_ERROR       On entry, the current file position is
 168                                   beyond the end of the file, or the device
 169                                   reported an error while performing the read
 170                                   operation.
 171   @retval  EFI_INVALID_PARAMETER  At least one of the parameters is invalid.
 172
 173 **/
 174 EFIAPI
 175 EFI_STATUS
 176 BootMonFsReadFile (
 177   IN EFI_FILE_PROTOCOL  *This,
 178   IN OUT UINTN          *BufferSize,
 179   OUT VOID              *Buffer
 180   );
 181
 182 EFIAPI
 183 EFI_STATUS
 184 BootMonFsSetDirPosition (
 185   IN EFI_FILE_PROTOCOL  *This,
 186   IN UINT64             Position
 187   );
 188
 189 EFIAPI
 190 EFI_STATUS
 191 BootMonFsGetPosition (
 192   IN EFI_FILE_PROTOCOL  *This,
 193   OUT UINT64            *Position
 194   );
 195
 196 /**
 197   Write data to an open file.
 198
 199   The data is not written to the flash yet. It will be written when the file
 200   will be either read, closed or flushed.
 201
 202   @param[in]      This        A pointer to the EFI_FILE_PROTOCOL instance that
 203                               is the file handle to write data to.
 204   @param[in out]  BufferSize  On input, the size of the Buffer. On output, the
 205                               size of the data actually written. In both cases,
 206                               the size is measured in bytes.
 207   @param[in]      Buffer      The buffer of data to write.
 208
 209   @retval  EFI_SUCCESS            The data was written.
 210   @retval  EFI_ACCESS_DENIED      The file was opened read only.
 211   @retval  EFI_OUT_OF_RESOURCES   Unable to allocate the buffer to store the
 212                                   data to write.
 213   @retval  EFI_INVALID_PARAMETER  At least one of the parameters is invalid.
 214
 215 **/
 216 EFIAPI
 217 EFI_STATUS
 218 BootMonFsWriteFile (
 219   IN EFI_FILE_PROTOCOL  *This,
 220   IN OUT UINTN          *BufferSize,
 221   IN VOID               *Buffer
 222   );
 223
 224 EFIAPI
 225 EFI_STATUS
 226 BootMonFsDeleteFail (
 227   IN EFI_FILE_PROTOCOL *This
 228   );
 229
 230 /**
 231   Close and delete a file from the boot monitor file system.
 232
 233   @param[in]  This  A pointer to the EFI_FILE_PROTOCOL instance that is the file
 234                     handle to delete.
 235
 236   @retval  EFI_SUCCESS              The file was closed and deleted.
 237   @retval  EFI_INVALID_PARAMETER    The parameter "This" is NULL or is not an open
 238                                     file handle.
 239   @retval  EFI_WARN_DELETE_FAILURE  The handle was closed, but the file was not deleted.
 240
 241 **/
 242 EFIAPI
 243 EFI_STATUS
 244 BootMonFsDelete (
 245   IN EFI_FILE_PROTOCOL *This
 246   );
 247
 248 /**
 249   Set a file's current position.
 250
 251   @param[in]  This      A pointer to the EFI_FILE_PROTOCOL instance that is
 252                         the file handle to set the requested position on.
 253   @param[in]  Position  The byte position from the start of the file to set.
 254
 255   @retval  EFI_SUCCESS            The position was set.
 256   @retval  EFI_INVALID_PARAMETER  At least one of the parameters is invalid.
 257
 258 **/
 259 EFIAPI
 260 EFI_STATUS
 261 BootMonFsSetPosition (
 262   IN EFI_FILE_PROTOCOL  *This,
 263   IN UINT64             Position
 264   );
 265
 266 /**
 267   Return a file's current position.
 268
 269   @param[in]   This      A pointer to the EFI_FILE_PROTOCOL instance that is
 270                          the file handle to get the current position on.
 271   @param[out]  Position  The address to return the file's current position value.
 272
 273   @retval  EFI_SUCCESS            The position was returned.
 274   @retval  EFI_INVALID_PARAMETER  At least one of the parameters is invalid.
 275
 276 **/
 277 EFIAPI
 278 EFI_STATUS
 279 BootMonFsGetPosition(
 280   IN EFI_FILE_PROTOCOL  *This,
 281   OUT UINT64            *Position
 282   );
 283
 284 //
 285 // UNSUPPORTED OPERATIONS
 286 //
 287
 288 EFIAPI
 289 EFI_STATUS
 290 BootMonFsGetPositionUnsupported (
 291   IN EFI_FILE_PROTOCOL  *This,
 292   OUT UINT64            *Position
 293   );
 294
 295 /**
 296   Set information about a file or a volume.
 297
 298   @param[in]  This             A pointer to the EFI_FILE_PROTOCOL instance that
 299                                is the file handle the information is for.
 300   @param[in]  InformationType  The type identifier for the information being set :
 301                                EFI_FILE_INFO_ID or EFI_FILE_SYSTEM_INFO_ID or
 302                                EFI_FILE_SYSTEM_VOLUME_LABEL_ID
 303   @param[in]  BufferSize       The size, in bytes, of Buffer.
 304   @param[in]  Buffer           A pointer to the data buffer to write. The type of the
 305                                data inside the buffer is indicated by InformationType.
 306
 307   @retval  EFI_SUCCESS            The information was set.
 308   @retval  EFI_UNSUPPORTED        The InformationType is not known.
 309   @retval  EFI_DEVICE_ERROR       The last issued semi-hosting operation failed.
 310   @retval  EFI_ACCESS_DENIED      An attempt is made to change the name of a file
 311                                   to a file that is already present.
 312   @retval  EFI_ACCESS_DENIED      An attempt is being made to change the
 313                                   EFI_FILE_DIRECTORY Attribute.
 314   @retval  EFI_ACCESS_DENIED      InformationType is EFI_FILE_INFO_ID and
 315                                   the file was opened in read-only mode and an
 316                                   attempt is being made to modify a field other
 317                                   than Attribute.
 318   @retval  EFI_WRITE_PROTECTED    An attempt is being made to modify a read-only
 319                                   attribute.
 320   @retval  EFI_BAD_BUFFER_SIZE    The size of the buffer is lower than that indicated by
 321                                   the data inside the buffer.
 322   @retval  EFI_OUT_OF_RESOURCES   A allocation needed to process the request failed.
 323   @retval  EFI_INVALID_PARAMETER  At least one of the parameters is invalid.
 324
 325 **/
 326 EFIAPI
 327 EFI_STATUS
 328 BootMonFsSetInfo (
 329   IN EFI_FILE_PROTOCOL  *This,
 330   IN EFI_GUID           *InformationType,
 331   IN UINTN              BufferSize,
 332   IN VOID               *Buffer
 333   );
 334
 335 //
 336 // Directory API
 337 //
 338
 339 EFI_STATUS
 340 BootMonFsOpenDirectory (
 341   OUT EFI_FILE_PROTOCOL **NewHandle,
 342   IN CHAR16             *FileName,
 343   IN BOOTMON_FS_INSTANCE *Volume
 344   );
 345
 346 //
 347 // Internal API
 348 //
 349
 350 /**
 351   Search for a file given its name coded in Ascii.
 352
 353   When searching through the files of the volume, if a file is currently not
 354   open, its name was written on the media and is kept in RAM in the
 355   "HwDescription.Footer.Filename[]" field of the file's description.
 356
 357   If a file is currently open, its name might not have been written on the
 358   media yet, and as the "HwDescription" is a mirror in RAM of what is on the
 359   media the "HwDescription.Footer.Filename[]" might be outdated. In that case,
 360   the up to date name of the file is stored in the "Info" field of the file's
 361   description.
 362
 363   @param[in]   Instance       Pointer to the description of the volume in which
 364                               the file has to be search for.
 365   @param[in]   AsciiFileName  Name of the file.
 366
 367   @param[out]  File           Pointer to the description of the file if the
 368                               file was found.
 369
 370   @retval  EFI_SUCCESS    The file was found.
 371   @retval  EFI_NOT_FOUND  The file was not found.
 372
 373 **/
 374 EFI_STATUS
 375 BootMonGetFileFromAsciiFileName (
 376   IN  BOOTMON_FS_INSTANCE   *Instance,
 377   IN  CHAR8*                AsciiFileName,
 378   OUT BOOTMON_FS_FILE       **File
 379   );
 380
 381 EFI_STATUS
 382 BootMonGetFileFromPosition (
 383   IN  BOOTMON_FS_INSTANCE   *Instance,
 384   IN  UINTN                 Position,
 385   OUT BOOTMON_FS_FILE       **File
 386   );
 387
 388 #endif