ArmPkg/Filesystem/SemihostFs/Arm/SemihostFs.h

   1 /** @file
   2   Support a Semi Host file system over a debuggers JTAG
   3
   4   Copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
   5
   6   This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef __SEMIHOST_FS_H__
  17 #define __SEMIHOST_FS_H__
  18
  19 EFI_STATUS
  20 VolumeOpen (
  21   IN  EFI_SIMPLE_FILE_SYSTEM_PROTOCOL *This,
  22   OUT EFI_FILE                        **Root
  23   );
  24
  25 /**
  26   Open a file on the host system by means of the semihosting interface.
  27
  28   @param[in]   This        A pointer to the EFI_FILE_PROTOCOL instance that is
  29                            the file handle to source location.
  30   @param[out]  NewHandle   A pointer to the location to return the opened
  31                            handle for the new file.
  32   @param[in]   FileName    The Null-terminated string of the name of the file
  33                            to be opened.
  34   @param[in]   OpenMode    The mode to open the file : Read or Read/Write or
  35                            Read/Write/Create
  36   @param[in]   Attributes  Only valid for EFI_FILE_MODE_CREATE, in which case these
  37                            are the attribute bits for the newly created file. The
  38                            mnemonics of the attribute bits are : EFI_FILE_READ_ONLY,
  39                            EFI_FILE_HIDDEN, EFI_FILE_SYSTEM, EFI_FILE_RESERVED,
  40                            EFI_FILE_DIRECTORY and EFI_FILE_ARCHIVE.
  41
  42   @retval  EFI_SUCCESS            The file was open.
  43   @retval  EFI_NOT_FOUND          The specified file could not be found.
  44   @retval  EFI_DEVICE_ERROR       The last issued semi-hosting operation failed.
  45   @retval  EFI_WRITE_PROTECTED    Attempt to create a directory. This is not possible
  46                                   with the semi-hosting interface.
  47   @retval  EFI_OUT_OF_RESOURCES   Not enough resources were available to open the file.
  48   @retval  EFI_INVALID_PARAMETER  At least one of the parameters is invalid.
  49
  50 **/
  51 EFI_STATUS
  52 FileOpen (
  53   IN  EFI_FILE  *This,
  54   OUT EFI_FILE  **NewHandle,
  55   IN  CHAR16    *FileName,
  56   IN  UINT64    OpenMode,
  57   IN  UINT64    Attributes
  58   );
  59
  60 /**
  61   Close a specified file handle.
  62
  63   @param[in]  This  A pointer to the EFI_FILE_PROTOCOL instance that is the file
  64                     handle to close.
  65
  66   @retval  EFI_SUCCESS            The file was closed.
  67   @retval  EFI_INVALID_PARAMETER  The parameter "This" is NULL.
  68
  69 **/
  70 EFI_STATUS
  71 FileClose (
  72   IN EFI_FILE  *This
  73   );
  74
  75 /**
  76   Close and delete a file.
  77
  78   @param[in]  This  A pointer to the EFI_FILE_PROTOCOL instance that is the file
  79                     handle to delete.
  80
  81   @retval  EFI_SUCCESS              The file was closed and deleted.
  82   @retval  EFI_WARN_DELETE_FAILURE  The handle was closed, but the file was not deleted.
  83   @retval  EFI_INVALID_PARAMETER    The parameter "This" is NULL.
  84
  85 **/
  86 EFI_STATUS
  87 FileDelete (
  88   IN EFI_FILE *This
  89   );
  90
  91 /**
  92   Read data from an open file.
  93
  94   @param[in]      This        A pointer to the EFI_FILE_PROTOCOL instance that
  95                               is the file handle to read data from.
  96   @param[in out]  BufferSize  On input, the size of the Buffer. On output, the
  97                               amount of data returned in Buffer. In both cases,
  98                               the size is measured in bytes.
  99   @param[out]     Buffer      The buffer into which the data is read.
 100
 101   @retval  EFI_SUCCESS            The data was read.
 102   @retval  EFI_DEVICE_ERROR       On entry, the current file position is
 103                                   beyond the end of the file, or the semi-hosting
 104                                   interface reported an error while performing the
 105                                   read operation.
 106   @retval  EFI_INVALID_PARAMETER  The parameter "This" or the parameter "Buffer"
 107                                   is NULL.
 108 **/
 109 EFI_STATUS
 110 FileRead (
 111   IN     EFI_FILE  *This,
 112   IN OUT UINTN     *BufferSize,
 113   OUT    VOID      *Buffer
 114   );
 115
 116 /**
 117   Write data to an open file.
 118
 119   @param[in]      This        A pointer to the EFI_FILE_PROTOCOL instance that
 120                               is the file handle to write data to.
 121   @param[in out]  BufferSize  On input, the size of the Buffer. On output, the
 122                               size of the data actually written. In both cases,
 123                               the size is measured in bytes.
 124   @param[in]      Buffer      The buffer of data to write.
 125
 126   @retval  EFI_SUCCESS            The data was written.
 127   @retval  EFI_ACCESS_DENIED      Attempt to write into a read only file or
 128                                   in a file opened in read only mode.
 129   @retval  EFI_DEVICE_ERROR       The last issued semi-hosting operation failed.
 130   @retval  EFI_INVALID_PARAMETER  The parameter "This" or the parameter "Buffer"
 131                                   is NULL.
 132
 133 **/
 134 EFI_STATUS
 135 FileWrite (
 136   IN     EFI_FILE *This,
 137   IN OUT UINTN    *BufferSize,
 138   IN     VOID     *Buffer
 139   );
 140
 141 /**
 142   Return a file's current position.
 143
 144   @param[in]   This      A pointer to the EFI_FILE_PROTOCOL instance that is
 145                          the file handle to get the current position on.
 146   @param[out]  Position  The address to return the file's current position value.
 147
 148   @retval  EFI_SUCCESS            The position was returned.
 149   @retval  EFI_INVALID_PARAMETER  Position is a NULL pointer.
 150
 151 **/
 152 EFI_STATUS
 153 FileGetPosition (
 154   IN  EFI_FILE    *File,
 155   OUT UINT64      *Position
 156   );
 157
 158 /**
 159   Set a file's current position.
 160
 161   @param[in]  This      A pointer to the EFI_FILE_PROTOCOL instance that is
 162                         the file handle to set the requested position on.
 163   @param[in]  Position  The byte position from the start of the file to set.
 164
 165   @retval  EFI_SUCCESS       The position was set.
 166   @retval  EFI_DEVICE_ERROR  The semi-hosting positionning operation failed.
 167   @retval  EFI_UNSUPPORTED   The seek request for nonzero is not valid on open
 168                              directories.
 169
 170 **/
 171 EFI_STATUS
 172 FileSetPosition (
 173   IN EFI_FILE *File,
 174   IN UINT64   Position
 175   );
 176
 177 /**
 178   Return information about a file or a file system.
 179
 180   @param[in]      This             A pointer to the EFI_FILE_PROTOCOL instance that
 181                                    is the file handle the requested information is for.
 182   @param[in]      InformationType  The type identifier for the information being requested :
 183                                    EFI_FILE_INFO_ID or EFI_FILE_SYSTEM_INFO_ID or
 184                                    EFI_FILE_SYSTEM_VOLUME_LABEL_ID
 185   @param[in out]  BufferSize       The size, in bytes, of Buffer.
 186   @param[out]     Buffer           A pointer to the data buffer to return. The type of the
 187                                    data inside the buffer is indicated by InformationType.
 188
 189   @retval  EFI_SUCCESS           The information was returned.
 190   @retval  EFI_UNSUPPORTED       The InformationType is not known.
 191   @retval  EFI_BUFFER_TOO_SMALL  The BufferSize is too small to return the information.
 192                                  BufferSize has been updated with the size needed to
 193                                  complete the request.
 194   @retval  EFI_INVALID_PARAMETER  The parameter "This" or the parameter "Buffer"
 195                                   is NULL.
 196
 197 **/
 198 EFI_STATUS
 199 FileGetInfo (
 200   IN     EFI_FILE  *This,
 201   IN     EFI_GUID  *InformationType,
 202   IN OUT UINTN     *BufferSize,
 203   OUT    VOID      *Buffer
 204   );
 205
 206 /**
 207   Set information about a file or a file system.
 208
 209   @param[in]  This             A pointer to the EFI_FILE_PROTOCOL instance that
 210                                is the file handle the information is for.
 211   @param[in]  InformationType  The type identifier for the information being set :
 212                                EFI_FILE_INFO_ID or EFI_FILE_SYSTEM_INFO_ID or
 213                                EFI_FILE_SYSTEM_VOLUME_LABEL_ID
 214   @param[in]  BufferSize       The size, in bytes, of Buffer.
 215   @param[in]  Buffer           A pointer to the data buffer to write. The type of the
 216                                data inside the buffer is indicated by InformationType.
 217
 218   @retval  EFI_SUCCESS            The information was set.
 219   @retval  EFI_UNSUPPORTED        The InformationType is not known.
 220   @retval  EFI_DEVICE_ERROR       The last issued semi-hosting operation failed.
 221   @retval  EFI_ACCESS_DENIED      An attempt is being made to change the
 222                                   EFI_FILE_DIRECTORY Attribute.
 223   @retval  EFI_ACCESS_DENIED      InformationType is EFI_FILE_INFO_ID and
 224                                   the file is a read-only file or has been
 225                                   opened in read-only mode and an attempt is
 226                                   being made to modify a field other than
 227                                   Attribute.
 228   @retval  EFI_ACCESS_DENIED      An attempt is made to change the name of a file
 229                                   to a file that is already present.
 230   @retval  EFI_WRITE_PROTECTED    An attempt is being made to modify a
 231                                   read-only attribute.
 232   @retval  EFI_BAD_BUFFER_SIZE    The size of the buffer is lower than that indicated by
 233                                   the data inside the buffer.
 234   @retval  EFI_OUT_OF_RESOURCES   An allocation needed to process the request failed.
 235   @retval  EFI_INVALID_PARAMETER  At least one of the parameters is invalid.
 236
 237 **/
 238 EFI_STATUS
 239 FileSetInfo (
 240   IN EFI_FILE  *This,
 241   IN EFI_GUID  *InformationType,
 242   IN UINTN     BufferSize,
 243   IN VOID      *Buffer
 244   );
 245
 246 EFI_STATUS
 247 FileFlush (
 248   IN EFI_FILE *File
 249   );
 250
 251 #endif // __SEMIHOST_FS_H__
 252