]> git.proxmox.com Git - mirror_edk2.git/blobdiff - IntelFrameworkModulePkg/Include/Protocol/IsaIo.h
Update comments for IsaAcpi.h, IsaIo.h, and VgaMiniPort.h
[mirror_edk2.git] / IntelFrameworkModulePkg / Include / Protocol / IsaIo.h
index 9a2822937f5622b848e89fb1bd1102d981f7a7af..63999b0dc6d4c3465d86747067095c18fb49ade6 100644 (file)
 /** @file\r
-  ISA I/O Protocol is used to perform ISA device Io/Mem operations.\r
-\r
-Copyright (c) 2006 - 2009, 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
-which accompanies this distribution.  The full text of the license may be found at        \r
-http://opensource.org/licenses/bsd-license.php                                            \r
-                                                                                          \r
-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
+  ISA I/O Protocol is used by ISA device drivers to perform I/O, MMIO and DMA \r
+  operations on the ISA controllers they manage.\r
+  \r
+  Copyright (c) 2006 - 2009, 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
+  which accompanies this distribution.  The full text of the license may be found at\r
+  http://opensource.org/licenses/bsd-license.php\r
+\r
+  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
 **/\r
 \r
 #ifndef _EFI_ISA_IO_H_\r
 #define _EFI_ISA_IO_H_\r
 \r
-\r
 #include <Protocol/IsaAcpi.h>\r
 \r
-//\r
-// Global GUID for the ISA I/O Protocol\r
-//\r
+///\r
+/// Global ID for the EFI_ISA_IO_PROTOCOL\r
+///\r
 #define EFI_ISA_IO_PROTOCOL_GUID \\r
-  { 0x7ee2bd44, 0x3da0, 0x11d4, { 0x9a, 0x38, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d } }\r
+  { \\r
+    0x7ee2bd44, 0x3da0, 0x11d4, { 0x9a, 0x38, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \\r
+  }\r
 \r
+///\r
+/// Forward declaration for the EFI_ISA_IO_PROTOCOL\r
+///\r
 typedef struct _EFI_ISA_IO_PROTOCOL EFI_ISA_IO_PROTOCOL;\r
 \r
-//\r
-// Width of ISA Io/Mem operation\r
-//\r
+///\r
+/// Width of EFI_ISA_IO_PROTOCOL I/O Port and MMIO operations\r
+///\r
 typedef enum {\r
-  EfiIsaIoWidthUint8,\r
-  EfiIsaIoWidthUint16,\r
-  EfiIsaIoWidthUint32,\r
+  EfiIsaIoWidthUint8 = 0,      ///< 8-bit operation\r
+  EfiIsaIoWidthUint16,         ///< 16-bit operation\r
+  EfiIsaIoWidthUint32,         ///< 32-bit operation\r
   EfiIsaIoWidthReserved,\r
-  EfiIsaIoWidthFifoUint8,\r
-  EfiIsaIoWidthFifoUint16,\r
-  EfiIsaIoWidthFifoUint32,\r
+  EfiIsaIoWidthFifoUint8,      ///< 8-bit FIFO operation\r
+  EfiIsaIoWidthFifoUint16,     ///< 16-bit FIFO operation\r
+  EfiIsaIoWidthFifoUint32,     ///< 32-bit FIFO operation\r
   EfiIsaIoWidthFifoReserved,\r
-  EfiIsaIoWidthFillUint8,\r
-  EfiIsaIoWidthFillUint16,\r
-  EfiIsaIoWidthFillUint32,\r
+  EfiIsaIoWidthFillUint8,      ///< 8-bit Fill operation\r
+  EfiIsaIoWidthFillUint16,     ///< 16-bit Fill operation\r
+  EfiIsaIoWidthFillUint32,     ///< 32-bit Fill operation\r
   EfiIsaIoWidthFillReserved,\r
   EfiIsaIoWidthMaximum\r
 } EFI_ISA_IO_PROTOCOL_WIDTH;\r
 \r
-//\r
-// Attributes for common buffer allocations\r
-//\r
+///\r
+/// Attributes for the EFI_ISA_IO_PROTOCOL common DMA buffer allocations\r
+///\r
 #define EFI_ISA_IO_ATTRIBUTE_MEMORY_WRITE_COMBINE  0x080    ///< Map a memory range so write are combined\r
 #define EFI_ISA_IO_ATTRIBUTE_MEMORY_CACHED         0x800    ///< Map a memory range so all r/w accesses are cached\r
 #define EFI_ISA_IO_ATTRIBUTE_MEMORY_DISABLE        0x1000   ///< Disable a memory range \r
 \r
-//\r
-// Channel attribute for DMA operations\r
-//\r
-#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_COMPATIBLE  0x001\r
-#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_A           0x002\r
-#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_B           0x004\r
-#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_C           0x008\r
-#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_WIDTH_8           0x010\r
-#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_WIDTH_16          0x020\r
-#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SINGLE_MODE       0x040\r
-#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_DEMAND_MODE       0x080\r
-#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_AUTO_INITIALIZE   0x100\r
-\r
+///\r
+/// Channel attribute for EFI_ISA_IO_PROTOCOL slave DMA requests\r
+///\r
+#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_COMPATIBLE  0x001   ///< Set the speed of the DMA transfer in compatible mode\r
+#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_A           0x002   ///< Not supported\r
+#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_B           0x004   ///< Not supported\r
+#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_C           0x008   ///< Not supported\r
+#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_WIDTH_8           0x010   ///< Request 8-bit DMA transfers.  Only available on channels 0..3\r
+#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_WIDTH_16          0x020   ///< Request 16-bit DMA transfers.  Only available on channels 4..7\r
+#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SINGLE_MODE       0x040   ///< Request a single DMA transfer\r
+#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_DEMAND_MODE       0x080   ///< Request multiple DMA transfers until TC(Terminal Count) or EOP(End of Process)\r
+#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_AUTO_INITIALIZE   0x100   ///< Automatically reload base and count at the end of the DMA transfer\r
+\r
+///\r
+/// The DMA opreration type for EFI_ISA_IO_PROTOCOL DMA requests\r
+///\r
 typedef enum {\r
+  ///\r
+  /// A read operation from system memory by a bus master.\r
+  ///\r
   EfiIsaIoOperationBusMasterRead,\r
+  ///\r
+  /// A write operation to system memory by a bus master.\r
+  ///\r
   EfiIsaIoOperationBusMasterWrite,\r
+  ///\r
+  /// Provides both read and write access to system memory by both the processor\r
+  /// and a bus master. The buffer is coherent from both the processor's and the \r
+  /// bus master's point of view.\r
+  ///\r
   EfiIsaIoOperationBusMasterCommonBuffer,\r
+  ///\r
+  /// A read operation from system memory by a slave device.\r
+  ///\r
   EfiIsaIoOperationSlaveRead,\r
+  ///\r
+  /// A write operation to system memory by a slave master.\r
+  ///\r
   EfiIsaIoOperationSlaveWrite,\r
   EfiIsaIoOperationMaximum\r
 } EFI_ISA_IO_PROTOCOL_OPERATION;\r
 \r
 /**\r
-  Performs an ISA Io/Memory Read/Write Cycle\r
-\r
-  @param This                    A pointer to the EFI_ISA_IO_PROTOCOL instance.  \r
-  @param Width                   Signifies the width of the Io/Memory operation.\r
-  @param Offset                  The offset in ISA Io/Memory space to start the Io/Memory operation.  \r
-  @param Count                   The number of Io/Memory operations to perform.\r
-  @param Buffer                  [OUT] The destination buffer to store the results.\r
-                                 [IN] The source buffer to write data to the device.\r
-\r
+  Performs ISA I/O and MMIO Read/Write Cycles\r
+\r
+  @param[in]      This     A pointer to the EFI_ISA_IO_PROTOCOL instance.  \r
+  @param[in]      Width    Specifies the width of the I/O or MMIO operation.\r
+  @param[in]      Offset   The offset into the ISA I/O or MMIO space to start the \r
+                           operation.  \r
+  @param[in]      Count    The number of I/O or MMIO operations to perform.\r
+  @param[in, out] Buffer   For read operations, the destination buffer to store \r
+                           the results. For write operations, the source buffer to \r
+                           write data from. \r
+                                 \r
   @retval EFI_SUCCESS             The data was read from / written to the device sucessfully.\r
   @retval EFI_UNSUPPORTED         The Offset is not valid for this device.\r
   @retval EFI_INVALID_PARAMETER   Width or Count, or both, were invalid.\r
@@ -92,27 +119,37 @@ typedef enum {
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_ISA_IO_PROTOCOL_IO_MEM) (\r
-  IN     EFI_ISA_IO_PROTOCOL          *This,\r
-  IN     EFI_ISA_IO_PROTOCOL_WIDTH    Width,\r
-  IN     UINT32                       Offset,\r
-  IN     UINTN                        Count,\r
-  IN OUT VOID                         *Buffer\r
+(EFIAPI *EFI_ISA_IO_PROTOCOL_IO_MEM)(\r
+  IN     EFI_ISA_IO_PROTOCOL        *This,\r
+  IN     EFI_ISA_IO_PROTOCOL_WIDTH  Width,\r
+  IN     UINT32                     Offset,\r
+  IN     UINTN                      Count,\r
+  IN OUT VOID                       *Buffer\r
   );\r
 \r
+///\r
+/// Structure of functions for accessing ISA I/O and MMIO space\r
+///\r
 typedef struct {\r
+  ///\r
+  /// Read from ISA I/O or MMIO space.\r
+  ///\r
   EFI_ISA_IO_PROTOCOL_IO_MEM  Read;\r
+  ///\r
+  /// Write to ISA I/O or MMIO space.\r
+  ///\r
   EFI_ISA_IO_PROTOCOL_IO_MEM  Write;\r
 } EFI_ISA_IO_PROTOCOL_ACCESS;\r
 \r
 /**\r
-  Performs an ISA I/O Copy Memory \r
+  Copies data from one region of ISA MMIO space to another region of ISA\r
+  MMIO space.\r
 \r
-  @param This                    A pointer to the EFI_ISA_IO_PROTOCOL instance.\r
-  @param Width                   Signifies the width of the memory copy operation.\r
-  @param DestOffset              The offset of the destination \r
-  @param SrcOffset               The offset of the source\r
-  @param Count                   The number of memory copy  operations to perform\r
+  @param[in] This         A pointer to the EFI_ISA_IO_PROTOCOL instance.\r
+  @param[in] Width        Specifies the width of the MMIO copy operation.\r
+  @param[in] DestOffset   The offset of the destination in ISA MMIO space\r
+  @param[in] SrcOffset    The offset of the source in ISA MMIO space\r
+  @param[in] Count        The number tranfers to perform for this copy operation\r
 \r
   @retval EFI_SUCCESS             The data was copied sucessfully.\r
   @retval EFI_UNSUPPORTED         The DestOffset or SrcOffset is not valid for this device.\r
@@ -122,35 +159,63 @@ typedef struct {
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_ISA_IO_PROTOCOL_COPY_MEM) (\r
-  IN     EFI_ISA_IO_PROTOCOL          *This,\r
-  IN     EFI_ISA_IO_PROTOCOL_WIDTH    Width,\r
-  IN     UINT32                       DestOffset,\r
-  IN     UINT32                       SrcOffset,\r
-  IN     UINTN                        Count\r
+(EFIAPI *EFI_ISA_IO_PROTOCOL_COPY_MEM)(\r
+  IN EFI_ISA_IO_PROTOCOL         *This,\r
+  IN EFI_ISA_IO_PROTOCOL_WIDTH   Width,\r
+  IN UINT32                      DestOffset,\r
+  IN UINT32                      SrcOffset,\r
+  IN UINTN                       Count\r
   );\r
 \r
 /**\r
-  Maps a memory region for DMA\r
-\r
-  @param This                    A pointer to the EFI_ISA_IO_PROTOCOL instance.\r
-  @param Operation               Indicates the type of DMA (slave or bus master), and if \r
-                                 the DMA operation is going to read or write to system memory. \r
-  @param ChannelNumber           The slave channel number to use for this DMA operation. \r
-                                 If Operation and ChannelAttributes shows that this device \r
-                                 performs bus mastering DMA, then this field is ignored.  \r
-                                 The legal range for this field is 0..7.  \r
-  @param ChannelAttributes       The attributes of the DMA channel to use for this DMA operation\r
-  @param HostAddress             The system memory address to map to the device.  \r
-  @param NumberOfBytes           On input the number of bytes to map.  On output the number \r
-                                 of bytes that were mapped.\r
-  @param DeviceAddress           The resulting map address for the bus master device to use \r
-                                 to access the hosts HostAddress.  \r
-  @param Mapping                 A resulting value to pass to EFI_ISA_IO.Unmap().\r
-\r
+  Maps a memory region for DMA.\r
+\r
+  This function returns the device specific addresses required to access system memory.\r
+  This function is used to map system memory for ISA DMA operations.  All ISA DMA \r
+  operations must be performed through their mapped addresses and such mappings must \r
+  be freed with EFI_ISA_IO_PROTOCOL.Unmap() after the DMA operation is completed.  \r
+  If the DMA operation is a single read or write data transfer through an ISA bus \r
+  master, then EfiIsaIoOperationBusMasterRead or EfiIsaIoOperationBusMasterWrite \r
+  is used and the range is unmapped to complete the operation. If the DMA operation\r
+  is a single read or write data transfer through an ISA slave controller, then \r
+  EfiIsaIoOperationSlaveRead or EfiIsaIoOperationSlaveWrite is used and the range \r
+  is unmapped to complete the operation.  If performing a DMA read operation, all \r
+  the data must be present in system memory before the Map() is performed.  Similarly, \r
+  if performing a DMA write operation, the data must not be accessed in system \r
+  memory until EFI_ISA_IO_PROTOCOL.Unmap() is performed.  Bus master operations that \r
+  require both read and write access or require multiple host device interactions \r
+  within the same mapped region must use EfiIsaIoOperationBusMasterCommonBuffer.  \r
+  However, only memory allocated via the EFI_ISA_IO_PROTOCOL.AllocateBuffer() interface \r
+  are guaranteed to be able to be mapped for this operation type.  In all mapping \r
+  requests the NumberOfBytes returned may be less than originally requested.  It is\r
+  the caller's responsibility to make additional requests to complete the entire\r
+  transfer.\r
+\r
+  @param[in]      This                A pointer to the EFI_ISA_IO_PROTOCOL instance.\r
+  @param[in]      Operation           Indicates the type of DMA (slave or bus master), \r
+                                      and if the DMA operation is going to read or \r
+                                      write to system memory. \r
+  @param[in]      ChannelNumber       The slave channel number to use for this DMA \r
+                                      operation.  If Operation and ChannelAttributes \r
+                                      shows that this device performs bus mastering \r
+                                      DMA, then this field is ignored.  The legal \r
+                                      range for this field is 0..7.\r
+  @param[in]      ChannelAttributes   A bitmask of the attributes used to configure\r
+                                      the slave DMA channel for this DMA operation.  \r
+                                      See EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_* for the\r
+                                      legal bit combinations.\r
+  @param[in]      HostAddress         The system memory address to map to the device.\r
+  @param[in, out] NumberOfBytes       On input the number of bytes to map.  On \r
+                                      output the number of bytes that were mapped.\r
+  @param[out]     DeviceAddress       The resulting map address for the bus master \r
+                                      device to use to access the hosts HostAddress.  \r
+  @param[out]     Mapping             A returned value that must be passed to into\r
+                                      EFI_ISA_IO_PROTOCOL.Unmap() to free all the the \r
+                                      resources associated with this map request.\r
 \r
   @retval EFI_SUCCESS             The range was mapped for the returned NumberOfBytes.\r
-  @retval EFI_INVALID_PARAMETER   The Operation or HostAddress is undefined.\r
+  @retval EFI_INVALID_PARAMETER   The Operation is undefined.\r
+  @retval EFI_INVALID_PARAMETER   The HostAddress is undefined.\r
   @retval EFI_UNSUPPORTED         The HostAddress can not be mapped as a common buffer.\r
   @retval EFI_DEVICE_ERROR        The system hardware could not map the requested address.\r
   @retval EFI_OUT_OF_RESOURCES    The memory pages could not be allocated.\r
@@ -158,7 +223,7 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_ISA_IO_PROTOCOL_MAP) (\r
+(EFIAPI *EFI_ISA_IO_PROTOCOL_MAP)(\r
   IN     EFI_ISA_IO_PROTOCOL            *This,\r
   IN     EFI_ISA_IO_PROTOCOL_OPERATION  Operation,\r
   IN     UINT8                          ChannelNumber      OPTIONAL,\r
@@ -170,56 +235,64 @@ EFI_STATUS
   );\r
 \r
 /**\r
-  Unmaps a memory region for DMA\r
+  Unmaps a memory region that was previously mapped with EFI_ISA_IO_PROTOCOL.Map()\r
 \r
-  @param This               A pointer to the EFI_ISA_IO_PROTOCOL instance.\r
-  @param Mapping            The mapping value returned from EFI_ISA_IO.Map().\r
+  The EFI_ISA_IO_PROTOCOL.Map() operation is completed and any corresponding \r
+  resources are released.  If the operation was EfiIsaIoOperationSlaveWrite \r
+  or EfiIsaIoOperationBusMasterWrite, the data is committed to system memory.  \r
+  Any resources used for the mapping are freed.\r
 \r
-  @retval EFI_SUCCESS        The range was unmapped.\r
-  @retval EFI_DEVICE_ERROR   The data was not committed to the target system memory.\r
+  @param[in] This           A pointer to the EFI_ISA_IO_PROTOCOL instance.\r
+  @param[in] Mapping        The mapping value returned from EFI_ISA_IO_PROTOCOL.Map().\r
 \r
+  @retval EFI_SUCCESS       The memory region was unmapped.\r
+  @retval EFI_DEVICE_ERROR  The data was not committed to the target system memory.\r
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_ISA_IO_PROTOCOL_UNMAP) (\r
-  IN  EFI_ISA_IO_PROTOCOL          *This,\r
-  IN  VOID                         *Mapping\r
+(EFIAPI *EFI_ISA_IO_PROTOCOL_UNMAP)(\r
+  IN  EFI_ISA_IO_PROTOCOL  *This,\r
+  IN  VOID                 *Mapping\r
   );\r
 \r
 /**\r
-  Allocates a common buffer for DMA\r
+  Allocates pages that are suitable for an EfiIsaIoOperationBusMasterCommonBuffer\r
+  mapping.                                                                       \r
 \r
-  @param This                    A pointer to the EFI_ISA_IO_PROTOCOL instance.\r
-  @param Type                    The type allocation to perform.\r
-  @param MemoryType              The type of memory to allocate.\r
-  @param Pages                   The number of pages to allocate.\r
-  @param HostAddress             A pointer to store the base address of the allocated range.\r
-  @param Attributes              The requested bit mask of attributes for the allocated range.\r
+  @param[in]  This          A pointer to the EFI_ISA_IO_PROTOCOL instance.\r
+  @param[in]  Type          The type allocation to perform. \r
+  @param[in]  MemoryType    The type of memory to allocate.\r
+  @param[in]  Pages         The number of pages to allocate.\r
+  @param[out] HostAddress   A pointer to store the base address of the allocated range.\r
+  @param[in]  Attributes    The requested bit mask of attributes for the allocated range.\r
 \r
   @retval EFI_SUCCESS             The requested memory pages were allocated.\r
-  @retval EFI_INVALID_PARAMETER   Type is invalid or MemoryType is invalid or HostAddress is NULL\r
-  @retval EFI_UNSUPPORTED         Attributes is unsupported or the memory range specified \r
-                                  by HostAddress, Pages, and Type is not available for common buffer use.\r
+  @retval EFI_INVALID_PARAMETER   Type is invalid.\r
+  @retval EFI_INVALID_PARAMETER   MemoryType is invalid\r
+  @retval EFI_INVALID_PARAMETER   HostAddress is NULL\r
+  @retval EFI_UNSUPPORTED         Attributes is unsupported.\r
+  @retval EFI_UNSUPPORTED         The memory range specified by HostAddress, Pages,\r
+                                  and Type is not available for common buffer use.\r
   @retval EFI_OUT_OF_RESOURCES    The memory pages could not be allocated.\r
 \r
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_ISA_IO_PROTOCOL_ALLOCATE_BUFFER) (\r
-  IN  EFI_ISA_IO_PROTOCOL          *This,\r
-  IN  EFI_ALLOCATE_TYPE            Type,\r
-  IN  EFI_MEMORY_TYPE              MemoryType,\r
-  IN  UINTN                        Pages,\r
-  OUT VOID                         **HostAddress,\r
-  IN  UINT64                       Attributes\r
+(EFIAPI *EFI_ISA_IO_PROTOCOL_ALLOCATE_BUFFER)(\r
+  IN  EFI_ISA_IO_PROTOCOL  *This,\r
+  IN  EFI_ALLOCATE_TYPE    Type,\r
+  IN  EFI_MEMORY_TYPE      MemoryType,\r
+  IN  UINTN                Pages,\r
+  OUT VOID                 **HostAddress,\r
+  IN  UINT64               Attributes\r
   );\r
 \r
 /**\r
-  Frees a common buffer \r
+  Frees a common buffer that was allocated with EFI_ISA_IO_PROTOCOL.AllocateBuffer()\r
 \r
-  @param This                    A pointer to the EFI_ISA_IO_PROTOCOL instance.\r
-  @param Pages                   The number of pages to free.\r
-  @param HostAddress             The base address of the allocated range.\r
+  @param[in] This          A pointer to the EFI_ISA_IO_PROTOCOL instance.\r
+  @param[in] Pages         The number of pages to free from the previously allocated common buffer.\r
+  @param[in] HostAddress   The base address of the previously allocated common buffer.\r
 \r
 \r
   @retval EFI_SUCCESS             The requested memory pages were freed.\r
@@ -228,30 +301,34 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_ISA_IO_PROTOCOL_FREE_BUFFER) (\r
-  IN  EFI_ISA_IO_PROTOCOL          *This,\r
-  IN  UINTN                        Pages,\r
-  IN  VOID                         *HostAddress\r
+(EFIAPI *EFI_ISA_IO_PROTOCOL_FREE_BUFFER)(\r
+  IN  EFI_ISA_IO_PROTOCOL  *This,\r
+  IN  UINTN                Pages,\r
+  IN  VOID                 *HostAddress\r
   );\r
 \r
 /**\r
-  Flushes a DMA buffer\r
+  Flushes a DMA buffer.  This forces all DMA posted write transactions to complete.\r
 \r
-  @param This                 A pointer to the EFI_ISA_IO_PROTOCOL instance.\r
+  @param[in] This   A pointer to the EFI_ISA_IO_PROTOCOL instance.\r
 \r
-  @retval  EFI_SUCCESS        The buffers were flushed.\r
+  @retval  EFI_SUCCESS        The DMA buffers were flushed.\r
   @retval  EFI_DEVICE_ERROR   The buffers were not flushed due to a hardware error.\r
 \r
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_ISA_IO_PROTOCOL_FLUSH) (\r
-  IN EFI_ISA_IO_PROTOCOL                  *This\r
+(EFIAPI *EFI_ISA_IO_PROTOCOL_FLUSH)(\r
+  IN EFI_ISA_IO_PROTOCOL  *This\r
   );\r
 \r
-//\r
-// Interface structure for the ISA I/O Protocol\r
-//\r
+///\r
+/// The EFI_ISA_IO_PROTOCOL provides the basic Memory, I/O, and DMA interfaces \r
+/// used to abstract accesses to ISA controllers.  There is one EFI_ISA_IO_PROTOCOL \r
+/// instance for each ISA controller on a ISA bus. A device driver that wishes \r
+/// to manage an ISA controller in a system will have to retrieve the \r
+/// ISA_PCI_IO_PROTOCOL instance that is associated with the ISA controller.\r
+///\r
 struct _EFI_ISA_IO_PROTOCOL {\r
   EFI_ISA_IO_PROTOCOL_ACCESS           Mem;\r
   EFI_ISA_IO_PROTOCOL_ACCESS           Io;\r
@@ -261,8 +338,20 @@ struct _EFI_ISA_IO_PROTOCOL {
   EFI_ISA_IO_PROTOCOL_ALLOCATE_BUFFER  AllocateBuffer;\r
   EFI_ISA_IO_PROTOCOL_FREE_BUFFER      FreeBuffer;\r
   EFI_ISA_IO_PROTOCOL_FLUSH            Flush;\r
+  ///\r
+  /// The list of I/O , MMIO, DMA, and Interrupt resources associated with the\r
+  /// ISA controller abstracted by this instance of the EFI_ISA_IO_PROTOCOL.\r
+  ///\r
   EFI_ISA_ACPI_RESOURCE_LIST           *ResourceList;\r
+  ///\r
+  /// The size, in bytes, of the ROM image.\r
+  ///\r
   UINT32                               RomSize;\r
+  ///\r
+  /// A pointer to the in memory copy of the ROM image. The ISA Bus Driver is responsible \r
+  /// for allocating memory for the ROM image, and copying the contents of the ROM to memory\r
+  /// during ISA Bus initialization.\r
+  /// \r
   VOID                                 *RomImage;\r
 };\r
 \r