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:
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
20080407 (this is the only defined standard at the moment)0 (this is the only defined standard at the moment)The following query attributes must be supplied:
uname -runame -mExample (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
20080407 (this is the only defined standard at the moment)0 (this is the only defined standard at the moment)
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:
20080407 (this is the only defined standard at the moment)0 (this is the only defined standard at the moment)Output:
20080407 (this is the only defined standard at the moment)0 (this is the only defined standard at the moment)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:
20080407 (this is the only defined standard at the moment)0 (this is the only defined standard at the moment)Output:
20080407 (this is the only defined standard at the moment)0 (this is the only defined standard at the moment)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 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: