MdePkg/UefiLib: introduce EfiOpenFileByDevicePath()

The EfiOpenFileByDevicePath() function centralizes functionality from

- MdeModulePkg/Universal/Disk/RamDiskDxe
- NetworkPkg/TlsAuthConfigDxe
- SecurityPkg/VariableAuthenticated/SecureBootConfigDxe
- ShellPkg/Library/UefiShellLib

unifying the implementation and fixing various bugs.

(Ray suggested that we eliminate the special handling of
EFI_FILE_MODE_CREATE in the "OpenMode" input parameter as well. We plan to
implement that separately, under
<https://bugzilla.tianocore.org/show_bug.cgi?id=1074>.)

Cc: Chao Zhang <chao.b.zhang@intel.com>
Cc: Eric Dong <eric.dong@intel.com>
Cc: Jaben Carsey <jaben.carsey@intel.com>
Cc: Jiaxin Wu <jiaxin.wu@intel.com>
Cc: Jiewen Yao <jiewen.yao@intel.com>
Cc: Liming Gao <liming.gao@intel.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Roman Bacik <roman.bacik@broadcom.com>
Cc: Ruiyu Ni <ruiyu.ni@intel.com>
Cc: Siyuan Fu <siyuan.fu@intel.com>
Cc: Star Zeng <star.zeng@intel.com>
Ref: https://bugzilla.tianocore.org/show_bug.cgi?id=1008
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
Reviewed-by: Ruiyu Ni <ruiyu.ni@intel.com>
Reviewed-by: Liming Gao <liming.gao@intel.com>

1 files changed, 88 insertions, 0 deletions

diff --git a/MdePkg/Include/Library/UefiLib.h b/MdePkg/Include/Library/UefiLib.h
index 7c6fde620c..f950f1c9c6 100644
--- a/MdePkg/Include/Library/UefiLib.h
+++ b/MdePkg/Include/Library/UefiLib.h
@@ -33,6 +33,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #include <Protocol/DriverDiagnostics.h>

 #include <Protocol/DriverDiagnostics2.h>

 #include <Protocol/GraphicsOutput.h>

+#include <Protocol/DevicePath.h>

+#include <Protocol/SimpleFileSystem.h>

 

 #include <Library/BaseLib.h>

 

@@ -1520,4 +1522,90 @@ EfiLocateProtocolBuffer (
   OUT UINTN     *NoProtocols,

   OUT VOID      ***Buffer

   );

+

+/**

+  Open or create a file or directory, possibly creating the chain of

+  directories leading up to the directory.

+

+  EfiOpenFileByDevicePath() first locates EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on

+  FilePath, and opens the root directory of that filesystem with

+  EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume().

+

+  On the remaining device path, the longest initial sequence of

+  FILEPATH_DEVICE_PATH nodes is node-wise traversed with

+  EFI_FILE_PROTOCOL.Open(). For the pathname fragment specified by each

+  traversed FILEPATH_DEVICE_PATH node, EfiOpenFileByDevicePath() first masks

+  EFI_FILE_MODE_CREATE out of OpenMode, and passes 0 for Attributes. If

+  EFI_FILE_PROTOCOL.Open() fails, and OpenMode includes EFI_FILE_MODE_CREATE,

+  then the operation is retried with the caller's OpenMode and Attributes

+  unmodified.

+

+  (As a consequence, if OpenMode includes EFI_FILE_MODE_CREATE, and Attributes

+  includes EFI_FILE_DIRECTORY, and each FILEPATH_DEVICE_PATH specifies a single

+  pathname component, then EfiOpenFileByDevicePath() ensures that the specified

+  series of subdirectories exist on return.)

+

+  The EFI_FILE_PROTOCOL identified by the last FILEPATH_DEVICE_PATH node is

+  output to the caller; intermediate EFI_FILE_PROTOCOL instances are closed. If

+  there are no FILEPATH_DEVICE_PATH nodes past the node that identifies the

+  filesystem, then the EFI_FILE_PROTOCOL of the root directory of the

+  filesystem is output to the caller. If a device path node that is different

+  from FILEPATH_DEVICE_PATH is encountered relative to the filesystem, the

+  traversal is stopped with an error, and a NULL EFI_FILE_PROTOCOL is output.

+

+  @param[in,out] FilePath  On input, the device path to the file or directory

+                           to open or create. The caller is responsible for

+                           ensuring that the device path pointed-to by FilePath

+                           is well-formed. On output, FilePath points one past

+                           the last node in the original device path that has

+                           been successfully processed. FilePath is set on

+                           output even if EfiOpenFileByDevicePath() returns an

+                           error.

+

+  @param[out] File         On error, File is set to NULL. On success, File is

+                           set to the EFI_FILE_PROTOCOL of the root directory

+                           of the filesystem, if there are no

+                           FILEPATH_DEVICE_PATH nodes in FilePath; otherwise,

+                           File is set to the EFI_FILE_PROTOCOL identified by

+                           the last node in FilePath.

+

+  @param[in] OpenMode      The OpenMode parameter to pass to

+                           EFI_FILE_PROTOCOL.Open(). For each

+                           FILEPATH_DEVICE_PATH node in FilePath,

+                           EfiOpenFileByDevicePath() first opens the specified

+                           pathname fragment with EFI_FILE_MODE_CREATE masked

+                           out of OpenMode and with Attributes set to 0, and

+                           only retries the operation with EFI_FILE_MODE_CREATE

+                           unmasked and Attributes propagated if the first open

+                           attempt fails.

+

+  @param[in] Attributes    The Attributes parameter to pass to

+                           EFI_FILE_PROTOCOL.Open(), when EFI_FILE_MODE_CREATE

+                           is propagated unmasked in OpenMode.

+

+  @retval EFI_SUCCESS            The file or directory has been opened or

+                                 created.

+

+  @retval EFI_INVALID_PARAMETER  FilePath is NULL; or File is NULL; or FilePath

+                                 contains a device path node, past the node

+                                 that identifies

+                                 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL, that is not a

+                                 FILEPATH_DEVICE_PATH node.

+

+  @retval EFI_OUT_OF_RESOURCES   Memory allocation failed.

+

+  @return                        Error codes propagated from the

+                                 LocateDevicePath() and OpenProtocol() boot

+                                 services, and from the

+                                 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume()

+                                 and EFI_FILE_PROTOCOL.Open() member functions.

+**/

+EFI_STATUS

+EFIAPI

+EfiOpenFileByDevicePath (

+  IN OUT EFI_DEVICE_PATH_PROTOCOL  **FilePath,

+  OUT    EFI_FILE_PROTOCOL         **File,

+  IN     UINT64                    OpenMode,

+  IN     UINT64                    Attributes

+  );

 #endif