Refine comments.
authorklu2 <klu2@6f19259b-4bc3-4df7-8a09-765794883524>
Tue, 7 Jul 2009 02:15:40 +0000 (02:15 +0000)
committerklu2 <klu2@6f19259b-4bc3-4df7-8a09-765794883524>
Tue, 7 Jul 2009 02:15:40 +0000 (02:15 +0000)
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8765 6f19259b-4bc3-4df7-8a09-765794883524

IntelFrameworkPkg/Include/Protocol/LegacyBios.h

index c881d9c2c50b43ff07a0396b24ddf5a88dff6407..e08dd3ff98d37cd8ef1fe7f455dc664a7519b6c2 100644 (file)
@@ -243,7 +243,10 @@ BOOLEAN
   @param  PciHandle             The PCI PC-AT OPROM from this devices ROM BAR will be loaded\r
   @param  RomImage              Return the legacy PCI ROM for this device\r
   @param  RomSize               Size of ROM Image\r
-  @param  Flags                 Indicates if ROM found and if PC-AT.\r
+  @param  Flags                 Indicates if ROM found and if PC-AT. Multiple bits can be set as follows:\r
+                                00 = No ROM\r
+                                01 = ROM Found\r
+                                02 = ROM is a valid legacy ROM\r
 \r
   @retval EFI_SUCCESS           Legacy Option ROM availible for this device\r
   @retval EFI_UNSUPPORTED       Legacy Option ROM not supported.\r
@@ -272,7 +275,10 @@ EFI_STATUS
                                 no hardware associated with the ROM and thus no PciHandle,\r
                                 otherwise is must be NULL.\r
                                 Example is PXE base code.\r
-  @param  Flags                 Return Status if ROM was found and if was Legacy OPROM.\r
+  @param  Flags                 The type of ROM discovered. Multiple bits can be set, as follows:\r
+                                00 = No ROM.\r
+                                01 = ROM found.\r
+                                02 = ROM is a valid legacy ROM.\r
   @param  DiskStart             Disk number of first device hooked by the ROM. If DiskStart\r
                                 is the same as DiskEnd no disked were hooked.\r
   @param  DiskEnd               Disk number of the last device hooked by the ROM.\r
@@ -297,15 +303,38 @@ EFI_STATUS
   );\r
 \r
 /**\r
-  Attempt to legacy boot the BootOption. If the EFI contexted has been\r
-  compromised this function will not return.\r
+  This function attempts to traditionally boot the specified BootOption. If the EFI context has\r
+  been compromised, this function will not return. This procedure is not used for loading an EFIaware\r
+  OS off a traditional device. The following actions occur:\r
+  - Get EFI SMBIOS data structures, convert them to a traditional format, and copy to\r
+    Compatibility16.\r
+  - Get a pointer to ACPI data structures and copy the Compatibility16 RSD PTR to F0000 block.\r
+  - Find the traditional SMI handler from a firmware volume and register the traditional SMI\r
+    handler with the EFI SMI handler.\r
+  - Build onboard IDE information and pass this information to the Compatibility16 code.\r
+  - Make sure all PCI Interrupt Line registers are programmed to match 8259.\r
+  - Reconfigure SIO devices from EFI mode (polled) into traditional mode (interrupt driven).\r
+  - Shadow all PCI ROMs.\r
+  - Set up BDA and EBDA standard areas before the legacy boot.\r
+  - Construct the Compatibility16 boot memory map and pass it to the Compatibility16 code.\r
+  - Invoke the Compatibility16 table function Compatibility16PrepareToBoot(). This\r
+    invocation causes a thunk into the Compatibility16 code, which sets all appropriate internal\r
+    data structures. The boot device list is a parameter.\r
+  - Invoke the Compatibility16 Table function Compatibility16Boot(). This invocation\r
+    causes a thunk into the Compatibility16 code, which does an INT19.\r
+  - If the Compatibility16Boot() function returns, then the boot failed in a graceful\r
+    manner—i.e., EFI code is still valid. An ungraceful boot failure causes a reset because the state\r
+    of EFI code is unknown.\r
 \r
   @param  This                  Protocol instance pointer.\r
   @param  BootOption            EFI Device Path from BootXXXX variable.\r
   @param  LoadOptionSize        Size of LoadOption in size.\r
   @param  LoadOption            LoadOption from BootXXXX variable\r
 \r
-  @retval EFI_SUCCESS           Removable media not present\r
+  @retval EFI_DEVICE_ERROR      Failed to boot from any boot device and memory is uncorrupted.\r
+                                Note: This function normally never returns. It will either boot the\r
+                                OS or reset the system if memory has been "corrupted" by loading\r
+                                a boot sector and passing control to it.\r
 \r
 **/\r
 typedef\r
@@ -318,7 +347,11 @@ EFI_STATUS
   );\r
 \r
 /**\r
-  Update BDA with current Scroll, Num & Cap lock LEDS\r
+  This function takes the Leds input parameter and sets/resets the BDA accordingly. \r
+  Leds is also passed to Compatibility16 code, in case any special processing is required. \r
+  This function is normally called from EFI Setup drivers that handle userselectable\r
+  keyboard options such as boot with NUM LOCK on/off. This function does not\r
+  touch the keyboard or keyboard LEDs but only the BDA.\r
 \r
   @param  This                  Protocol instance pointer.\r
   @param  Leds                  Status of current Scroll, Num & Cap lock LEDS\r
@@ -326,7 +359,7 @@ EFI_STATUS
                                 Bit 1 is Num Lock\r
                                 Bit 2 is Caps Lock\r
 \r
-  @retval EFI_SUCCESS           Removable media not present\r
+  @retval EFI_SUCCESS           The BDA was updated successfully.\r
 \r
 **/\r
 typedef\r
@@ -343,7 +376,7 @@ EFI_STATUS
   @param  HddCount              Number of HDD_INFO structures\r
   @param  HddInfo               Onboard IDE controller information\r
   @param  BbsCount              Number of BBS_TABLE structures\r
-  @param  BbsTable              List BBS entries\r
+  @param  BbsTable              Point to List of BBS_TABLE\r
 \r
   @retval EFI_SUCCESS           Tables returned\r
 \r
@@ -390,7 +423,7 @@ EFI_STATUS
                                 caller must provide a pointer to the specific Service\r
                                 Area and not the start all Service Areas.\r
 \r
-  EFI_INVALID_PARAMETER if error. Does NOT return if no error.\r
+  @retval EFI_INVALID_PARAMETER if error. Does NOT return if no error.\r
 \r
 **/\r
 typedef\r
@@ -432,6 +465,7 @@ EFI_STATUS
   @param  LegacyMemoryAddress   Region Assigned\r
 \r
   @retval EFI_SUCCESS           Region assigned\r
+  @retval EFI_ACCESS_DENIED     The function was previously invoked.\r
   @retval Other                 Region not assigned\r
 \r
 **/\r
@@ -454,7 +488,7 @@ EFI_STATUS
                                 Note: must be in region assigned by\r
                                 LegacyBiosGetLegacyRegion\r
   @param  LegacyMemorySourceAddress\r
-                                Source of data\r
+                                Source of the data to copy.\r
 \r
   @retval EFI_SUCCESS           Region assigned\r
   @retval EFI_ACCESS_DENIED     Destination outside assigned region\r