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 hasrequired
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 hasoptional
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