/*! \page page_configfiles Configuration Files

\tableofcontents

For permanent configuration of certain device behaviours, UHD supports
configuration files.

\section configfiles_format Format of the configuration files

Configurations files use the INI format. A UHD configuration file might look
like this:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.ini}
; Comments start with a semicolon
; Sections are put in square brackets:
[type=b200]
; These settings apply to all USRPs that are of type b200:
master_clock_rate=20e6

[serial=FE18011]
; These settings apply to the USRPs with the given serial:
master_clock_rate=10e6 ; If this is a b200, this will overwrite the above settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

\section configfiles_usrps Configuring USRPs

For the most part, any setting that can get put into device args at
initialization time can be put into the config file. For example, the X300 has
a key called `ext_adc_self_test` which is disabled by default. To enable it,
you can add it to your device args:

~~~{.cpp}
auto usrp = uhd::usrp::multi_usrp::make("type=x300,ext_adc_self_test=1");
~~~

However, this can be cumbersome if the intention is to permanently enable this
for all X300s connected to this machine. To generally enable this option for
all X300s without having to modify the `make()` call, the config file can
simply be updated as such:

~~~~{.ini}
[type=x300]
ext_adc_self_test=1
~~~~

This will act as if this key/value pair had been passed to the device args
directly. This means the valid key/value pairs for the config files are the
same as those for the device args (see \ref config_devaddr).

\section configfiles_usrps_dpdk Configuring DPDK

DPDK is a special case. Because there are so many things to configure for
DPDK, it is highly recommended to use config files. The section headers for
DPDK configurations depend on on the network device used, not the USRP device.
For more details, see \ref dpdk_nic_config.

\section configfiles_usrps_mpm Configuring MPM

MPM devices (N3xx, E3xx) have their own configuration file (`mpm.conf`)
which is read once during initialization of MPM. It controls different things
than the `uhd.conf` file (both can be used for a session, but the UHD
configuration will be used at every UHD session, whereas the MPM configuration
file is only read once during MPM initialization). To reload the MPM
configuration file, a restart of MPM is required.

The `mpm.conf` files are structured a bit differently from `uhd.conf`, so here's
an example:

~~~~{.ini}
; This section is for any MPM behaviour
[mpm]
; Default log level for journald, can be overwritten by -v when starting manually
log_level=info
; Number of log records to buffer for the next get_log_buf() API call
log_buf_size=100

; Device-specific behaviour is set here. This allows having the same file for
; different device types, e.g., when a fleet of different devices are
; managed via Salt or similar tools. The key here is the same as what you would
; use in device args as a type value.
[n3xx]
KEY=VALUE

; Alternatively, specify a product value.
[n310]
KEY=VALUE
~~~~

The key/value pairs for the `type` or `product` sections are documented
in \ref config_mpm.

\section configfiles_location Location of configuration files

\b UHD will look for up to three configuration files:

1. A system-wide configuration file. On Unix systems, the default location for
   this file is <b><tt>/etc/uhd/uhd.conf</tt></b>. On Windows systems,
   <b><tt>\%programdata%/uhd/uhd.conf</tt></b>. The default can be overwritten
   at compile time by setting `UHD_SYS_CONF_FILE` through CMake.
2. A user-specific configuration file. On Unix systems, it defaults to
   `$XDG_CONFIG_HOME/uhd.conf`, where `$XDG_CONFIG_HOME` is usually the same as
   `$HOME/.config`. On Windows systems, it also checks
   <b><tt>\%localappdata%</tt></b> and <b><tt>\%appdata%</tt></b>.
   The default can be overwritten at compile time by setting
   the `UHD_USER_CONF_FILE` through CMake.
3. A configuration file specified by the environment variable `UHD_CONFIG_FILE`

UHD will read these files in this order (if they exist). Settings from one file
will overwrite those from a previous one, so if the same setting exists in the
system-wide file and the user-specific file, the settings from the
user-specific file will take effect. There is no error if a file does not
exist, or the environment variable is not set.

\b MPM will only look for a configuration file in `/etc/uhd/mpm.conf`, on the
device running MPM itself.

*/
// vim:ft=doxygen: