======OnlineDriverDB======
=====Contents=====

  * [[https://www.linuxfoundation.org/#Introduction|1 Introduction]]
  * [[https://www.linuxfoundation.org/#Client-side_Protocol|2 Client-side Protocol]]
    * [[https://www.linuxfoundation.org/#HardwareID|2.1 HardwareID]]
    * [[https://www.linuxfoundation.org/#DriverDesc|2.2 DriverDesc]]
    * [[https://www.linuxfoundation.org/#query.28.29_argument_format|2.3 query() argument format]]
    * [[https://www.linuxfoundation.org/#query.28.29_Response_format|2.4 query() Response format]]
    * [[https://www.linuxfoundation.org/#Database_dump|2.5 Database dump]]
  * [[https://www.linuxfoundation.org/#Administration_protocol|3 Administration protocol]]
    * [[https://www.linuxfoundation.org/#Adding_an_entry|3.1 Adding an entry]]
    * [[https://www.linuxfoundation.org/#Deleting_an_entry|3.2 Deleting an entry]]
  * [[https://www.linuxfoundation.org/#Server_requirements|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 [[https://launchpad.net/jockey|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 //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:
<code>
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</code>
**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):
<code>
  ('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'
  })</code>
**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):
<code>
  ('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
	}
     ]
  })</code>
**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.)