From 7b6b7746627e106f5b1e05990d78c313f14c9081 Mon Sep 17 00:00:00 2001 From: pkandel Date: Thu, 9 Jul 2009 12:36:25 +0000 Subject: [PATCH] Committing changes to the comments, to improve code documentation. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8842 6f19259b-4bc3-4df7-8a09-765794883524 --- .../Include/Protocol/DiskInfo.h | 2 +- .../Include/Protocol/IsaAcpi.h | 33 +++++++++---------- .../Include/Protocol/IsaIo.h | 24 +++++++------- .../Include/Protocol/OEMBadging.h | 8 ++--- .../Include/Protocol/PciHotPlugRequest.h | 14 ++++---- 5 files changed, 39 insertions(+), 42 deletions(-) diff --git a/IntelFrameworkModulePkg/Include/Protocol/DiskInfo.h b/IntelFrameworkModulePkg/Include/Protocol/DiskInfo.h index 7f82a40aff..b6695e1655 100644 --- a/IntelFrameworkModulePkg/Include/Protocol/DiskInfo.h +++ b/IntelFrameworkModulePkg/Include/Protocol/DiskInfo.h @@ -37,7 +37,7 @@ typedef struct _EFI_DISK_INFO_PROTOCOL EFI_DISK_INFO_PROTOCOL; @retval EFI_SUCCESS The command was accepted without any errors. @retval EFI_NOT_FOUND Device does not support this data class @retval EFI_DEVICE_ERROR Error reading InquiryData from device - @retval EFI_BUFFER_TOO_SMALL IntquiryDataSize not big enough + @retval EFI_BUFFER_TOO_SMALL InquiryDataSize not big enough **/ typedef diff --git a/IntelFrameworkModulePkg/Include/Protocol/IsaAcpi.h b/IntelFrameworkModulePkg/Include/Protocol/IsaAcpi.h index 81e75f949e..819d5b499e 100644 --- a/IntelFrameworkModulePkg/Include/Protocol/IsaAcpi.h +++ b/IntelFrameworkModulePkg/Include/Protocol/IsaAcpi.h @@ -112,8 +112,8 @@ typedef struct { This service allows all the ISA controllers on an ISA bus to be enumerated. If Device is a pointer to a NULL value, then the first ISA controller on the ISA - bus is returned in Device and EFI_SUCESS is returned. If Device is a pointer - to value that was returned on a prior call to DeviceEnumerate(), then the next + bus is returned in Device and EFI_SUCCESS is returned. If Device is a pointer + to a value that was returned on a prior call to DeviceEnumerate(), then the next ISA controller on the ISA bus is returned in Device and EFI_SUCCESS is returned. If Device is a pointer to the last ISA controller on the ISA bus, then EFI_NOT_FOUND is returned. @@ -136,15 +136,13 @@ EFI_STATUS Sets the power state of an ISA controller. This services sets the power state of the ISA controller specified by Device to - the power state specified by OnOff. If OnOff is TRUE, then power is applied to - the ISA controller. If OnOff is FALSE, then power is remobed from the ISA - controller. If the power state is sucessfully set on the ISA Controller, then + the power state specified by OnOff. TRUE denotes on, FALSE denotes off. + If the power state is sucessfully set on the ISA Controller, then EFI_SUCCESS is returned. @param[in] This Pointer to the EFI_ISA_ACPI_PROTOCOL instance. @param[in] Device Pointer to an ISA controller named by ACPI HID/UID. - @param[in] OnOff TRUE to apply power to the ISA controller. FALSE to remove - power from the ISA controller. + @param[in] OnOff TRUE denotes on, FALSE denotes off. @retval EFI_SUCCESS Successfully set the power state of the ISA controller. @retval Other The ISA controller cound not be placed in the requested power state. @@ -159,7 +157,7 @@ EFI_STATUS ); /** - Retrieves the current set of resource associated with an ISA controller. + Retrieves the current set of resources associated with an ISA controller. Retrieves the set of I/O, MMIO, DMA, and interrupt resources currently assigned to the ISA controller specified by Device. These resources @@ -192,7 +190,7 @@ EFI_STATUS @param[in] Device Pointer to an ISA controller named by ACPI HID/UID. @param[out] ResourceList Pointer to the returned list of resource lists. - @retval EFI_UNSUPPORTED This services is not supported. + @retval EFI_UNSUPPORTED This service is not supported. **/ typedef @@ -207,8 +205,7 @@ EFI_STATUS Assigns resources to an ISA controller. Assigns the I/O, MMIO, DMA, and interrupt resources specified by ResourceList - to the ISA controller specified by Device. ResourceList must match on of the - possible resource lists returned by GetPosResource() for the same ISA controller. + to the ISA controller specified by Device. ResourceList must match a resource list returned by GetPosResource() for the same ISA controller. @param[in] This Pointer to the EFI_ISA_ACPI_PROTOCOL instance. @param[in] Device Pointer to an ISA controller named by ACPI HID/UID. @@ -249,7 +246,7 @@ EFI_STATUS ); /** - Places an ISA controller into a usable state. This service must be called + Initializes an ISA controller, so that it can be used. This service must be called before SetResource(), EnableDevice(), or SetPower() will behave as expected. @param[in] This Pointer to the EFI_ISA_ACPI_PROTOCOL instance. @@ -267,8 +264,8 @@ EFI_STATUS ); /** - Initializes all the HW state required for the ISA controlers on the ISA bus - to be enumerated and managed by this rest of the services in this prorotol. + Initializes all the HW states required for the ISA controllers on the ISA bus + to be enumerated and managed by the rest of the services in this prorotol. This service must be called before any of the other services in this protocol will function as expected. @@ -285,10 +282,10 @@ EFI_STATUS ); /// -/// The EFI_ISA_ACPI_PROTOCOL provides the services to enumberate and manage -/// ISA controllers on an ISA bus. This include the ability to initialize, -/// enable, disable, and manag the power state of ISA controllers. It also -/// includes services to query current ressources, query possible resources, +/// The EFI_ISA_ACPI_PROTOCOL provides the services to enumerate and manage +/// ISA controllers on an ISA bus. These services include the ability to initialize, +/// enable, disable, and manage the power state of ISA controllers. It also +/// includes services to query current resources, query possible resources, /// and assign resources to an ISA controller. /// struct _EFI_ISA_ACPI_PROTOCOL { diff --git a/IntelFrameworkModulePkg/Include/Protocol/IsaIo.h b/IntelFrameworkModulePkg/Include/Protocol/IsaIo.h index 63999b0dc6..395f295479 100644 --- a/IntelFrameworkModulePkg/Include/Protocol/IsaIo.h +++ b/IntelFrameworkModulePkg/Include/Protocol/IsaIo.h @@ -54,7 +54,7 @@ typedef enum { /// Attributes for the EFI_ISA_IO_PROTOCOL common DMA buffer allocations /// #define EFI_ISA_IO_ATTRIBUTE_MEMORY_WRITE_COMBINE 0x080 ///< Map a memory range so write are combined -#define EFI_ISA_IO_ATTRIBUTE_MEMORY_CACHED 0x800 ///< Map a memory range so all r/w accesses are cached +#define EFI_ISA_IO_ATTRIBUTE_MEMORY_CACHED 0x800 ///< Map a memory range so all read and write accesses are cached #define EFI_ISA_IO_ATTRIBUTE_MEMORY_DISABLE 0x1000 ///< Disable a memory range /// @@ -67,7 +67,7 @@ typedef enum { #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_WIDTH_8 0x010 ///< Request 8-bit DMA transfers. Only available on channels 0..3 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_WIDTH_16 0x020 ///< Request 16-bit DMA transfers. Only available on channels 4..7 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SINGLE_MODE 0x040 ///< Request a single DMA transfer -#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_DEMAND_MODE 0x080 ///< Request multiple DMA transfers until TC(Terminal Count) or EOP(End of Process) +#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_DEMAND_MODE 0x080 ///< Request multiple DMA transfers until TC (Terminal Count) or EOP (End of Process) #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_AUTO_INITIALIZE 0x100 ///< Automatically reload base and count at the end of the DMA transfer /// @@ -111,7 +111,7 @@ typedef enum { the results. For write operations, the source buffer to write data from. - @retval EFI_SUCCESS The data was read from / written to the device sucessfully. + @retval EFI_SUCCESS The data was successfully read from or written to the device. @retval EFI_UNSUPPORTED The Offset is not valid for this device. @retval EFI_INVALID_PARAMETER Width or Count, or both, were invalid. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @@ -170,23 +170,25 @@ EFI_STATUS /** Maps a memory region for DMA. - This function returns the device specific addresses required to access system memory. + This function returns the device-specific addresses required to access system memory. This function is used to map system memory for ISA DMA operations. All ISA DMA - operations must be performed through their mapped addresses and such mappings must - be freed with EFI_ISA_IO_PROTOCOL.Unmap() after the DMA operation is completed. + operations must be performed through their mapped addresses, and such mappings must + be freed with EFI_ISA_IO_PROTOCOL.Unmap() after the DMA operation is completed. + If the DMA operation is a single read or write data transfer through an ISA bus master, then EfiIsaIoOperationBusMasterRead or EfiIsaIoOperationBusMasterWrite is used and the range is unmapped to complete the operation. If the DMA operation is a single read or write data transfer through an ISA slave controller, then EfiIsaIoOperationSlaveRead or EfiIsaIoOperationSlaveWrite is used and the range - is unmapped to complete the operation. If performing a DMA read operation, all - the data must be present in system memory before the Map() is performed. Similarly, + is unmapped to complete the operation. + + If performing a DMA read operation, all the data must be present in system memory before the Map() is performed. Similarly, if performing a DMA write operation, the data must not be accessed in system memory until EFI_ISA_IO_PROTOCOL.Unmap() is performed. Bus master operations that require both read and write access or require multiple host device interactions within the same mapped region must use EfiIsaIoOperationBusMasterCommonBuffer. However, only memory allocated via the EFI_ISA_IO_PROTOCOL.AllocateBuffer() interface - are guaranteed to be able to be mapped for this operation type. In all mapping + is guaranteed to be able to be mapped for this operation type. In all mapping requests the NumberOfBytes returned may be less than originally requested. It is the caller's responsibility to make additional requests to complete the entire transfer. @@ -308,7 +310,7 @@ EFI_STATUS ); /** - Flushes a DMA buffer. This forces all DMA posted write transactions to complete. + Flushes a DMA buffer, which forces all DMA posted write transactions to complete. @param[in] This A pointer to the EFI_ISA_IO_PROTOCOL instance. @@ -327,7 +329,7 @@ EFI_STATUS /// used to abstract accesses to ISA controllers. There is one EFI_ISA_IO_PROTOCOL /// instance for each ISA controller on a ISA bus. A device driver that wishes /// to manage an ISA controller in a system will have to retrieve the -/// ISA_PCI_IO_PROTOCOL instance that is associated with the ISA controller. +/// ISA_PCI_IO_PROTOCOL instance associated with the ISA controller. /// struct _EFI_ISA_IO_PROTOCOL { EFI_ISA_IO_PROTOCOL_ACCESS Mem; diff --git a/IntelFrameworkModulePkg/Include/Protocol/OEMBadging.h b/IntelFrameworkModulePkg/Include/Protocol/OEMBadging.h index c274dab53c..a0d380878f 100644 --- a/IntelFrameworkModulePkg/Include/Protocol/OEMBadging.h +++ b/IntelFrameworkModulePkg/Include/Protocol/OEMBadging.h @@ -1,6 +1,6 @@ /** @file The OEM Badging Protocol defines the interface to get the OEM badging - image with the dispaly attribute. This protocol can be produced based on OEM badging images. + image with the display attribute. This protocol can be produced based on OEM badging images. Copyright (c) 2006 - 2008, Intel Corporation.
All rights reserved. This program and the accompanying materials @@ -48,11 +48,11 @@ typedef enum { /** - Load an OEM badge image and return its data as well as attributes. + Load an OEM badge image and return its data and attributes. @param This Pointer to this protocol instance. - @param Instance The visiable image instance is found. - @param Format Format of the image such as BMP,JPEG,etc. + @param Instance The visible image instance is found. + @param Format Format of the image. Examples: BMP, JPEG. @param ImageData Image data returned. @param ImageSize Size of the image returned. @param Attribute Display attributes of the image returned. diff --git a/IntelFrameworkModulePkg/Include/Protocol/PciHotPlugRequest.h b/IntelFrameworkModulePkg/Include/Protocol/PciHotPlugRequest.h index d4a36aea0e..40c13498e4 100644 --- a/IntelFrameworkModulePkg/Include/Protocol/PciHotPlugRequest.h +++ b/IntelFrameworkModulePkg/Include/Protocol/PciHotPlugRequest.h @@ -1,6 +1,6 @@ /** @file - Provides services to notify PCI bus driver that some events have happened in a hot-plug controller - (for example, PC Card socket, or PHPC), and ask PCI bus driver to create or destroy handles for the + Provides services to notify the PCI bus driver that some events have happened in a hot-plug controller + (such as a PC Card socket, or PHPC), and to ask the PCI bus driver to create or destroy handles for PCI-like devices. Copyright (c) 2006 - 2009, Intel Corporation @@ -25,7 +25,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. typedef enum { /// /// The PCI bus driver is requested to create handles for the specified devices. An array of - /// EFI_HANDLE is returned, a NULL element marks the end of the array. + /// EFI_HANDLE is returned, with a NULL element marking the end of the array. /// EfiPciHotPlugRequestAdd, @@ -38,18 +38,16 @@ typedef enum { typedef struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL EFI_PCI_HOTPLUG_REQUEST_PROTOCOL; /** - This function allows the PCI bus driver to be notified to act as requested when a hot-plug event has - happened on the hot-plug controller. Currently, the operations include add operation and remove operation. - + This function allows the PCI bus driver to be notified to act as requested when a hot-plug event has happened on the hot-plug controller. Currently, the operations include add operation and remove operation. @param This A pointer to the hot plug request protocol. @param Operation The operation the PCI bus driver is requested to make. @param Controller The handle of the hot-plug controller. @param RemainingDevicePath The remaining device path for the PCI-like hot-plug device. - @param NumberOfChildren The number of child handles. For a add operation, it is an output parameter. + @param NumberOfChildren The number of child handles. For an add operation, it is an output parameter. For a remove operation, it's an input parameter. When it contains a non-zero value, children handles specified in ChildHandleBuffer are destroyed. Otherwise, PCI bus driver is notified to stop managing the controller handle. - @param ChildHandleBuffer The buffer which contains the child handles. For a add operation, it is an output + @param ChildHandleBuffer The buffer which contains the child handles. For an add operation, it is an output parameter and contains all newly created child handles. For a remove operation, it contains child handles to be destroyed when NumberOfChildren contains a non- zero value. It can be NULL when NumberOfChildren is 0. It's the caller's -- 2.39.2