• 1 Introduction
• 2 Client-side Protocol
  • 2.1 HardwareID
  • 2.2 DriverDesc
  • 2.3 query() argument format
  • 2.4 query() Response format
  • 2.5 Database dump
• 3 Administration protocol
  • 3.1 Adding an entry
  • 3.2 Deleting an entry
• 4 Server requirements

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

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 attribute →value.

The following attributes are defined:

• driver_type 
• kernel_module | printer_driver | … (required)
• driver_vendor 
• very short string, requirements as in pci.ids (required)
• description 
• locale → string mapping (human-readable single-line) (required)
• long_description 
• locale → string (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_attribute → query_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.)