MdeModulePkg/EbcDxe: reorganize EBC header definitions

[mirror_edk2.git] / MdePkg / Include / Protocol / PciPlatform.h

diff --git a/MdePkg/Include/Protocol/PciPlatform.h b/MdePkg/Include/Protocol/PciPlatform.h
index 123309b8b18655e755ca0c3f07d5645a08217f40..15d735e1fe7ed3b21ffeece8597544176d91b51c 100644 (file)
--- a/MdePkg/Include/Protocol/PciPlatform.h
+++ b/MdePkg/Include/Protocol/PciPlatform.h
@@ -1,17 +1,17 @@
 /** @file\r
 /** @file\r

-  This file declares PlatfromOpRom protocols which provides the interface between \r
+  This file declares PlatfromOpRom protocols that provide the interface between \r

   the PCI bus driver/PCI Host Bridge Resource Allocation driver and a platform-specific \r
   the PCI bus driver/PCI Host Bridge Resource Allocation driver and a platform-specific \r

-  driver to describe the unique features of a platform. This\r
-  protocol is optional.\r
+  driver to describe the unique features of a platform. \r
+  This protocol is optional.\r

   \r
   \r

-  Copyright (c) 2007 - 2009, Intel Corporation\r
-  All rights reserved. This program and the accompanying materials\r
-  are licensed and made available under the terms and conditions of the BSD License\r
-  which accompanies this distribution.  The full text of the license may be found at\r
-  http://opensource.org/licenses/bsd-license.php\r
-\r
-  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
-  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR>\r
+This program and the accompanying materials are licensed and made available under \r
+the terms and conditions of the BSD License that accompanies this distribution.  \r
+The full text of the license may be found at\r
+http://opensource.org/licenses/bsd-license.php.                                          \r
+    \r
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     \r
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r

 \r
   @par Revision Reference:\r
   This Protocol is defined in UEFI Platform Initialization Specification 1.2 \r
 \r
   @par Revision Reference:\r
   This Protocol is defined in UEFI Platform Initialization Specification 1.2 \r


@@ -24,12 +24,12 @@
 \r
 ///\r
 /// This file must be included because the EFI_PCI_PLATFORM_PROTOCOL uses\r
 \r
 ///\r
 /// This file must be included because the EFI_PCI_PLATFORM_PROTOCOL uses\r

-/// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE\r
+/// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE.\r

 ///\r
 #include <Protocol/PciHostBridgeResourceAllocation.h>\r
 \r
 ///\r
 ///\r
 #include <Protocol/PciHostBridgeResourceAllocation.h>\r
 \r
 ///\r

-/// Global ID for the EFI_PCI_PLATFORM_PROTOCOL\r
+/// Global ID for the EFI_PCI_PLATFORM_PROTOCOL.\r

 ///\r
 #define EFI_PCI_PLATFORM_PROTOCOL_GUID \\r
   { \\r
 ///\r
 #define EFI_PCI_PLATFORM_PROTOCOL_GUID \\r
   { \\r


@@ -37,12 +37,12 @@
   }\r
 \r
 ///\r
   }\r
 \r
 ///\r

-/// Forward declaration for EFI_PCI_PLATFORM_PROTOCOL\r
+/// Forward declaration for EFI_PCI_PLATFORM_PROTOCOL.\r

 ///\r
 typedef struct _EFI_PCI_PLATFORM_PROTOCOL EFI_PCI_PLATFORM_PROTOCOL;\r
 \r
 ///\r
 ///\r
 typedef struct _EFI_PCI_PLATFORM_PROTOCOL EFI_PCI_PLATFORM_PROTOCOL;\r
 \r
 ///\r

-/// EFI_PCI_PLATYFORM_POLICY that is a bitmask with the following legal combinations:\r
+/// EFI_PCI_PLATFORM_POLICY that is a bitmask with the following legal combinations:\r

 ///   - EFI_RESERVE_NONE_IO_ALIAS:<BR>\r
 ///       Does not set aside either ISA or VGA I/O resources during PCI\r
 ///       enumeration. By using this selection, the platform indicates that it does\r
 ///   - EFI_RESERVE_NONE_IO_ALIAS:<BR>\r
 ///       Does not set aside either ISA or VGA I/O resources during PCI\r
 ///       enumeration. By using this selection, the platform indicates that it does\r


@@ -52,7 +52,7 @@ typedef struct _EFI_PCI_PLATFORM_PROTOCOL EFI_PCI_PLATFORM_PROTOCOL;
 ///   - EFI_RESERVE_ISA_IO_ALIAS | EFI_RESERVE_VGA_IO_ALIAS:<BR>\r
 ///       Sets aside the ISA I/O range and all the aliases during PCI\r
 ///       enumeration. VGA I/O ranges and aliases are included in ISA alias\r
 ///   - EFI_RESERVE_ISA_IO_ALIAS | EFI_RESERVE_VGA_IO_ALIAS:<BR>\r
 ///       Sets aside the ISA I/O range and all the aliases during PCI\r
 ///       enumeration. VGA I/O ranges and aliases are included in ISA alias\r

-///       ranges. In this scheme, 75 percent of the I/O space remains unused.\r
+///       ranges. In this scheme, seventy-five percent of the I/O space remains unused.\r

 ///       By using this selection, the platform indicates that it wants to support\r
 ///       PCI devices that require the following, at the cost of wasted I/O space:\r
 ///       ISA range and its aliases\r
 ///       By using this selection, the platform indicates that it wants to support\r
 ///       PCI devices that require the following, at the cost of wasted I/O space:\r
 ///       ISA range and its aliases\r


@@ -70,15 +70,15 @@ typedef struct _EFI_PCI_PLATFORM_PROTOCOL EFI_PCI_PLATFORM_PROTOCOL;
 ///       The first device that requests the legacy VGA range will get all the\r
 ///       legacy VGA range plus its aliased addresses forwarded to it. The first\r
 ///       device that requests the legacy ISA range will get all the legacy ISA\r
 ///       The first device that requests the legacy VGA range will get all the\r
 ///       legacy VGA range plus its aliased addresses forwarded to it. The first\r
 ///       device that requests the legacy ISA range will get all the legacy ISA\r

-///       range plus its aliased addresses forwarded to it.\r
+///       range, plus its aliased addresses, forwarded to it.\r

 ///   - EFI_RESERVE_ISA_IO_NO_ALIAS | EFI_RESERVE_VGA_IO_ALIAS:<BR>\r
 ///   - EFI_RESERVE_ISA_IO_NO_ALIAS | EFI_RESERVE_VGA_IO_ALIAS:<BR>\r

-///       Sets aside the ISA I/O range (0x100\960x3FF) during PCI enumeration\r
+///       Sets aside the ISA I/O range (0x100 - 0x3FF) during PCI enumeration\r

 ///       and the aliases of the VGA I/O ranges. By using this selection, the\r
 ///       platform indicates that it will support VGA devices that require VGA\r
 ///       ranges, including those that require VGA aliases. The platform further\r
 ///       and the aliases of the VGA I/O ranges. By using this selection, the\r
 ///       platform indicates that it will support VGA devices that require VGA\r
 ///       ranges, including those that require VGA aliases. The platform further\r

-///       wants to support non-VGA devices that ask for the ISA range (0x100\96\r
+///       wants to support non-VGA devices that ask for the ISA range (0x100 -\r

 ///       3FF), but not if it also asks for the ISA aliases. The PCI bus driver will\r
 ///       3FF), but not if it also asks for the ISA aliases. The PCI bus driver will\r

-///       not allocate I/O addresses out of the legacy ISA I/O range (0x100\96\r
+///       not allocate I/O addresses out of the legacy ISA I/O range (0x100 -\r

 ///       0x3FF) range or the aliases of the VGA I/O range. If a PCI device\r
 ///       driver asks for the ISA I/O ranges, including aliases, the request will be\r
 ///       turned down. The first device that requests the legacy VGA range will\r
 ///       0x3FF) range or the aliases of the VGA I/O range. If a PCI device\r
 ///       driver asks for the ISA I/O ranges, including aliases, the request will be\r
 ///       turned down. The first device that requests the legacy VGA range will\r


@@ -95,13 +95,13 @@ typedef struct _EFI_PCI_PLATFORM_PROTOCOL EFI_PCI_PLATFORM_PROTOCOL;
 ///       and Windows Server 2003. The PCI enumeration process must be\r
 ///       cognizant of this restriction.\r
 ///   - EFI_RESERVE_ISA_IO_NO_ALIAS | EFI_RESERVE_VGA_IO_NO_ALIAS:<BR>\r
 ///       and Windows Server 2003. The PCI enumeration process must be\r
 ///       cognizant of this restriction.\r
 ///   - EFI_RESERVE_ISA_IO_NO_ALIAS | EFI_RESERVE_VGA_IO_NO_ALIAS:<BR>\r

-///       Sets aside the ISA I/O range (0x100\960x3FF) during PCI enumeration.\r
+///       Sets aside the ISA I/O range (0x100 - 0x3FF) during PCI enumeration.\r

 ///       VGA I/O ranges are included in the ISA range. By using this selection,\r
 ///       the platform indicates that it wants to support PCI devices that require\r
 ///       the ISA range and legacy VGA range, but it does not want to support\r
 ///       devices that require ISA alias ranges or VGA alias ranges. The PCI\r
 ///       bus driver will not allocate I/O addresses out of the legacy ISA I/O\r
 ///       VGA I/O ranges are included in the ISA range. By using this selection,\r
 ///       the platform indicates that it wants to support PCI devices that require\r
 ///       the ISA range and legacy VGA range, but it does not want to support\r
 ///       devices that require ISA alias ranges or VGA alias ranges. The PCI\r
 ///       bus driver will not allocate I/O addresses out of the legacy ISA I/O\r

-///       range (0x100\960x3FF). If a PCI device driver asks for the ISA I/O\r
+///       range (0x100-0x3FF). If a PCI device driver asks for the ISA I/O\r

 ///       ranges, including aliases, the request will be turned down. By using\r
 ///       this selection, the platform indicates that it will support VGA devices\r
 ///       that require VGA ranges, but it will not support VGA devices that\r
 ///       ranges, including aliases, the request will be turned down. By using\r
 ///       this selection, the platform indicates that it will support VGA devices\r
 ///       that require VGA ranges, but it will not support VGA devices that\r


@@ -125,26 +125,26 @@ typedef UINT32  EFI_PCI_PLATFORM_POLICY;
 #define     EFI_RESERVE_NONE_IO_ALIAS        0x0000\r
 \r
 ///\r
 #define     EFI_RESERVE_NONE_IO_ALIAS        0x0000\r
 \r
 ///\r

-/// Sets aside ISA I/O range and all aliases\r
+/// Sets aside ISA I/O range and all aliases:\r

 ///   - n100..n3FF\r
 ///   - n500..n7FF\r
 ///   - n900..nBFF\r
 ///   - n100..n3FF\r
 ///   - n500..n7FF\r
 ///   - n900..nBFF\r

-///   - nD00..nFFF\r
+///   - nD00..nFFF.\r

 ///\r
 #define     EFI_RESERVE_ISA_IO_ALIAS         0x0001\r
 \r
 ///\r
 ///\r
 #define     EFI_RESERVE_ISA_IO_ALIAS         0x0001\r
 \r
 ///\r

-/// Sets aside ISA I/O range 0x100-0x3FF\r
+/// Sets aside ISA I/O range 0x100-0x3FF.\r

 ///\r
 #define     EFI_RESERVE_ISA_IO_NO_ALIAS      0x0002\r
 \r
 ///\r
 ///\r
 #define     EFI_RESERVE_ISA_IO_NO_ALIAS      0x0002\r
 \r
 ///\r

-/// Sets aside VGA I/O ranges and all aliases\r
+/// Sets aside VGA I/O ranges and all aliases.\r

 ///\r
 #define     EFI_RESERVE_VGA_IO_ALIAS         0x0004\r
 \r
 ///\r
 ///\r
 #define     EFI_RESERVE_VGA_IO_ALIAS         0x0004\r
 \r
 ///\r

-/// Sets aside VGA I/O rangess\r
+/// Sets aside VGA I/O ranges\r

 ///\r
 #define     EFI_RESERVE_VGA_IO_NO_ALIAS      0x0008\r
 \r
 ///\r
 #define     EFI_RESERVE_VGA_IO_NO_ALIAS      0x0008\r
 \r


@@ -200,10 +200,10 @@ typedef EFI_PCI_EXECUTION_PHASE EFI_PCI_CHIPSET_EXECUTION_PHASE;
   it needs to handle those errors on its own because there is no way to surface any\r
   errors to the caller.\r
 \r
   it needs to handle those errors on its own because there is no way to surface any\r
   errors to the caller.\r
 \r

-  @param[in] This           Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.\r
+  @param[in] This           The pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.\r

   @param[in] HostBridge     The handle of the host bridge controller.\r
   @param[in] Phase          The phase of the PCI bus enumeration.\r
   @param[in] HostBridge     The handle of the host bridge controller.\r
   @param[in] Phase          The phase of the PCI bus enumeration.\r

-  @param[in] ChipsetPhase   Defines the execution phase of the PCI chipset driver.\r
+  @param[in] ExecPhase      Defines the execution phase of the PCI chipset driver.\r

 \r
   @retval EFI_SUCCESS   The function completed successfully.\r
 \r
 \r
   @retval EFI_SUCCESS   The function completed successfully.\r
 \r


@@ -214,7 +214,7 @@ EFI_STATUS
   IN EFI_PCI_PLATFORM_PROTOCOL                      *This,\r
   IN EFI_HANDLE                                     HostBridge,\r
   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE  Phase,\r
   IN EFI_PCI_PLATFORM_PROTOCOL                      *This,\r
   IN EFI_HANDLE                                     HostBridge,\r
   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE  Phase,\r

-  IN EFI_PCI_CHIPSET_EXECUTION_PHASE                ChipsetPhase\r
+  IN EFI_PCI_EXECUTION_PHASE                        ExecPhase\r

   );\r
 \r
 /**\r
   );\r
 \r
 /**\r


@@ -233,12 +233,12 @@ EFI_STATUS
   needs to handle those errors on its own because there is no way to surface any errors to\r
   the caller.\r
 \r
   needs to handle those errors on its own because there is no way to surface any errors to\r
   the caller.\r
 \r

-  @param[in] This           Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.\r
+  @param[in] This           The pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.\r

   @param[in] HostBridge     The associated PCI host bridge handle.\r
   @param[in] RootBridge     The associated PCI root bridge handle.\r
   @param[in] PciAddress     The address of the PCI device on the PCI bus.\r
   @param[in] Phase          The phase of the PCI controller enumeration.\r
   @param[in] HostBridge     The associated PCI host bridge handle.\r
   @param[in] RootBridge     The associated PCI root bridge handle.\r
   @param[in] PciAddress     The address of the PCI device on the PCI bus.\r
   @param[in] Phase          The phase of the PCI controller enumeration.\r

-  @param[in] ChipsetPhase   Defines the execution phase of the PCI chipset driver.\r
+  @param[in] ExecPhase      Defines the execution phase of the PCI chipset driver.\r

 \r
   @retval EFI_SUCCESS   The function completed successfully.\r
 \r
 \r
   @retval EFI_SUCCESS   The function completed successfully.\r
 \r


@@ -251,7 +251,7 @@ EFI_STATUS
   IN EFI_HANDLE                                    RootBridge,\r
   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS   PciAddress,\r
   IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE  Phase,\r
   IN EFI_HANDLE                                    RootBridge,\r
   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS   PciAddress,\r
   IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE  Phase,\r

-  IN EFI_PCI_CHIPSET_EXECUTION_PHASE               ChipsetPhase\r
+  IN EFI_PCI_EXECUTION_PHASE                       ExecPhase\r

   );\r
 \r
 /**\r
   );\r
 \r
 /**\r


@@ -261,7 +261,7 @@ EFI_STATUS
   enumeration. The PCI bus driver and the PCI Host Bridge Resource Allocation Protocol\r
   driver can call this member function to retrieve the policy.\r
 \r
   enumeration. The PCI bus driver and the PCI Host Bridge Resource Allocation Protocol\r
   driver can call this member function to retrieve the policy.\r
 \r

-  @param[in]  This        Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.\r
+  @param[in]  This        The pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.\r

   @param[out] PciPolicy   The platform policy with respect to VGA and ISA aliasing.\r
 \r
   @retval EFI_SUCCESS             The function completed successfully.\r
   @param[out] PciPolicy   The platform policy with respect to VGA and ISA aliasing.\r
 \r
   @retval EFI_SUCCESS             The function completed successfully.\r


@@ -271,8 +271,8 @@ EFI_STATUS
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_PCI_PLATFORM_GET_PLATFORM_POLICY)(\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_PCI_PLATFORM_GET_PLATFORM_POLICY)(\r

-  IN  EFI_PCI_PLATFORM_PROTOCOL  *This,\r
-  OUT EFI_PCI_PLATFORM_POLICY    *PciPolicy\r
+  IN  CONST EFI_PCI_PLATFORM_PROTOCOL  *This,\r
+  OUT       EFI_PCI_PLATFORM_POLICY    *PciPolicy\r

   );\r
 \r
 /**\r
   );\r
 \r
 /**\r


@@ -288,7 +288,7 @@ EFI_STATUS
   scanning the ROM that is attached to any controller, which allows a platform to specify a ROM\r
   image that is different from the ROM image on a PCI card.\r
 \r
   scanning the ROM that is attached to any controller, which allows a platform to specify a ROM\r
   image that is different from the ROM image on a PCI card.\r
 \r

-  @param[in]  This        Pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.\r
+  @param[in]  This        The pointer to the EFI_PCI_PLATFORM_PROTOCOL instance.\r

   @param[in]  PciHandle   The handle of the PCI device.\r
   @param[out] RomImage    If the call succeeds, the pointer to the pointer to the option ROM image.\r
                           Otherwise, this field is undefined. The memory for RomImage is allocated\r
   @param[in]  PciHandle   The handle of the PCI device.\r
   @param[out] RomImage    If the call succeeds, the pointer to the pointer to the option ROM image.\r
                           Otherwise, this field is undefined. The memory for RomImage is allocated\r


@@ -301,16 +301,16 @@ EFI_STATUS
   @retval EFI_SUCCESS            The option ROM was available for this device and loaded into memory.\r
   @retval EFI_NOT_FOUND          No option ROM was available for this device.\r
   @retval EFI_OUT_OF_RESOURCES   No memory was available to load the option ROM.\r
   @retval EFI_SUCCESS            The option ROM was available for this device and loaded into memory.\r
   @retval EFI_NOT_FOUND          No option ROM was available for this device.\r
   @retval EFI_OUT_OF_RESOURCES   No memory was available to load the option ROM.\r

-  @retval EFI_DEVICE_ERROR       An error occurred in getting the option ROM.\r
+  @retval EFI_DEVICE_ERROR       An error occurred in obtaining the option ROM.\r

 \r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_PCI_PLATFORM_GET_PCI_ROM)(\r
 \r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_PCI_PLATFORM_GET_PCI_ROM)(\r

-  IN  EFI_PCI_PLATFORM_PROTOCOL  *This,\r
-  IN  EFI_HANDLE                 PciHandle,\r
-  OUT VOID                       **RomImage,\r
-  OUT UINTN                      *RomSize\r
+  IN  CONST EFI_PCI_PLATFORM_PROTOCOL  *This,\r
+  IN        EFI_HANDLE                 PciHandle,\r
+  OUT       VOID                       **RomImage,\r
+  OUT       UINTN                      *RomSize\r

   );\r
 \r
 ///\r
   );\r
 \r
 ///\r


@@ -334,7 +334,7 @@ struct _EFI_PCI_PLATFORM_PROTOCOL {
   ///\r
   EFI_PCI_PLATFORM_GET_PLATFORM_POLICY   GetPlatformPolicy;\r
   ///\r
   ///\r
   EFI_PCI_PLATFORM_GET_PLATFORM_POLICY   GetPlatformPolicy;\r
   ///\r

-  /// Gets the PCI device\92s option ROM from a platform-specific location.\r
+  /// Gets the PCI device's option ROM from a platform-specific location.\r

   ///\r
   EFI_PCI_PLATFORM_GET_PCI_ROM           GetPciRom;\r
 };\r
   ///\r
   EFI_PCI_PLATFORM_GET_PCI_ROM           GetPciRom;\r
 };\r