sravan/system76-edk2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update comments for IsaAcpi.h, IsaIo.h, and VgaMiniPort.h

Browse Source 
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8728 6f19259b-4bc3-4df7-8a09-765794883524
This commit is contained in:
mdkinney
2009-07-03 00:37:42 +00:00
parent 2e747cee12
commit 099fae5d83
3 changed files with 473 additions and 280 deletions
Download Patch File Download Diff File Expand all files Collapse all files

339
IntelFrameworkModulePkg/Include/Protocol/IsaIo.h
View File

@ -1,89 +1,116 @@
/** @file
ISA I/O Protocol is used to perform ISA device Io/Mem operations.
ISA I/O Protocol is used by ISA device drivers to perform I/O, MMIO and DMA
operations on the ISA controllers they manage.
Copyright (c) 2006 - 2009, 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
which accompanies this distribution. The full text of the license may be found at
http://opensource.org/licenses/bsd-license.php
Copyright (c) 2006 - 2009, 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
which accompanies this distribution. The full text of the license may be found at
http://opensource.org/licenses/bsd-license.php
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#ifndef _EFI_ISA_IO_H_
#define _EFI_ISA_IO_H_
#include <Protocol/IsaAcpi.h>
//
// Global GUID for the ISA I/O Protocol
//
///
/// Global ID for the EFI_ISA_IO_PROTOCOL
///
#define EFI_ISA_IO_PROTOCOL_GUID \
{ 0x7ee2bd44, 0x3da0, 0x11d4, { 0x9a, 0x38, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d } }
{ \
0x7ee2bd44, 0x3da0, 0x11d4, { 0x9a, 0x38, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \
}
///
/// Forward declaration for the EFI_ISA_IO_PROTOCOL
///
typedef struct _EFI_ISA_IO_PROTOCOL EFI_ISA_IO_PROTOCOL;
//
// Width of ISA Io/Mem operation
//
///
/// Width of EFI_ISA_IO_PROTOCOL I/O Port and MMIO operations
///
typedef enum {
EfiIsaIoWidthUint8,
EfiIsaIoWidthUint16,
EfiIsaIoWidthUint32,
EfiIsaIoWidthUint8 = 0, ///< 8-bit operation
EfiIsaIoWidthUint16, ///< 16-bit operation
EfiIsaIoWidthUint32, ///< 32-bit operation
EfiIsaIoWidthReserved,
EfiIsaIoWidthFifoUint8,
EfiIsaIoWidthFifoUint16,
EfiIsaIoWidthFifoUint32,
EfiIsaIoWidthFifoUint8, ///< 8-bit FIFO operation
EfiIsaIoWidthFifoUint16, ///< 16-bit FIFO operation
EfiIsaIoWidthFifoUint32, ///< 32-bit FIFO operation
EfiIsaIoWidthFifoReserved,
EfiIsaIoWidthFillUint8,
EfiIsaIoWidthFillUint16,
EfiIsaIoWidthFillUint32,
EfiIsaIoWidthFillUint8, ///< 8-bit Fill operation
EfiIsaIoWidthFillUint16, ///< 16-bit Fill operation
EfiIsaIoWidthFillUint32, ///< 32-bit Fill operation
EfiIsaIoWidthFillReserved,
EfiIsaIoWidthMaximum
} EFI_ISA_IO_PROTOCOL_WIDTH;
//
// Attributes for common buffer allocations
//
///
/// 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_DISABLE 0x1000 ///< Disable a memory range
//
// Channel attribute for DMA operations
//
#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_COMPATIBLE 0x001
#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_A 0x002
#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_B 0x004
#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_C 0x008
#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_WIDTH_8 0x010
#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_WIDTH_16 0x020
#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SINGLE_MODE 0x040
#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_DEMAND_MODE 0x080
#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_AUTO_INITIALIZE 0x100
///
/// Channel attribute for EFI_ISA_IO_PROTOCOL slave DMA requests
///
#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_COMPATIBLE 0x001 ///< Set the speed of the DMA transfer in compatible mode
#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_A 0x002 ///< Not supported
#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_B 0x004 ///< Not supported
#define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_C 0x008 ///< Not supported
#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_AUTO_INITIALIZE 0x100 ///< Automatically reload base and count at the end of the DMA transfer
///
/// The DMA opreration type for EFI_ISA_IO_PROTOCOL DMA requests
///
typedef enum {
///
/// A read operation from system memory by a bus master.
///
EfiIsaIoOperationBusMasterRead,
///
/// A write operation to system memory by a bus master.
///
EfiIsaIoOperationBusMasterWrite,
///
/// Provides both read and write access to system memory by both the processor
/// and a bus master. The buffer is coherent from both the processor's and the
/// bus master's point of view.
///
EfiIsaIoOperationBusMasterCommonBuffer,
///
/// A read operation from system memory by a slave device.
///
EfiIsaIoOperationSlaveRead,
///
/// A write operation to system memory by a slave master.
///
EfiIsaIoOperationSlaveWrite,
EfiIsaIoOperationMaximum
} EFI_ISA_IO_PROTOCOL_OPERATION;
/**
Performs an ISA Io/Memory Read/Write Cycle
@param This A pointer to the EFI_ISA_IO_PROTOCOL instance.
@param Width Signifies the width of the Io/Memory operation.
@param Offset The offset in ISA Io/Memory space to start the Io/Memory operation.
@param Count The number of Io/Memory operations to perform.
@param Buffer [OUT] The destination buffer to store the results.
[IN] The source buffer to write data to the device.
Performs ISA I/O and MMIO Read/Write Cycles
@param[in] This A pointer to the EFI_ISA_IO_PROTOCOL instance.
@param[in] Width Specifies the width of the I/O or MMIO operation.
@param[in] Offset The offset into the ISA I/O or MMIO space to start the
operation.
@param[in] Count The number of I/O or MMIO operations to perform.
@param[in, out] Buffer For read operations, the destination buffer to store
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_UNSUPPORTED The Offset is not valid for this device.
@retval EFI_INVALID_PARAMETER Width or Count, or both, were invalid.
@ -92,27 +119,37 @@ typedef enum {
**/
typedef
EFI_STATUS
(EFIAPI *EFI_ISA_IO_PROTOCOL_IO_MEM) (
IN EFI_ISA_IO_PROTOCOL *This,
IN EFI_ISA_IO_PROTOCOL_WIDTH Width,
IN UINT32 Offset,
IN UINTN Count,
IN OUT VOID *Buffer
(EFIAPI *EFI_ISA_IO_PROTOCOL_IO_MEM)(
IN EFI_ISA_IO_PROTOCOL *This,
IN EFI_ISA_IO_PROTOCOL_WIDTH Width,
IN UINT32 Offset,
IN UINTN Count,
IN OUT VOID *Buffer
);
///
/// Structure of functions for accessing ISA I/O and MMIO space
///
typedef struct {
///
/// Read from ISA I/O or MMIO space.
///
EFI_ISA_IO_PROTOCOL_IO_MEM Read;
///
/// Write to ISA I/O or MMIO space.
///
EFI_ISA_IO_PROTOCOL_IO_MEM Write;
} EFI_ISA_IO_PROTOCOL_ACCESS;
/**
Performs an ISA I/O Copy Memory
Copies data from one region of ISA MMIO space to another region of ISA
MMIO space.
@param This A pointer to the EFI_ISA_IO_PROTOCOL instance.
@param Width Signifies the width of the memory copy operation.
@param DestOffset The offset of the destination
@param SrcOffset The offset of the source
@param Count The number of memory copy operations to perform
@param[in] This A pointer to the EFI_ISA_IO_PROTOCOL instance.
@param[in] Width Specifies the width of the MMIO copy operation.
@param[in] DestOffset The offset of the destination in ISA MMIO space
@param[in] SrcOffset The offset of the source in ISA MMIO space
@param[in] Count The number tranfers to perform for this copy operation
@retval EFI_SUCCESS The data was copied sucessfully.
@retval EFI_UNSUPPORTED The DestOffset or SrcOffset is not valid for this device.
@ -122,35 +159,63 @@ typedef struct {
**/
typedef
EFI_STATUS
(EFIAPI *EFI_ISA_IO_PROTOCOL_COPY_MEM) (
IN EFI_ISA_IO_PROTOCOL *This,
IN EFI_ISA_IO_PROTOCOL_WIDTH Width,
IN UINT32 DestOffset,
IN UINT32 SrcOffset,
IN UINTN Count
(EFIAPI *EFI_ISA_IO_PROTOCOL_COPY_MEM)(
IN EFI_ISA_IO_PROTOCOL *This,
IN EFI_ISA_IO_PROTOCOL_WIDTH Width,
IN UINT32 DestOffset,
IN UINT32 SrcOffset,
IN UINTN Count
);
/**
Maps a memory region for DMA
Maps a memory region for DMA.
@param This A pointer to the EFI_ISA_IO_PROTOCOL instance.
@param Operation Indicates the type of DMA (slave or bus master), and if
the DMA operation is going to read or write to system memory.
@param ChannelNumber The slave channel number to use for this DMA operation.
If Operation and ChannelAttributes shows that this device
performs bus mastering DMA, then this field is ignored.
The legal range for this field is 0..7.
@param ChannelAttributes The attributes of the DMA channel to use for this DMA operation
@param HostAddress The system memory address to map to the device.
@param NumberOfBytes On input the number of bytes to map. On output the number
of bytes that were mapped.
@param DeviceAddress The resulting map address for the bus master device to use
to access the hosts HostAddress.
@param Mapping A resulting value to pass to EFI_ISA_IO.Unmap().
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.
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,
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
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.
@param[in] This A pointer to the EFI_ISA_IO_PROTOCOL instance.
@param[in] Operation Indicates the type of DMA (slave or bus master),
and if the DMA operation is going to read or
write to system memory.
@param[in] ChannelNumber The slave channel number to use for this DMA
operation. If Operation and ChannelAttributes
shows that this device performs bus mastering
DMA, then this field is ignored. The legal
range for this field is 0..7.
@param[in] ChannelAttributes A bitmask of the attributes used to configure
the slave DMA channel for this DMA operation.
See EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_* for the
legal bit combinations.
@param[in] HostAddress The system memory address to map to the device.
@param[in, out] NumberOfBytes On input the number of bytes to map. On
output the number of bytes that were mapped.
@param[out] DeviceAddress The resulting map address for the bus master
device to use to access the hosts HostAddress.
@param[out] Mapping A returned value that must be passed to into
EFI_ISA_IO_PROTOCOL.Unmap() to free all the the
resources associated with this map request.
@retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes.
@retval EFI_INVALID_PARAMETER The Operation or HostAddress is undefined.
@retval EFI_INVALID_PARAMETER The Operation is undefined.
@retval EFI_INVALID_PARAMETER The HostAddress is undefined.
@retval EFI_UNSUPPORTED The HostAddress can not be mapped as a common buffer.
@retval EFI_DEVICE_ERROR The system hardware could not map the requested address.
@retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
@ -158,7 +223,7 @@ EFI_STATUS
**/
typedef
EFI_STATUS
(EFIAPI *EFI_ISA_IO_PROTOCOL_MAP) (
(EFIAPI *EFI_ISA_IO_PROTOCOL_MAP)(
IN EFI_ISA_IO_PROTOCOL *This,
IN EFI_ISA_IO_PROTOCOL_OPERATION Operation,
IN UINT8 ChannelNumber OPTIONAL,
@ -170,56 +235,64 @@ EFI_STATUS
);
/**
Unmaps a memory region for DMA
Unmaps a memory region that was previously mapped with EFI_ISA_IO_PROTOCOL.Map()
@param This A pointer to the EFI_ISA_IO_PROTOCOL instance.
@param Mapping The mapping value returned from EFI_ISA_IO.Map().
The EFI_ISA_IO_PROTOCOL.Map() operation is completed and any corresponding
resources are released. If the operation was EfiIsaIoOperationSlaveWrite
or EfiIsaIoOperationBusMasterWrite, the data is committed to system memory.
Any resources used for the mapping are freed.
@retval EFI_SUCCESS The range was unmapped.
@retval EFI_DEVICE_ERROR The data was not committed to the target system memory.
@param[in] This A pointer to the EFI_ISA_IO_PROTOCOL instance.
@param[in] Mapping The mapping value returned from EFI_ISA_IO_PROTOCOL.Map().
@retval EFI_SUCCESS The memory region was unmapped.
@retval EFI_DEVICE_ERROR The data was not committed to the target system memory.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_ISA_IO_PROTOCOL_UNMAP) (
IN EFI_ISA_IO_PROTOCOL *This,
IN VOID *Mapping
(EFIAPI *EFI_ISA_IO_PROTOCOL_UNMAP)(
IN EFI_ISA_IO_PROTOCOL *This,
IN VOID *Mapping
);
/**
Allocates a common buffer for DMA
Allocates pages that are suitable for an EfiIsaIoOperationBusMasterCommonBuffer
mapping.
@param This A pointer to the EFI_ISA_IO_PROTOCOL instance.
@param Type The type allocation to perform.
@param MemoryType The type of memory to allocate.
@param Pages The number of pages to allocate.
@param HostAddress A pointer to store the base address of the allocated range.
@param Attributes The requested bit mask of attributes for the allocated range.
@param[in] This A pointer to the EFI_ISA_IO_PROTOCOL instance.
@param[in] Type The type allocation to perform.
@param[in] MemoryType The type of memory to allocate.
@param[in] Pages The number of pages to allocate.
@param[out] HostAddress A pointer to store the base address of the allocated range.
@param[in] Attributes The requested bit mask of attributes for the allocated range.
@retval EFI_SUCCESS The requested memory pages were allocated.
@retval EFI_INVALID_PARAMETER Type is invalid or MemoryType is invalid or HostAddress is NULL
@retval EFI_UNSUPPORTED Attributes is unsupported or the memory range specified
by HostAddress, Pages, and Type is not available for common buffer use.
@retval EFI_INVALID_PARAMETER Type is invalid.
@retval EFI_INVALID_PARAMETER MemoryType is invalid
@retval EFI_INVALID_PARAMETER HostAddress is NULL
@retval EFI_UNSUPPORTED Attributes is unsupported.
@retval EFI_UNSUPPORTED The memory range specified by HostAddress, Pages,
and Type is not available for common buffer use.
@retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_ISA_IO_PROTOCOL_ALLOCATE_BUFFER) (
IN EFI_ISA_IO_PROTOCOL *This,
IN EFI_ALLOCATE_TYPE Type,
IN EFI_MEMORY_TYPE MemoryType,
IN UINTN Pages,
OUT VOID **HostAddress,
IN UINT64 Attributes
(EFIAPI *EFI_ISA_IO_PROTOCOL_ALLOCATE_BUFFER)(
IN EFI_ISA_IO_PROTOCOL *This,
IN EFI_ALLOCATE_TYPE Type,
IN EFI_MEMORY_TYPE MemoryType,
IN UINTN Pages,
OUT VOID **HostAddress,
IN UINT64 Attributes
);
/**
Frees a common buffer
Frees a common buffer that was allocated with EFI_ISA_IO_PROTOCOL.AllocateBuffer()
@param This A pointer to the EFI_ISA_IO_PROTOCOL instance.
@param Pages The number of pages to free.
@param HostAddress The base address of the allocated range.
@param[in] This A pointer to the EFI_ISA_IO_PROTOCOL instance.
@param[in] Pages The number of pages to free from the previously allocated common buffer.
@param[in] HostAddress The base address of the previously allocated common buffer.
@retval EFI_SUCCESS The requested memory pages were freed.
@ -228,30 +301,34 @@ EFI_STATUS
**/
typedef
EFI_STATUS
(EFIAPI *EFI_ISA_IO_PROTOCOL_FREE_BUFFER) (
IN EFI_ISA_IO_PROTOCOL *This,
IN UINTN Pages,
IN VOID *HostAddress
(EFIAPI *EFI_ISA_IO_PROTOCOL_FREE_BUFFER)(
IN EFI_ISA_IO_PROTOCOL *This,
IN UINTN Pages,
IN VOID *HostAddress
);
/**
Flushes a DMA buffer
Flushes a DMA buffer. This forces all DMA posted write transactions to complete.
@param This A pointer to the EFI_ISA_IO_PROTOCOL instance.
@param[in] This A pointer to the EFI_ISA_IO_PROTOCOL instance.
@retval EFI_SUCCESS The buffers were flushed.
@retval EFI_SUCCESS The DMA buffers were flushed.
@retval EFI_DEVICE_ERROR The buffers were not flushed due to a hardware error.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_ISA_IO_PROTOCOL_FLUSH) (
IN EFI_ISA_IO_PROTOCOL *This
(EFIAPI *EFI_ISA_IO_PROTOCOL_FLUSH)(
IN EFI_ISA_IO_PROTOCOL *This
);
//
// Interface structure for the ISA I/O Protocol
//
///
/// The EFI_ISA_IO_PROTOCOL provides the basic Memory, I/O, and DMA interfaces
/// 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.
///
struct _EFI_ISA_IO_PROTOCOL {
EFI_ISA_IO_PROTOCOL_ACCESS Mem;
EFI_ISA_IO_PROTOCOL_ACCESS Io;
@ -261,8 +338,20 @@ struct _EFI_ISA_IO_PROTOCOL {
EFI_ISA_IO_PROTOCOL_ALLOCATE_BUFFER AllocateBuffer;
EFI_ISA_IO_PROTOCOL_FREE_BUFFER FreeBuffer;
EFI_ISA_IO_PROTOCOL_FLUSH Flush;
///
/// The list of I/O , MMIO, DMA, and Interrupt resources associated with the
/// ISA controller abstracted by this instance of the EFI_ISA_IO_PROTOCOL.
///
EFI_ISA_ACPI_RESOURCE_LIST *ResourceList;
///
/// The size, in bytes, of the ROM image.
///
UINT32 RomSize;
///
/// A pointer to the in memory copy of the ROM image. The ISA Bus Driver is responsible
/// for allocating memory for the ROM image, and copying the contents of the ROM to memory
/// during ISA Bus initialization.
///
VOID *RomImage;
};