OvmfPkg/QemuBootOrderLib: add ConnectDevicesFromQemu()

[mirror_edk2.git] / OvmfPkg / Include / Library / QemuBootOrderLib.h

diff --git a/OvmfPkg/Include/Library/QemuBootOrderLib.h b/OvmfPkg/Include/Library/QemuBootOrderLib.h
index 874344a95d80258e6f1d4a07e0a67fd81f9cdb7c..d17de3bb8fae2c732846b7e62b82e6727c933c78 100644 (file)
--- a/OvmfPkg/Include/Library/QemuBootOrderLib.h
+++ b/OvmfPkg/Include/Library/QemuBootOrderLib.h
@@ -20,6 +20,41 @@
 #include <Base.h>\r
 \r
 \r
+/**\r
+  Connect devices based on the boot order retrieved from QEMU.\r
+\r
+  Attempt to retrieve the "bootorder" fw_cfg file from QEMU. Translate the\r
+  OpenFirmware device paths therein to UEFI device path fragments. Connect the\r
+  devices identified by the UEFI devpath prefixes as narrowly as possible, then\r
+  connect all their child devices, recursively.\r
+\r
+  If this function fails, then platform BDS should fall back to\r
+  EfiBootManagerConnectAll(), or some other method for connecting any expected\r
+  boot devices.\r
+\r
+  @retval RETURN_SUCCESS            The "bootorder" fw_cfg file has been\r
+                                    parsed, and the referenced device-subtrees\r
+                                    have been connected.\r
+\r
+  @retval RETURN_UNSUPPORTED        QEMU's fw_cfg is not supported.\r
+\r
+  @retval RETURN_NOT_FOUND          Empty or nonexistent "bootorder" fw_cfg\r
+                                    file.\r
+\r
+  @retval RETURN_INVALID_PARAMETER  Parse error in the "bootorder" fw_cfg file.\r
+\r
+  @retval RETURN_OUT_OF_RESOURCES   Memory allocation failed.\r
+\r
+  @return                           Error statuses propagated from underlying\r
+                                    functions.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+ConnectDevicesFromQemu (\r
+  VOID\r
+  );\r
+\r
+\r
 /**\r
 \r
   Set the boot order based on configuration retrieved from QEMU.\r
@@ -29,8 +64,8 @@
   translated fragments against the current list of boot options, and rewrite\r
   the BootOrder NvVar so that it corresponds to the order described in fw_cfg.\r
 \r
-  Platform BDS should call this function after EfiBootManagerConnectAll () and\r
-  EfiBootManagerRefreshAllBootOption () return.\r
+  Platform BDS should call this function after connecting any expected boot\r
+  devices and calling EfiBootManagerRefreshAllBootOption ().\r
 \r
   @retval RETURN_SUCCESS            BootOrder NvVar rewritten.\r
 \r