OvmfPkg/Include/Library/QemuFwCfgLib.h

   1 /** @file
   2   QEMU/KVM Firmware Configuration access
   3
   4   Copyright (c) 2011 - 2013, Intel Corporation. All rights reserved.<BR>
   5   Copyright (C) 2013, Red Hat, Inc.
   6
   7   This program and the accompanying materials
   8   are licensed and made available under the terms and conditions of the BSD License
   9   which accompanies this distribution.  The full text of the license may be found at
  10   http://opensource.org/licenses/bsd-license.php
  11
  12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15 **/
  16
  17 #ifndef __FW_CFG_LIB__
  18 #define __FW_CFG_LIB__
  19
  20 //
  21 // The size, in bytes, of names of firmware configuration files, including at
  22 // least one terminating NUL byte.
  23 //
  24 #define QEMU_FW_CFG_FNAME_SIZE 56
  25
  26 //
  27 // If the following bit is set in the UINT32 fw_cfg revision / feature bitmap
  28 // -- read from key 0x0001 with the basic IO Port or MMIO method --, then the
  29 // DMA interface is available.
  30 //
  31 #define FW_CFG_F_DMA BIT1
  32
  33 //
  34 // Macros for the FW_CFG_DMA_ACCESS.Control bitmap (in native encoding).
  35 //
  36 #define FW_CFG_DMA_CTL_ERROR  BIT0
  37 #define FW_CFG_DMA_CTL_READ   BIT1
  38 #define FW_CFG_DMA_CTL_SKIP   BIT2
  39 #define FW_CFG_DMA_CTL_SELECT BIT3
  40 #define FW_CFG_DMA_CTL_WRITE  BIT4
  41
  42 typedef enum {
  43   QemuFwCfgItemSignature            = 0x0000,
  44   QemuFwCfgItemInterfaceVersion     = 0x0001,
  45   QemuFwCfgItemSystemUuid           = 0x0002,
  46   QemuFwCfgItemRamSize              = 0x0003,
  47   QemuFwCfgItemGraphicsEnabled      = 0x0004,
  48   QemuFwCfgItemSmpCpuCount          = 0x0005,
  49   QemuFwCfgItemMachineId            = 0x0006,
  50   QemuFwCfgItemKernelAddress        = 0x0007,
  51   QemuFwCfgItemKernelSize           = 0x0008,
  52   QemuFwCfgItemKernelCommandLine    = 0x0009,
  53   QemuFwCfgItemInitrdAddress        = 0x000a,
  54   QemuFwCfgItemInitrdSize           = 0x000b,
  55   QemuFwCfgItemBootDevice           = 0x000c,
  56   QemuFwCfgItemNumaData             = 0x000d,
  57   QemuFwCfgItemBootMenu             = 0x000e,
  58   QemuFwCfgItemMaximumCpuCount      = 0x000f,
  59   QemuFwCfgItemKernelEntry          = 0x0010,
  60   QemuFwCfgItemKernelData           = 0x0011,
  61   QemuFwCfgItemInitrdData           = 0x0012,
  62   QemuFwCfgItemCommandLineAddress   = 0x0013,
  63   QemuFwCfgItemCommandLineSize      = 0x0014,
  64   QemuFwCfgItemCommandLineData      = 0x0015,
  65   QemuFwCfgItemKernelSetupAddress   = 0x0016,
  66   QemuFwCfgItemKernelSetupSize      = 0x0017,
  67   QemuFwCfgItemKernelSetupData      = 0x0018,
  68   QemuFwCfgItemFileDir              = 0x0019,
  69
  70   QemuFwCfgItemX86AcpiTables        = 0x8000,
  71   QemuFwCfgItemX86SmbiosTables      = 0x8001,
  72   QemuFwCfgItemX86Irq0Override      = 0x8002,
  73   QemuFwCfgItemX86E820Table         = 0x8003,
  74   QemuFwCfgItemX86HpetData          = 0x8004,
  75
  76 } FIRMWARE_CONFIG_ITEM;
  77
  78 //
  79 // Communication structure for the DMA access method. All fields are encoded in
  80 // big endian.
  81 //
  82 #pragma pack (1)
  83 typedef struct {
  84   UINT32 Control;
  85   UINT32 Length;
  86   UINT64 Address;
  87 } FW_CFG_DMA_ACCESS;
  88 #pragma pack ()
  89
  90 /**
  91   Returns a boolean indicating if the firmware configuration interface
  92   is available or not.
  93
  94   This function may change fw_cfg state.
  95
  96   @retval    TRUE   The interface is available
  97   @retval    FALSE  The interface is not available
  98
  99 **/
 100 BOOLEAN
 101 EFIAPI
 102 QemuFwCfgIsAvailable (
 103   VOID
 104   );
 105
 106
 107 /**
 108   Selects a firmware configuration item for reading.
 109
 110   Following this call, any data read from this item will start from
 111   the beginning of the configuration item's data.
 112
 113   @param[in] QemuFwCfgItem - Firmware Configuration item to read
 114
 115 **/
 116 VOID
 117 EFIAPI
 118 QemuFwCfgSelectItem (
 119   IN FIRMWARE_CONFIG_ITEM   QemuFwCfgItem
 120   );
 121
 122
 123 /**
 124   Reads firmware configuration bytes into a buffer
 125
 126   If called multiple times, then the data read will
 127   continue at the offset of the firmware configuration
 128   item where the previous read ended.
 129
 130   @param[in] Size - Size in bytes to read
 131   @param[in] Buffer - Buffer to store data into
 132
 133 **/
 134 VOID
 135 EFIAPI
 136 QemuFwCfgReadBytes (
 137   IN UINTN                  Size,
 138   IN VOID                   *Buffer  OPTIONAL
 139   );
 140
 141
 142 /**
 143   Writes firmware configuration bytes from a buffer
 144
 145   If called multiple times, then the data written will
 146   continue at the offset of the firmware configuration
 147   item where the previous write ended.
 148
 149   @param[in] Size - Size in bytes to write
 150   @param[in] Buffer - Buffer to read data from
 151
 152 **/
 153 VOID
 154 EFIAPI
 155 QemuFwCfgWriteBytes (
 156   IN UINTN                  Size,
 157   IN VOID                   *Buffer
 158   );
 159
 160
 161 /**
 162   Reads a UINT8 firmware configuration value
 163
 164   @return    Value of Firmware Configuration item read
 165
 166 **/
 167 UINT8
 168 EFIAPI
 169 QemuFwCfgRead8 (
 170   VOID
 171   );
 172
 173
 174 /**
 175   Reads a UINT16 firmware configuration value
 176
 177   @return    Value of Firmware Configuration item read
 178
 179 **/
 180 UINT16
 181 EFIAPI
 182 QemuFwCfgRead16 (
 183   VOID
 184   );
 185
 186
 187 /**
 188   Reads a UINT32 firmware configuration value
 189
 190   @return    Value of Firmware Configuration item read
 191
 192 **/
 193 UINT32
 194 EFIAPI
 195 QemuFwCfgRead32 (
 196   VOID
 197   );
 198
 199
 200 /**
 201   Reads a UINT64 firmware configuration value
 202
 203   @return    Value of Firmware Configuration item read
 204
 205 **/
 206 UINT64
 207 EFIAPI
 208 QemuFwCfgRead64 (
 209   VOID
 210   );
 211
 212
 213 /**
 214   Find the configuration item corresponding to the firmware configuration file.
 215
 216   @param[in]  Name - Name of file to look up.
 217   @param[out] Item - Configuration item corresponding to the file, to be passed
 218                      to QemuFwCfgSelectItem ().
 219   @param[out] Size - Number of bytes in the file.
 220
 221   @return    RETURN_SUCCESS       If file is found.
 222              RETURN_NOT_FOUND     If file is not found.
 223              RETURN_UNSUPPORTED   If firmware configuration is unavailable.
 224
 225 **/
 226 RETURN_STATUS
 227 EFIAPI
 228 QemuFwCfgFindFile (
 229   IN   CONST CHAR8           *Name,
 230   OUT  FIRMWARE_CONFIG_ITEM  *Item,
 231   OUT  UINTN                 *Size
 232   );
 233
 234
 235 /**
 236   Determine if S3 support is explicitly enabled.
 237
 238   @retval  TRUE   if S3 support is explicitly enabled.
 239            FALSE  otherwise. This includes unavailability of the firmware
 240                   configuration interface.
 241 **/
 242 BOOLEAN
 243 EFIAPI
 244 QemuFwCfgS3Enabled (
 245   VOID
 246   );
 247
 248 #endif
 249