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 389