<?xml version="1.0" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBk XML V4.1.2//EN"
        "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd"
[
<!ENTITY % progeny-entity SYSTEM "../doctools/progeny.ent">
%progeny-entity;

<!ENTITY % config-entity SYSTEM "../doctools/config.ent">
%config-entity;

<!ENTITY % package-entity SYSTEM "../package.ent">
%package-entity;

<!ENTITY discover-1 SYSTEM "discover.refentry">
<!ENTITY discover-conf-5 SYSTEM "discover.conf.refentry">
<!ENTITY discover-modprobe-8 SYSTEM "discover-modprobe.refentry">
<!ENTITY discover-modprobe-conf-5 SYSTEM "discover-modprobe.conf.refentry">
]
>

<!--
Copyright 2002 Progeny Linux Systems, Inc.
Copyright 2002 Hewlett-Packard Company

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
-->

<!---

id attribute naming convention for this document

All preface, part, chapter, section, appendix, figure, and example elements
should have id attributes.  The id should start with an abbreviation of the
parent element as follows:

appendix  ap
chapter   ch
example   ex
figure    fg
part      pt
preface   pr
section   sc

The remainder of the id attribute value should duplicate the actual content
of the title, downcased and with spaces transliterated to underscores
("_").  It is acceptable to drop articles and abbreviate very long titles.  It
may be necessary to make the id attribute value communicate the hierarchy of
one or parent element ids to prevent collisions.

Example:

<section id="sc-vendor_element">
  <title id="sc-vendor_element-title">The <sgmltag>vendor</sgmltag> element</title>

  [...]

  <section id="sc-vendor_element_id_attribute">
    <title id="sc-vendor_element_name_attribute-title">The <sgmltag>name</sgmltag> attribute</title>

Furthermore, all of the elements listed above should contain a title element,
which itself possesses an id attribute named identically to the parent
element's id, but with "-title" suffixed.

Example:

<example id="ex-naming_convention">
  <title id="ex-naming_convention-title">Naming Convention</title>
</example>

We do not use the endterm attribute of link or xref elements because of
problems they cause with formatted output when using DSSSL backends.  Talk
to jdaily or branden about this issue.

-->

<book>
  <bookinfo>
    <releaseinfo>$Progeny$</releaseinfo>

    <authorgroup>
      &author.branden;
      &author.jdaily;
    </authorgroup>

    <title>The &discover; Hardware Detection System</title>
    <titleabbrev>Discover</titleabbrev>

    <copyright>
      <year>2002</year> <holder>Progeny Linux Systems, Inc.</holder>
    </copyright>
    <copyright>
      <year>2002</year> <holder>Hewlett-Packard Company</holder>
    </copyright>
    &license.mit;
    <legalnotice>
      <para>Linux is a registered trademark of Linus Torvalds.</para>
    </legalnotice>
  </bookinfo>

  <preface id="pr-what_is_discover">
    <title id="pr-what_is_discover-title">What Is &discover;?</title>

    <para>&discover; is a tool that reports information about a
    system's hardware.  It uses operating system-dependent modules
    (selected at build time) to detect what hardware is actually on the
    system and provides system-independent interfaces for querying &xml; data
    sources about this hardware.  These data sources contain specific
    information required to enable support for various devices via defined
    software interfaces.  The tool can be accessed by linking to the
    &discover; library or by calling <link
    linkend="ch-discover_manpage"><command>discover</command></link> (which
    itself links to the &discover; library) and parsing its output.  In the
    future, other interfaces (for example, modules for interpreted
    languages such as Perl and Python) may be included.</para>

    <para>Why use &discover;?  There are at least a few reasons:</para>

    <itemizedlist>
      <listitem>
        <para><emphasis>Flexibility.</emphasis> &discover; is designed
        from the ground up to be flexible.  It is portable to a variety
        of operating environments, and its modular design supports the
        addition
        of arbitrary methods for querying the host operating system (OS)
        about installed devices.  &discover; is also designed to be
        flexible in terms of the types of data that can be retrieved.
        &discover; does not tie the user to retrieving only one type of
        information, such as the name of the Linux kernel module that
        should be loaded to support a given device.  Instead, &discover;
        supports the association of arbitrary data with hardware devices,
        typically through specification of an interface to the hardware in
        question, such as a Linux kernel module or an XFree86 server driver
        module.</para>
      </listitem>
      <listitem>
        <para><emphasis>Updatability.</emphasis> Many
        hardware-autodetection programs suffer from an inherent
        limitation in that they are restricted to reading hardware
        lists or databases that are stored on the local filesystem.
        This is not an efficient approach in the fast-moving world of
        consumer computer hardware, with new devices constantly being
        introduced.  A couple of months after the latest version of
        your OS of choice is released, it may fail to recognize that
        the latest revision of, for instance, a video chipset is
        compatible with an older one, and can use the same software
        interfaces.  &discover; overcomes this problem by supporting the
        retrieval of hardware information via &http;<footnote><para>Other
        protocols such as &ftp; are available but deprecated; &discover;
        uses integrity verification mechanisms such as
        <acronym>MD5</acronym> checksums in the &http;
        protocol.</para></footnote> (<quote>over the web</quote>).  When
        &http; access is impossible, &discover; falls back to
        locally stored hardware lists.</para>
      </listitem>
      <listitem>
        <para><emphasis>Portability.</emphasis> On top of its
        flexibility in terms of system interfaces to hardware, &discover;
        has been written to be broadly portable to all of
        today's popular POSIX-compliant systems.  &discover; is not a
        Linux-only solution.  &discover; is intended to provide operating
        system vendors, computer manufacturers, and third-party vendors of
        software and peripherals with a powerful tool for describing the
        hardware they support to the interfaces they care about.  Because
        &discover;'s data sources can be anywhere on the Internet, the OS
        vendor need not be the sole provider of hardware catalogs.</para>
      </listitem>
      <listitem>
        <para><emphasis>Usability.</emphasis> &discover; is not an in-house
        tool designed to solve a narrow class of problems.  &discover; is
        designed to be easy to use from the perspectives of the individual
        system administrator, the applications programmer, and the hardware
        manufacturer or support staff.  &discover;'s &xml; database
        structure, its command-line tools, and its library &api; are
        well documented and support extensions to meet diverse
        demands.</para>
      </listitem>
      <listitem>
        <para><emphasis>Freely licensed.</emphasis> &discover; has a
        copyright license that is highly adaptable to the needs of the
        varied audiences to which &discover; is targeted.  Under the
        so-called
        <quote>UCB/BSD</quote> or <quote>MIT/X Consortium</quote> terms,
        after the names of American universities and some very well known
        software projects that used these terms, anyone is free to copy,
        modify, and distribute the software, and to extend (or not) these
        same freedoms to those who receive the software.  Progeny
        would like to see &discover; adopted by a wide variety of existing
        software products, such the various GNU/Linux distributions; the
        FreeBSD, NetBSD, and OpenBSD projects; the GNU Project of the Free
        Software Foundation; the XFree86 Project; system integrators; and
        the designers and manufacturers of computer hardware.
        We believe that &discover;'s design empowers those with the
        greatest knowledge of hardware and the software interfaces to that
        hardware to express
        that knowledge and make it available to the world, thereby
        ameliorating an entire class of computer configuration problems.
        Progeny does not want &discover;'s licensing to stand in the way of
        realizing that dream, which is why we have chosen these license
        terms.</para>
      </listitem>
    </itemizedlist>

    <para>We must take a moment to explain what &discover; is
    <emphasis>not</emphasis>: &discover; is not a replacement for the
    service &mdash; usually provided by the underlying operating system
    kernel or a user-space program that interfaces with it &mdash; of
    simply translating bus-specific vendor and model identifiers to
    human-readable names.  &discover; performs its own translations of
    this data as a convenience for generating human-readable reports, but
    it does not attempt to enumerate all hardware devices that exist for a
    particular bus architecture.  Rather, &discover; is intended only to
    catalog data for which there is some useful information to impart
    regarding software interfaces.  Facilities already exist in modern
    operating systems for answering the questions <quote>What is the name
    of this device?</quote> and <quote>Who manufactured it?</quote>
    &discover;'s role is to answer questions like <quote>What Linux kernel
    module do I need to load for this device to work?</quote>  More
    importantly, &discover; will enable you to provide answers in the
    future to questions you don't even expect to ask today.</para>

    <para>&discover; is not intended to be a comprehensive
    hardware-management tool.  It is an
    <emphasis>enabling technology</emphasis>,
    designed to provide data that a tool layered above it can use.  Two
    applications are provided with &discover; to demonstrate how the
    library can be leveraged: the command-line utility &discover-command;,
    and a Linux kernel module loading script,
    <command>discover-modprobe</command>, designed to be invoked at system
    boot time.</para>

    <para>This manual is divided into four parts.  First, we examine the
    &discover; &xml; data file format, exploring the elements and
    attributes used to describe hardware and various interfaces to it. This
    part will enable you to read and understand a &discover; &xml; file.  
    Next, we offer some recommendations for writing your own &discover;
    &xml; data. Knowing the syntax is valuable, but knowing how best to
    take advantage of it is even more useful.  We then present the
    reference pages describing Progeny's &discover;-based command-line
    tools and the configuration files used to control their behavior. You
    may want to use these references as a guide when implementing your own
    &discover;-based applications.  The final part describes the &discover;
    library &api; so that you can develop your own solutions based on
    &discover;.  Appendices offer references to the formal descriptions of
    the &discover; &api; and &xml; &dtd;s.</para>

  </preface>

  <part id="pt-data_structure">
    <title id="pt-data_structure-title">Data Structure</title>

    <chapter id="ch-overview_discover_data_format">
      <title id="ch-overview_discover_data_format-title">Overview of
      the &discover; Data Format</title>
      <para>Most modern computer peripherals contain self-identifying
      information in a format standardized for the hardware interface
      (bus).  This enables the OS on the host system
      to query or scan a bus and catalog the devices.  In general, the OS
      stores this information in the same basic format in which it is
      returned, without translating it more times than necessary for
      device drivers to communicate with the peripheral.  However, this
      information varies by bus type and is often insufficiently clear for
      human consumption. Furthermore, many operating systems do not contain
      a comprehensive database that maps each peripheral to every subsystem
      running on the OS that may want to communicate with that peripheral.
      &discover; addresses these issues by providing flexible databases
      stored in &xml; format.</para>

      <para>Extensible Markup Language (&xml;) is a highly flexible
      hypertext format. &discover; uses &xml; exclusively to store hardware
      information externally.  Some familiarity with &xml; syntax is
      therefore assumed. For more information,
      see <ulink url="http://www.w3.org/XML/">the
      W3C's &xml; website</ulink>.</para>

      <para>For a formal description of &discover;'s &xml; data format, see
      the &discover; <link linkend="ap-discover_dtd">Document Type
      Definition (&dtd;)</link> document.  The purpose of this document is
      to present the information in a form digestible by the novice.</para>

      <para>Because each hardware bus type, such as &pci; or &usb;,
      communicates different details about the connected devices
      (essentially, each one solves the same problem in a different way),
      &discover; has a different set of lists for each bus type.  For each
      bus, up to three lists are stored: a bus class list
      maps the bus specification's notion of a device type (hereinafter
      referred to as a <quote>device class</quote> to reduce confusion) to
      &discover;'s device types, which are used for running selective
      queries; a vendor list associates bus-specific vendor identification
      data with natural-language names for hardware vendors; and a device
      list contains information specific to individual devices.</para>

    </chapter>

    <chapter id="ch-master_list">
      <title id="ch-master_list-title">Master List</title>

      <para>When &discover; is provided with a &url; for the retrieval of
      hardware information, the data retrieved is expected to be in
      &xml; format and to contain further &url;s for retrieval.</para>

      <para>The root element must be <sgmltag
        class="element">discover-data</sgmltag>, which has no attributes,
        and can only contain <sgmltag class="element">location</sgmltag>
        elements.</para>

      <para>The <sgmltag class="element">location</sgmltag> element is
      always empty, and has three required attributes: <sgmltag
      class="attribute">bus</sgmltag>, <sgmltag
      class="attribute">type</sgmltag>, and <sgmltag
      class="attribute">url</sgmltag>.</para>

      <variablelist>
        <title><sgmltag class="element">location</sgmltag>
        Attributes</title>
        <varlistentry>
          <term><sgmltag class="attribute">type</sgmltag></term>
          <listitem>
            <para>This attribute can have one of these values: <sgmltag
            class="attvalue">busclass</sgmltag>, <sgmltag
            class="attvalue">device</sgmltag>, or <sgmltag
            class="attvalue">vendor</sgmltag>. See <xref
            linkend="ch-busclass_lists"/>, <xref
            linkend="ch-vendor_lists"/>, and <xref
            linkend="ch-device_lists"/>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><sgmltag class="attribute">url</sgmltag></term>
          <listitem>
            <para>This must be a valid &url; containing one of the three
              types of data lists.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><sgmltag class="attribute">bus</sgmltag></term>
          <listitem>
            <para>This is the bus to which the &url; applies.  See <xref
            linkend="sc-busclass_element_name_attribute"/> for a list of
            valid bus names.</para>
          </listitem>
        </varlistentry>

      </variablelist>

    </chapter>

    <chapter id="ch-busclass_lists">
      <title id="ch-busclass_lists-title">Busclass Lists</title>
      <para>As noted in the previous chapter, a busclass list provides a
      mapping between device classes recognized by the hardware bus and the
      device type names used by &discover;.  Because every bus is
      different, sometimes there is no perfect, one-to-one correspondence
      between &discover; device types and the device classes recognized by
      a particular bus.  This is one reason that the busclass lists, like
      other types of &discover; data lists, are updatable.
      Revisions in a bus specification may demand updates to the
      mapping.</para>

      <para>The device classes recognized by a bus are typically determined
      by the specification for the bus as determined by a standards
      committee or other technical body, and do not change frequently (if
      at all).</para>

      <example id="ex-busclass_list">
        <title id="ex-busclass_list-title">The
        <sgmltag>busclass_list</sgmltag> element</title>
        <programlisting><![CDATA[<?xml version="1.0"?>

<busclass_list bus="usb">
  <busclass id="0202" name="modem"/>
  <busclass id="1030" name="broadband"/>
  <busclass id="0101" name="printer"/>
  <busclass id="ffff" name="imaging"/>
  <busclass id="0206" name="network"/>
  <busclass id="0300" name="humaninput"/>
  <busclass id="ff00" name="video"/>
  <busclass id="0000" name="unknown"/>
  <busclass id="0804" name="removabledisk"/>
</busclass_list>]]></programlisting>
      </example>

      <para>In the foregoing example, we can see one possible mapping of
      the &usb; bus's numeric device class IDs to &discover;'s device type
      names (see <xref linkend="sc-busclass_element_name_attribute"/>).
      The file begins by declaring the version of the &xml; standard to
      which it conforms, and then presents data.  The format should be
      fairly familiar to those accustomed to &html;-style structured markup
      languages.</para>

      <para>Not all of &discover;'s supported device types are listed in
      the example; for example, <literal>display</literal> is missing.
      This is not a problem, since not all buses are used for all hardware
      applications.  &usb; 1.1 would be a poor choice of bus for
      &vga;-compatible display controllers, for instance, because the
      available bandwidth on the &usb; 1.1 bus is insufficient to handle
      typical data loads for such devices.</para>

      <para>Another infelicity in the above example is the association of
      the <literal>ffff</literal> device class ID with the &discover; 
      device type <literal>imaging</literal>.  In actuality, a device type 
      class of <literal>ffff</literal> in the &usb; specification indicates 
      a device of an unknown classification.  In practice, most
      consumer-level devices with this device class are scanners, one of 
      the first applications of &usb; technology in the consumer 
      marketplace.  It is
      possible that in certain deployments, the association of &usb;'s
      unknown device class ID with &discover;'s <literal>imaging</literal>
      device type is suboptimal &mdash; another reason the busclass lists
      are not hard-coded into the library.</para>

      <section id="sc-busclass_list_element">
        <title id="sc-busclass_list_element-title">The
        <sgmltag>busclass_list</sgmltag> element</title>

        <para>A <sgmltag>busclass_list</sgmltag> element possesses a
        <sgmltag>bus</sgmltag> attribute and contains one or more
        <sgmltag>busclass</sgmltag> elements.</para>

        <section id="sc-busclass_list_element_bus_attribute">
          <title id="sc-busclass_list_element_bus_attribute-title">The
          <sgmltag>bus</sgmltag> attribute</title>

          <para>The <sgmltag>bus</sgmltag> attribute of the
          <sgmltag>busclass_list</sgmltag> element is set to the name of
          the bus being described by the busclass list.</para>

          <para>The <sgmltag class="attribute">bus</sgmltag> attribute
          presently supports the following values:</para>

          &bus-classes;

          <para>We expect to support more buses in the future;
          <literal>ieee1394</literal> and <literal>sbus</literal> are
          possible candidates.</para>

        </section>
      </section>

      <section id="sc-busclass_element">
        <title id="sc-busclass_element-title">The
        <sgmltag>busclass</sgmltag> element</title>

        <para>A <sgmltag>busclass</sgmltag> element possesses two
        attributes, <sgmltag>id</sgmltag> and <sgmltag>name</sgmltag>, and
        contains no elements.</para>

        <section id="sc-busclass_element_id_attribute">
          <title id="sc-busclass_element_id_attribute-title">The
          <sgmltag>id</sgmltag> attribute</title>

          <para>The <sgmltag>id</sgmltag> attribute is set to a bus-specific
          device class identifier.</para>
        </section>

        <section id="sc-busclass_element_name_attribute">
          <title id="sc-busclass_element_name_attribute-title">The
          <sgmltag>name</sgmltag> attribute</title>

          <para>The <sgmltag>name</sgmltag> attribute is set to a
          &discover; device type.  &discover;'s device types are an effort
          to balance a few criteria:</para>

          <itemizedlist>
            <listitem>
              <para>Device types (<quote>bus classes</quote> in &discover;
              terminology) defined by the &pci; specification</para>
            </listitem>
            <listitem>
              <para>Bus classes defined by the &usb; specification</para>
            </listitem>
            <listitem>
              <para>Bus classes defined by the &scsi; specification</para>
            </listitem>
            <listitem>
              <para>Device types commonly conceived of by the personal
              computer user</para>
            </listitem>
          </itemizedlist>

          <para>&discover;'s definitions of device types will not meet with
          universal agreement; as happens in most categorization problems,
          some decisions had to be made arbitrarily.  &discover; does not
          attempt to solve the general problem of grouping various
          peripherals into categories; rather, &discover; solves the
          problem for itself and uses bus-specific mappings to translate a
          device's own notion of its type to &discover;'s device
          type.</para>

          &device-types;
        </section>
      </section>

    </chapter>

    <chapter id="ch-vendor_lists">
      <title id="ch-vendor_lists-title">Vendor Lists</title>
      <para>Many buses have vendor identification numbers
      that are registered with that bus's standardization body and
      programmed into the devices when they are manufactured.  These
      numbers generally are assigned arbitrarily, and typically have little
      meaning to the end user; therefore, most hardware detection tools
      provide a way to translate these numeric vendor IDs to human-readable
      strings.  Thus, instead of knowing that your &pci; or &agp; video card
      was manufactured by <quote>1002,</quote> you can determine that it
      was manufactured by <quote>ATI Technologies, Inc.</quote></para>

      <example id="ex-vendor_list">
        <title id="ex-vendor_list-title">The <sgmltag>vendor_list</sgmltag>
        element</title>
        <programlisting><![CDATA[<?xml version="1.0"?>

<vendor_list bus="pci">
  <vendor id="0675" name="Dynalink"/>
  <vendor id="0e11" name="Compaq Computer Corporation"/>
  <vendor id="1004" name="VLSI Technology Inc"/>
  <vendor id="1025" name="Acer Incorporated [ALI]"/>
  <vendor id="102b" name="Matrox Graphics, Inc."/>
  <vendor id="109e" name="Brooktree Corporation"/>
</vendor_list>]]></programlisting>
      </example>

      <para>The foregoing example is similar in structure to the <link
      linkend="ex-busclass_list">busclass list example</link>; a numeric
      vendor ID maps to a vendor name, which can be used by &discover; for
      queries or reports generated for the user's benefit.</para>

      <section id="sc-vendor_list_element">
        <title id="sc-vendor_list_element-title">The
        <sgmltag>vendor_list</sgmltag> element</title>

        <para>A <sgmltag>vendor_list</sgmltag> element possesses a
        <sgmltag>bus</sgmltag> attribute and contains one or more
        <sgmltag>vendor</sgmltag> elements.</para>

        <section id="sc-vendor_list_element_bus_attribute">
          <title id="sc-vendor_list_element_bus_attribute-title">The
          <sgmltag>bus</sgmltag> attribute</title>

          <para>The <sgmltag>bus</sgmltag> attribute of the
          <sgmltag>vendor_list</sgmltag> element is set to the name of
          the bus being described by the vendor list.</para>

          <para>The following bus attributes are supported:</para>

          &bus-classes;
        </section>
      </section>

      <section id="sc-vendor_element">
        <title id="sc-vendor_element-title">The <sgmltag>vendor</sgmltag> element</title>

        <para>A <sgmltag>vendor</sgmltag> element possesses two
        attributes, <sgmltag>id</sgmltag> and <sgmltag>name</sgmltag>, and
        contains no elements.</para>

        <section id="sc-vendor_element_id_attribute">
          <title id="sc-vendor_element_id_attribute-title">The <sgmltag>id</sgmltag> attribute</title>

          <para>The <sgmltag>id</sgmltag> attribute is set to a bus-specific
          vendor identifier.</para>
        </section>

        <section id="sc-vendor_element_name_attribute">
          <title id="sc-vendor_element_name_attribute-title">The <sgmltag>name</sgmltag> attribute</title>

          <para>The <sgmltag>name</sgmltag> attribute is set to a
          human-readable vendor identifier, typically the official name of
          the corporation or other business entity that designed or
          manufactured that peripheral.</para>
        </section>
      </section>

    </chapter>

    <chapter id="ch-device_lists">
      <title id="ch-device_lists-title">Device Lists</title>
      <para>The device lists are the heart of &discover;'s functionality.
      They are the most frequently updated lists and contain the
      information of greatest value.</para>

      <para>&discover;'s device lists not only provide a way to identify
      individual peripherals by name, but also permit the specification of
      an arbitrary quantity of organized data for each device, supporting
      an arbitrary number of software interfaces.</para>

      <note>
        <para>The following is a fictitious example.  The information
        within it is for illustrative purposes only.  See <xref
        linkend="pt-data_content"/> for a discussion of the
        <quote>real</quote> hardware data as provided by Progeny, and for
        some suggested conventions on organizing the data namespace.</para>
      </note>

      <example id="ex-sample_device_data">
        <title id="ex-sample_device_data-title">Sample device data</title>
        <programlisting><![CDATA[<?xml version="1.0"?>

<device_list bus="pci">
  <device busclass="1984" model="0101" model_name="Cerebral Reprogrammer" vendor="B16B">
    <data class="linux">
      <data class="module">
        <data class="name">winston</data>
        <data class="options">base_address=0x300 manual_override=0</data>
      </data>
    </data>
    <data class="win2k">
      <data class="hal_driver">
        <data class="StrUglyHungarianNotatedDriverName">settlement</data>
        <data class="flags">NSA_KEY=96b5f3e3283a62c85f6cb6f4017135c2</data>
      </data>
    </data>
  </device>
</device_list>]]></programlisting>
      </example>

      <para>The example above includes a <sgmltag>device_list</sgmltag>
      element containing <sgmltag>device</sgmltag> elements, and a
      <sgmltag>device</sgmltag> element that defines the device itself,
      but reserves any software- or interface-specific details to the
      <sgmltag>data</sgmltag> elements it contains.</para>

      <para>The actual data provided in the example is accessed by means of
      data paths; see <xref linkend="sc-accessing_device_data"/> for 
      further information.</para>

      <section id="sc-device_list_element">
        <title id="sc-device_list_element-title">The
        <sgmltag>device_list</sgmltag> element</title>

        <para>A <sgmltag>device_list</sgmltag> element possesses a
        <sgmltag>bus</sgmltag> attribute and contains one or more
        <sgmltag>device</sgmltag> elements.</para>

        <section id="sc-device_list_element_bus_attribute">
          <title id="sc-device_list_element_bus_attribute-title">The
          <sgmltag>bus</sgmltag> attribute</title>

          <para>The <sgmltag>bus</sgmltag> attribute of the
          <sgmltag>device_list</sgmltag> element is set to the name of
          the bus described by the device list.</para>

          <para>The following bus attributes are supported:</para>

          &bus-classes;
        </section>
      </section>

      <section id="sc-device_element">
        <title id="sc-device_element-title">The <sgmltag>device</sgmltag> element</title>

        <para>A <sgmltag>device</sgmltag> element possesses four attributes:</para>

        <itemizedlist>
          <listitem>
            <para><sgmltag>busclass</sgmltag></para>
          </listitem>
          <listitem>
            <para><sgmltag>vendor</sgmltag></para>
          </listitem>
          <listitem>
            <para><sgmltag>model</sgmltag></para>
          </listitem>
          <listitem>
            <para><sgmltag>model_name</sgmltag></para>
          </listitem>
        </itemizedlist>

        <para>All of these attributes must be specified for each
        <sgmltag>device</sgmltag> element.  The <sgmltag>busclass</sgmltag>
        attribute is set to a <link
        linkend="sc-busclass_element_id_attribute">busclass
        identifier</link>, <sgmltag>vendor</sgmltag> to a <link
        linkend="sc-vendor_element_id_attribute">vendor
        identifier</link>, <sgmltag>model</sgmltag> to a bus-specific
        model identifier, and <sgmltag>model_name</sgmltag> to a
        human-readable vendor identifier, typically the name of the product
        under which the device reporting the <sgmltag>model</sgmltag>
        identifier is sold or otherwise distributed.</para>

        <para>A <sgmltag>device</sgmltag> element contains zero or more
        <sgmltag>data</sgmltag> elements.</para>

      </section>

      <section id="sc-data_element">
        <title id="sc-data_element-title">The <sgmltag>data</sgmltag> element</title>

        <para>A <sgmltag>data</sgmltag> element possesses a mandatory
        <sgmltag>class</sgmltag> attribute, an optional
        <sgmltag>version</sgmltag> attribute, and zero or more
        <sgmltag>data</sgmltag> elements.</para>

        <para>The ability to nest <sgmltag>data</sgmltag> elements inside
        other <sgmltag>data</sgmltag> 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.</para>

        <section id="sc-data_element_class_attribute">
          <title id="sc-data_element_class_attribute-title">The <sgmltag>class</sgmltag> attribute</title>

          <para>A <sgmltag>class</sgmltag> attribute is set to an arbitrary
          value determined by an interface designer.  For
          <sgmltag>data</sgmltag> elements whose parent element is a
          <sgmltag>device</sgmltag> element, this should be the name of
          the interface being described, such as
          <literal>freebsd</literal>, <literal>linux</literal>, or
          <literal>xfree86</literal>.</para>

          <para>A <sgmltag>data</sgmltag> element whose parent element is a
          <sgmltag>data</sgmltag> element should set this attribute to a
          term reflecting the interface designer's intended data hierarchy.
          &discover; does not mandate any particular hierarchy for
          interface designers.</para>
        </section>

        <section id="sc-data_element_version_attribute">
          <title id="sc-data_element_version_attribute-title">The <sgmltag>version</sgmltag> attribute</title>

          <para>Data elements have an optional attribute named <sgmltag
          class="attribute">version</sgmltag>.  This indicates a version
          <emphasis>range</emphasis> applicable to the data contained
          within the element.  The purpose of this attribute is to permit
          the specification of data that is valid only for a range of
          versions of the given interface.  For example, the Linux kernel
          changed some of the names of its modules between the 2.2 and 2.4
          series.</para>

          <para>&discover;'s range syntax, common in mathematical writings,
          is expressed as an interval; that is, it consists of a pair of
          endpoints with a comma between them, and brackets or parentheses
          as qualifiers for inclusion or exclusion of the endpoints' exact
          values.  For example, the version specification <literal>[1.0,
          2.0)</literal> matches any version less than 2.0 and greater
          than or equal to 1.0.  It is the responsibility of the calling
          environment to specify the version of the interface actually in
          use.  In other words, the &discover; library does not take it
          upon itself to determine the currently running version of the
          Linux kernel, XFree86 X server, CUPS printing daemon, and so
          forth.</para>

          <para>Due to the lack of consistent standards for version numbers
          (in fact, some version numbers aren't numbers at all),
          &discover; requires simplifications for the <sgmltag
          class="attribute">version</sgmltag> attribute.  The versions that
          express the range must be in dotted-decimal form, such as
          <literal>7.1.0</literal>.  The version that is supplied to the
          &discover; library as part of a query (for example, via the
          <option>--data-version</option> argument to &discover-command;)
          may or may not comply with this requirement, but should
          be expressed such that it compares in a desirable way against
          version strings that do.</para>

          <para>In place of the upper end of the range,
          <literal>inf</literal> (infinity) can be used if the information
          is still relevant and should be for forseeable versions.</para>

        </section>

      </section>

      <section id="sc-accessing_device_data">
        <title id="sc-accessing_device_data-title">Accessing the Device
        Data</title>

        <para>&discover; data is grouped into hierarchical <sgmltag
        class="element">data</sgmltag> elements.  This data can be accessed
        via its data path.  The data path is the concatenation of the class
        attribute values of a <sgmltag class="element">data</sgmltag>
        element and all its parents, separated by slash
        (<literal>/</literal>) characters.  In the following example,
        <literal>quux</literal> is accessed via the data path
        <quote>foo/bar</quote>:</para>

        <informalexample>
          <programlisting><![CDATA[<data class="foo">
  <data class="bar">quux</data>
</data>]]></programlisting>
        </informalexample>

        <para>In <xref linkend="ex-sample_device_data"/> above, we would
        determine the name of the Linux kernel module
        (<quote>winston</quote>) for the <quote>Cerebral
        Reprogrammer</quote> device by referencing the data path
        <literal>linux/module/name</literal>; similarly, the data path
        <literal>win2k/hal_driver/flags</literal> returns
        <literal>NSA_KEY=96b5f3e3283a62c85f6cb6f4017135c2</literal>.</para>

      </section>

    </chapter>
  </part>

  <part id="pt-data_content">
    <title id="pt-data_content-title">Recommended Data Content Conventions</title>

    <partintro>
      <para>As discussed in the <link
      linkend="pr-what_is_discover">preface</link>, &discover; is not
      intended to be a replacement for system utilities such as
      <command>lspci</command> on Linux.  A
      <sgmltag class="element">device</sgmltag> element should exist
      for a piece of hardware only if there is some interface information
      to communicate about the hardware; that is, some 
      <sgmltag class="element">data</sgmltag> elements to house within the
      <sgmltag class="element">device</sgmltag> element. This part of the
      manual contains Progeny's recommendations on how to organize that
      information for maximum utility.</para>
    </partintro>

    <chapter id="ch-data_hierarchy">
      <title id="ch-data_hierarchy-title">Data Hierarchy</title>

      <para>As discussed in <xref linkend="sc-accessing_device_data"/>, the
      &xml; structure around the data allows for a hierarchical
      view.</para>

      <para>While &discover; does not mandate any particular hierarchy or
      namespace organization for <sgmltag class="element">data</sgmltag>
      elements, the &xml; files provided by Progeny express &mdash; and
      some applications based on &discover; (such as
      <command>discover-modprobe</command>) expect &mdash; a certain
      structure for Linux kernel module and XFree86 configuration
      information.</para>

      <para>At Progeny, we have often found it convenient to refer to a
      top-level <sgmltag class="element">data</sgmltag> element's <sgmltag
      class="attribute">class</sgmltag> attribute value as an
      <quote>interface</quote> (see the following example).</para>

      <example id="ex-defining_an_interface">
        <title id="ex-defining_an_interface-title">Defining an interface</title>
        <programlisting><![CDATA[<device busclass="0300" vendor="de8d" model="90a9" model_name="Stingray">
  <data class="xfree86">
    <data class="server" version="[3, 4)">
      <data class="name">XF86_SVGA</data>
    </data>
  </data>
  <data class="openbsd">
    <data class="security_level">untrusted</data>
  </data>
</device>]]></programlisting>
      </example>

      <para>In <xref linkend="ex-defining_an_interface"/>, two interfaces
      have been defined for the <quote>Stingray</quote> device:
      <literal>xfree86</literal> and <literal>openbsd</literal>.</para>

      <section id="sc-linux_kernel_modules">
        <title id="sc-linux_kernel_modules-title">Linux Kernel Modules</title>

        <para>A hardware device that requires a particular Linux kernel
        module should have nested <sgmltag class="element">data</sgmltag>
        elements to describe that module.  The top-level <sgmltag
        class="element">data</sgmltag> element should have a <sgmltag
        class="attribute">class</sgmltag> attribute with a value of
        <sgmltag class="attvalue">linux</sgmltag>.  Underneath that should
        be a <sgmltag class="element">data</sgmltag> element with a
        <sgmltag class="attribute">class</sgmltag> of <sgmltag
        class="attvalue">module</sgmltag>.</para>

        <para>Within that <sgmltag class="element">data</sgmltag> element,
        there should be one or two more, one with a <sgmltag
        class="attribute">class</sgmltag> of <sgmltag
        class="attvalue">name</sgmltag>, and an optional one with a
        <sgmltag class="attribute">class</sgmltag> of <sgmltag
        class="attvalue">options</sgmltag>.  The former has as content the
        name of the module; the latter, options to be passed to
        <command>modprobe</command>.</para>

        <figure id="fg-linux_interface">
          <title id="fg-linux_interface-title">Linux interface</title>
          <screen><![CDATA[/linux
    |
    |-/module
          |
          |-/name
          |
          |-/options]]></screen>
        </figure>

        <para>In <xref linkend="fg-linux_interface"/>, each component of
        the tree represents a <sgmltag class="element">data</sgmltag>
        element; the label is the value of its <sgmltag
        class="attribute">class</sgmltag> attribute.</para>

        <para>If the kernel version affects the choice of module name or
        options, the top-level <sgmltag class="attvalue">linux</sgmltag>
        <sgmltag class="element">data</sgmltag> element should have a
        version range attribute; see <xref
        linkend="sc-data_element_version_attribute"/>.</para>

        <example id="ex-using_linux_interface">
          <title id="ex-using_linux_interface-title">Using the <sgmltag class="attvalue">linux</sgmltag> interface</title>
          <programlisting><![CDATA[<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>]]></programlisting>
        </example>

        <para>See <xref 
        linkend="ex-using_version_attribute_of_data_element"/> for guidance
        on how to specify different Linux kernel modules for the same
        device, depending on the version of the Linux kernel in use.</para>

      </section>

      <section id="sc-xfree86_x_servers">
        <title id="sc-xfree86_x_servers-title">XFree86 X Servers</title>

        <para>The data hierarchy of a video card device (&discover;'s
        <literal>display</literal> type) should include a top-level
        <sgmltag class="element">data</sgmltag> element with a <sgmltag
        class="attribute">class</sgmltag> attribute of <sgmltag
        class="attvalue">xfree86</sgmltag> (the interface)
        and likely with a <sgmltag class="attribute">version</sgmltag>
        attribute as well; nested within that element will be a <sgmltag
        class="attvalue">server</sgmltag> <sgmltag
        class="element">data</sgmltag> element containing a <sgmltag
        class="attvalue">name</sgmltag> <sgmltag
        class="element">data</sgmltag> element identifying the name of the
        server executable.  For XFree86 version 4.0 or greater, the
        <sgmltag class="attvalue">name</sgmltag> will always be <sgmltag
        class="attvalue">XFree86</sgmltag>, and the <sgmltag
        class="attvalue">server</sgmltag> <sgmltag
        class="element">data</sgmltag> element will also contain a <sgmltag
        class="attvalue">device</sgmltag> <sgmltag
        class="element">data</sgmltag> element, which contains one or more
        <sgmltag class="element">data</sgmltag> elements communicating
        information to be stored in the <filename>XF86Config</filename>
        file.  The children of the <sgmltag
        class="attvalue">device</sgmltag> <sgmltag
        class="element">data</sgmltag> element are named in correspondence
        with the syntax of the <filename>XF86Config</filename> file's
        <literal>Device</literal> section; see the <ulink
        url="http://www.xfree86.org/current/XF86Config.5.html">XF86Config
        manual page</ulink> for further information.  In particular, note
        that in many cases only a
        <sgmltag class="attvalue">driver</sgmltag> <sgmltag
        class="element">data</sgmltag> element is necessary.</para>

        <figure id="fg-xfree86_interface">
          <title id="fg-xfree86_interface-title">XFree86 interface</title>
          <screen><![CDATA[/xfree86
    |
    |-/server
          |
          |-/name
          |
          |-/device
                |
                |-/driver
                |
                |-/chipid
                |
                |-/chipset
                |
                |-/ramdac
                |
                |-/dacspeed
                |
                |-/videoram
                |
                |-/options
                |
                |-...]]></screen>
        </figure>

        <para><xref linkend="fg-xfree86_interface"/> illustrates the
        <sgmltag class="attvalue">xfree86</sgmltag>
        interface.  <xref linkend="ex-using_xfree86_interface"/> shows
        how you might write <sgmltag class="attvalue">xfree86</sgmltag>
        interface information for a &discover; <sgmltag
        class="attvalue">display</sgmltag> device.</para>

        <example id="ex-using_xfree86_interface">
          <title id="ex-using_xfree86_interface-title">Using the <sgmltag class="attvalue">xfree86</sgmltag> interface</title>
          <programlisting><![CDATA[<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>]]></programlisting>
        </example>
      </section>

      <section id="sc-locally-defined_interfaces">
        <title id="sc-locally-defined_interfaces-title">Locally-Defined Interfaces</title>

          <para>Progeny recommends that publicly distributed &discover;
          &xml; files avoid using the interface name
          <literal>local</literal>; that is, a
          <sgmltag class="attribute">class</sgmltag> attribute value of
          <literal>local</literal> in a top-level
          <sgmltag class="element">data</sgmltag> element.  This
          means that data paths such as <literal>local/foo/bar</literal>
          should not be defined in a public &discover; &xml; file, but
          both <literal>foo/bar/local</literal> and
          <literal>foo/local/bar</literal> are okay.</para>

          <para>The intention is to reserve this part of the namespace
          for users' experiments with defining their own &mdash;
          and possibly future, widely adopted &mdash; interface definitions
          for &discover; data.  An interface definition could thus be
          <quote>beta tested</quote> 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.</para>

          <para>Likewise, Progeny recommends that authors of applications
          that use &discover; avoid traversing into a top-level
          <literal>local</literal> <sgmltag class="element">data</sgmltag>
          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.)</para>
      </section>

    </chapter>

    <chapter id="ch-order-matters">
      <title id="ch-order-matters-title">Why Order Matters</title>

      <para>When searching device elements, the first exact match will be
      selected.  Subsequent matches are ignored.
      </para>

      <para>Specifically, three comparisons are made:</para>

      <orderedlist>
        <listitem>
          <para>The hardware must provide identification that matches
          attributes of the <sgmltag>device</sgmltag> element.  As an
          example, a &pci; device supplies numeric vendor and model
          identifiers, which are used to match the
          <sgmltag>model</sgmltag> and <sgmltag>vendor</sgmltag>
          attributes.</para>
        </listitem>
        <listitem>
          <para>The <sgmltag>class</sgmltag> attributes of child
          <sgmltag>data</sgmltag> elements must match the data path as
          given to the library for searching.</para>
        </listitem>
        <listitem>
          <para>The first version range, if any, associated with the nested
          <sgmltag>data</sgmltag> elements must encompass any
          version provided by the client.</para>
        </listitem>
      </orderedlist>

      <example>
        <title>Matching <sgmltag>device</sgmltag> elements</title>

        <para>Assume that the path <literal>linux/module/name</literal> is
        provided, along with a version of 2.4.2.  The following is sample
        data; the <sgmltag>device</sgmltag> elements may be from the same
        or different data files.</para>

        <programlisting><![CDATA[
<device busclass="0000" vendor="102f" model="5555" model_name="100VG ethernet">
  <data class="linux" version="[2.4, inf)">]]><co id="bad_name"/><![CDATA[
    <data class="modules">
        <data class="name">vg100</data>
    </data>
  </data>
  <data class="linux" version="[2.0, 2.2)">]]><co id="range_20to22"/><![CDATA[
    <data class="module">
        <data class="name">vg100</data>
        <data class="options">io=0x300</data>
    </data>
  </data>
</device>

<device busclass="0000" vendor="102f" model="5555" model_name="100VG ethernet">
  <data class="linux">]]><co id="blank_range"/><![CDATA[
    <data class="module">
        <data class="name">vg100new</data>
    </data>
  </data>
  <data class="linux" version="[2.4, inf)">]]><co id="range_24toinf"/><![CDATA[
    <data class="module">
        <data class="name">vg100old</data>
    </data>
  </data>
</device>

]]></programlisting>

        <calloutlist>
          <callout arearefs="bad_name">
            <para>This item is the first one scanned, and would match,
            except that the requested data path includes
            <quote>module</quote> as a component, not
            <quote>modules</quote> as specified here.</para>
          </callout>
          <callout arearefs="range_20to22">
            <para>This item doesn't match because the provided range is
            outside the limits defined by the element. (2.4.2 is not
            greater than or equal to 2.0 and less than 2.2.)</para>
          </callout>
          <callout arearefs="blank_range">
            <para>This item matches because no range is given, so
            <quote>vg100new</quote> is the value returned.</para>
          </callout>
          <callout arearefs="range_24toinf">
            <para>This is the nearest match, but the &discover; library
            will never select it because its previous sibling has no
            version range, and thus will catch any version provided.</para>
          </callout>
        </calloutlist>
      </example>
    </chapter>

    <chapter id="ch-using_data_versioning">
      <title id="ch-using_data_versioning-title">Using Data Versioning</title>

      <section id="sc-specifying_range">
        <title id="sc-specifying_range-title">Specifying a Range</title>

        <para>Because multiple versions of a software interface often are
        in simultaneous deployment, Progeny recommendeds that the upper
        bound of a <sgmltag class="element">data</sgmltag> element's
        <sgmltag class="attribute">version</sgmltag> 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 <literal>rtl8139</literal> in the 2.2
        kernel series and <literal>8139too</literal> in the 2.4 series.  To
        express this, we would say the following:</para>

        <example id="ex-using_version_attribute_of_data_element">
          <title
          id="ex-using_version_attribute_of_data_element-title">Using the
          <sgmltag>version</sgmltag> attribute of the
          <sgmltag>data</sgmltag> element</title>
        <programlisting><![CDATA[<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>]]></programlisting>
        </example>

        <para>In the first data element, for instance, we would not use a
        version attribute of <literal>[2.2.0,2.2.19]</literal> because it is needlessly specific.  What happens if the Linux kernel
        developers release Linux kernel 2.2.20?  By saying
        <literal>[2.2,2.4)</literal>, we <quote>catch</quote> everything in
        the kernel 2.2 series<footnote><para>We would say
        <literal>[2.2,2.3)</literal> instead, but, like many Free Software
        projects, the Linux kernel uses odd minor version numbers to
        denote unstable, development series of the software, and even minor
        version numbers to denote stable, production series of the
        software. In the example, then, we arbitrarily treat all 2.3 series
        kernels the same as 2.2 kernels.</para></footnote> &mdash; past,
        present, and future.</para>

      </section>

      <section id="sc-how_discover_library_matches_range">
        <title id="sc-how_discover_library_matches_range-title">How the &discover; Library Matches a Range</title>

        <para>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.</para>

        <para>Recalling the discussion in <xref
        linkend="sc-data_element_version_attribute"/>, if you want the
        first data element matching the requested data path to also be the
        <quote>fallback</quote> 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 <literal>[2.4, inf)</literal> for
        Linux kernel modules in
        <xref linkend="ex-using_version_attribute_of_data_element"/>.  This
        will have the effect of <quote>assuming</quote> that
        all unversioned requests for <literal>linux</literal> data will be
        for Linux kernel 2.4 or later.</para>
      </section>
    </chapter>

  </part>

  <part id="pt-command-line_tools">
    <title id="pt-command-line_tools-title">Command-Line Tools</title>
    <chapter id="ch-discover_manpage">
      <title id="ch-discover_manpage-title"><command>discover</command> Manual Page</title>

    <refentry>
      &discover-1;
    </refentry>
    </chapter>
    <chapter id="ch-discover-conf_manpage">
      <title
      id="ch-discover-conf_manpage-title"><filename>discover.conf</filename> Manual Page</title>
      <refentry>
        &discover-conf-5;
      </refentry>
    </chapter>
    <chapter id="ch-discover-modprobe_manpage">
      <title
      id="ch-discover-modprobe_manpage-title"><command>discover-modprobe</command>
      Manual Page</title>
        <refentry>
          &discover-modprobe-8;
        </refentry>
    </chapter>

    <chapter id="ch-discover-modprobe-conf_manpage">
      <title
      id="ch-discover-modprobe-conf_manpage-title"><filename>discover-modprobe.conf</filename>
      Manual Page</title>
        <refentry>
          &discover-modprobe-conf-5;
        </refentry>
    </chapter>
  </part>

  <part id="pt-library">
    <title id="pt-library-title">Library</title>
    <chapter id="ch-discover_library">
      <title id="ch-discover_library-title">The &discover; Library</title>

      <section id="sc-library_design_principles">
        <title id="sc-library_design_principles-title">Library Design
        Principles</title>

        <para>Lazy allocation is used throughout &discover;.  This means
        that there are no <quote>init</quote> 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.</para>
      </section>

      <section id="sc-discover_data_sources">
        <title id="sc-discover_data_sources-title">&discover; Data
        Sources</title>

        <para>&discover; knows about one data source by default: the local
        data from the <literal>discover-data</literal> package.  Additional
        sources can be added with the
        <function>discover_conf_append_url</function> and
        <function>discover_conf_insert_url</function> functions.  As their
        names suggest, they append or insert &url;s on the data source
        list.  Earlier data overrides later data; to override
        the local data sources, insert &url;s.</para>
        <!-- XXX: Need to verify the insert/append behavior -->
      </section>

      <section id="sc-bus_map">
        <title id="sc-bus_map-title">The Bus Map</title>

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

        <para>The following functions are available in the bus map.  The
        <quote>get</quote> functions take a single <ulink
        url="api-reference/group__types.html#a1"><type>discover_error_t</type></ulink>
        argument and return a list of <ulink
        url="api-reference/group__types.html#a3"><type>discover_device_t</type></ulink>
        structures, while the <quote>free</quote> functions take no
        arguments and return no value.</para>

        <variablelist>
          <varlistentry>
            <term><function>get_devices</function></term>
            <listitem>
              <para>Retrieve the list of devices found on this bus.
              Returns NULL if the bus is not present on the
              system, or if no devices are attached to it.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><function>xml_get_busclasses</function></term>
            <listitem>
              <para>Retrieve the list of busclasses for this bus (from
              the &xml; data sources).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><function>xml_get_devices</function></term>
            <listitem>
              <para>Retrieve the list of devices for this bus (from
              the &xml; data sources).  Note that this is the list of
              devices that &discover; knows about, not the list of devices
              present on the system.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><function>xml_get_vendors</function></term>
            <listitem>
              <para>Retrieve the list of vendors for this bus (from
              the &xml; data sources).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><function>xml_get_busclass_urls</function></term>
            <listitem>
              <para>Retrieve the list of &url;s from which busclass data
              is retrieved.  This function is probably not useful to
              most clients.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><function>xml_get_device_urls</function></term>
            <listitem>
              <para>Retrieve the list of &url;s from which device data
              is retrieved.  This function is probably not useful to
              most clients.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><function>xml_get_vendor_urls</function></term>
            <listitem>
              <para>Retrieve the list of &url;s from which vendor data
              is retrieved.  This function is probably not useful to
              most clients.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><function>free_devices</function></term>
            <listitem>
              <para>Free the list of devices.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><function>xml_free_busclasses</function></term>
            <listitem>
              <para>Free the list of busclasses.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><function>xml_free_devices</function></term>
            <listitem>
              <para>Free the list of devices (the &xml; data, not the
              list of devices found on the system).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><function>xml_free_vendors</function></term>
            <listitem>
              <para>Free the list of vendors.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><function>xml_free_busclass_urls</function></term>
            <listitem>
              <para>Free the list of busclass &url;s.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><function>xml_free_device_urls</function></term>
            <listitem>
              <para>Free the list of device &url;s.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><function>xml_free_vendor_urls</function></term>
            <listitem>
              <para>Free the list of vendor &url;s.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>

      <section id="sc-scanning_system">
        <title id="sc-scanning_system-title">Scanning the System</title>

        <para>&discover; provides a few ways to scan the system for
        information.</para>

        <para>You can walk the bus map:</para>

        <informalexample>
          <programlisting><![CDATA[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);
    }
}]]></programlisting>
        </informalexample>

        <para>You can scan a specific bus:</para>

        <informalexample>
          <programlisting><![CDATA[devices = discover_get_pci_devices(&status);
check_status(status);
do_something_cool(devices);]]></programlisting>
        </informalexample>

        <para>Perhaps most usefully, you can scan for devices
        of a specific type:</para>

        <informalexample>
          <programlisting><![CDATA[devices = discover_device_find("video", &status);
check_status(status);
do_something_video(devices);]]></programlisting>
        </informalexample>
      </section>

      <section id="sc-using_discover_device_t_structures">
        <title id="sc-using_discover_device_t_structures-title">Using
        <type>discover_device_t</type> Structures</title>

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

        <para><function>discover_device_get_data</function> takes a
        <link linkend="sc-accessing_device_data">data path</link> and a
        <link linkend="sc-data_element_version_attribute">version
        number</link> and searches for the first data structure that
        matches.</para>

        <para><function>discover_device_get_vendor_name</function>
        returns the human-readable name for the device's
        vendor.</para>

        <para><function>discover_device_get_model_name</function>
        returns the human-readable name for the device's model.</para>

        <para><function>discover_device_get_model_id</function>
        returns the bus-specific ID for the device model.</para>

        <para><function>discover_device_get_vendor_id</function>
        returns the bus-specific ID for the device vendor.</para>
      </section>
    </chapter>

    <chapter id="ch-sysdeps">
      <title id="ch-sysdeps-title">System Dependencies</title>

      <section id="sc-sysdeps_api">
        <title id="sc-sysdeps_api-title">&api;</title>

        <para>The system-dependent code (<firstterm>sysdeps</firstterm>)
        that must be custom-written for each operating system conforms to a
        very simple &api;.  &discover; invokes
        <function>_discover_get_<replaceable>busname</replaceable>_raw()</function>
        with no arguments, and expects a linked list of
        <ulink url="api-reference/sysdep_8h.html#a0"><type>discover_sysdep_data_t</type></ulink> structures in return.</para>

        <para>The <ulink url="api-reference/sysdep_8h.html#a0"><type>discover_sysdep_data_t</type></ulink> structures should
        contain as much descriptive information as they can regarding the
        devices discovered.  Specifically, the three pieces of information
        desired are the <link
        linkend="ch-busclass_lists">busclass</link> (device
        type), <link linkend="ch-vendor_lists">vendor
        identifier</link>, and model identifier, which is a unique
        identification string that the vendor has provided for the given
        piece of hardware.</para>

        <example>
          <title>Linux &pci; sysdep code</title>

          <programlisting><![CDATA[#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;
}]]>
</programlisting>
        </example>
      </section>
    </chapter>
  </part>

  <appendix id="ap-discover_api_reference">
    <title id="ap-discover_api_reference-title">&discover; &api; Reference</title>

    <para>The &api; reference is <ulink
    url="api-reference/index.html">here</ulink>.</para>
  </appendix>

  <appendix id="ap-discover_dtd">
    <title id="ap-discover_dtd-title">&discover; &dtd;</title>
    <programlisting>
<inlinegraphic format='linespecific' fileref="../discover.dtd"/>
    </programlisting>
  </appendix>

  <appendix id="ap-discover_conf_dtd">
    <title id="ap-discover_conf_dtd-title">&discover; Configuration File &dtd;</title>
    <programlisting>
<inlinegraphic format='linespecific' fileref="../etc/conffile.dtd"/>
    </programlisting>
  </appendix>

  <appendix id="ap-licensing_issue_linux_sysdeps">
    <title id="ap-licensing_issue_linux_sysdeps-title">Licensing Issue on the Linux Sysdeps</title>

    <para>It should be noted that the Linux-specific files in the
    <filename>sysdeps/linux</filename> directory of the source distribution
    are derived from code written for the <application>Detect</application>
    library by MandrakeSoft SA, and are licensed under the
    <acronym>GNU</acronym> Project's <ulink
    url="http://www.gnu.org/copyleft/gpl.html">General Public
    License</ulink> (<acronym>GPL</acronym>).</para>

    <para>Note that section 2 of the <acronym>GPL</acronym> places
    requirements on derived works that prevent licensees from exercising
    some of the permissions granted under the license on the rest of
    &discover;.  However, not everyone who modifies or distributes
    &discover; will necessarily be subject to the terms of the
    <acronym>GPL</acronym>.  If you do not compile, use, or distribute the
    Linux sysdeps (for instance, if you are building &discover; for
    FreeBSD), then the license terms on them do not attach.</para>

    <para>We realize, however, that it is desirable that all of &discover;
    be under the the same license terms.  There are a few possible
    solutions to this problem:</para>

    <itemizedlist>
      <listitem>
        <para>If you do not need the Linux sysdeps, you can delete them
        from your copy of &discover;.</para>
      </listitem>
      <listitem>
        <para>You can rewrite the Linux sysdeps.  The resulting code will
        be your work, so the only limitations on you will be those imposed
        by &discover;'s license.  If you do so, we encourage you to license
        your rewrite under the same terms as the rest of &discover; &mdash;
        in that event, Progeny will be happy to incorporate your code into
        a future release of &discover;.</para>
      </listitem>
      <listitem>
        <para>You can contact MandrakeSoft SA and negotiate a different
        license to their code that is used in the Linux sysdeps.</para>
      </listitem>
      <listitem>
        <para>You can contact MandrakeSoft SA and attempt to persuade them
        to relicense their code that is used in the Linux sydeps
        under the terms used by the rest of &discover;. (MandrakeSoft SA
        would not have to abandon or assign their copyright.)  If you
        succeed in this effort, please let Progeny know and we will update
        the license terms on our copy of the MandrakeSoft SA code.</para>
      </listitem>
      <listitem>
        <para>You can wait; eventually Progeny employees, or some
        volunteer, will rewrite the Linux sysdeps and license them under
        the terms that the rest of &discover; uses.</para>
      </listitem>
    </itemizedlist>

    <note>
      <para>The foregoing discussing is not legal advice and makes no claim
      to be such.  It is a layperson's understanding of the licensing
      issues from a software developer's perspective.  Progeny makes no
      warranties or guarantees as to the accuracy of the above
      analysis in a legal context.  If you require a professional legal
      opinion, consult attorneys specializing in copyright and licensed to
      practice in the jurisdictions of interest to you or to your
      organization.</para>
    </note>
  </appendix>

</book>

<!-- vim: set ai et tw=75 sw=2 sts=2: -->
<!--  Local variables: -->
<!--  eval: (sgml-load-dtd "../doctools/docbook-book.ced") -->
<!--  End: -->