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 ed69b2e853d1cf33b37e816793764fb92ef8cc26..31662cc1cb5c2327bb8dce10bef6300a07877533 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 f6c91df9bd590c6e3f64509c571efa1b30c6036e..e449354b392af84f25204c4e32e688ef7cad5de3 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 5f789e1099bd186e4c92b331dee3853df2e9e9e1..cd0484fc901ee7e08fb3ed24750907b6ebfd50cd 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 aef6a2ea269d49100f978f4fbb5341cd50577106..8192f51ee6f96b2543e3b184fc388af1494b8fd6 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 0c45fb7c2741646cda096374531f2ee4159e94cc..3e72539aba269a2ffa897ebeafdc2b08c9a1a8fe 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 0ebbc5143a01c24521332219ff633b7c11cfd453..f0c28bdab59702338f5939e34d0408f69ef0b2c4 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 33b4c34d45a1ff0f686b57bd0de6c5958e09cb35..92d7c5ac17b99b7f5158ef67aeef8fa3c5125e40 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 177245041ba33d3bff7a7394a7624a1f0cfca7d3..4f0b045693df49c6af55981a667495bc53d45077 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 2db71ebc14d337ffc431738cfc19204625f54e2a..d1044b6209bc55094734efb5827c7b2e38aa0f3a 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 df7a87ed8bc82efd337ddf921876975380081f8c..231247c0df0e4cdbc41a5aaafd9b4efd5e6a91fc 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 ab14f1c23b724487bb10cac139d8830805719ba1..97f0de6b2b0c7aeed5142922fa2cfc9b1a354d58 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 2dbf412ff71b1cd05237bc080666f16d88ce7ac1..3b326a1c786bbf3f773ab16f9d1f0da2362f2bfd 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 c6cdf608f52e5142887deca8b284202b723f6669..592f56430955c54d13d56ffd934e4d1fac6aa2a6 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 49c5b8b44ac932bcf781203a05422b90830b46f0..3e906888148676d7aef7b7e8a21c009b9061369e 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 dbc05ed4b8a72371b24a57d8d154af70ac2ab004..653e2a82a15cff67014f84571164b71ca94d94e4 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 01b87c33b5a91c9ee7c54fdb828b71e6e4605800..59553b6d5a4892605966d32b20ba5d9ad8f61c06 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 3770154ca40215e2ca517599142e079473cd0323..e319ee24c0e44da8c2d4337b257e9c7ecd7853ea 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 cb82a3c087048576a945aa5599d3bf9f3946cecb..2c10c2060bed5a75559d7f16b1e659f1d7cc8aff 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 66f059463ac16bebb11409bc2893bd85c59006d8..c6c0c1870e09d63d40eabed1071cd07fe4c95951 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 741b0a1a7e1a8c7712540cefe62ad945fcdb3169..79dc3efba7d26bd2dc617b2780991aa279dda623 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