Add more comments for IntelFramework's header files.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5004 6f19259b-4bc3-4df7-8a09-765794883524

19 files changed, 87 insertions, 28 deletions

diff --git a/IntelFrameworkPkg/Include/Protocol/CpuIo.h b/IntelFrameworkPkg/Include/Protocol/CpuIo.h
index f6c91df9bd..e449354b39 100644
--- a/IntelFrameworkPkg/Include/Protocol/CpuIo.h
+++ b/IntelFrameworkPkg/Include/Protocol/CpuIo.h
@@ -1,5 +1,6 @@
 /** @file

-  This code abstracts the CPU IO Protocol

+  This code abstracts the CPU IO Protocol which installed by some platform or chipset-specific 

+  PEIM that abstracts the processor-visible I/O operations.

 

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

diff --git a/IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h b/IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h
index 5f789e1099..cd0484fc90 100644
--- a/IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h
+++ b/IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h
@@ -1,6 +1,10 @@
 /** @file

   This file declares Firmware Volume protocol.

-

+  The Firmware Volume Protocol provides file-level access to the firmware volume.E ach firmware

+  volume driver must produce an instance of the Firmware Volume Protocol if the firmware volume

+  is to be visible to the system.T he Firmware Volume Protocol also provides mechanisms for

+  determining and modifying some attributes of the firmware volume.

+  

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

   are licensed and made available under the terms and conditions of the BSD License

@@ -10,8 +14,6 @@
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 

-  Module Name:  FirmwareVolume.h

-

   @par Revision Reference:

   This protocol is defined in Firmware Volume specification.

   Version 0.9

diff --git a/IntelFrameworkPkg/Include/Protocol/IdeControllerInit.h b/IntelFrameworkPkg/Include/Protocol/IdeControllerInit.h
index aef6a2ea26..8192f51ee6 100644
--- a/IntelFrameworkPkg/Include/Protocol/IdeControllerInit.h
+++ b/IntelFrameworkPkg/Include/Protocol/IdeControllerInit.h
@@ -1,5 +1,13 @@
 /** @file

   This file declares EFI IDE Controller Init Protocol

+  The EFI_IDE_CONTROLLER_INIT_PROTOCOL provides the chipset-specific information to

+  the IDE bus driver. This protocol is mandatory for IDE controllers if the IDE devices behind the

+  controller are to be enumerated by an IDE bus driver.

+  There can only be one instance of EFI_IDE_CONTROLLER_INIT_PROTOCOL for each IDE

+  controller in a system. It is installed on the handle that corresponds to the IDE controller. An IDE

+  bus driver that wishes to manage an IDE bus and possibly IDE devices in a system will have to

+  retrieve the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance that is associated with the

+  controller to be managed.

 

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

diff --git a/IntelFrameworkPkg/Include/Protocol/IncompatiblePciDeviceSupport.h b/IntelFrameworkPkg/Include/Protocol/IncompatiblePciDeviceSupport.h
index 0c45fb7c27..3e72539aba 100644
--- a/IntelFrameworkPkg/Include/Protocol/IncompatiblePciDeviceSupport.h
+++ b/IntelFrameworkPkg/Include/Protocol/IncompatiblePciDeviceSupport.h
@@ -1,5 +1,19 @@
 /** @file

   This file declares EFI Incompatible PCI Device Support Protocol

+  This protocol allows the PCI bus driver to support resource allocation for some PCI devices that do not comply

+  with the PCI Specification.

+  The EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL is used by the PCI bus driver

+  to support resource allocation for some PCI devices that do not comply with the PCI Specification.

+  This protocol can find some incompatible PCI devices and report their special resource

+  requirements to the PCI bus driver. The generic PCI bus driver does not have prior knowledge of

+  any incompatible PCI devices. It interfaces with the

+  EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL to find out if a device is

+  incompatible and to obtain the special configuration requirements for a specific incompatible PCI

+  device.

+  This protocol is optional, and only one instance of this protocol can be present in the system. If a

+  platform supports this protocol, this protocol is produced by a Driver Execution Environment

+  (DXE) driver and must be made available before the Boot Device Selection (BDS) phase. The PCI

+  bus driver will look for the presence of this protocol before it begins PCI enumeration.

 

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

diff --git a/IntelFrameworkPkg/Include/Protocol/LegacyInterrupt.h b/IntelFrameworkPkg/Include/Protocol/LegacyInterrupt.h
index 0ebbc5143a..f0c28bdab5 100644
--- a/IntelFrameworkPkg/Include/Protocol/LegacyInterrupt.h
+++ b/IntelFrameworkPkg/Include/Protocol/LegacyInterrupt.h
@@ -1,5 +1,5 @@
 /** @file

-  This protocol manages the legacy memory regions between 0xc0000 - 0xfffff

+  This protocol abstracts the PIRQ programming from the generic EFI Compatibility Support Modules (CSMs).

 

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

@@ -10,8 +10,6 @@
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 

-  Module Name:  LegacyInterrupt.h

-

   @par Revision Reference:

   This protocol is defined in Framework for EFI Compatibility Support Module spec

   Version 0.96

diff --git a/IntelFrameworkPkg/Include/Protocol/PciHostBridgeResourceAllocation.h b/IntelFrameworkPkg/Include/Protocol/PciHostBridgeResourceAllocation.h
index 33b4c34d45..92d7c5ac17 100644
--- a/IntelFrameworkPkg/Include/Protocol/PciHostBridgeResourceAllocation.h
+++ b/IntelFrameworkPkg/Include/Protocol/PciHostBridgeResourceAllocation.h
@@ -1,6 +1,8 @@
 /** @file

-  This file declares Pci Host Bridge Resource Allocation Protocol

-

+  This file declares Pci Host Bridge Resource Allocation Protocol which 

+  Provides the basic interfaces to abstract a PCI host bridge resource allocation. This protocol is

+  mandatory if the system includes PCI devices.

+  

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

   are licensed and made available under the terms and conditions of the BSD License

@@ -10,8 +12,6 @@
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 

-  Module Name:  PciHostBridgeResourceAllocation.h

-

   @par Revision Reference:

   This protocol is defined in Framework of EFI Pci Host Bridge Resource Allocation Protocol Spec

   Version 0.9

diff --git a/IntelFrameworkPkg/Include/Protocol/PciHotPlugInit.h b/IntelFrameworkPkg/Include/Protocol/PciHotPlugInit.h
index 177245041b..4f0b045693 100644
--- a/IntelFrameworkPkg/Include/Protocol/PciHotPlugInit.h
+++ b/IntelFrameworkPkg/Include/Protocol/PciHotPlugInit.h
@@ -1,5 +1,7 @@
 /** @file

   This file declares EFI PCI Hot Plug Init Protocol

+  This protocol provides the necessary functionality to initialize the Hot Plug Controllers (HPCs) and

+  the buses that they control. This protocol also provides information regarding resource padding.

 

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

diff --git a/IntelFrameworkPkg/Include/Protocol/PciPlatform.h b/IntelFrameworkPkg/Include/Protocol/PciPlatform.h
index 2db71ebc14..d1044b6209 100644
--- a/IntelFrameworkPkg/Include/Protocol/PciPlatform.h
+++ b/IntelFrameworkPkg/Include/Protocol/PciPlatform.h
@@ -1,6 +1,9 @@
 /** @file

-  This file declares PlatfromOpRom protocols.

-

+  This file declares PlatfromOpRom protocols which provides the interface between 

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

+  driver to describe the unique features of a platform. This

+  protocol is optional.

+  

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

   are licensed and made available under the terms and conditions of the BSD License

@@ -10,8 +13,6 @@
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 

-  Module Name:  PciPlatform.h

-

   @par Revision Reference:

   This protocol is defined in PCI Platform Support Specification

   Version 0.9

diff --git a/IntelFrameworkPkg/Include/Protocol/SmmAccess.h b/IntelFrameworkPkg/Include/Protocol/SmmAccess.h
index df7a87ed8b..231247c0df 100644
--- a/IntelFrameworkPkg/Include/Protocol/SmmAccess.h
+++ b/IntelFrameworkPkg/Include/Protocol/SmmAccess.h
@@ -1,5 +1,10 @@
 /** @file

-  This file declares SMM SMRAM Access abstraction protocol

+  This file declares SMM SMRAM Access abstraction protocol which is used to control 

+  the visibility of the SMRAM on the platform. The expectation is

+  that the north bridge or memory controller would publish this protocol. 

+  For example, the Memory Controller Hub (MCH) has the hardware provision for this 

+  type of control. Because of the protected, distinguished class of memory for IA-32 

+  systems, the expectation is that this protocol would be supported only on IA-32 systems.

 

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

@@ -10,8 +15,6 @@
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 

-  Module Name:  SmmAccess.h

-

   @par Revision Reference:

   This Protocol is defined in Framework of EFI SMM Core Interface Spec

   Version 0.9.

diff --git a/IntelFrameworkPkg/Include/Protocol/SmmBase.h b/IntelFrameworkPkg/Include/Protocol/SmmBase.h
index ab14f1c23b..97f0de6b2b 100644
--- a/IntelFrameworkPkg/Include/Protocol/SmmBase.h
+++ b/IntelFrameworkPkg/Include/Protocol/SmmBase.h
@@ -1,7 +1,24 @@
 /** @file

   This file declares SMM Base abstraction protocol.

-  This is the base level of compatiblity for SMM drivers.

-

+  This protocol is used to install SMM handlers for support of subsequent SMI/PMI activations. This

+  protocol is available on both IA-32 and ItaniumŪ-based systems.

+ 

+  The EFI_SMM_BASE_PROTOCOL is a set of services that is exported by a processor device. It is

+  a required protocol for the platform processor. This protocol can be used in both boot services and

+  runtime mode. However, only the following member functions need to exist into runtime:

+  - InSmm()

+  - Communicate()

+  This protocol is responsible for registering the handler services. The order in which the handlers are

+  executed is prescribed only with respect to the MakeLast flag in the RegisterCallback()

+  service. The driver exports these registration and unregistration services in boot services mode, but

+  the registered handlers will execute through the preboot and runtime. The only way to change the

+  behavior of a registered driver after ExitBootServices() has been invoked is to use some

+  private communication mechanism with the driver to order it to quiesce. This model permits typical

+  use cases, such as invoking the handler to enter ACPI mode, where the OS loader would make this

+  call before boot services are terminated. On the other hand, handlers for services such as chipset

+  workarounds for the century rollover in CMOS should provide commensurate services throughout

+  preboot and OS runtime.

+ 

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

   are licensed and made available under the terms and conditions of the BSD License

diff --git a/IntelFrameworkPkg/Include/Protocol/SmmControl.h b/IntelFrameworkPkg/Include/Protocol/SmmControl.h
index 2dbf412ff7..3b326a1c78 100644
--- a/IntelFrameworkPkg/Include/Protocol/SmmControl.h
+++ b/IntelFrameworkPkg/Include/Protocol/SmmControl.h
@@ -1,5 +1,13 @@
 /** @file

   This file declares SMM Control abstraction protocol.

+  This protocol is used initiate SMI/PMI activations. This protocol could be published by either of

+  the following:

+  - A processor driver to abstract the SMI/PMI IPI

+  - The driver that abstracts the ASIC that is supporting the APM port, such as the ICH in an

+  IntelŪ chipset

+  Because of the possibility of performing SMI or PMI IPI transactions, the ability to generate this

+  event from a platform chipset agent is an optional capability for both IA-32 and ItaniumŪ-based

+  systems.

 

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

diff --git a/IntelFrameworkPkg/Include/Protocol/SmmGpiDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmGpiDispatch.h
index c6cdf608f5..592f564309 100644
--- a/IntelFrameworkPkg/Include/Protocol/SmmGpiDispatch.h
+++ b/IntelFrameworkPkg/Include/Protocol/SmmGpiDispatch.h
@@ -1,6 +1,9 @@
 /** @file

   This file declares Smm Gpi Smi Child Protocol

-

+  The EFI_SMM_GPI_DISPATCH_PROTOCOL provides the ability to install child handlers for the

+  given event types. Several inputs can be enabled. This purpose of this interface is to generate an

+  SMI in response to any of these inputs having a true value provided.

+  

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

   are licensed and made available under the terms and conditions of the BSD License

diff --git a/IntelFrameworkPkg/Include/Protocol/SmmIchnDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmIchnDispatch.h
index 49c5b8b44a..3e90688814 100644
--- a/IntelFrameworkPkg/Include/Protocol/SmmIchnDispatch.h
+++ b/IntelFrameworkPkg/Include/Protocol/SmmIchnDispatch.h
@@ -1,5 +1,7 @@
 /** @file

-  This file declares EFI Smm ICH [N] Specific Smi Child Protocol

+  Provides the parent dispatch service for a given SMI source generator.

+  The EFI_SMM_ICHN_DISPATCH_PROTOCOL provides the ability to install child handlers for

+  the given event types.

 

   Copyright (c) 2008, Intel Corporation

   All rights reserved. This program and the accompanying materials

diff --git a/IntelFrameworkPkg/Include/Protocol/SmmPeriodicTimerDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmPeriodicTimerDispatch.h
index dbc05ed4b8..653e2a82a1 100644
--- a/IntelFrameworkPkg/Include/Protocol/SmmPeriodicTimerDispatch.h
+++ b/IntelFrameworkPkg/Include/Protocol/SmmPeriodicTimerDispatch.h
@@ -1,5 +1,5 @@
 /** @file

-  This file declares EFI Smm Periodic Timer Smi Child Protocol

+  Provides the parent dispatch service for the periodical timer SMI source generator.

 

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

diff --git a/IntelFrameworkPkg/Include/Protocol/SmmPowerButtonDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmPowerButtonDispatch.h
index 01b87c33b5..59553b6d5a 100644
--- a/IntelFrameworkPkg/Include/Protocol/SmmPowerButtonDispatch.h
+++ b/IntelFrameworkPkg/Include/Protocol/SmmPowerButtonDispatch.h
@@ -1,5 +1,5 @@
 /** @file

-  This file declares EFI Smm Power Button Smi Child Protocol

+  Provides the parent dispatch service for the power button SMI source generator.

 

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

diff --git a/IntelFrameworkPkg/Include/Protocol/SmmStandbyButtonDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmStandbyButtonDispatch.h
index 3770154ca4..e319ee24c0 100644
--- a/IntelFrameworkPkg/Include/Protocol/SmmStandbyButtonDispatch.h
+++ b/IntelFrameworkPkg/Include/Protocol/SmmStandbyButtonDispatch.h
@@ -1,5 +1,5 @@
 /** @file

-  This file declares EFI Smm Standby Button Smi Child Protocol

+  Provides the parent dispatch service for the standby button SMI source generator.

 

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

diff --git a/IntelFrameworkPkg/Include/Protocol/SmmSwDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmSwDispatch.h
index cb82a3c087..2c10c2060b 100644
--- a/IntelFrameworkPkg/Include/Protocol/SmmSwDispatch.h
+++ b/IntelFrameworkPkg/Include/Protocol/SmmSwDispatch.h
@@ -1,5 +1,5 @@
 /** @file

-  This file declares EFI Smm Software Smi Child Protocol

+  Provides the parent dispatch service for a given SMI source generator.

 

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

diff --git a/IntelFrameworkPkg/Include/Protocol/SmmSxDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmSxDispatch.h
index 66f059463a..c6c0c1870e 100644
--- a/IntelFrameworkPkg/Include/Protocol/SmmSxDispatch.h
+++ b/IntelFrameworkPkg/Include/Protocol/SmmSxDispatch.h
@@ -1,5 +1,5 @@
 /** @file

-  This file declares EFI Smm Sx Smi Child Protocol

+  Provides the parent dispatch service for a given Sx-state source generator.

 

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials

diff --git a/IntelFrameworkPkg/Include/Protocol/SmmUsbDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmUsbDispatch.h
index 741b0a1a7e..79dc3efba7 100644
--- a/IntelFrameworkPkg/Include/Protocol/SmmUsbDispatch.h
+++ b/IntelFrameworkPkg/Include/Protocol/SmmUsbDispatch.h
@@ -1,5 +1,5 @@
 /** @file

-  This file declares EFI Smm USB Smi Child Protocol.

+  Provides the parent dispatch service for the USB SMI source generator.

 

   Copyright (c) 2007, Intel Corporation

   All rights reserved. This program and the accompanying materials