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 // Macros for the FW_CFG_DMA_ACCESS.Control bitmap (in native encoding).
  28 //
  29 #define FW_CFG_DMA_CTL_ERROR  BIT0
  30 #define FW_CFG_DMA_CTL_READ   BIT1
  31 #define FW_CFG_DMA_CTL_SKIP   BIT2
  32 #define FW_CFG_DMA_CTL_SELECT BIT3
  33
  34 typedef enum {
  35   QemuFwCfgItemSignature            = 0x0000,
  36   QemuFwCfgItemInterfaceVersion     = 0x0001,
  37   QemuFwCfgItemSystemUuid           = 0x0002,
  38   QemuFwCfgItemRamSize              = 0x0003,
  39   QemuFwCfgItemGraphicsEnabled      = 0x0004,
  40   QemuFwCfgItemSmpCpuCount          = 0x0005,
  41   QemuFwCfgItemMachineId            = 0x0006,
  42   QemuFwCfgItemKernelAddress        = 0x0007,
  43   QemuFwCfgItemKernelSize           = 0x0008,
  44   QemuFwCfgItemKernelCommandLine    = 0x0009,
  45   QemuFwCfgItemInitrdAddress        = 0x000a,
  46   QemuFwCfgItemInitrdSize           = 0x000b,
  47   QemuFwCfgItemBootDevice           = 0x000c,
  48   QemuFwCfgItemNumaData             = 0x000d,
  49   QemuFwCfgItemBootMenu             = 0x000e,
  50   QemuFwCfgItemMaximumCpuCount      = 0x000f,
  51   QemuFwCfgItemKernelEntry          = 0x0010,
  52   QemuFwCfgItemKernelData           = 0x0011,
  53   QemuFwCfgItemInitrdData           = 0x0012,
  54   QemuFwCfgItemCommandLineAddress   = 0x0013,
  55   QemuFwCfgItemCommandLineSize      = 0x0014,
  56   QemuFwCfgItemCommandLineData      = 0x0015,
  57   QemuFwCfgItemKernelSetupAddress   = 0x0016,
  58   QemuFwCfgItemKernelSetupSize      = 0x0017,
  59   QemuFwCfgItemKernelSetupData      = 0x0018,
  60   QemuFwCfgItemFileDir              = 0x0019,
  61
  62   QemuFwCfgItemX86AcpiTables        = 0x8000,
  63   QemuFwCfgItemX86SmbiosTables      = 0x8001,
  64   QemuFwCfgItemX86Irq0Override      = 0x8002,
  65   QemuFwCfgItemX86E820Table         = 0x8003,
  66   QemuFwCfgItemX86HpetData          = 0x8004,
  67
  68 } FIRMWARE_CONFIG_ITEM;
  69
  70 //
  71 // Communication structure for the DMA access method. All fields are encoded in
  72 // big endian.
  73 //
  74 #pragma pack (1)
  75 typedef struct {
  76   UINT32 Control;
  77   UINT32 Length;
  78   UINT64 Address;
  79 } FW_CFG_DMA_ACCESS;
  80 #pragma pack ()
  81
  82 /**
  83   Returns a boolean indicating if the firmware configuration interface
  84   is available or not.
  85
  86   This function may change fw_cfg state.
  87
  88   @retval    TRUE   The interface is available
  89   @retval    FALSE  The interface is not available
  90
  91 **/
  92 BOOLEAN
  93 EFIAPI
  94 QemuFwCfgIsAvailable (
  95   VOID
  96   );
  97
  98
  99 /**
 100   Selects a firmware configuration item for reading.
 101
 102   Following this call, any data read from this item will start from
 103   the beginning of the configuration item's data.
 104
 105   @param[in] QemuFwCfgItem - Firmware Configuration item to read
 106
 107 **/
 108 VOID
 109 EFIAPI
 110 QemuFwCfgSelectItem (
 111   IN FIRMWARE_CONFIG_ITEM   QemuFwCfgItem
 112   );
 113
 114
 115 /**
 116   Reads firmware configuration bytes into a buffer
 117
 118   If called multiple times, then the data read will
 119   continue at the offset of the firmware configuration
 120   item where the previous read ended.
 121
 122   @param[in] Size - Size in bytes to read
 123   @param[in] Buffer - Buffer to store data into
 124
 125 **/
 126 VOID
 127 EFIAPI
 128 QemuFwCfgReadBytes (
 129   IN UINTN                  Size,
 130   IN VOID                   *Buffer  OPTIONAL
 131   );
 132
 133
 134 /**
 135   Writes firmware configuration bytes from a buffer
 136
 137   If called multiple times, then the data written will
 138   continue at the offset of the firmware configuration
 139   item where the previous write ended.
 140
 141   @param[in] Size - Size in bytes to write
 142   @param[in] Buffer - Buffer to read data from
 143
 144 **/
 145 VOID
 146 EFIAPI
 147 QemuFwCfgWriteBytes (
 148   IN UINTN                  Size,
 149   IN VOID                   *Buffer
 150   );
 151
 152
 153 /**
 154   Reads a UINT8 firmware configuration value
 155
 156   @return    Value of Firmware Configuration item read
 157
 158 **/
 159 UINT8
 160 EFIAPI
 161 QemuFwCfgRead8 (
 162   VOID
 163   );
 164
 165
 166 /**
 167   Reads a UINT16 firmware configuration value
 168
 169   @return    Value of Firmware Configuration item read
 170
 171 **/
 172 UINT16
 173 EFIAPI
 174 QemuFwCfgRead16 (
 175   VOID
 176   );
 177
 178
 179 /**
 180   Reads a UINT32 firmware configuration value
 181
 182   @return    Value of Firmware Configuration item read
 183
 184 **/
 185 UINT32
 186 EFIAPI
 187 QemuFwCfgRead32 (
 188   VOID
 189   );
 190
 191
 192 /**
 193   Reads a UINT64 firmware configuration value
 194
 195   @return    Value of Firmware Configuration item read
 196
 197 **/
 198 UINT64
 199 EFIAPI
 200 QemuFwCfgRead64 (
 201   VOID
 202   );
 203
 204
 205 /**
 206   Find the configuration item corresponding to the firmware configuration file.
 207
 208   @param[in]  Name - Name of file to look up.
 209   @param[out] Item - Configuration item corresponding to the file, to be passed
 210                      to QemuFwCfgSelectItem ().
 211   @param[out] Size - Number of bytes in the file.
 212
 213   @return    RETURN_SUCCESS       If file is found.
 214              RETURN_NOT_FOUND     If file is not found.
 215              RETURN_UNSUPPORTED   If firmware configuration is unavailable.
 216
 217 **/
 218 RETURN_STATUS
 219 EFIAPI
 220 QemuFwCfgFindFile (
 221   IN   CONST CHAR8           *Name,
 222   OUT  FIRMWARE_CONFIG_ITEM  *Item,
 223   OUT  UINTN                 *Size
 224   );
 225
 226
 227 /**
 228   Determine if S3 support is explicitly enabled.
 229
 230   @retval  TRUE   if S3 support is explicitly enabled.
 231            FALSE  otherwise. This includes unavailability of the firmware
 232                   configuration interface.
 233 **/
 234 BOOLEAN
 235 EFIAPI
 236 QemuFwCfgS3Enabled (
 237   VOID
 238   );
 239
 240 #endif
 241