IntelFrameworkModulePkg/Bus/Isa/IsaIoDxe/IsaIo.h

   1 /** @file
   2   The header file for EFI_ISA_IO protocol implementation.
   3
   4 Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef _ISA_IO_H_
  16 #define _ISA_IO_H_
  17
  18 #include "IsaDriver.h"
  19
  20 //
  21 // Bits definition of PcdIsaBusSupportedFeatures
  22 //
  23 #define PCD_ISA_BUS_SUPPORT_DMA                  BIT0
  24 #define PCD_ISA_BUS_ONLY_SUPPORT_SLAVE_DMA       BIT1
  25 #define PCD_ISA_BUS_SUPPORT_ISA_MEMORY           BIT2
  26
  27 //
  28 // ISA I/O Support Function Prototypes
  29 //
  30
  31 /**
  32   Verifies access to an ISA device
  33
  34   @param[in] IsaIoDevice         The ISA device to be verified.
  35   @param[in] Type                The Access type. The input must be either IsaAccessTypeMem or IsaAccessTypeIo.
  36   @param[in] Width               The width of the memory operation.
  37   @param[in] Count               The number of memory operations to perform.
  38   @param[in] Offset              The offset in ISA memory space to start the memory operation.
  39
  40   @retval EFI_SUCCESS            Verify success.
  41   @retval EFI_INVALID_PARAMETER  One of the parameters has an invalid value.
  42   @retval EFI_UNSUPPORTED        The device ont support the access type.
  43 **/
  44 EFI_STATUS
  45 IsaIoVerifyAccess (
  46   IN ISA_IO_DEVICE              *IsaIoDevice,
  47   IN ISA_ACCESS_TYPE            Type,
  48   IN EFI_ISA_IO_PROTOCOL_WIDTH  Width,
  49   IN UINTN                      Count,
  50   IN UINT32                     Offset
  51   );
  52
  53 /**
  54   Performs an ISA I/O Read Cycle
  55
  56   @param[in]  This              A pointer to the EFI_ISA_IO_PROTOCOL instance.
  57   @param[in]  Width             Specifies the width of the I/O operation.
  58   @param[in]  Offset            The offset in ISA I/O space to start the I/O operation.
  59   @param[in]  Count             The number of I/O operations to perform.
  60   @param[out] Buffer            The destination buffer to store the results
  61
  62   @retval EFI_SUCCESS           The data was read from the device sucessfully.
  63   @retval EFI_UNSUPPORTED       The Offset is not valid for this device.
  64   @retval EFI_INVALID_PARAMETER Width or Count, or both, were invalid.
  65   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
  66 **/
  67 EFI_STATUS
  68 EFIAPI
  69 IsaIoIoRead (
  70   IN  EFI_ISA_IO_PROTOCOL        *This,
  71   IN  EFI_ISA_IO_PROTOCOL_WIDTH  Width,
  72   IN  UINT32                     Offset,
  73   IN  UINTN                      Count,
  74   OUT VOID                       *Buffer
  75   );
  76
  77 /**
  78   Performs an ISA I/O Write Cycle
  79
  80   @param[in] This                A pointer to the EFI_ISA_IO_PROTOCOL instance.
  81   @param[in] Width               Specifies the width of the I/O operation.
  82   @param[in] Offset              The offset in ISA I/O space to start the I/O operation.
  83   @param[in] Count               The number of I/O operations to perform.
  84   @param[in] Buffer              The source buffer to write data from
  85
  86   @retval EFI_SUCCESS            The data was writen to the device sucessfully.
  87   @retval EFI_UNSUPPORTED        The Offset is not valid for this device.
  88   @retval EFI_INVALID_PARAMETER  Width or Count, or both, were invalid.
  89   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.
  90 **/
  91 EFI_STATUS
  92 EFIAPI
  93 IsaIoIoWrite (
  94   IN EFI_ISA_IO_PROTOCOL        *This,
  95   IN EFI_ISA_IO_PROTOCOL_WIDTH  Width,
  96   IN UINT32                     Offset,
  97   IN UINTN                      Count,
  98   IN VOID                       *Buffer
  99   );
 100
 101 /**
 102   Maps a memory region for DMA
 103
 104   @param This                    A pointer to the EFI_ISA_IO_PROTOCOL instance.
 105   @param Operation               Indicates the type of DMA (slave or bus master), and if
 106                                  the DMA operation is going to read or write to system memory.
 107   @param ChannelNumber           The slave channel number to use for this DMA operation.
 108                                  If Operation and ChannelAttributes shows that this device
 109                                  performs bus mastering DMA, then this field is ignored.
 110                                  The legal range for this field is 0..7.
 111   @param ChannelAttributes       The attributes of the DMA channel to use for this DMA operation
 112   @param HostAddress             The system memory address to map to the device.
 113   @param NumberOfBytes           On input the number of bytes to map.  On output the number
 114                                  of bytes that were mapped.
 115   @param DeviceAddress           The resulting map address for the bus master device to use
 116                                  to access the hosts HostAddress.
 117   @param Mapping                 A resulting value to pass to EFI_ISA_IO.Unmap().
 118
 119   @retval EFI_SUCCESS            The range was mapped for the returned NumberOfBytes.
 120   @retval EFI_INVALID_PARAMETER  The Operation or HostAddress is undefined.
 121   @retval EFI_UNSUPPORTED        The HostAddress can not be mapped as a common buffer.
 122   @retval EFI_DEVICE_ERROR       The system hardware could not map the requested address.
 123   @retval EFI_OUT_OF_RESOURCES   The memory pages could not be allocated.
 124 **/
 125 EFI_STATUS
 126 EFIAPI
 127 IsaIoMap (
 128   IN     EFI_ISA_IO_PROTOCOL            *This,
 129   IN     EFI_ISA_IO_PROTOCOL_OPERATION  Operation,
 130   IN     UINT8                          ChannelNumber  OPTIONAL,
 131   IN     UINT32                         ChannelAttributes,
 132   IN     VOID                           *HostAddress,
 133   IN OUT UINTN                          *NumberOfBytes,
 134   OUT    EFI_PHYSICAL_ADDRESS           *DeviceAddress,
 135   OUT    VOID                           **Mapping
 136   );
 137
 138 /**
 139   Unmaps a memory region for DMA
 140
 141   @param[in] This           A pointer to the EFI_ISA_IO_PROTOCOL instance.
 142   @param[in] Mapping        The mapping value returned from EFI_ISA_IO.Map().
 143
 144   @retval EFI_SUCCESS       The range was unmapped.
 145   @retval EFI_DEVICE_ERROR  The data was not committed to the target system memory.
 146 **/
 147 EFI_STATUS
 148 EFIAPI
 149 IsaIoUnmap (
 150   IN EFI_ISA_IO_PROTOCOL  *This,
 151   IN VOID                 *Mapping
 152   );
 153
 154 /**
 155   Flushes any posted write data to the system memory.
 156
 157   @param[in] This             A pointer to the EFI_ISA_IO_PROTOCOL instance.
 158
 159   @retval  EFI_SUCCESS        The buffers were flushed.
 160   @retval  EFI_DEVICE_ERROR   The buffers were not flushed due to a hardware error.
 161 **/
 162 EFI_STATUS
 163 EFIAPI
 164 IsaIoFlush (
 165   IN EFI_ISA_IO_PROTOCOL  *This
 166   );
 167
 168 /**
 169   Writes I/O operation base address and count number to a 8 bit I/O Port.
 170
 171   @param[in] This                A pointer to the EFI_ISA_IO_PROTOCOL instance.
 172   @param[in] AddrOffset          The address' offset.
 173   @param[in] PageOffset          The page's offest.
 174   @param[in] CountOffset         The count's offset.
 175   @param[in] BaseAddress         The base address.
 176   @param[in] Count               The number of I/O operations to perform.
 177
 178   @retval EFI_SUCCESS            Success.
 179   @retval EFI_INVALID_PARAMETER  Parameter is invalid.
 180   @retval EFI_UNSUPPORTED        The address range specified by these Offsets and Count is not valid.
 181   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.
 182 **/
 183 EFI_STATUS
 184 WriteDmaPort (
 185   IN EFI_ISA_IO_PROTOCOL  *This,
 186   IN UINT32               AddrOffset,
 187   IN UINT32               PageOffset,
 188   IN UINT32               CountOffset,
 189   IN UINT32               BaseAddress,
 190   IN UINT16               Count
 191   );
 192
 193 /**
 194   Writes an 8-bit I/O Port
 195
 196   @param[in] This                A pointer to the EFI_ISA_IO_PROTOCOL instance.
 197   @param[in] Offset              The offset in ISA IO space to start the IO operation.
 198   @param[in] Value               The data to write port.
 199
 200   @retval EFI_SUCCESS            Success.
 201   @retval EFI_INVALID_PARAMETER  Parameter is invalid.
 202   @retval EFI_UNSUPPORTED        The address range specified by Offset is not valid.
 203   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.
 204 **/
 205 EFI_STATUS
 206 WritePort (
 207   IN EFI_ISA_IO_PROTOCOL  *This,
 208   IN UINT32               Offset,
 209   IN UINT8                Value
 210   );
 211
 212 /**
 213   Performs an ISA Memory Read Cycle
 214
 215   @param[in]  This               A pointer to the EFI_ISA_IO_PROTOCOL instance.
 216   @param[in]  Width              Specifies the width of the memory operation.
 217   @param[in]  Offset             The offset in ISA memory space to start the memory operation.
 218   @param[in]  Count              The number of memory operations to perform.
 219   @param[out] Buffer             The destination buffer to store the results
 220
 221   @retval EFI_SUCCESS            The data was read from the device successfully.
 222   @retval EFI_UNSUPPORTED        The Offset is not valid for this device.
 223   @retval EFI_INVALID_PARAMETER  Width or Count, or both, were invalid.
 224   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.
 225 **/
 226 EFI_STATUS
 227 EFIAPI
 228 IsaIoMemRead (
 229   IN  EFI_ISA_IO_PROTOCOL        *This,
 230   IN  EFI_ISA_IO_PROTOCOL_WIDTH  Width,
 231   IN  UINT32                     Offset,
 232   IN  UINTN                      Count,
 233   OUT VOID                       *Buffer
 234   );
 235
 236
 237 /**
 238   Performs an ISA Memory Write Cycle
 239
 240   @param[in] This                A pointer to the EFI_ISA_IO_PROTOCOL instance.
 241   @param[in] Width               Specifies the width of the memory operation.
 242   @param[in] Offset              The offset in ISA memory space to start the memory operation.
 243   @param[in] Count               The number of memory operations to perform.
 244   @param[in] Buffer              The source buffer to write data from
 245
 246   @retval EFI_SUCCESS            The data was written to the device sucessfully.
 247   @retval EFI_UNSUPPORTED        The Offset is not valid for this device.
 248   @retval EFI_INVALID_PARAMETER  Width or Count, or both, were invalid.
 249   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.
 250 **/
 251 EFI_STATUS
 252 EFIAPI
 253 IsaIoMemWrite (
 254   IN EFI_ISA_IO_PROTOCOL        *This,
 255   IN EFI_ISA_IO_PROTOCOL_WIDTH  Width,
 256   IN UINT32                     Offset,
 257   IN UINTN                      Count,
 258   IN VOID                       *Buffer
 259   );
 260
 261 /**
 262   Copy one region of ISA memory space to another region of ISA memory space on the ISA controller.
 263
 264   @param[in]  This               A pointer to the EFI_ISA_IO_PROTOCOL instance.
 265   @param[in]  Width              Specifies the width of the memory copy operation.
 266   @param[in]  DestOffset         The offset of the destination
 267   @param[in]  SrcOffset          The offset of the source
 268   @param[in]  Count              The number of memory copy  operations to perform
 269
 270   @retval EFI_SUCCESS            The data was copied sucessfully.
 271   @retval EFI_UNSUPPORTED        The DestOffset or SrcOffset is not valid for this device.
 272   @retval EFI_INVALID_PARAMETER  Width or Count, or both, were invalid.
 273   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.
 274 **/
 275 EFI_STATUS
 276 EFIAPI
 277 IsaIoCopyMem (
 278   IN EFI_ISA_IO_PROTOCOL        *This,
 279   IN EFI_ISA_IO_PROTOCOL_WIDTH  Width,
 280   IN UINT32                     DestOffset,
 281   IN UINT32                     SrcOffset,
 282   IN UINTN                      Count
 283   );
 284
 285 /**
 286   Allocates pages that are suitable for an EfiIsaIoOperationBusMasterCommonBuffer mapping.
 287
 288   @param[in]  This               A pointer to the EFI_ISA_IO_PROTOCOL instance.
 289   @param[in]  Type               The type allocation to perform.
 290   @param[in]  MemoryType         The type of memory to allocate.
 291   @param[in]  Pages              The number of pages to allocate.
 292   @param[out] HostAddress        A pointer to store the base address of the allocated range.
 293   @param[in]  Attributes         The requested bit mask of attributes for the allocated range.
 294
 295   @retval EFI_SUCCESS            The requested memory pages were allocated.
 296   @retval EFI_INVALID_PARAMETER  Type is invalid or MemoryType is invalid or HostAddress is NULL
 297   @retval EFI_UNSUPPORTED        Attributes is unsupported or the memory range specified
 298                                  by HostAddress, Pages, and Type is not available for common buffer use.
 299   @retval EFI_OUT_OF_RESOURCES   The memory pages could not be allocated.
 300 **/
 301 EFI_STATUS
 302 EFIAPI
 303 IsaIoAllocateBuffer (
 304   IN  EFI_ISA_IO_PROTOCOL  *This,
 305   IN  EFI_ALLOCATE_TYPE    Type,
 306   IN  EFI_MEMORY_TYPE      MemoryType,
 307   IN  UINTN                Pages,
 308   OUT VOID                 **HostAddress,
 309   IN  UINT64               Attributes
 310   );
 311
 312 /**
 313   Frees memory that was allocated with EFI_ISA_IO.AllocateBuffer().
 314
 315   @param[in] This                A pointer to the EFI_ISA_IO_PROTOCOL instance.
 316   @param[in] Pages               The number of pages to free.
 317   @param[in] HostAddress         The base address of the allocated range.
 318
 319   @retval EFI_SUCCESS            The requested memory pages were freed.
 320   @retval EFI_INVALID_PARAMETER  The memory was not allocated with EFI_ISA_IO.AllocateBufer().
 321 **/
 322 EFI_STATUS
 323 EFIAPI
 324 IsaIoFreeBuffer (
 325   IN EFI_ISA_IO_PROTOCOL  *This,
 326   IN UINTN                Pages,
 327   IN VOID                 *HostAddress
 328   );
 329
 330 #endif
 331