The NVIDIA FreeBSD driver supports configuring various driver settings on a per-process basis through the use of "application profiles": collections of settings that are only applied if the current process matches attributes detected by the driver when it is loaded into the process. This mechanism allows users to selectively override global driver settings for a particular application without the need to set environment variables on the command line prior to running the application.

Application profiles consist of "rules" and "profiles". A "profile" defines what settings to use, and a "rule" identifies an application and defines what profile should be used with that application.

A rule identifies an application by describing various features of the application; for example, the name of the application binary (e.g. "glxgears") or a shared library loaded into the application (e.g. "libpthread.so.0"). The particular features supported by this NVIDIA FreeBSD implementation are listed below in the "Supported Features" section.

Currently, application profiles are only supported by the NVIDIA FreeBSD GLX implementation, but other NVIDIA driver components may use them in the future.

Application profiles can be configured using the nvidia-settings control panel. To learn more, consult the online help text by clicking the "Help" button under the "Application Profiles" page in nvidia-settings.

Note: if HOME is unset, then any configuration files listed below located under $HOME will not be loaded by the driver.

To enable application profile support globally on a system, edit the file $HOME/.nv/nvidia-application-profile-globals-rc to contain a JSON object with a member "enabled" set to true or false. For example, if this file contains the following string:

{ "enabled" : true }

application profiles will be enabled globally in the driver. If this file does not exist or cannot be read by the parser, application profiles will be enabled by default.

Application profile support in the driver can be toggled for an individual application by using the __GL_APPLICATION_PROFILE environment variable. Setting this to 1 enables application profile support, and setting this to 0 disables application profile support. If this environment variable is set, this overrides any setting specified in $HOME/.nv/nvidia-application-profile-globals-rc.

Additionally, the application profile parser can log debugging information to stderr if the __GL_APPLICATION_PROFILE_LOG environment variable is set to 1. Conversely, setting __GL_APPLICATION_PROFILE_LOG to 0 disables logging of parse information to stderr.

By default, when the driver component ("libGL.so.1" in the case of GLX) is loaded by a process, the driver looks for files in the following search path:

By convention, the *-rc.d files are directories and the *-rc files are regular files, but the driver places no restrictions on file type, and any of the above files can be a directory or regular file, or a symbolic link which resolves to a directory or regular file. Files of other types (e.g. character or block devices, sockets, and named pipes) will be ignored.

If a file in the search path is a directory, the parser will examine all regular files (or symbolic links which resolve to regular files) in that directory in alphanumeric order, as determined by strcoll(3). Files in the directory of other types (e.g. other directories, character or block devices, sockets, and named pipes) will be ignored.

When application profiles are enabled in the driver, the driver configuration is defined by a set of profiles and rules. Profiles are collections of driver settings given as key/value pairs, and rules are mappings between one or more patterns which match against some feature of the process and a profile.

Configuration files are written in a superset of JSON (http://www.json.org/) with the following additional features:

Each file consists of a root object with two optional members:

Each rule is an object with the following members:

Each profile is an object with the following members:

Each setting object contains the following members:

A pattern object may consist of a pattern primitive, or a logical operation on pattern objects. A pattern primitive is an object containing the following members:

A pattern operation is an object containing the following members:

If the pattern is an operation, then the pattern matches if and only if the logical operation applied to the subpatterns is true. For example,

    {
        "op" : "or",
        "sub" : [ { "feature" : "procname", "matches" : "foo" },
                  { "feature" : "procname", "matches" : "bar" } ]
    }

matches all processes with the name "foo" *or* "bar". Similarly,

    {
        "op" : "and",
        "sub" : [ { "feature" : "procname", "matches" : "foo" },
                  { "feature" : "dso", "matches" : "bar.so" } ]
    }

matches all processes with the name "foo" that load DSO "bar.so", and

    {
        "op" : "not",
        "sub" : { "feature" : "procname", "matches" : "foo" }
    }

matches a process which is *not* named "foo". Nested operations are possible; for example:

    {
        "op" : "and",
        "sub" : [
            { "feature" : "dso", "matches" : "foo.so" },
            { "op" : "not", "sub" : { "feature" : "procname", "matches" : "bar" } }
         ]
    }

matches processes that are *not* named "bar" that load DSO "foo.so".

Note: this definition omits the presence of whitespace or comments, which can be inserted between any pair of symbols.

This is written in an "EBNF-like" grammar based on ISO/IEC 14977, using the following (non-EBNF) extensions:

The grammar follows.

    config_file = object( [ attr(rules, array(rule)) ] ,
                          [ attr(profiles, array(profile)) ] ) ;
    rule = object(attr(pattern, pattern_object | array(pattern_object)),
                  attr(profile, profile_ref)) ;
    pattern_object = pattern_op | pattern_primitive ;
    pattern_op = object(attr(op, string),
                        attr(sub, pattern_object | array(pattern_object))) ;
    pattern_primitive = object(attr(feature, string),
                               attr(matches, string)) ;
    profile_ref = string | settings | rule_profile ;
    profile = object(attr(name, string),
                     attr(settings,
                          (array(setting_kv) | array(setting_obj)))) ;
    rule_profile = object([ attr(name, string) ],
                          attr(settings,
                          (array(setting_kv) | array(setting_obj)))) ;
    setting_kv = string ',' value ;
    setting_obj = object(attr(k,string) | attr(key,string),
                         attr(v,value) | attr(value,value)) ;
    string = ? any valid json string ? ;
    value = ? any valid json number ? | 'true' | 'false' |
            hex_value | oct_value ;
    hex_value = '0', ('x' | 'x'), hex_digit, { hex_digit } ;
    oct_value = '0', oct_digit, { oct_digit } ;
    hex_digit = ? any character in the range [0-9a-fA-F] ? ;
    oct_digit = ? any character in the range [0-7] ? ;
            

Profiles may be specified in any order, and rules defined in files earlier in the search path may refer to profiles defined later in the search path.

Rules are prioritized based on the order in which they are defined: each rule has precedence over rules defined after it in the same file, and rules defined in a file have precedence over rules defined in files that come after that file in the search path.

For example, if there are two files A and B, such that A comes before B in the search path, with the following contents:

    # File A
    {
        "rules" : [ { "pattern" : "foo",
                      "profile" : [ "a", 1 ] },
                    { "pattern" : "foo",
                      "profile" : [ "a", 0, "b", 2 ] } ]
    }

    # File B
    {
        "rules" : [ { "pattern" : "foo",
                      "profile" : [ "a", 0, "b", 0, "c", 3 ] } ]
    }
            

and the driver is loaded into a process with the name "foo", it will apply the settings "a" = 1, "b" = 2, and "c" = 3.

Settings specified via application profiles have higher precedence than global settings specified in nvidia-settings, but lower precedence than settings specified directly via environment variables.

The following is a sample configuration file which demonstrates the various ways one can specify application profiles and rules for different processes.

    {
    "rules" : [

        # Define a rule with an inline profile, (implicitly) using
        # feature "procname".
        { "pattern" : "glxgears", "profile" : [ "GLSyncToVBlank", "1" ] },

        # Define a rule with a named profile, (implicitly) using feature
        # "procname".
        { "pattern" : "gloss", "profile" : "p0" },

        # Define a rule with a named profile, using feature "dso".
        { "pattern" : { "feature" : "dso", "matches" : "libpthread.so.0" },
          "profile" : "p1" },

        # Define a rule with a named, inline profile, using feature "true";
        # patterns using this feature will always match, and can be used
        # to write catch-all rules.
        { "pattern" : { "feature" : "true", "matches" : "" },
          "profile" : { "name" : "p2",
                        "settings" : [ "GLSyncToVBlank", 1 ] } },

        # Define a rule with multiple patterns. This rule will only be
        # applied if the current process is named "foo" and has loaded
        # "bar.so".
        { "pattern" : [ { "feature" : "procname", "matches" : "foo" },
                        { "feature" : "dso", "matches" : "bar.so" } ],
          "profile" : "p1" },

        # Define a rule with no patterns. This rule will always be applied.
        { "pattern" : [], "profile" : "p1" }

    ],
    "profiles" : [

        # define a profile with settings defined in a key/value array
        { "name" : "p0", "settings" : [ "GLSyncToVBlank", 0 ] },

        # define a profile with settings defined in an array of setting
        # objects
        { "name" : "p1", "settings" : [ { "k" : "GLDoom3", "v" : false } ] }

    ]
    }
        

This NVIDIA FreeBSD driver supports detection of the following features:

The list of supported application profile settings and their equivalent environment variable names (if any) is as follows: