Add more comments for IntelFramework's header files.
authorklu2 <klu2@6f19259b-4bc3-4df7-8a09-765794883524>
Tue, 8 Apr 2008 07:40:30 +0000 (07:40 +0000)
committerklu2 <klu2@6f19259b-4bc3-4df7-8a09-765794883524>
Tue, 8 Apr 2008 07:40:30 +0000 (07:40 +0000)
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5004 6f19259b-4bc3-4df7-8a09-765794883524

20 files changed:
IntelFrameworkPkg/Include/FrameworkSmm.h
IntelFrameworkPkg/Include/Protocol/CpuIo.h
IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h
IntelFrameworkPkg/Include/Protocol/IdeControllerInit.h
IntelFrameworkPkg/Include/Protocol/IncompatiblePciDeviceSupport.h
IntelFrameworkPkg/Include/Protocol/LegacyInterrupt.h
IntelFrameworkPkg/Include/Protocol/PciHostBridgeResourceAllocation.h
IntelFrameworkPkg/Include/Protocol/PciHotPlugInit.h
IntelFrameworkPkg/Include/Protocol/PciPlatform.h
IntelFrameworkPkg/Include/Protocol/SmmAccess.h
IntelFrameworkPkg/Include/Protocol/SmmBase.h
IntelFrameworkPkg/Include/Protocol/SmmControl.h
IntelFrameworkPkg/Include/Protocol/SmmGpiDispatch.h
IntelFrameworkPkg/Include/Protocol/SmmIchnDispatch.h
IntelFrameworkPkg/Include/Protocol/SmmPeriodicTimerDispatch.h
IntelFrameworkPkg/Include/Protocol/SmmPowerButtonDispatch.h
IntelFrameworkPkg/Include/Protocol/SmmStandbyButtonDispatch.h
IntelFrameworkPkg/Include/Protocol/SmmSwDispatch.h
IntelFrameworkPkg/Include/Protocol/SmmSxDispatch.h
IntelFrameworkPkg/Include/Protocol/SmmUsbDispatch.h

index ed69b2e..31662cc 100644 (file)
@@ -1,5 +1,5 @@
 /** @file\r
-  Header file that supports Framework extension to UEFI/PI for DXE modules.\r
+  Header file that supports Framework extension to UEFI/PI for SMM modules.\r
 \r
   This header file must include Framework extension definitions common to DXE\r
   modules.\r
index f6c91df..e449354 100644 (file)
@@ -1,5 +1,6 @@
 /** @file\r
-  This code abstracts the CPU IO Protocol\r
+  This code abstracts the CPU IO Protocol which installed by some platform or chipset-specific \r
+  PEIM that abstracts the processor-visible I/O operations.\r
 \r
   Copyright (c) 2007, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r
index 5f789e1..cd0484f 100644 (file)
@@ -1,6 +1,10 @@
 /** @file\r
   This file declares Firmware Volume protocol.\r
-\r
+  The Firmware Volume Protocol provides file-level access to the firmware volume.E ach firmware\r
+  volume driver must produce an instance of the Firmware Volume Protocol if the firmware volume\r
+  is to be visible to the system.T he Firmware Volume Protocol also provides mechanisms for\r
+  determining and modifying some attributes of the firmware volume.\r
+  \r
   Copyright (c) 2007, 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
@@ -10,8 +14,6 @@
   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
-  Module Name:  FirmwareVolume.h\r
-\r
   @par Revision Reference:\r
   This protocol is defined in Firmware Volume specification.\r
   Version 0.9\r
index aef6a2e..8192f51 100644 (file)
@@ -1,5 +1,13 @@
 /** @file\r
   This file declares EFI IDE Controller Init Protocol\r
+  The EFI_IDE_CONTROLLER_INIT_PROTOCOL provides the chipset-specific information to\r
+  the IDE bus driver. This protocol is mandatory for IDE controllers if the IDE devices behind the\r
+  controller are to be enumerated by an IDE bus driver.\r
+  There can only be one instance of EFI_IDE_CONTROLLER_INIT_PROTOCOL for each IDE\r
+  controller in a system. It is installed on the handle that corresponds to the IDE controller. An IDE\r
+  bus driver that wishes to manage an IDE bus and possibly IDE devices in a system will have to\r
+  retrieve the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance that is associated with the\r
+  controller to be managed.\r
 \r
   Copyright (c) 2007, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r
index 0c45fb7..3e72539 100644 (file)
@@ -1,5 +1,19 @@
 /** @file\r
   This file declares EFI Incompatible PCI Device Support Protocol\r
+  This protocol allows the PCI bus driver to support resource allocation for some PCI devices that do not comply\r
+  with the PCI Specification.\r
+  The EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL is used by the PCI bus driver\r
+  to support resource allocation for some PCI devices that do not comply with the PCI Specification.\r
+  This protocol can find some incompatible PCI devices and report their special resource\r
+  requirements to the PCI bus driver. The generic PCI bus driver does not have prior knowledge of\r
+  any incompatible PCI devices. It interfaces with the\r
+  EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL to find out if a device is\r
+  incompatible and to obtain the special configuration requirements for a specific incompatible PCI\r
+  device.\r
+  This protocol is optional, and only one instance of this protocol can be present in the system. If a\r
+  platform supports this protocol, this protocol is produced by a Driver Execution Environment\r
+  (DXE) driver and must be made available before the Boot Device Selection (BDS) phase. The PCI\r
+  bus driver will look for the presence of this protocol before it begins PCI enumeration.\r
 \r
   Copyright (c) 2007, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r
index 0ebbc51..f0c28bd 100644 (file)
@@ -1,5 +1,5 @@
 /** @file\r
-  This protocol manages the legacy memory regions between 0xc0000 - 0xfffff\r
+  This protocol abstracts the PIRQ programming from the generic EFI Compatibility Support Modules (CSMs).\r
 \r
   Copyright (c) 2007, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r
@@ -10,8 +10,6 @@
   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
-  Module Name:  LegacyInterrupt.h\r
-\r
   @par Revision Reference:\r
   This protocol is defined in Framework for EFI Compatibility Support Module spec\r
   Version 0.96\r
index 33b4c34..92d7c5a 100644 (file)
@@ -1,6 +1,8 @@
 /** @file\r
-  This file declares Pci Host Bridge Resource Allocation Protocol\r
-\r
+  This file declares Pci Host Bridge Resource Allocation Protocol which \r
+  Provides the basic interfaces to abstract a PCI host bridge resource allocation. This protocol is\r
+  mandatory if the system includes PCI devices.\r
+  \r
   Copyright (c) 2007, 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
@@ -10,8 +12,6 @@
   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
-  Module Name:  PciHostBridgeResourceAllocation.h\r
-\r
   @par Revision Reference:\r
   This protocol is defined in Framework of EFI Pci Host Bridge Resource Allocation Protocol Spec\r
   Version 0.9\r
index 1772450..4f0b045 100644 (file)
@@ -1,5 +1,7 @@
 /** @file\r
   This file declares EFI PCI Hot Plug Init Protocol\r
+  This protocol provides the necessary functionality to initialize the Hot Plug Controllers (HPCs) and\r
+  the buses that they control. This protocol also provides information regarding resource padding.\r
 \r
   Copyright (c) 2007, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r
index 2db71eb..d1044b6 100644 (file)
@@ -1,6 +1,9 @@
 /** @file\r
-  This file declares PlatfromOpRom protocols.\r
-\r
+  This file declares PlatfromOpRom protocols which provides the interface between \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
+  \r
   Copyright (c) 2007, 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
@@ -10,8 +13,6 @@
   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
-  Module Name:  PciPlatform.h\r
-\r
   @par Revision Reference:\r
   This protocol is defined in PCI Platform Support Specification\r
   Version 0.9\r
index df7a87e..231247c 100644 (file)
@@ -1,5 +1,10 @@
 /** @file\r
-  This file declares SMM SMRAM Access abstraction protocol\r
+  This file declares SMM SMRAM Access abstraction protocol which is used to control \r
+  the visibility of the SMRAM on the platform. The expectation is\r
+  that the north bridge or memory controller would publish this protocol. \r
+  For example, the Memory Controller Hub (MCH) has the hardware provision for this \r
+  type of control. Because of the protected, distinguished class of memory for IA-32 \r
+  systems, the expectation is that this protocol would be supported only on IA-32 systems.\r
 \r
   Copyright (c) 2007, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r
@@ -10,8 +15,6 @@
   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
-  Module Name:  SmmAccess.h\r
-\r
   @par Revision Reference:\r
   This Protocol is defined in Framework of EFI SMM Core Interface Spec\r
   Version 0.9.\r
index ab14f1c..97f0de6 100644 (file)
@@ -1,7 +1,24 @@
 /** @file\r
   This file declares SMM Base abstraction protocol.\r
-  This is the base level of compatiblity for SMM drivers.\r
-\r
+  This protocol is used to install SMM handlers for support of subsequent SMI/PMI activations. This\r
+  protocol is available on both IA-32 and Itanium®-based systems.\r
\r
+  The EFI_SMM_BASE_PROTOCOL is a set of services that is exported by a processor device. It is\r
+  a required protocol for the platform processor. This protocol can be used in both boot services and\r
+  runtime mode. However, only the following member functions need to exist into runtime:\r
+  - InSmm()\r
+  - Communicate()\r
+  This protocol is responsible for registering the handler services. The order in which the handlers are\r
+  executed is prescribed only with respect to the MakeLast flag in the RegisterCallback()\r
+  service. The driver exports these registration and unregistration services in boot services mode, but\r
+  the registered handlers will execute through the preboot and runtime. The only way to change the\r
+  behavior of a registered driver after ExitBootServices() has been invoked is to use some\r
+  private communication mechanism with the driver to order it to quiesce. This model permits typical\r
+  use cases, such as invoking the handler to enter ACPI mode, where the OS loader would make this\r
+  call before boot services are terminated. On the other hand, handlers for services such as chipset\r
+  workarounds for the century rollover in CMOS should provide commensurate services throughout\r
+  preboot and OS runtime.\r
\r
   Copyright (c) 2007, 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
index 2dbf412..3b326a1 100644 (file)
@@ -1,5 +1,13 @@
 /** @file\r
   This file declares SMM Control abstraction protocol.\r
+  This protocol is used initiate SMI/PMI activations. This protocol could be published by either of\r
+  the following:\r
+  - A processor driver to abstract the SMI/PMI IPI\r
+  - The driver that abstracts the ASIC that is supporting the APM port, such as the ICH in an\r
+  Intel® chipset\r
+  Because of the possibility of performing SMI or PMI IPI transactions, the ability to generate this\r
+  event from a platform chipset agent is an optional capability for both IA-32 and Itanium®-based\r
+  systems.\r
 \r
   Copyright (c) 2007, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r
index c6cdf60..592f564 100644 (file)
@@ -1,6 +1,9 @@
 /** @file\r
   This file declares Smm Gpi Smi Child Protocol\r
-\r
+  The EFI_SMM_GPI_DISPATCH_PROTOCOL provides the ability to install child handlers for the\r
+  given event types. Several inputs can be enabled. This purpose of this interface is to generate an\r
+  SMI in response to any of these inputs having a true value provided.\r
+  \r
   Copyright (c) 2007, 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
index 49c5b8b..3e90688 100644 (file)
@@ -1,5 +1,7 @@
 /** @file\r
-  This file declares EFI Smm ICH [N] Specific Smi Child Protocol\r
+  Provides the parent dispatch service for a given SMI source generator.\r
+  The EFI_SMM_ICHN_DISPATCH_PROTOCOL provides the ability to install child handlers for\r
+  the given event types.\r
 \r
   Copyright (c) 2008, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r
index dbc05ed..653e2a8 100644 (file)
@@ -1,5 +1,5 @@
 /** @file\r
-  This file declares EFI Smm Periodic Timer Smi Child Protocol\r
+  Provides the parent dispatch service for the periodical timer SMI source generator.\r
 \r
   Copyright (c) 2007, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r
index 01b87c3..59553b6 100644 (file)
@@ -1,5 +1,5 @@
 /** @file\r
-  This file declares EFI Smm Power Button Smi Child Protocol\r
+  Provides the parent dispatch service for the power button SMI source generator.\r
 \r
   Copyright (c) 2007, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r
index 3770154..e319ee2 100644 (file)
@@ -1,5 +1,5 @@
 /** @file\r
-  This file declares EFI Smm Standby Button Smi Child Protocol\r
+  Provides the parent dispatch service for the standby button SMI source generator.\r
 \r
   Copyright (c) 2007, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r
index cb82a3c..2c10c20 100644 (file)
@@ -1,5 +1,5 @@
 /** @file\r
-  This file declares EFI Smm Software Smi Child Protocol\r
+  Provides the parent dispatch service for a given SMI source generator.\r
 \r
   Copyright (c) 2007, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r
index 66f0594..c6c0c18 100644 (file)
@@ -1,5 +1,5 @@
 /** @file\r
-  This file declares EFI Smm Sx Smi Child Protocol\r
+  Provides the parent dispatch service for a given Sx-state source generator.\r
 \r
   Copyright (c) 2007, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r
index 741b0a1..79dc3ef 100644 (file)
@@ -1,5 +1,5 @@
 /** @file\r
-  This file declares EFI Smm USB Smi Child Protocol.\r
+  Provides the parent dispatch service for the USB SMI source generator.\r
 \r
   Copyright (c) 2007, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r