MdePkg/Include/Protocol/IsaHc.h

   1 /** @file
   2   ISA HC Protocol as defined in the PI 1.2.1 specification.
   3
   4   This protocol provides registration for ISA devices on a positive- or
   5   subtractive-decode ISA bus. It allows devices to be registered and also
   6   handles opening and closing the apertures which are positively-decoded.
   7
   8   Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR>
   9   SPDX-License-Identifier: BSD-2-Clause-Patent
  10
  11   @par Revision Reference:
  12   This protocol is from PI Version 1.2.1.
  13
  14 **/
  15
  16 #ifndef __ISA_HC_PROTOCOL_H__
  17 #define __ISA_HC_PROTOCOL_H__
  18
  19 #define EFI_ISA_HC_PROTOCOL_GUID \
  20   { \
  21     0xbcdaf080, 0x1bde, 0x4e22, {0xae, 0x6a, 0x43, 0x54, 0x1e, 0x12, 0x8e, 0xc4} \
  22   }
  23
  24 #define EFI_ISA_HC_SERVICE_BINDING_PROTOCOL_GUID \
  25   { \
  26     0xfad7933a, 0x6c21, 0x4234, {0xa4, 0x34, 0x0a, 0x8a, 0x0d, 0x2b, 0x07, 0x81} \
  27   }
  28
  29 typedef struct _EFI_ISA_HC_PROTOCOL EFI_ISA_HC_PROTOCOL;
  30 typedef struct _EFI_ISA_HC_PROTOCOL *PEFI_ISA_HC_PROTOCOL;
  31
  32 /**
  33   Open I/O aperture.
  34
  35   This function opens an I/O aperture in a ISA Host Controller for the I/O addresses
  36   specified by IoAddress to IoAddress + IoLength - 1. It may be possible that a
  37   single hardware aperture may be used for more than one device. This function
  38   tracks the number of times that each aperture is referenced, and does not close
  39   the hardware aperture (via CloseIoAperture()) until there are no more references to it.
  40
  41   @param This             A pointer to this instance of the EFI_ISA_HC_PROTOCOL.
  42   @param IoAddress        An unsigned integer that specifies the first byte of the
  43                           I/O space required.
  44   @param IoLength         An unsigned integer that specifies the number of bytes
  45                           of the I/O space required.
  46   @param IoApertureHandle A pointer to the returned I/O aperture handle. This
  47                           value can be used on subsequent calls to CloseIoAperture().
  48
  49   @retval EFI_SUCCESS          The I/O aperture was opened successfully.
  50   @retval EFI_UNSUPPORTED      The ISA Host Controller is a subtractive-decode controller.
  51   @retval EFI_OUT_OF_RESOURCES There is no available I/O aperture.
  52 **/
  53 typedef
  54 EFI_STATUS
  55 (EFIAPI *EFI_ISA_HC_OPEN_IO) (
  56   IN CONST EFI_ISA_HC_PROTOCOL  *This,
  57   IN UINT16                     IoAddress,
  58   IN UINT16                     IoLength,
  59   OUT UINT64                    *IoApertureHandle
  60   );
  61
  62 /**
  63   Close I/O aperture.
  64
  65   This function closes a previously opened I/O aperture handle. If there are no
  66   more I/O aperture handles that refer to the hardware I/O aperture resource,
  67   then the hardware I/O aperture is closed. It may be possible that a single
  68   hardware aperture may be used for more than one device. This function tracks
  69   the number of times that each aperture is referenced, and does not close the
  70   hardware aperture (via CloseIoAperture()) until there are no more references to it.
  71
  72   @param This             A pointer to this instance of the EFI_ISA_HC_PROTOCOL.
  73   @param IoApertureHandle The I/O aperture handle previously returned from a
  74                           call to OpenIoAperture().
  75
  76   @retval EFI_SUCCESS     The IO aperture was closed successfully.
  77 **/
  78 typedef
  79 EFI_STATUS
  80 (EFIAPI *EFI_ISA_HC_CLOSE_IO) (
  81   IN CONST EFI_ISA_HC_PROTOCOL      *This,
  82   IN UINT64                         IoApertureHandle
  83   );
  84
  85 ///
  86 /// ISA HC Protocol
  87 ///
  88 struct _EFI_ISA_HC_PROTOCOL {
  89   ///
  90   /// The version of this protocol. Higher version numbers are backward
  91   /// compatible with lower version numbers.
  92   ///
  93   UINT32               Version;
  94   ///
  95   /// Open an I/O aperture.
  96   ///
  97   EFI_ISA_HC_OPEN_IO   OpenIoAperture;
  98   ///
  99   /// Close an I/O aperture.
 100   ///
 101   EFI_ISA_HC_CLOSE_IO  CloseIoAperture;
 102 };
 103
 104 ///
 105 /// Reference to variable defined in the .DEC file
 106 ///
 107 extern EFI_GUID gEfiIsaHcProtocolGuid;
 108 extern EFI_GUID gEfiIsaHcServiceBindingProtocolGuid;
 109
 110 #endif  //  __ISA_HC_H__