3.1. The busclass_list element

A busclass_list element possesses a bus attribute and contains one or more busclass elements.

3.2. The busclass element

A busclass element possesses two attributes, id and name, and contains no elements.

4.1. The vendor_list element

A vendor_list element possesses a bus attribute and contains one or more vendor elements.

4.2. The vendor element

A vendor element possesses two attributes, id and name, and contains no elements.

5.1. The device_list element

A device_list element possesses a bus attribute and contains one or more device elements.

5.2. The device element

A device element possesses four attributes:

• busclass

• vendor

• model

• model_name

All of these attributes must be specified for each device element. The busclass attribute is set to a busclass identifier, vendor to a vendor identifier, model to a bus-specific model identifier, and model_name to a human-readable vendor identifier, typically the name of the product under which the device reporting the model identifier is sold or otherwise distributed.

A device element contains zero or more data elements.

5.3. The data element

A data element possesses a mandatory class attribute, an optional version attribute, and zero or more data elements.

The ability to nest data elements inside other data elements affords interface designers and device driver authors the ability to specify a hierarchy of data, instead of being compelled to encapsulate only one piece of data per device for their interface.

5.4. Accessing the Device Data

Discover data is grouped into hierarchical data elements. This data can be accessed via its data path. The data path is the concatenation of the class attribute values of a data element and all its parents, separated by slash (/) characters. In the following example, quux is accessed via the data path "foo/bar":

<data class="foo">
  <data class="bar">quux</data>
</data>

In Example 5-1 above, we would determine the name of the Linux kernel module ("winston") for the "Cerebral Reprogrammer" device by referencing the data path linux/module/name; similarly, the data path win2k/hal_driver/flags returns NSA_KEY=96b5f3e3283a62c85f6cb6f4017135c2.

6.1. Linux Kernel Modules

A hardware device that requires a particular Linux kernel module should have nested data elements to describe that module. The top-level data element should have a class attribute with a value of linux. Underneath that should be a data element with a class of module.

Within that data element, there should be one or two more, one with a class of name, and an optional one with a class of options. The former has as content the name of the module; the latter, options to be passed to modprobe.

/linux
    |
    |-/module
          |
          |-/name
          |
          |-/options

In Figure 6-1, each component of the tree represents a data element; the label is the value of its class attribute.

If the kernel version affects the choice of module name or options, the top-level linux data element should have a version range attribute; see Section 5.3.2.

<device busclass="0204" model="1702" model_name="IS64PH ISDN Adapter" vendor="0675">
  <data class="linux">
    <data class="module">
       <data class="name">hisax</data>
       <data class="options">io=0x300 irq=11</data>
    </data>
  </data>
</device>

See Example 8-1 for guidance on how to specify different Linux kernel modules for the same device, depending on the version of the Linux kernel in use.

6.2. XFree86 X Servers

The data hierarchy of a video card device (Discover's display type) should include a top-level data element with a class attribute of xfree86 (the interface) and likely with a version attribute as well; nested within that element will be a server data element containing a name data element identifying the name of the server executable. For XFree86 version 4.0 or greater, the name will always be XFree86, and the server data element will also contain a device data element, which contains one or more data elements communicating information to be stored in the XF86Config file. The children of the device data element are named in correspondence with the syntax of the XF86Config file's Device section; see the XF86Config manual page for further information. In particular, note that in many cases only a driver data element is necessary.

/xfree86
    |
    |-/server
          |
          |-/name
          |
          |-/device
                |
                |-/driver
                |
                |-/chipid
                |
                |-/chipset
                |
                |-/ramdac
                |
                |-/dacspeed
                |
                |-/videoram
                |
                |-/options
                |
                |-...

Figure 6-2 illustrates the xfree86 interface. Example 6-3 shows how you might write xfree86 interface information for a Discover display device.

<device busclass="0300" vendor="1002" model="4654" model_name="Mach64 VT [264VT FT]">
  <data class="xfree86">
    <data class="server" version="[4, inf)">
      <data class="name">XFree86</data>
      <data class="device">
        <data class="driver">ati</data>
      </data>
    </data>
    <data class="server" version="(0, 4)">
      <data class="name">XF86_Mach64</data>
    </data>
  </data>
</device>

6.3. Locally-Defined Interfaces

Progeny recommends that publicly distributed Discover XML files avoid using the interface name local; that is, a class attribute value of local in a top-level data element. This means that data paths such as local/foo/bar should not be defined in a public Discover XML file, but both foo/bar/local and foo/local/bar are okay.

The intention is to reserve this part of the namespace for users' experiments with defining their own — and possibly future, widely adopted — interface definitions for Discover data. An interface definition could thus be "beta tested" by a person or organization to ensure that it is efficiently structured before it is unleashed upon the world elsewhere in the namespace, where people may write tools that expect to be able to resolve the interface definition's data paths.

Likewise, Progeny recommends that authors of applications that use Discover avoid traversing into a top-level local data element, which may impose an undesirable support burden on the designers of the interface while they are still working out their design. (The application also may not find the data it desires, or may not get back what it expects.)

8.1. Specifying a Range

Because multiple versions of a software interface often are in simultaneous deployment, Progeny recommendeds that the upper bound of a data element's version attribute be defined as the first version that is inconsistent with the information provided within it, and that the upper end of the interval be open (terminated with a parenthesis). As an example, suppose we know that the name of the Linux kernel module to drive the RealTek RTL-8139 Ethernet device was rtl8139 in the 2.2 kernel series and 8139too in the 2.4 series. To express this, we would say the following:

<device_list bus="pci">
<device busclass="0200" model="8139" model_name="RTL-8139" vendor="10ec">
  <data class="linux" version="[2.4,inf)">
    <data class="module">
       <data class="name">8139too</data>
    </data>
  </data>
  <data class="linux" version="[2.2,2.4)">
    <data class="module">
       <data class="name">rtl8139</data>
    </data>
  </data>
</device>
</device_list>

In the first data element, for instance, we would not use a version attribute of [2.2.0,2.2.19] because it is needlessly specific. What happens if the Linux kernel developers release Linux kernel 2.2.20? By saying [2.2,2.4), we "catch" everything in the kernel 2.2 series[2] — past, present, and future.

8.2. How the Discover Library Matches a Range

The data files will be searched in order; the first data path that matches the version range or doesn't have a version range will be returned.

Recalling the discussion in Section 5.3.2, if you want the first data element matching the requested data path to also be the "fallback" element if no version range applies, you can duplicate that data element and place it at the end. However, a better practice is to make certain that all reasonable versions will match one of the ranges, and that the first range listed has an open-ended high end, such as [2.4, inf) for Linux kernel modules in Example 8-1. This will have the effect of "assuming" that all unversioned requests for linux data will be for Linux kernel 2.4 or later.

13.1. Library Design Principles

Lazy allocation is used throughout Discover. This means that there are no "init" functions, and no functions to scan the bus. Instead, retrieval functions scan or initialize as necessary. Each of these retrieval functions has an equivalent function for freeing the allocated memory. This is valuable to long-lived processes to aid in memory management, but even short-lived processes may want to use them to force reloading of the information.

13.2. Discover Data Sources

Discover knows about one data source by default: the local data from the discover-data package. Additional sources can be added with the discover_conf_append_url and discover_conf_insert_url functions. As their names suggest, they append or insert URLs on the data source list. Earlier data overrides later data; to override the local data sources, insert URLs.

13.3. The Bus Map

Most high-level operations begin at the bus map. Bus maps (discover_bus_map_t) are retrieved with calls to discover_conf_get_bus_map or discover_conf_get_bus_map_by_name. discover_conf_get_bus_map returns an array of maps, one for each supported bus, with the last element being all 0s. discover_conf_get_bus_map_by_name returns the map for the named bus. The map contains pointers to all the functions that operate on the bus, as well as the scan_default variable, which determines whether the bus is scanned by default. There is also a scan_never variable, but it is for internal use only. The name of the bus is stored in the name variable.

The following functions are available in the bus map. The "get" functions take a single discover_error_t argument and return a list of discover_device_t structures, while the "free" functions take no arguments and return no value.

13.4. Scanning the System

Discover provides a few ways to scan the system for information.

You can walk the bus map:

for (i = 0; busmap[i].name; i++) {
    if (busmap[i].scan == DISCOVER_SCAN_DEFAULT) {
        devices = busmap[i].get_devices(&status);
        check_status(status);
        do_something_cool(devices);
    }
}

You can scan a specific bus:

devices = discover_get_pci_devices(&status);
check_status(status);
do_something_cool(devices);

Perhaps most usefully, you can scan for devices of a specific type:

devices = discover_device_find("video", &status);
check_status(status);
do_something_video(devices);

13.5. Using discover_device_t Structures

Now that you have some device structures, what can you do with them? The most interesting operation is retrieving data with discover_device_get_data. Also available are discover_device_get_vendor_name, discover_device_get_model_name, discover_device_get_model_id, and discover_device_get_vendor_id.

discover_device_get_data takes a data path and a version number and searches for the first data structure that matches.

discover_device_get_vendor_name returns the human-readable name for the device's vendor.

discover_device_get_model_name returns the human-readable name for the device's model.

discover_device_get_model_id returns the bus-specific ID for the device model.

discover_device_get_vendor_id returns the bus-specific ID for the device vendor.

14.1. API

The system-dependent code (sysdeps) that must be custom-written for each operating system conforms to a very simple API. Discover invokes _discover_get_busname_raw() with no arguments, and expects a linked list of discover_sysdep_data_t structures in return.

The discover_sysdep_data_t structures should contain as much descriptive information as they can regarding the devices discovered. Specifically, the three pieces of information desired are the busclass (device type), vendor identifier, and model identifier, which is a unique identification string that the vendor has provided for the given piece of hardware.

#include <config.h>

#include <stdio.h>
#include <stdlib.h>

#include <sysdep.h>

discover_sysdep_data_t *
_discover_get_pci_raw(void)
{
    FILE *f;
    char *line = NULL;
    size_t len = 0;
    discover_sysdep_data_t *head = NULL, *node, *last = NULL;
    unsigned int id;

    if ((f = fopen(PATH_PROC_PCI, "r"))) {
        while (getline(&line, &len, f) >= 0) {
            if (line[0] == '\n' || line[0] == '#') {
                continue;
            }

            node = _discover_sysdep_data_new();
            sscanf(line, "%*04x\t%08x", &id);
            node->vendor = (id >> 16);
            node->model = id & 0xffff;

            if (head == NULL) {
                head = node;
                last = head;
            } else {
                last->next = node;
                last = node;
            }
        }
        free(line);
        fclose(f);
    }
    return head;
}