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