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

IntelFrameworkPkg/Include/FrameworkSmm.h

@@ -1,5 +1,5 @@
 /** @file
-  Header file that supports Framework extension to UEFI/PI for DXE modules.
+  Header file that supports Framework extension to UEFI/PI for SMM modules.
 
   This header file must include Framework extension definitions common to DXE
   modules.

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

IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h

@@ -1,5 +1,9 @@
 /** @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
@@ -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

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

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

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

IntelFrameworkPkg/Include/Protocol/PciHostBridgeResourceAllocation.h

@@ -1,5 +1,7 @@
 /** @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
@@ -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

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

IntelFrameworkPkg/Include/Protocol/PciPlatform.h

@@ -1,5 +1,8 @@
 /** @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
@@ -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

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.

IntelFrameworkPkg/Include/Protocol/SmmBase.h

@@ -1,6 +1,23 @@
 /** @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<75>-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

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<65> 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<75>-based
+  systems.
 
   Copyright (c) 2007, Intel Corporation
   All rights reserved. This program and the accompanying materials

IntelFrameworkPkg/Include/Protocol/SmmGpiDispatch.h

@@ -1,5 +1,8 @@
 /** @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

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

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

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

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

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

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

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