MdeModulePkg/Universal/FvSimpleFileSystemDxe/FvSimpleFileSystemInternal.h

   1 /** @file
   2   The internal header file of FvSimpleFileSystem driver.
   3
   4 Copyright (c) 2014, ARM Limited. All rights reserved.
   5 Copyright (c) 2014 - 2018, Intel Corporation. All rights reserved.<BR>
   6
   7 SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef __FVFS_INTERNAL_H__
  12 #define __FVFS_INTERNAL_H__
  13
  14 #include <Uefi.h>
  15 #include <PiDxe.h>
  16
  17 #include <Library/BaseLib.h>
  18 #include <Library/BaseMemoryLib.h>
  19 #include <Library/DebugLib.h>
  20 #include <Library/DevicePathLib.h>
  21 #include <Library/MemoryAllocationLib.h>
  22 #include <Library/PrintLib.h>
  23 #include <Library/UefiBootServicesTableLib.h>
  24 #include <Library/UefiLib.h>
  25
  26 #include <Protocol/DriverBinding.h>
  27 #include <Protocol/FirmwareVolume2.h>
  28 #include <Protocol/SimpleFileSystem.h>
  29 #include <Protocol/UnicodeCollation.h>
  30
  31 #include <Guid/FileSystemInfo.h>
  32 #include <Guid/FileInfo.h>
  33 #include <Guid/FileSystemVolumeLabelInfo.h>
  34
  35 typedef struct _FV_FILESYSTEM_FILE       FV_FILESYSTEM_FILE;
  36 typedef struct _FV_FILESYSTEM_FILE_INFO  FV_FILESYSTEM_FILE_INFO;
  37 typedef struct _FV_FILESYSTEM_INSTANCE   FV_FILESYSTEM_INSTANCE;
  38
  39 //
  40 // Struct representing an instance of the "filesystem". There will be one of
  41 // these structs per FV.
  42 //
  43 struct _FV_FILESYSTEM_INSTANCE {
  44   UINT32                             Signature;
  45   LIST_ENTRY                         FileInfoHead;
  46   LIST_ENTRY                         FileHead;
  47   EFI_DRIVER_BINDING_PROTOCOL        *DriverBinding;
  48   EFI_FIRMWARE_VOLUME2_PROTOCOL      *FvProtocol;
  49   EFI_SIMPLE_FILE_SYSTEM_PROTOCOL    SimpleFs;
  50   FV_FILESYSTEM_FILE                 *Root;
  51   CHAR16                             *VolumeLabel;
  52 };
  53
  54 //
  55 // Struct representing a opening file. Each opening operation on file will
  56 // create such an instance except for the "root directory", which will only
  57 // be created once for each FV.
  58 //
  59 struct _FV_FILESYSTEM_FILE {
  60   UINT32                     Signature;
  61   LIST_ENTRY                 Link;
  62   FV_FILESYSTEM_FILE_INFO    *DirReadNext;
  63   FV_FILESYSTEM_INSTANCE     *Instance;
  64   EFI_FILE_PROTOCOL          FileProtocol;
  65   FV_FILESYSTEM_FILE_INFO    *FvFileInfo;
  66   UINT64                     Position;
  67 };
  68
  69 //
  70 // Struct representing the info of a file.
  71 //
  72 struct _FV_FILESYSTEM_FILE_INFO {
  73   UINT32             Signature;
  74   LIST_ENTRY         Link;
  75   EFI_GUID           NameGuid;
  76   EFI_FV_FILETYPE    Type;
  77   EFI_FILE_INFO      FileInfo;
  78 };
  79
  80 #define FVFS_FILE_SIGNATURE       SIGNATURE_32 ('f', 'v', 'f', 'i')
  81 #define FVFS_FILE_INFO_SIGNATURE  SIGNATURE_32 ('f', 'v', 'i', 'n')
  82 #define FVFS_INSTANCE_SIGNATURE   SIGNATURE_32 ('f', 'v', 'f', 's')
  83
  84 #define FVFS_INSTANCE_FROM_SIMPLE_FS_THIS(This)  CR ( \
  85           This,                                       \
  86           FV_FILESYSTEM_INSTANCE,                     \
  87           SimpleFs,                                   \
  88           FVFS_INSTANCE_SIGNATURE                     \
  89           )
  90
  91 #define FVFS_FILE_FROM_FILE_THIS(This)  CR (          \
  92           This,                                       \
  93           FV_FILESYSTEM_FILE,                         \
  94           FileProtocol,                               \
  95           FVFS_FILE_SIGNATURE                         \
  96           )
  97
  98 #define FVFS_FILE_INFO_FROM_LINK(This)  CR (          \
  99           This,                                       \
 100           FV_FILESYSTEM_FILE_INFO,                    \
 101           Link,                                       \
 102           FVFS_FILE_INFO_SIGNATURE                    \
 103           )
 104
 105 #define FVFS_FILE_FROM_LINK(FileLink)  CR (FileLink, FV_FILESYSTEM_FILE, Link, FVFS_FILE_SIGNATURE)
 106
 107 #define FVFS_GET_FIRST_FILE(Instance)  FVFS_FILE_FROM_LINK (GetFirstNode (&Instance->FileHead))
 108
 109 #define FVFS_GET_FIRST_FILE_INFO(Instance)  FVFS_FILE_INFO_FROM_LINK (GetFirstNode (&Instance->FileInfoHead))
 110
 111 #define FV_FILETYPE_IS_EXECUTABLE(Type)  ((Type) == EFI_FV_FILETYPE_PEIM                  ||\
 112                                          (Type) == EFI_FV_FILETYPE_DRIVER                || \
 113                                          (Type) == EFI_FV_FILETYPE_COMBINED_PEIM_DRIVER  || \
 114                                          (Type) == EFI_FV_FILETYPE_APPLICATION)
 115
 116 /**
 117   Open the root directory on a volume.
 118
 119   @param  This     A pointer to the volume to open the root directory.
 120   @param  RootFile A pointer to the location to return the opened file handle for the
 121                    root directory.
 122
 123   @retval EFI_SUCCESS          The device was opened.
 124   @retval EFI_UNSUPPORTED      This volume does not support the requested file system type.
 125   @retval EFI_NO_MEDIA         The device has no medium.
 126   @retval EFI_DEVICE_ERROR     The device reported an error.
 127   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 128   @retval EFI_ACCESS_DENIED    The service denied access to the file.
 129   @retval EFI_OUT_OF_RESOURCES The volume was not opened due to lack of resources.
 130   @retval EFI_MEDIA_CHANGED    The device has a different medium in it or the medium is no
 131                                longer supported. Any existing file handles for this volume are
 132                                no longer valid. To access the files on the new medium, the
 133                                volume must be reopened with OpenVolume().
 134
 135 **/
 136 EFI_STATUS
 137 EFIAPI
 138 FvSimpleFileSystemOpenVolume (
 139   IN     EFI_SIMPLE_FILE_SYSTEM_PROTOCOL  *This,
 140   OUT EFI_FILE_PROTOCOL                   **RootFile
 141   );
 142
 143 /**
 144   Test to see if this driver supports ControllerHandle.
 145
 146   @param  DriverBinding       Protocol instance pointer.
 147   @param  ControllerHandle    Handle of device to test
 148   @param  RemainingDevicePath Optional parameter use to pick a specific child
 149                               device to start.
 150
 151   @retval EFI_SUCCESS         This driver supports this device
 152   @retval EFI_ALREADY_STARTED This driver is already running on this device
 153   @retval other               This driver does not support this device
 154
 155 **/
 156 EFI_STATUS
 157 EFIAPI
 158 FvSimpleFileSystemDriverSupported (
 159   IN  EFI_DRIVER_BINDING_PROTOCOL  *DriverBinding,
 160   IN  EFI_HANDLE                   ControllerHandle,
 161   IN  EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 162   );
 163
 164 /**
 165   Start this driver on ControllerHandle by opening a FV protocol and
 166   installing a SimpleFileSystem protocol on ControllerHandle.
 167
 168   @param  DriverBinding        Protocol instance pointer.
 169   @param  ControllerHandle     Handle of device to bind driver to
 170   @param  RemainingDevicePath  Optional parameter use to pick a specific child
 171                                device to start.
 172
 173   @retval EFI_SUCCESS          This driver is added to ControllerHandle
 174   @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle
 175   @retval other                This driver does not support this device
 176
 177 **/
 178 EFI_STATUS
 179 EFIAPI
 180 FvSimpleFileSystemDriverStart (
 181   IN  EFI_DRIVER_BINDING_PROTOCOL  *DriverBinding,
 182   IN  EFI_HANDLE                   ControllerHandle,
 183   IN  EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 184   );
 185
 186 /**
 187   Stop this driver on ControllerHandle by removing SimpleFileSystem protocol and closing
 188   the FV protocol on ControllerHandle.
 189
 190   @param  DriverBinding     Protocol instance pointer.
 191   @param  ControllerHandle  Handle of device to stop driver on
 192   @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of
 193                             children is zero stop the entire bus driver.
 194   @param  ChildHandleBuffer List of Child Handles to Stop.
 195
 196   @retval EFI_SUCCESS       This driver is removed ControllerHandle
 197   @retval other             This driver was not removed from this device
 198
 199 **/
 200 EFI_STATUS
 201 EFIAPI
 202 FvSimpleFileSystemDriverStop (
 203   IN  EFI_DRIVER_BINDING_PROTOCOL  *DriverBinding,
 204   IN  EFI_HANDLE                   ControllerHandle,
 205   IN  UINTN                        NumberOfChildren,
 206   IN  EFI_HANDLE                   *ChildHandleBuffer OPTIONAL
 207   );
 208
 209 /**
 210   Opens a new file relative to the source file's location.
 211
 212   @param  This       A pointer to the EFI_FILE_PROTOCOL instance that is the file
 213                      handle to the source location. This would typically be an open
 214                      handle to a directory.
 215   @param  NewHandle  A pointer to the location to return the opened handle for the new
 216                      file.
 217   @param  FileName   The Null-terminated string of the name of the file to be opened.
 218                      The file name may contain the following path modifiers: "\", ".",
 219                      and "..".
 220   @param  OpenMode   The mode to open the file. The only valid combinations that the
 221                      file may be opened with are: Read, Read/Write, or Create/Read/Write.
 222   @param  Attributes Only valid for EFI_FILE_MODE_CREATE, in which case these are the
 223                      attribute bits for the newly created file.
 224
 225   @retval EFI_SUCCESS          The file was opened.
 226   @retval EFI_NOT_FOUND        The specified file could not be found on the device.
 227   @retval EFI_NO_MEDIA         The device has no medium.
 228   @retval EFI_MEDIA_CHANGED    The device has a different medium in it or the medium is no
 229                                longer supported.
 230   @retval EFI_DEVICE_ERROR     The device reported an error.
 231   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 232   @retval EFI_WRITE_PROTECTED  An attempt was made to create a file, or open a file for write
 233                                when the media is write-protected.
 234   @retval EFI_ACCESS_DENIED    The service denied access to the file.
 235   @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the file.
 236   @retval EFI_VOLUME_FULL      The volume is full.
 237
 238 **/
 239 EFI_STATUS
 240 EFIAPI
 241 FvSimpleFileSystemOpen (
 242   IN     EFI_FILE_PROTOCOL  *This,
 243   OUT EFI_FILE_PROTOCOL     **NewHandle,
 244   IN     CHAR16             *FileName,
 245   IN     UINT64             OpenMode,
 246   IN     UINT64             Attributes
 247   );
 248
 249 /**
 250   Closes a specified file handle.
 251
 252   @param  This          A pointer to the EFI_FILE_PROTOCOL instance that is the file
 253                         handle to close.
 254
 255   @retval EFI_SUCCESS   The file was closed.
 256
 257 **/
 258 EFI_STATUS
 259 EFIAPI
 260 FvSimpleFileSystemClose (
 261   IN EFI_FILE_PROTOCOL  *This
 262   );
 263
 264 /**
 265   Reads data from a file.
 266
 267   @param  This       A pointer to the EFI_FILE_PROTOCOL instance that is the file
 268                      handle to read data from.
 269   @param  BufferSize On input, the size of the Buffer. On output, the amount of data
 270                      returned in Buffer. In both cases, the size is measured in bytes.
 271   @param  Buffer     The buffer into which the data is read.
 272
 273   @retval EFI_SUCCESS          Data was read.
 274   @retval EFI_NO_MEDIA         The device has no medium.
 275   @retval EFI_DEVICE_ERROR     The device reported an error.
 276   @retval EFI_DEVICE_ERROR     An attempt was made to read from a deleted file.
 277   @retval EFI_DEVICE_ERROR     On entry, the current file position is beyond the end of the file.
 278   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 279   @retval EFI_BUFFER_TOO_SMALL The BufferSize is too small to read the current directory
 280                                entry. BufferSize has been updated with the size
 281                                needed to complete the request.
 282
 283 **/
 284 EFI_STATUS
 285 EFIAPI
 286 FvSimpleFileSystemRead (
 287   IN     EFI_FILE_PROTOCOL  *This,
 288   IN OUT UINTN              *BufferSize,
 289   OUT VOID                  *Buffer
 290   );
 291
 292 /**
 293   Writes data to a file.
 294
 295   @param  This       A pointer to the EFI_FILE_PROTOCOL instance that is the file
 296                      handle to write data to.
 297   @param  BufferSize On input, the size of the Buffer. On output, the amount of data
 298                      actually written. In both cases, the size is measured in bytes.
 299   @param  Buffer     The buffer of data to write.
 300
 301   @retval EFI_SUCCESS          Data was written.
 302   @retval EFI_UNSUPPORTED      Writes to open directory files are not supported.
 303   @retval EFI_NO_MEDIA         The device has no medium.
 304   @retval EFI_DEVICE_ERROR     The device reported an error.
 305   @retval EFI_DEVICE_ERROR     An attempt was made to write to a deleted file.
 306   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 307   @retval EFI_WRITE_PROTECTED  The file or medium is write-protected.
 308   @retval EFI_ACCESS_DENIED    The file was opened read only.
 309   @retval EFI_VOLUME_FULL      The volume is full.
 310
 311 **/
 312 EFI_STATUS
 313 EFIAPI
 314 FvSimpleFileSystemWrite (
 315   IN     EFI_FILE_PROTOCOL  *This,
 316   IN OUT UINTN              *BufferSize,
 317   IN     VOID               *Buffer
 318   );
 319
 320 /**
 321   Returns a file's current position.
 322
 323   @param  This            A pointer to the EFI_FILE_PROTOCOL instance that is the file
 324                           handle to get the current position on.
 325   @param  Position        The address to return the file's current position value.
 326
 327   @retval EFI_SUCCESS      The position was returned.
 328   @retval EFI_UNSUPPORTED  The request is not valid on open directories.
 329   @retval EFI_DEVICE_ERROR An attempt was made to get the position from a deleted file.
 330
 331 **/
 332 EFI_STATUS
 333 EFIAPI
 334 FvSimpleFileSystemGetPosition (
 335   IN     EFI_FILE_PROTOCOL  *This,
 336   OUT UINT64                *Position
 337   );
 338
 339 /**
 340   Sets a file's current position.
 341
 342   @param  This            A pointer to the EFI_FILE_PROTOCOL instance that is the
 343                           file handle to set the requested position on.
 344   @param  Position        The byte position from the start of the file to set.
 345
 346   @retval EFI_SUCCESS      The position was set.
 347   @retval EFI_UNSUPPORTED  The seek request for nonzero is not valid on open
 348                            directories.
 349   @retval EFI_DEVICE_ERROR An attempt was made to set the position of a deleted file.
 350
 351 **/
 352 EFI_STATUS
 353 EFIAPI
 354 FvSimpleFileSystemSetPosition (
 355   IN EFI_FILE_PROTOCOL  *This,
 356   IN UINT64             Position
 357   );
 358
 359 /**
 360   Flushes all modified data associated with a file to a device.
 361
 362   @param  This A pointer to the EFI_FILE_PROTOCOL instance that is the file
 363                handle to flush.
 364
 365   @retval EFI_SUCCESS          The data was flushed.
 366   @retval EFI_NO_MEDIA         The device has no medium.
 367   @retval EFI_DEVICE_ERROR     The device reported an error.
 368   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 369   @retval EFI_WRITE_PROTECTED  The file or medium is write-protected.
 370   @retval EFI_ACCESS_DENIED    The file was opened read-only.
 371   @retval EFI_VOLUME_FULL      The volume is full.
 372
 373 **/
 374 EFI_STATUS
 375 EFIAPI
 376 FvSimpleFileSystemFlush (
 377   IN EFI_FILE_PROTOCOL  *This
 378   );
 379
 380 /**
 381   Close and delete the file handle.
 382
 383   @param  This                     A pointer to the EFI_FILE_PROTOCOL instance that is the
 384                                    handle to the file to delete.
 385
 386   @retval EFI_SUCCESS              The file was closed and deleted, and the handle was closed.
 387   @retval EFI_WARN_DELETE_FAILURE  The handle was closed, but the file was not deleted.
 388
 389 **/
 390 EFI_STATUS
 391 EFIAPI
 392 FvSimpleFileSystemDelete (
 393   IN EFI_FILE_PROTOCOL  *This
 394   );
 395
 396 /**
 397   Returns information about a file.
 398
 399   @param  This            A pointer to the EFI_FILE_PROTOCOL instance that is the file
 400                           handle the requested information is for.
 401   @param  InformationType The type identifier for the information being requested.
 402   @param  BufferSize      On input, the size of Buffer. On output, the amount of data
 403                           returned in Buffer. In both cases, the size is measured in bytes.
 404   @param  Buffer          A pointer to the data buffer to return. The buffer's type is
 405                           indicated by InformationType.
 406
 407   @retval EFI_SUCCESS          The information was returned.
 408   @retval EFI_UNSUPPORTED      The InformationType is not known.
 409   @retval EFI_NO_MEDIA         The device has no medium.
 410   @retval EFI_DEVICE_ERROR     The device reported an error.
 411   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 412   @retval EFI_BUFFER_TOO_SMALL The BufferSize is too small to read the current directory entry.
 413                                BufferSize has been updated with the size needed to complete
 414                                the request.
 415 **/
 416 EFI_STATUS
 417 EFIAPI
 418 FvSimpleFileSystemGetInfo (
 419   IN     EFI_FILE_PROTOCOL  *This,
 420   IN     EFI_GUID           *InformationType,
 421   IN OUT UINTN              *BufferSize,
 422   OUT VOID                  *Buffer
 423   );
 424
 425 /**
 426   Sets information about a file.
 427
 428   @param  This            A pointer to the EFI_FILE_PROTOCOL instance that is the file
 429                           handle the information is for.
 430   @param  InformationType The type identifier for the information being set.
 431   @param  BufferSize      The size, in bytes, of Buffer.
 432   @param  Buffer          A pointer to the data buffer to write. The buffer's type is
 433                           indicated by InformationType.
 434
 435   @retval EFI_SUCCESS          The information was set.
 436   @retval EFI_UNSUPPORTED      The InformationType is not known.
 437   @retval EFI_NO_MEDIA         The device has no medium.
 438   @retval EFI_DEVICE_ERROR     The device reported an error.
 439   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 440   @retval EFI_WRITE_PROTECTED  InformationType is EFI_FILE_INFO_ID and the media is
 441                                read-only.
 442   @retval EFI_WRITE_PROTECTED  InformationType is EFI_FILE_PROTOCOL_SYSTEM_INFO_ID
 443                                and the media is read only.
 444   @retval EFI_WRITE_PROTECTED  InformationType is EFI_FILE_SYSTEM_VOLUME_LABEL_ID
 445                                and the media is read-only.
 446   @retval EFI_ACCESS_DENIED    An attempt is made to change the name of a file to a
 447                                file that is already present.
 448   @retval EFI_ACCESS_DENIED    An attempt is being made to change the EFI_FILE_DIRECTORY
 449                                Attribute.
 450   @retval EFI_ACCESS_DENIED    An attempt is being made to change the size of a directory.
 451   @retval EFI_ACCESS_DENIED    InformationType is EFI_FILE_INFO_ID and the file was opened
 452                                read-only and an attempt is being made to modify a field
 453                                other than Attribute.
 454   @retval EFI_VOLUME_FULL      The volume is full.
 455   @retval EFI_BAD_BUFFER_SIZE  BufferSize is smaller than the size of the type indicated
 456                                by InformationType.
 457
 458 **/
 459 EFI_STATUS
 460 EFIAPI
 461 FvSimpleFileSystemSetInfo (
 462   IN EFI_FILE_PROTOCOL  *This,
 463   IN EFI_GUID           *InformationType,
 464   IN UINTN              BufferSize,
 465   IN VOID               *Buffer
 466   );
 467
 468 /**
 469   Get the size of the buffer that will be returned by FvFsReadFile.
 470
 471   @param  FvProtocol                  A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL instance.
 472   @param  FvFileInfo                  A pointer to the FV_FILESYSTEM_FILE_INFO instance that is a struct
 473                                       representing a file's info.
 474
 475   @retval EFI_SUCCESS                 The file size was gotten correctly.
 476   @retval Others                      The file size wasn't gotten correctly.
 477
 478 **/
 479 EFI_STATUS
 480 FvFsGetFileSize (
 481   IN     EFI_FIRMWARE_VOLUME2_PROTOCOL  *FvProtocol,
 482   IN OUT FV_FILESYSTEM_FILE_INFO        *FvFileInfo
 483   );
 484
 485 /**
 486   Retrieves a Unicode string that is the user readable name of the driver.
 487
 488   This function retrieves the user readable name of a driver in the form of a
 489   Unicode string. If the driver specified by This has a user readable name in
 490   the language specified by Language, then a pointer to the driver name is
 491   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 492   by This does not support the language specified by Language,
 493   then EFI_UNSUPPORTED is returned.
 494
 495   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 496                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 497
 498   @param  Language[in]          A pointer to a Null-terminated ASCII string
 499                                 array indicating the language. This is the
 500                                 language of the driver name that the caller is
 501                                 requesting, and it must match one of the
 502                                 languages specified in SupportedLanguages. The
 503                                 number of languages supported by a driver is up
 504                                 to the driver writer. Language is specified
 505                                 in RFC 4646 or ISO 639-2 language code format.
 506
 507   @param  DriverName[out]       A pointer to the Unicode string to return.
 508                                 This Unicode string is the name of the
 509                                 driver specified by This in the language
 510                                 specified by Language.
 511
 512   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 513                                 This and the language specified by Language was
 514                                 returned in DriverName.
 515
 516   @retval EFI_INVALID_PARAMETER Language is NULL.
 517
 518   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 519
 520   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 521                                 the language specified by Language.
 522
 523 **/
 524 EFI_STATUS
 525 EFIAPI
 526 FvSimpleFileSystemComponentNameGetDriverName (
 527   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 528   IN  CHAR8                        *Language,
 529   OUT CHAR16                       **DriverName
 530   );
 531
 532 /**
 533   Retrieves a Unicode string that is the user readable name of the controller
 534   that is being managed by a driver.
 535
 536   This function retrieves the user readable name of the controller specified by
 537   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 538   driver specified by This has a user readable name in the language specified by
 539   Language, then a pointer to the controller name is returned in ControllerName,
 540   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 541   managing the controller specified by ControllerHandle and ChildHandle,
 542   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 543   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 544
 545   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 546                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 547
 548   @param  ControllerHandle[in]  The handle of a controller that the driver
 549                                 specified by This is managing.  This handle
 550                                 specifies the controller whose name is to be
 551                                 returned.
 552
 553   @param  ChildHandle[in]       The handle of the child controller to retrieve
 554                                 the name of.  This is an optional parameter that
 555                                 may be NULL.  It will be NULL for device
 556                                 drivers.  It will also be NULL for a bus drivers
 557                                 that wish to retrieve the name of the bus
 558                                 controller.  It will not be NULL for a bus
 559                                 driver that wishes to retrieve the name of a
 560                                 child controller.
 561
 562   @param  Language[in]          A pointer to a Null-terminated ASCII string
 563                                 array indicating the language.  This is the
 564                                 language of the driver name that the caller is
 565                                 requesting, and it must match one of the
 566                                 languages specified in SupportedLanguages. The
 567                                 number of languages supported by a driver is up
 568                                 to the driver writer. Language is specified in
 569                                 RFC 4646 or ISO 639-2 language code format.
 570
 571   @param  ControllerName[out]   A pointer to the Unicode string to return.
 572                                 This Unicode string is the name of the
 573                                 controller specified by ControllerHandle and
 574                                 ChildHandle in the language specified by
 575                                 Language from the point of view of the driver
 576                                 specified by This.
 577
 578   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 579                                 the language specified by Language for the
 580                                 driver specified by This was returned in
 581                                 DriverName.
 582
 583   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 584
 585   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 586                                 EFI_HANDLE.
 587
 588   @retval EFI_INVALID_PARAMETER Language is NULL.
 589
 590   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 591
 592   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 593                                 managing the controller specified by
 594                                 ControllerHandle and ChildHandle.
 595
 596   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 597                                 the language specified by Language.
 598
 599 **/
 600 EFI_STATUS
 601 EFIAPI
 602 FvSimpleFileSystemComponentNameGetControllerName (
 603   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 604   IN  EFI_HANDLE                   ControllerHandle,
 605   IN  EFI_HANDLE                   ChildHandle        OPTIONAL,
 606   IN  CHAR8                        *Language,
 607   OUT CHAR16                       **ControllerName
 608   );
 609
 610 extern EFI_UNICODE_COLLATION_PROTOCOL  *mUnicodeCollation;
 611 extern EFI_FILE_PROTOCOL               mFileSystemTemplate;
 612 extern EFI_COMPONENT_NAME_PROTOCOL     gFvSimpleFileSystemComponentName;
 613 extern EFI_COMPONENT_NAME2_PROTOCOL    gFvSimpleFileSystemComponentName2;
 614
 615 #endif