Environment variables

The PCI server uses various environment variables. Their names are defined in <pci/pci.h>, in the form PCI_variable. The only mandatory environment variable is PCI_HW_MODULE; without a hardware-dependent module specified, there's no way to access the hardware.

Environment variables must be present in the environment of each process that uses libpci, including the PCI server process (pci-server). Unless otherwise indicated, any of these variables must be set in the [envars] section of the configuration file.

PCI_HW_MODULE

(Required) The name of the hardware-dependent module for your target system; see the pci_hw-* files in ${QNX_TARGET}/processor/lib/dll/pci/ on your development host and in /lib/dll/pci/ on your target. If you don't set this environment variable, you'll get a SIGSEGV.

PCI_HW_CONFIG_FILE

(Optional) The name of a hardware-dependent configuration file (see “Configuration files”).

PCI_SLOG_MODULE

(Optional) The name of the logging module (e.g., /lib/dll/pci/pci_slog2.so). If unset, no logs are recorded.

This variable must be set on the command line (not in the configuration file) prior to starting the PCI server:

PCI_SLOG_MODULE=pci_slog2.so pci-server --config=server_config_file

PCI_DEBUG_MODULE

(Optional) The name of the debug logging module (e.g., /lib/dll/pci/pci_debug2.so). If unset, no debug information is logged.

This variable must be set on the command line (not in the configuration file) prior to starting the PCI server:

PCI_DEBUG_MODULE=pci_debug2.so pci-server --config=server_config_file

PCI_CAP_MODULE_DIR

(Optional) The location of an alternate capability module directory (the default is /lib/dll/pci).

PCI_BASE_VERBOSITY

(Optional) Controls the amount of log detail for every module and library. Its value should be an unsigned integer. The default is 0; the higher the value, the more information is logged.

This environment variable works in conjunction with the pci_verbosity variable that's declared in <pci/pci.h>:

• For programs that don't manipulate the pci_verbosity variable, the value behaves the same as incrementing the verbosity parameter by the value of the PCI_BASE_VERBOSITY environment variable.
• For programs that do manipulate the pci_verbosity variable, this base level changes the default from 0 to the specified value, and any command-line options to increase pci_verbosity increase it from the base value set in the environment variable.

PCI_SERVER_BUSCFG_MODULE

(Optional) This environment variable is meaningful only for the PCI server, and it lets you select a bus configuration module. Target systems need a bus configuration module to perform reconfigurations in order to use Power Management, Hot Plug, or other such capabilities. They may need also it if devices are reset (either directly or as part of a bridge secondary bus reset), as some devices do not preserve state across such events.

This variable is required only if the PCI server configures the PCI bus (e.g., assigning secondary/subordinate bus numbers to bridges, (re)calculating address space requirements and assigning them to devices by updating BAR registers).

For information on starting the PCI server so it configures the bus, see “The PCI server”. In this case, if the environment variable isn't specified, the generic module identified by the PCI_SERVER_BUSCFG_MODULE_DEFAULT string (which is defined in <pci/pci.h>) is used. The variable lets you use alternative and/or board-specific configuration modules.

PCI_MODULE_BLACKLIST

(Optional) A colon-separated list of modules that you don't want to load. This is useful for testing and for controlling what capabilities a driver can use without having to recompile or use command-line controls.

The blacklist is checked when an attempt is made to load a module. Once a module has been successfully loaded, the blacklist is no longer consulted for that module, so it's important that the blacklist be created before a module is loaded for the first time.

While generally applicable to any PCI module, the blacklist's main purpose is to control the use of capability modules without modifying the driver software itself. For example, a driver written to use MSI-X and MSI (preferentially in that order) could be started with the MSI-X capability module blacklisted so that it uses the MSI module, without changing software or requiring a command-line option to the driver.

Because this is an environment variable, this control can be provided on a per-driver basis, but note that when this variable is specified for the PCI server, the effect is more global in nature. Blacklisting any capability modules in the server environment actually prevents their use for all driver software regardless of the setting of the variable in that driver's environment. Drivers can still read the device capabilities, but can't enable or use them.

You can specify modules as a simple name or with a leading slash. If you use a simple name, the module must exist in the /lib/dll/pci/ directory. If the first character of the name is a slash, the name must specify the full path to the module. Only an exact pathname match prevents the loading of a module. Keep this in mind if the capability module directory has been altered with the PCI_CAP_MODULE_DIR environment variable.

Note: Because a vid/did-specific capability module is always checked for before a generic capability module, if you're using a vid/did-specific capability module and wish to prevent the use of that capability, you should blacklist both the vid/did-specific and the generic modules.

PCI_SERVER_NODE_NAME

(Optional) The node name used to communicate with the PCI server (the default is /dev/pci).

This variable is required only if the PCI server is started with a different node name (with either the server's -n option or the SERVER_NODE_NAME parameter in a configuration file specified with the --config option, with the -n option taking precedence).

You typically don't need to change this name, and we don't encourage you to do so.

PCI_STRINGS_FILE

(Optional) The strings database file. If not set, the default file, /etc/system/config/pci/pcidatabase.com-tab_delimited.txt, is used. See “The Strings module.”