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 253