summaryrefslogtreecommitdiffstats
path: root/MdePkg/Include
diff options
context:
space:
mode:
authorLaszlo Ersek <lersek@redhat.com>2018-07-18 17:07:03 +0200
committerLaszlo Ersek <lersek@redhat.com>2018-08-16 20:02:39 +0200
commit768b611136d0f2b99a99e446c089d1a30c3fa5d5 (patch)
treeac4114c2f56446e4c12c6208c60bf83ad2b2a527 /MdePkg/Include
parent52047be0243074f50fab45650f36ae693c93d1b3 (diff)
downloadedk2-768b611136d0f2b99a99e446c089d1a30c3fa5d5.tar.gz
edk2-768b611136d0f2b99a99e446c089d1a30c3fa5d5.tar.bz2
edk2-768b611136d0f2b99a99e446c089d1a30c3fa5d5.zip
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>
Diffstat (limited to 'MdePkg/Include')
-rw-r--r--MdePkg/Include/Library/UefiLib.h88
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