From 8411f1c002faf9a16c28a643a1c8a32de904a7d7 Mon Sep 17 00:00:00 2001 From: klu2 Date: Tue, 8 Apr 2008 07:40:30 +0000 Subject: [PATCH] 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 | 2 +- IntelFrameworkPkg/Include/Protocol/CpuIo.h | 3 ++- .../Include/Protocol/FirmwareVolume.h | 8 ++++--- .../Include/Protocol/IdeControllerInit.h | 8 +++++++ .../Protocol/IncompatiblePciDeviceSupport.h | 14 +++++++++++++ .../Include/Protocol/LegacyInterrupt.h | 4 +--- .../PciHostBridgeResourceAllocation.h | 8 +++---- .../Include/Protocol/PciHotPlugInit.h | 2 ++ .../Include/Protocol/PciPlatform.h | 9 ++++---- .../Include/Protocol/SmmAccess.h | 9 +++++--- IntelFrameworkPkg/Include/Protocol/SmmBase.h | 21 +++++++++++++++++-- .../Include/Protocol/SmmControl.h | 8 +++++++ .../Include/Protocol/SmmGpiDispatch.h | 5 ++++- .../Include/Protocol/SmmIchnDispatch.h | 4 +++- .../Protocol/SmmPeriodicTimerDispatch.h | 2 +- .../Include/Protocol/SmmPowerButtonDispatch.h | 2 +- .../Protocol/SmmStandbyButtonDispatch.h | 2 +- .../Include/Protocol/SmmSwDispatch.h | 2 +- .../Include/Protocol/SmmSxDispatch.h | 2 +- .../Include/Protocol/SmmUsbDispatch.h | 2 +- 20 files changed, 88 insertions(+), 29 deletions(-) diff --git a/IntelFrameworkPkg/Include/FrameworkSmm.h b/IntelFrameworkPkg/Include/FrameworkSmm.h index ed69b2e853..31662cc1cb 100644 --- a/IntelFrameworkPkg/Include/FrameworkSmm.h +++ b/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. 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 -- 2.39.2