Managed Drivers¶

Pantavisor offers a declarative way to define drivers at BSP level that containers can depend on to realize a managed driver loading experience optimized for pantavisors system lifecycle.

For managed drivers, Pantavisor facilitates the loading and unloading of drivers as part of the system state lifecycle.

Managed drivers will get loaded and unloaded lazily, that is: at the time when the container gets started.

BSP Drivers¶

To make a driver available for being operated in such "managed" manner, the BSP author can define drivers as part of the bsp/drivers.json file.

The drivers.json is very simply structured as an array of module alias entries that map to one-to-many kernel modules. Parameters for kernel loading are supported (see below).

Example drivers.json:

{
    "#spec": "driver-aliases@1",
    "all": {
        "bluetooth": [
            "hci_uart",
            "btintel"
        ],
        "wifi": [
            "iwlwifi ${user-meta:drivers.iwlwifi.opts}"
        ]
    },
    "dtb:all": {}
}

The above drivers.json defines three "driver" aliases for "bluetooth" and "wifi" that containers can reference for auto loading.

Each alias is comprised as an array of module aliases. Parameters can be added statically and dynamically by referencing either user-meta (like in the example above) or device-meta.

So in this case if a container references the "bluetooth" driver, upon start pantavisor will ensure hci_uart and btintel get loaded.

Container Drivers¶

Managed Drivers can be referenced by containers as "required", "optional" and "manual".

required drivers will be loaded on container start. Pantavisor will fail to run a system state that has required drivers that cannot be enabled through the BSP.
optional drivers will be loaded on container start. Pantavisor will NOT fail to run a system state that has optional drivers that cannot be enabled through the BSP. In this case pantavisor will simply not load the driver, but otherwise continue the lifecycle process as normal.
manual drivers can be loaded from within containers through a REST API. manual drivers will not make a system state fail to run in all cases if its not provided by BSP, but the REST calls will fail.

Container drivers in run.json¶

Below an example of the 'drivers' element in run.json that containers can use to reference driver aliases that they would like to seea loaded automatically or manually.

container/run.json:

{
...
    "drivers": {
        "required": [ "ethernet", "bluetooth" ],
        "optional": [ "usbnet" ],
        "manual": [ "wifi" ],
    }
...
}

Container drivers with pvr in src.json¶

Similarly, pvr offers templating support to generate the right run.json for you.

For that you have the template "args" keys PV_DRIVERS_REQUIRED (=> required), PV_DRIVERS_OPTIONAL: (=> optional) and PV_DRIVERS_MANUAL (=> manual) available.

See below example:

container/src.json
{
...
    "args": {
        "PV_DRIVERS_REQUIRED": ["ethernet", "bluetooth"],
        "PV_DRIVERS_OPTIONAL": ["usbnet"],
        "PV_DRIVERS_MANUAL": ["wifi"]
    }
...
}

Manual Drivers REST API¶

Manual drivers can be loaded and unloaded from within container through simple REST API call to pantavisor control socket.

The operations are:

Get drivers¶

Get drivers list referenced by container and their load state.

# GET drivers
# curl --unix-socket /pantavisor/pv-ctrl http://x/drivers

Load drivers¶

Manual drivers can be loaded at bulk from within container.

# Load all container drivers
# curl -XPUT --unix-socket /pantavisor/pv-ctrl http://x/drivers/load

Alternatively you can also load specific drivers:

# Load manual wifi driver
# curl -XPUT --unix-socket /pantavisor/pv-ctrl http://x/drivers/wifi/load

Unload drivers¶

Manual drivers can be unloaded at bulk from within container.

# Unload all container drivers
# curl -XPUT --unix-socket /pantavisor/pv-ctrl http://x/drivers/unload

Alternatively you can also unload specific drivers:

# Unload manual wifi driver
# curl -XPUT --unix-socket /pantavisor/pv-ctrl http://x/drivers/wifi/unload

Linux Kernel Parameters¶

As mentioned above and shown in the example, each module alias can include parameters that reference a user-meta or device-meta field.

The syntax will use of the permissions of the loading container to determine whether the user-meta or device-meta fields referenced can be seen or not.

Example:

{
    "#spec": "driver-aliases@1",
    "all": {
        "wifi": [
            "iwlwifi ${user-meta:drivers.iwlwifi.opts}"
        ]
    }
}

The modprobe used to load the above abstract driver "wifi" can be configured by setting the drivers.iwlwifi.opts user-meta data on your device.

In offline mode, set user-meta the platform could issue the following curl command:

$ curl -XPUT --unix-socket /pantavisor/pv-ctrl \
    --data="power_save=true power_level=5"  \
    http://x/user-meta/drivers.iwlwifi.opts

In online mode you would do that through pantahub.

This will practically result in a module being loaded using the following modprobe command next time the "wifi" driver will need loading:

$ modprobe iwlwifi power_save=true power_level=5