OnlineDriverDB

Contents

Introduction

Distro and kernel specific local detection of available device drivers
are hard to maintain for stable distribution releases, since they
require uploads. They also do not apply to community contributed
drivers which are not officially supported by the distribution. An
online database makes post-release updates much easier and less
intrusive, and also allows for DB instances which are community
supported.

This document defines the version 20080407, sub-version 0 of the
XML-RPC protocol RPC protocol, as discussed on the 2008
LinuxFoundation Collaboration Summit. This driver database protocol
can be used by Jockey.

TODO: How many instances of this DriverDB make sense, and where do
they life?

Client-side Protocol

HardwareID

A particular piece of hardware is described by a "Hardware Identifier"
(HardwareID) in (type, value) pair. Currently defined types
are modalias and printer; more types are likely to
get defined in the near future.

Examples:

  • (modalias, pci:v00008086d000027A2sv00001028sd00000201bc03sc00i00)
  • (printer, Canon BJ2)

Due to limitations of XML-RPC, the protocol encodes HardwareIDs as
a single string type:value instead of a pair.

DriverDesc

The driver database cannot and should not store the actual driver
packages, but merely provide their description and location. This is
represented as a mapping attributevalue.

The following attributes are defined:

driver_type 
kernel_module | printer_driver | ... (required)
driver_vendor 
very short string, requirements as in pci.ids (required)
description 
localestring mapping (human-readable single-line) (required)
long_description 
localestring (human-readable paragraph) (optional)
version 
string, arbitrary differentiation (optional)
jockey_handler 
class name for Jockey handler (inferred from driver_type for standard handlers) (optional)
repository 
distribution specific package repository location (optional)
package 
Package name (optional)
free 
boolean; True (free software) or False (proprietary driver) (required)
license 
verbatim license text (required if free == no, otherwise optional)

Depending on the particular driver type, there are more required and
optional attributes. The only attribute so far is kernel_module
for the kernel_module driver type.

Example:

driver_type: kernel_module
driver_vendor: ABM
kernel_module: abm_sb43
description: ("C": "SuperBeam 43 Wifi cards", "de": "SuperBeam 43 Funknetzwerk")
repository: http://drivers.abm.com/foonux
package: linux-superbeam43
free: True

query() argument format

The query() call to the XML-RPC driver database takes a triple as argument:

(protocol_version, protocol_subversion, query_attributequery_value)

where

protocol_version 
20080407 (this is the only defined standard at the moment)
protocol_subversion 
0 (this is the only defined standard at the moment)
query_attribute → query_value 
Mapping of hardware/OS attributes to values

The following query attributes must be supplied:

system_vendor 
Computer vendor (e. g. "Dell"); empty string if unknown
system_product 
Computer model (e. g. "Latitude D430"); empty string if unknown
os_name 
Operating system name
os_version 
Operating system version
kernel_ver 
Output of uname -r
architecture 
Output of uname -m
components 
list of HardwareID

Example (in Python syntax):

  ('20080407', '0', {
    'components': ['modalias:pci:12345', 'printer:Canon BJ2'],
    'system_vendor': 'Doll',
    'system_product': 'Longitude A380',
    'os_name': 'FooTux',
    'os_version': '2.0',
    'kernel_ver': '2.6.24-15-generic',
    'architecture': 'i686'
  })

query() Response format

The XML-RPC driver database server sends back a triple

(protocol_version, protocol_subversion, HardwareID → list of DriverDesc)

protocol_version should generally match the version from the
request, protocol_subversion might differ. However, as with the
request format, the only defined protocol at the moment is 20080407/0.

HardwareID and DriverDesc are structured like described in the
previous two paragraphs.

Example (in Python syntax):

  ('20080407', '0', {
     'modalias:pci:12345': [
	{'driver_type': 'kernel_module',
         'kernel_module': 'abm_sb43',
         'driver_vendor': 'ABM',
         'description': {'C': 'ABM SuperBeam 43 Wifi cards', 'de': 'SuperBeam 43 Funknetzwerk'},
         'repository': 'http://drivers.abm.com/foonux',
         'package': 'abm-superbeam43'
         'free': False,
         'license': 'You have to send us your soul to use this.',
	},
	{'driver_type': 'kernel_module',
         'kernel_module': 'sbeam',
         'driver_vendor': 'FooTux',
         'description': {'C': 'Default SuperBeam Linux driver'},
         'package': 'superbeam-drv',
         'free': True
	},
     ],
     'printer:Canon BJ2': [
     	{'driver_type': 'printer_driver',
	 'driver_vendor': '', # local distro package
	 'description': {'C': 'Canon BubbleJet Color printer driver'},
	 'foomatic_module': 'canon_bj',
	 'bj_arg': 'color'
	 'free': True
	}
     ]
  })

Database Dump

The XML-RPC call for dumping the entire database has the following signature:

dump: () → (protocol_version, protocol_subversion, (query_attribute → query_value) → list of DriverDesc)

i. e. it takes no arguments at all, and returns a triple

protocol_version 
20080407 (this is the only defined standard at the moment)
protocol_subversion 
0 (this is the only defined standard at the moment)
query_attribute → query_value 
as in "Query format" above, but with exactly one component
list of DriverDesc 
like above, but every driver record has an additional field "id" with an unique value to identify this driver record; this ID can be used to modify/delete driver records

Administration Protocol

These commands should only be available to authorized people who are able to change the database.

Adding an Entry

Signature:

add: (protocol_version, protocol_subversion, (query_attribute → query_value), DriverDesc) → (protocol_version, protocol_subversion, status, id)

Input:

protocol_version 
20080407 (this is the only defined standard at the moment)
protocol_subversion 
0 (this is the only defined standard at the moment)
query_attribute → query_value 
as in "Query format" above, but with exactly one component
DriverDesc 
as above

Output:

protocol_version 
20080407 (this is the only defined standard at the moment)
protocol_subversion 
0 (this is the only defined standard at the moment)
status 
"OK" on success, or error message on failure
id 
assigned unique identifier for the driver, as returned in the dump() call

The command should fail if query → DriverDesc already exists, and return the existing id; in this case, the old record needs to be deleted first. This prevents admins from accidentally overwriting records.

Deleting an Entry

Signature:

delete: (protocol_version, protocol_subversion, id) → (protocol_version, protocol_subversion, status)

Input:

protocol_version 
20080407 (this is the only defined standard at the moment)
protocol_subversion 
0 (this is the only defined standard at the moment)
id 
unique identifier for the driver, as returned in the dump() call

Output:

protocol_version 
20080407 (this is the only defined standard at the moment)
protocol_subversion 
0 (this is the only defined standard at the moment)
status 
"OK" on success, or error message on failure

Note: the database should clean up HardwareID records which do not have any associated drivers any more.

Server Requirements

The following features are needed to provide enough functionality for
a per-distro/per-community driver database, which could then be used
by Jockey:

  • a database design which efficiently supports the query format above
  • unauthenticated read-only data retrieval (queries)
  • authenticated changing of data over an XML-RPC call
  • autentication preferably happens over mutual SSL certificates, alternatively with a password from the client side
  • should not have a lot of logic; all the clever data-extraction from modules etc. should happen on the distributor's client side
  • A way to ensure data integrity (SSL authentication for queries? GPG signed checksums? TBD)
  • An XML-RPC API to dump the entire database.

A further extension should implement server-side ACLs and multi-user
authentication, so that various distros/other groups can get access to
the distro specific database entries (selection by
os_name/os_version). With this, we can put the database on a common
server like drivertool.org, and synchronizing DB entries between
distros would become easier and more attractive.

Further improvements would provide:

  • a WebUI for queries (unauthenticated)
  • a WebUI for managing DB entries (authenticated)
  • Knowledge about particular distribution repositories for providing integrity checks (URLs and package names correct, etc.)