OvmfPkg/PlatformBootManagerLib: rejuvenate old-style function comments
[mirror_edk2.git] / OvmfPkg / Library / PlatformBootManagerLib / BdsPlatform.c
index 99b7db7..b155639 100644 (file)
@@ -328,25 +328,24 @@ SaveS3BootScript (
 //\r
 // BDS Platform Functions\r
 //\r
+/**\r
+  Do the platform init, can be customized by OEM/IBV\r
+\r
+  Possible things that can be done in PlatformBootManagerBeforeConsole:\r
+\r
+  > Update console variable: 1. include hot-plug devices;\r
+  >                          2. Clear ConIn and add SOL for AMT\r
+  > Register new Driver#### or Boot####\r
+  > Register new Key####: e.g.: F12\r
+  > Signal ReadyToLock event\r
+  > Authentication action: 1. connect Auth devices;\r
+  >                        2. Identify auto logon user.\r
+**/\r
 VOID\r
 EFIAPI\r
 PlatformBootManagerBeforeConsole (\r
   VOID\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  Platform Bds init. Include the platform firmware vendor, revision\r
-  and so crc check.\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-  None.\r
-\r
---*/\r
 {\r
   EFI_HANDLE    Handle;\r
   EFI_STATUS    Status;\r
@@ -429,28 +428,21 @@ ConnectRootBridge (
 }\r
 \r
 \r
+/**\r
+  Add IsaKeyboard to ConIn; add IsaSerial to ConOut, ConIn, ErrOut.\r
+\r
+  @param[in] DeviceHandle  Handle of the LPC Bridge device.\r
+\r
+  @retval EFI_SUCCESS  Console devices on the LPC bridge have been added to\r
+                       ConOut, ConIn, and ErrOut.\r
+\r
+  @return              Error codes, due to EFI_DEVICE_PATH_PROTOCOL missing\r
+                       from DeviceHandle.\r
+**/\r
 EFI_STATUS\r
 PrepareLpcBridgeDevicePath (\r
   IN EFI_HANDLE                DeviceHandle\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  Add IsaKeyboard to ConIn,\r
-  add IsaSerial to ConOut, ConIn, ErrOut.\r
-  LPC Bridge: 06 01 00\r
-\r
-Arguments:\r
-\r
-  DeviceHandle            - Handle of PCIIO protocol.\r
-\r
-Returns:\r
-\r
-  EFI_SUCCESS             - LPC bridge is added to ConOut, ConIn, and ErrOut.\r
-  EFI_STATUS              - No LPC bridge is added.\r
-\r
---*/\r
 {\r
   EFI_STATUS                Status;\r
   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;\r
@@ -629,27 +621,20 @@ GetGopDevicePath (
   return EFI_SUCCESS;\r
 }\r
 \r
+/**\r
+  Add PCI display to ConOut.\r
+\r
+  @param[in] DeviceHandle  Handle of the PCI display device.\r
+\r
+  @retval EFI_SUCCESS  The PCI display device has been added to ConOut.\r
+\r
+  @return              Error codes, due to EFI_DEVICE_PATH_PROTOCOL missing\r
+                       from DeviceHandle.\r
+**/\r
 EFI_STATUS\r
 PreparePciDisplayDevicePath (\r
   IN EFI_HANDLE                DeviceHandle\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  Add PCI VGA to ConOut.\r
-  PCI VGA: 03 00 00\r
-\r
-Arguments:\r
-\r
-  DeviceHandle            - Handle of PCIIO protocol.\r
-\r
-Returns:\r
-\r
-  EFI_SUCCESS             - PCI VGA is added to ConOut.\r
-  EFI_STATUS              - No PCI VGA device is added.\r
-\r
---*/\r
 {\r
   EFI_STATUS                Status;\r
   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;\r
@@ -674,27 +659,21 @@ Returns:
   return EFI_SUCCESS;\r
 }\r
 \r
-EFI_STATUS\r
-PreparePciSerialDevicePath (\r
-  IN EFI_HANDLE                DeviceHandle\r
-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
+/**\r
   Add PCI Serial to ConOut, ConIn, ErrOut.\r
-  PCI Serial: 07 00 02\r
-\r
-Arguments:\r
 \r
-  DeviceHandle            - Handle of PCIIO protocol.\r
+  @param[in] DeviceHandle  Handle of the PCI serial device.\r
 \r
-Returns:\r
+  @retval EFI_SUCCESS  The PCI serial device has been added to ConOut, ConIn,\r
+                       ErrOut.\r
 \r
-  EFI_SUCCESS             - PCI Serial is added to ConOut, ConIn, and ErrOut.\r
-  EFI_STATUS              - No PCI Serial device is added.\r
-\r
---*/\r
+  @return              Error codes, due to EFI_DEVICE_PATH_PROTOCOL missing\r
+                       from DeviceHandle.\r
+**/\r
+EFI_STATUS\r
+PreparePciSerialDevicePath (\r
+  IN EFI_HANDLE                DeviceHandle\r
+  )\r
 {\r
   EFI_STATUS                Status;\r
   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;\r
@@ -918,21 +897,17 @@ DetectAndPreparePlatformPciDevicePaths (
 }\r
 \r
 \r
+/**\r
+  Connect the predefined platform default console device.\r
+\r
+  Always try to find and enable PCI display devices.\r
+\r
+  @param[in] PlatformConsole  Predefined platform default console device array.\r
+**/\r
 VOID\r
 PlatformInitializeConsole (\r
   IN PLATFORM_CONSOLE_CONNECT_ENTRY   *PlatformConsole\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  Connect the predefined platform default console device. Always try to find\r
-  and enable the vga device if have.\r
-\r
-Arguments:\r
-\r
-  PlatformConsole         - Predefined platform default console device array.\r
---*/\r
 {\r
   UINTN                              Index;\r
   EFI_DEVICE_PATH_PROTOCOL           *VarConout;\r
@@ -1346,26 +1321,15 @@ PlatformBdsRestoreNvVarsFromHardDisk (
 \r
 }\r
 \r
+/**\r
+  Connect with predefined platform connect sequence.\r
+\r
+  The OEM/IBV can customize with their own connect sequence.\r
+**/\r
 VOID\r
 PlatformBdsConnectSequence (\r
   VOID\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  Connect with predefined platform connect sequence,\r
-  the OEM/IBV can customize with their own connect sequence.\r
-\r
-Arguments:\r
-\r
-  None.\r
-\r
-Returns:\r
-\r
-  None.\r
-\r
---*/\r
 {\r
   UINTN         Index;\r
   RETURN_STATUS Status;\r
@@ -1431,20 +1395,24 @@ SaveS3BootScript (
 }\r
 \r
 \r
+/**\r
+  Do the platform specific action after the console is ready\r
+\r
+  Possible things that can be done in PlatformBootManagerAfterConsole:\r
+\r
+  > Console post action:\r
+    > Dynamically switch output mode from 100x31 to 80x25 for certain senarino\r
+    > Signal console ready platform customized event\r
+  > Run diagnostics like memory testing\r
+  > Connect certain devices\r
+  > Dispatch aditional option roms\r
+  > Special boot: e.g.: USB boot, enter UI\r
+**/\r
 VOID\r
 EFIAPI\r
 PlatformBootManagerAfterConsole (\r
   VOID\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  The function will execute with as the platform policy, current policy\r
-  is driven by boot mode. IBV/OEM can customize this code for their specific\r
-  policy action.\r
-\r
---*/\r
 {\r
   EFI_BOOT_MODE                      BootMode;\r
 \r