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