Jockey driver manager
=====================

Jockey provides the infrastructure and the user interface for finding
and installing third-party drivers which are applicable to the
computer. This includes drivers which are added or updated after the
release of a distribution, or drivers which cannot be included into
the distribution for various reasons (CD space limitation, licensing
problems, etc.). 

A common use case is providing a friendly and semiautomatic way to
install Nvidia and ATI fglrx X.org drivers.

Jockey was designed to be distribution agnostic and fulfill the need
of different distributions, driver vendors, and system integrators. It
is designed and developed within the LinuxFoundation driver backports
workgroup [1].

Operation
---------

At startup, jockey probes the system for available hardware. This can
happen in various ways, currently implemented is scanning /sys for
modaliases. In the future it is planned to add more methods, such as
querying cups for detected printers which do not have a driver.
Detection methods will be added as needed by component vendors and
distributions. The set of available hardware is represented as
"HardwareID" objects (which can represent anything that uniquely
identifies a piece of hardware, such as a vendor/product ID, a
modalias, or a printer identification string).

For each hardware ID, a set of driver databases (instances of
DriverDB) are queried for available drivers. At the moment, the only
existing implementation is LocalKernelModulesDriverDB, which uses the
standard Linux kernel modules.alias maps to map modaliases to
kernel modules. In the near future we plan to add another
implementation which queries an online driver database as well.
The DriverDBs transform the set of HardwareIDs to a set of DriverIDs.

A DriverID represents all necessary metadata about a driver, such as:

 * driver class (kernel module, printer driver, driver package, X.org
   graphics driver, firmware, etc.)
 * handler class name (see below)
 * location of the driver (repository, package name, possibly sha1 and
   other checksums, signatures)
 * driver specific parameters (arbitrary type/value pairs which the
   handler understands)

All drivers handled by jockey need to be encapsulated by a subclass of
"Handler". A handler instance provides a hook for arbitrary code which
needs to run in order to fully install a driver. Jockey already
provides handler implementations for common cases such as kernel
modules, driver packages, kernel module firmware, X.org driver, etc.
The vast majority of drivers will use parameterized instances of these
default handlers, but drivers which need some more sophisticated
local configuration can ship their own handler subclass and add the
necessary code.

Adapting Jockey to a Linux distribution
---------------------------------------

Jockey is carefully written to not be specific to any Linux
distribution. All OS/distro specific operations are encapsulated in
the "OSLib" class, which needs to be subclassed and implemented by the
Linux distributions (primarily package query and installation and
paths to some binaries and files). While this minimizes the porting
efforts of distributors, this unfortunately also means that the
development trunk [2] cannot do very much on any distribution, since
the default implementation of e. g. the package_installed() will just
throw a "Not implemented" exception.

The abstract OSLib class is thoroughly documented, and there already
exists a branch for Ubuntu (using dpkg and synaptic as package
management interface) [3], and the test suite has a dummy
implementation (see tests/sandbox.py). These should suffice to
implement Jockey for other distributions (e. g. rpm-based ones) as
well.

Dependencies
------------

Jockey needs a working Python installation, and the following Python
modules:

 - pyxdg: http://freedesktop.org/wiki/Software/pyxdg

 - xorgconfig from the KDE guidance project for the X.org driver
   handler (to change xorg.conf). The latest entire guidance project
   can be downloaded from http://www.simonzone.com/software/guidance,
   but for Jockey you just need xorgconfig.py. (I appreciate
   suggestions for using a different backend.)

 - DistUtilsExtra for running setup.py (which will care about
   building, merging, and installing gettext .po files, installing
   icons, etc.): Latest tarball can be downloaded from
   http://ftp.debian.org/debian/pool/main/p/python-distutils-extra/
   Note that this is not necessary for running Jockey from the source
   tree.

For the GTK frontend, you need

 - pygtk: http://ftp.gnome.org/pub/GNOME/sources/pygtk/

 - pynotify: http://www.galago-project.org/downloads.php

For the KDE frontend, you need

 - PyQt4: http://www.riverbankcomputing.co.uk/pyqt/index.php

Trying it
---------

As written above, Jockey provides mostly infrastructure. Without an
implementation for a particular distribution and without actual
drivers it is fairly useless. However, you can get a first impression
by running either of

  PYTHONPATH=. gtk/jockey-gtk
  PYTHONPATH=. kde/jockey-kde
 
This will bring up the UI and list all standard kernel modules which
are tied to hardware. (Note that you will *not* see all this stuff in
a proper distribution implementation, of course.) If you run it as
normal user, you cannot actually disable or enable drivers, since this
requires writing /etc/modprobe.d/blacklist-local. If you start it as
root, that will work, and blacklist drivers if you disable them (make
sure to not render your system unbootable that way :-) ).

That way you can also try some of the other modes, like

  PYTHONPATH=. gtk/jockey-gtk --list --debug

for some insight of how jockey detects hardware and which
kernel modules are responsible for driving it.

The --mode switch also works on the upstream trunk. See --help for
further details.

Test suite
----------

Every new feature and bug fix should first get a test case, to
maintain nearly 100% code coverage. tests/sandbox.py provides fake
implemetations of OSLib, a fake /sys tree, modinfo, etc., so that the
entire hardware detection and handler system can be automatically
tested independent of the actual hardware Jockey runs on, as well as
being independent of a concrete OSLib implementation.

To run it, simply do

 tests/run 

The graphical UIs have separate test scripts, since they might not
work in all cases (like running them automatically during package
build):

  tests/run-gtk
  tests/run-qt

A commit to trunk must only be done if all test suites succeed.

Development
-----------

Development of trunk and the Ubuntu implementation happens on the
"jockey" Launchpad project: 

  https://launchpad.net/jockey
  
This is the place to report bugs, do translations, hosting your own
branches (if you wish to do so), and download upstream releases.

References
----------

[1] http://www.linux-foundation.org/en/Driver_Backport
[2] https://code.launchpad.net/~jockey-hackers/jockey/trunk
[3] https://code.launchpad.net/~ubuntu-core-dev/jockey/ubuntu

Martin Pitt <martin.pitt@ubuntu.com>
