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