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