Development:Adding Config Options

From FEX-Emu Wiki
Jump to navigation Jump to search

Configuration options are programatically generated from json.

This file lives in `FEXCore/Source/Interface/Config/Config.json`

Options section

To add a configuration option that can be set from JSON or from environment variables, you need to add the option to this file.

Currently FEX has six groups to group configs

  • CPU
  • Emulation
  • Debug
  • Logging
  • Hacks
  • Misc

Configuration option object

Each JSON object under a group becomes a configuration.

Object Layout

  • Key:
 * Becomes the C++ enum. eg. 'Multiblock' becomes `FEXCore::Config::ConfigOption::CONFIG_MULTIBLOCK`
 * Also used for the environment variable. Becomes `FEX_MULTIBLOCK`
 * If the object type is boolean then a negated argument also is generated. `--no-multiblock`
  • Type:
 * Can be `[bool, uint8, int32, uint32, uint64, str, strarray]`
 * This is what the argument type ends up being once loaded from a configuration backing
  • Default:
 * Default value that matches this object
 * Used to generate code so needs to handle being codified. Compilation will fail otherwise
 * If Type is str or strarray then this string will be automatically wrapped with double-quotes when generated
  • TextDefault:
 * If the `Default` option which is used in code can't be represented by text. Like an enum being used.
 * eg. `Core` has a `Default` which is an enum. `TextDefault` is set to `irjit` for the user to handle this case
  • Choices:
 * Allows us to represent the textual options that a argument can accept
 * eg. `Core` supports `[ "irint", "irjit", "host" ]`
  • ArgumentHandler:
 * If an argument option needs some special handling to be parsed then this points to a C++ function in the argument loader
 * `Core` uses it to convert the textual representation in to an enum
  • Desc:
 * Short description of what this option does
 * This is used to generate the text in the man pages

UnnamedOptions section

These are configuration options that can NOT be set by user means. There won't be any Environment variable or json helpers generated to load these.

These need to exist as a way to have internal configuration options existing in the same global space as user options. Allows us to pull internal configuration options the same way as user configurations.

These can exist under any group config. Currently only `Misc` is used. Only three things need to be set for these

  • Key: This is only used to generate the enum in code
  • Type: Same supported types as the regular options
  • Default: The default value of this configuration

Getting configurations in FEX code

FEX provides a `FEX_CONFIG_OPT` define to help developers get configuration options.

  • FEX_CONFIG_OPT(name, enum)
 * eg: `FEX_CONFIG_OPT(Cores, THREADS);`
 * This will load the THREADS configuration option from the configuration directory and save the value in to local value called `Cores`
  • Gotchas:
 * Construction of the object queries the the global configuration layer. This can be slow so be careful with its use.
 * Upon construction of the `FEXCore::Config::Value<T>` object it will pull the string configuration
 * Then it will convert that value in to whatever type the value needs
 * In high performance code, keep constructor instantiation outside of the hot code path
 * Construct the configuration inside of a class definition so it only pulls the configuration once
  • Caveats:
 * If the configuration changes then this doesn't pick up the change
 * Configuration isn't meant to change live in FEX so this is typically a non-issue
 * Frontend object loader needs to be careful with its configuration loading to ensure the meta layer stays in sync
 * ELFLoader.cpp for examples here