l4/pkg/io/doc/io.dox

   1 // vi:ft=c
   2 /**
   3  * \page io Io, the Io Server
   4  *
   5  * The Io server handles all platform devices and resources such as I/O
   6  * memory, ports (on x86) and interrupts, and grants access to those to
   7  * clients.
   8  *
   9  * Upon startup Io discovers all platform devices using available means on
  10  * the system, e.g. on x86 the PCI bus is scanned and the ACPI subsystem
  11  * initialised. Available I/O resource can also be configured via
  12  * configuration scripts.
  13  *
  14  * Io uses configuration can be considered as two parts:
  15  *  - the description of the real hardware
  16  *  - the description of virtual buses
  17  *
  18  * Both descriptions represent hierarchical (tree) structure of device nodes.
  19  * Where each device has a set of resources attached to it. And a device that
  20  * has child devices can be considered a bus.
  21  *
  22  * Hardware Description
  23  * --------------------
  24  *
  25  * The hardware description represents the devices that are available on the
  26  * particular platform including their resource descriptions, such as MMIO
  27  * regions, IO-Port regions, IRQs, bus numbers etc.
  28  *
  29  * The root of the hardware devices is formed by a system bus device
  30  * (accessible in the configuration via Io.system_bus()).
  31  * As mentioned before, platforms that support methods for device discovery may
  32  * populate the hardware description automatically, for example from ACPI. On
  33  * platforms that do not have support for such methods you have to specify the
  34  * hardware description by hand. A simple example for this is
  35  * <tt>x86-legacy.devs</tt>.
  36  *
  37  * Virtual Bus Description
  38  * -----------------------
  39  *
  40  * Each Io server client is provided with its own virtual bus which
  41  * it can iterate to find devices. A virtual PCI bus may be a part
  42  * of this virtual bus.
  43  *
  44  * \image html io-overview.png "IO Service Architecture Overview"
  45  * \image latex io-overview.pdf "IO Service Architecture Overview"
  46  *
  47  * The Io server must be configured to create virtual buses for its
  48  * clients.
  49  *
  50  * This is done with at least one configuration file
  51  * specifying static resources as well as virtual buses for clients. The
  52  * configuration may be split across several configuration files passed
  53  * to Io through the command line.
  54  *
  55  * To allow clients access to a available devices, a virtual system bus needs
  56  * to be created that lists the devices and their resources that should be
  57  * available to that client. The names of the busses correspond to the
  58  * capabilities given to Io in its launch configuration.
  59  *
  60  * A very simple configuration for Io could look like this:
  61  *
  62  * \include io/doc/example.io
  63  *
  64  * Each device supports a 'compatible' property. It is a list of compatibility
  65  * strings. A client matches itself against one (or multiple) compatibility IDs
  66  * and configures itself accordingly. All other device members are handled
  67  * according to their type. If the type is a resource (Io.Res) it is added as a
  68  * named resource. Note that resource names are truncated to 4 letters and are
  69  * stored in the ID field of a l4vbus_resource_t. If the type is a device it is
  70  * added as a child device to the current one. All other types are treated as a
  71  * device property which can be used to configure a device driver. Right now,
  72  * device properties are internal to Io only.
  73  *
  74  * Assigning clients PCI devices could look like this:
  75  *
  76  * \include io/doc/example_pci.io
  77  *
  78  * The CC numbers are PCI class codes. You can also use <tt>REV_</tt>,
  79  * <tt>VEN_</tt>, <tt>DEV_</tt> and <tt>SUBSYS_</tt> to specify revision,
  80  * vendor, device and subsystem with a hex number.
  81  */