OvmfPkg/Include/Library/QemuFwCfgSimpleParserLib.h

   1 /** @file
   2   Parse the contents of named fw_cfg files as simple (scalar) data types.
   3
   4   Copyright (C) 2020, Red Hat, Inc.
   5
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7 **/
   8
   9 #ifndef QEMU_FW_CFG_SIMPLE_PARSER_LIB_H_
  10 #define QEMU_FW_CFG_SIMPLE_PARSER_LIB_H_
  11
  12 #include <Base.h>
  13
  14 /**
  15   Look up FileName with QemuFwCfgFindFile() from QemuFwCfgLib. Read the fw_cfg
  16   file into a small array with automatic storage duration. Parse the array as
  17   the textual representation of a BOOLEAN.
  18
  19   @param[in] FileName  The name of the fw_cfg file to look up and parse.
  20
  21   @param[out] Value    On success, Value is TRUE if the contents of the fw_cfg
  22                        file case-insensitively match "true", "yes", "y",
  23                        "enable", "enabled", "1".
  24
  25                        On success, Value is FALSE if the contents of the fw_cfg
  26                        file case-insensitively match "false", "no", "n",
  27                        "disable", "disabled", "0".
  28
  29                        On failure, Value is not changed.
  30
  31   @retval RETURN_SUCCESS         Parsing successful. Value has been set.
  32
  33   @retval RETURN_UNSUPPORTED     Firmware configuration is unavailable.
  34
  35   @retval RETURN_PROTOCOL_ERROR  Parsing failed. Value has not been changed.
  36
  37   @return                        Error codes propagated from
  38                                  QemuFwCfgFindFile(). Value has not been
  39                                  changed.
  40 **/
  41 RETURN_STATUS
  42 EFIAPI
  43 QemuFwCfgParseBool (
  44   IN  CONST CHAR8  *FileName,
  45   OUT BOOLEAN      *Value
  46   );
  47
  48 /**
  49   Look up FileName with QemuFwCfgFindFile() from QemuFwCfgLib. Read the fw_cfg
  50   file into a small array with automatic storage duration. Parse the array as
  51   the textual representation of a UINT8.
  52
  53   @param[in] FileName    The name of the fw_cfg file to look up and parse.
  54
  55   @param[in] ParseAsHex  If TRUE, call BaseLib's AsciiStrHexToUint64S() for
  56                          parsing the fw_cfg file.
  57
  58                          If FALSE, call BaseLib's AsciiStrDecimalToUint64S()
  59                          for parsing the fw_cfg file.
  60
  61   @param[out] Value      On success, Value has been parsed with the BaseLib
  62                          function determined by ParseAsHex, and also
  63                          range-checked for [0, MAX_UINT8].
  64
  65                          On failure, Value is not changed.
  66
  67   @retval RETURN_SUCCESS         Parsing successful. Value has been set.
  68
  69   @retval RETURN_UNSUPPORTED     Firmware configuration is unavailable.
  70
  71   @retval RETURN_PROTOCOL_ERROR  Parsing failed. Value has not been changed.
  72
  73   @retval RETURN_PROTOCOL_ERROR  Parsing succeeded, but the result does not fit
  74                                  in the [0, MAX_UINT8] range. Value has not
  75                                  been changed.
  76
  77   @return                        Error codes propagated from
  78                                  QemuFwCfgFindFile() and from the BaseLib
  79                                  function selected by ParseAsHex. Value has not
  80                                  been changed.
  81 **/
  82 RETURN_STATUS
  83 EFIAPI
  84 QemuFwCfgParseUint8 (
  85   IN  CONST CHAR8  *FileName,
  86   IN  BOOLEAN      ParseAsHex,
  87   OUT UINT8        *Value
  88   );
  89
  90 //
  91 // The following functions behave identically to QemuFwCfgParseUint8(),
  92 // only their range checks use MAX_UINT16, MAX_UINT32, MAX_UINT64, MAX_UINTN,
  93 // respectively.
  94 //
  95
  96 RETURN_STATUS
  97 EFIAPI
  98 QemuFwCfgParseUint16 (
  99   IN  CONST CHAR8  *FileName,
 100   IN  BOOLEAN      ParseAsHex,
 101   OUT UINT16       *Value
 102   );
 103
 104 RETURN_STATUS
 105 EFIAPI
 106 QemuFwCfgParseUint32 (
 107   IN  CONST CHAR8  *FileName,
 108   IN  BOOLEAN      ParseAsHex,
 109   OUT UINT32       *Value
 110   );
 111
 112 RETURN_STATUS
 113 EFIAPI
 114 QemuFwCfgParseUint64 (
 115   IN  CONST CHAR8  *FileName,
 116   IN  BOOLEAN      ParseAsHex,
 117   OUT UINT64       *Value
 118   );
 119
 120 RETURN_STATUS
 121 EFIAPI
 122 QemuFwCfgParseUintn (
 123   IN  CONST CHAR8  *FileName,
 124   IN  BOOLEAN      ParseAsHex,
 125   OUT UINTN        *Value
 126   );
 127
 128 #endif // QEMU_FW_CFG_SIMPLE_PARSER_LIB_H_