<!--
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.
-->

  <refentryinfo>
    <releaseinfo>$Progeny$</releaseinfo>

    <authorgroup>
      &author.jdaily;
    </authorgroup>
    <copyright>
      <year>2002</year>
      <holder>&progeny.inc;</holder>
    </copyright>
  </refentryinfo>

  <refmeta>
    <refentrytitle>discover</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>discover</refname>
    <refpurpose>hardware detection utility</refpurpose>
  </refnamediv>

  <refsynopsisdiv>

    <cmdsynopsis>
      <command>discover</command>
      <arg choice="opt">DATA_OPTIONS</arg>
      <arg choice="opt">DISPLAY_OPTIONS</arg>
      <arg choice="opt">--bus-summary</arg>
      <arg choice="opt" rep="repeat">bus</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>discover</command>
      <arg choice="opt">DATA_OPTIONS</arg>
      <arg choice="opt">DISPLAY_OPTIONS</arg>
      <arg choice="plain">--type-summary</arg>
      <arg choice="opt" rep="repeat">type</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>discover</command>
      <arg choice="opt">DATA_OPTIONS</arg>
      <arg choice="plain" rep="repeat">--data-path=<replaceable>path/to/data</replaceable></arg>
      <arg choice="opt">--data-version=<replaceable>version</replaceable></arg>
      <arg choice="opt">--normalize-whitespace</arg>
      <arg choice="opt">--format=<replaceable>format string</replaceable></arg>
      <arg choice="opt" rep="repeat">type | id</arg>
    </cmdsynopsis>

    <variablelist>
      <varlistentry>
        <term>DATA_OPTIONS</term>
        <listitem>
          <itemizedlist>
            <listitem>
              <para><option>-d | --disable-bus=<replaceable>bus</replaceable></option></para>
            </listitem>
            <listitem>
              <para><option>-e | --enable-bus=<replaceable>bus</replaceable></option></para>
            </listitem>
            <listitem>
              <para><option>--insert-url=<replaceable>url</replaceable></option></para>
            </listitem>
            <listitem>
              <para><option>--append-url=<replaceable>url</replaceable></option></para>
            </listitem>
            <listitem>
              <para><option>-v | --verbose</option></para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>DISPLAY_OPTIONS</term>
        <listitem>
          <itemizedlist>
            <listitem>
              <para><option>--model | --no-model</option></para>
            </listitem>
            <listitem>
              <para><option>--model-id | --no-model-id</option></para>
            </listitem>
            <listitem>
              <para><option>--vendor | --no-vendor</option></para>
            </listitem>
            <listitem>
              <para><option>--vendor-id | --no-vendor-id</option></para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsynopsisdiv>


  <refsect1 id="d1-rs-description">
    <title id="d1-rs-title-description">Description</title>

    <para>&discover-command; provides an extensible hardware
    detection and reporting interface. Hardware information is stored in an
    &xml; data format and can be retrieved across the network.</para>

    <para>Fundamental modes of operation:</para>

    <itemizedlist>
      <listitem>
        <para>Display a list of hardware devices based on type of device or
          system bus on which the devices reside, via
          <option>--type-summary</option> or
          <option>--bus-summary</option> (the latter of which is the
          default behavior).
          <!-- If you reformat the above lines, please view the roff
          output and watch for excessive whitespace.
          -->
        </para>
      </listitem>

      <listitem><para>Query specified data for attached hardware, via
          <option>--data-path</option>.</para></listitem>
    </itemizedlist>
  </refsect1>

  <refsect1 id="d1-rs-options">
    <title id="d1-rs-title-options">Options</title>

    <variablelist>
      <varlistentry>
        <term><option>-h | --help</option></term>
        <listitem>
          <para>Display a simple help message.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-v | --verbose</option></term>
        <listitem>
          <para>Instruct the tool to provide feedback as it operates. This
          will affect the output as &discover-command; parses certain
          arguments, so this should appear early in the command line.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-V | --version</option></term>
        <listitem>
          <para>Display the tool name and version.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-b | --bus-summary</option></term>
        <listitem>
          <para>This is the default behavior: Display basic information
          regarding all devices on the appropriate buses. See
          <xref linkend="d1-rs-bus-selection" endterm="d1-rs-title-bus-selection"/>.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-t | --type-summary</option></term>
        <listitem>
          <para>Summarize devices by class of hardware. Examples of valid
          device types include <literal>broadband</literal>,
          <literal>fixeddisk</literal>,
          <literal>display</literal>, and
          <literal>network</literal>.  See <xref
          linkend="d1-rs-device-types" endterm="d1-rs-title-device-types"/>.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--data-path=<replaceable>path/to/data</replaceable></option></term>
        <listitem>
          <para>Query matching devices for detailed information.
          Device-specific data is stored in a hierarchical
          fashion, and the query argument comprises strings
          naming each level in that hierarchy.</para>

          <para>Typically, the top-level component of the data
          path will be the <quote>platform</quote> that will need
          the information, such as <literal>linux</literal> or
          <literal>xfree86</literal>. For example, to retrieve
          the Linux kernel module name for a piece of hardware,
          the <option>--data-path</option> argument would be
          <literal>linux/module/name</literal>.</para>

          <para>If multiple <option>--data-path</option>
          arguments are given and no format string (see
          <option>--format</option>) is provided, only the last
          path is used.</para>

          <para>See also the <option>--data-version</option>
          argument.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--data-version=<replaceable>version</replaceable></option></term>
        <listitem>
          <para>Specify a version string for the platform that
          will use the information specified by the argument to
          <option>--data-path</option>.</para>

          <para>This string must be in dotted-decimal notation in
          order to be matched against a range of values, and thus
          may be shorter than the real version.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--format=<replaceable>format string</replaceable></option></term>
        <listitem>
          <para>Dictate the output of the results of the queries
          specified by <option>--data-path</option> arguments.
          This format string should follow
          <function>printf(3)</function> specifications, although
          only <literal>%s</literal> and appropriate flags,
          precision, and width values are supported (or
          make sense); literal text and <literal>%%</literal>
          can also be used.  The behavior when the string is
          poorly formatted is undefined.  See also
          <option>--normalize-whitespace</option>.</para>
        </listitem>
      </varlistentry>      <varlistentry>
        <term><option>-d | --disable-bus=<replaceable>bus</replaceable></option></term>
        <listitem>
          <para>Use this option to override the list of
          buses to scan by default as defined in
          <filename>discover.conf</filename>. Use
          <replaceable>all</replaceable> as an argument to
          disable all buses; this is useful only if
          followed by
          <option>--enable-bus</option> (or <option>-e</option>)
          arguments.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-e | --enable-bus=<replaceable>bus</replaceable></option></term>
        <listitem>
          <para>Specify a bus to be scanned.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--insert-url=<replaceable>url</replaceable></option></term>
        <listitem>
          <para>Insert a <acronym>URL</acronym> at the head of
          the list of network resources to include in the search
          for hardware information.  Earlier data overrides
          later data; to override the local data
          sources, insert URLs into the list.  See also
          <option>--append-url</option>.</para>
        </listitem>
        <!-- XXX: Need to verify the insert/append behavior -->
      </varlistentry>
      <varlistentry>
        <term><option>--append-url=<replaceable>url</replaceable></option></term>
        <listitem>
          <para>Append a <acronym>URL</acronym> to the end of the
          list of network resources to search for
          hardware information. See also
          <option>--insert-url</option>.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--model</option></term>
        <listitem>
          <para>Include the model description in summary
          information. This is enabled by default.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--model-id</option></term>
        <listitem>
          <para>Include the numeric model identifier in summary
          information.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--no-model</option></term>
        <listitem>
          <para>Do not include the model description in summary
          information.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--no-model-id</option></term>
        <listitem>
          <para>Do not include the numeric model identifier in summary
          information. This is the default.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--vendor</option></term>
        <listitem>
          <para>Include the vendor description in summary
          information. This is enabled by default.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--vendor-id</option></term>
        <listitem>
          <para>Include the numeric vendor identifier in summary
          information.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--no-vendor</option></term>
        <listitem>
          <para>Do not include the vendor description in summary
          information.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--no-vendor-id</option></term>
        <listitem>
          <para>Do not include the numeric vendor identifier in summary
          information. This is the default.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--normalize-whitespace</option></term>
        <listitem>
          <para>Consolidate whitespace in the results of a
          <option>--data-path</option> query.  The default is not to do so,
          which faithfully reproduces all text in the raw &xml; data.</para>
          <para>With this option enabled, leading and trailing whitespace
          is removed, and any consecutive internal whitespaces are
          compressed to a single space character.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="d1-rs-bus-selection">
    <title id="d1-rs-title-bus-selection">Selecting Buses</title>

    <para><filename>discover.conf</filename> defines two lists of system
    buses: one to scan by default (used by the &discover-command;
    command), and one never to scan (used by the &discover; library).</para>

    <para>You can override and/or extend the list of default buses with
    <option>--disable-bus</option> and <option>--enable-bus</option>.
    The list of buses <emphasis>not</emphasis> to scan cannot be overridden
    without changing <filename>discover.conf</filename>, so that list
    should be used only for buses that may be dangerous to probe.</para>

    <para>Both arguments take the string <quote>all</quote> as a
    value.</para>

    <para>If a bus summary is being performed, which is indicated
    either by the presence of <option>--bus-summary</option> or
    the absence of <option>--type-summary</option> and
    <option>--data-path</option>, any unattached arguments on the
    command line will be interpreted as the only buses to scan.
    This is equivalent to using <option>--disable-bus
    all</option> before invoking <option>--enable-bus</option>
    for the buses of interest.</para>

    <para>The following buses are currently supported by &discover;:
    &bus-classes;
    </para>
  </refsect1>

  <refsect1 id="d1-rs-device-types">
    <title id="d1-rs-title-device-types">Device Types</title>

    <para>&discover; defines its own device types, to which the
    device types used by each bus are mapped.  &discover;
    currently recognizes the following device types:
    &device-types;
    </para>

  </refsect1>

  <refsect1 id="d1-rs-examples">
    <title id="d1-rs-title-examples">Examples</title>

        <example id="d1-ex-scan-buses">
          <title id="d1-ex-title-scan-buses">Scan the local buses</title>

          <screen><![CDATA[# discover
Intel Corporation 82815 Chipset Host Bridge and Memory Controller Hub
unknown unknown
unknown unknown
unknown unknown
Intel Corporation 82815 Chipset IDE controller
Intel Corporation 82815 Chipset USB (A)
Intel Corporation 82815 System Management bus controller
ATI Technologies, Inc. Rage 128 Pro GL [PF]
3Com Corporation 3c905C-TX [Fast Etherlink]
Ensoniq ES1371 [AudioPCI-97]
unknown unknown]]></screen>
        </example>

        <example id="d1-ex-view-video-cards">
          <title id="d1-ex-title-view-video-cards">View PCI video cards</title>

          <screen><![CDATA[# discover -v --type-summary --disable-bus all --enable-bus pci display
Disabled pci
Disabled pcmcia
Disabled scsi
Disabled usb
Enabled pci
Loading XML data... pci Done
Scanning buses... pci Done
ATI Technologies, Inc. Rage 128 Pro GL [PF]]]></screen>
        </example>
    <example id="d1-ex-query-xfree86">
      <title id="d1-ex-title-query-xfree86">Query for the driver module for
      XFree86 server version 4.2.0</title>
      <screen><![CDATA[# discover --data-path=xfree86/server/device/driver --data-version=4.2.0 display
ati]]></screen>
</example>
    <example id="d1-ex-type-summary">
      <title id="d1-ex-title-type-summary">Get model and vendor
      information by type</title>
      <screen><![CDATA[$ discover -t --no-model
Intel Corporation
NVIDIA Corporation
3Com Corporation
$ discover -t --no-vendor
82815 System Management bus controller
Vanta [NV6]
3c905C-TX [Fast Etherlink]]]></screen>
</example>
  </refsect1>
  <refsect1 id="d1-rs-files">
    <title id="d1-rs-title-files">Files</title>

    <variablelist>
      <varlistentry>
        <term><filename>&sysconfdir;/discover.conf.d</filename></term>
        <listitem>
          <para>The directory containing configuration files that control 
          the default behavior for both the &discover-command; tool and 
          the &discover; library.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><filename>&datadir;/discover/list.xml</filename></term>
        <listitem>
          <para>An &xml; file containing <acronym>URL</acronym>s with
            hardware information. This list can be extended with
            <option>--append-url</option> and
            <option>--extend-url</option>.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>


  <refsect1 id="d1-rs-authors">
    <title id="d1-rs-title-authors">Authors</title>

    <para>&name.bress;, &name.jdaily;, and
    &name.branden; developed the current implementation of
    &discover; for Progeny Linux Systems.</para>

    <para>The Linux implementation of the system-dependent interfaces is
    derived from <command>detect</command>, by MandrakeSoft SA.</para>
  </refsect1>

  <refsect1 id="d1-rs-see-also">
    <title id="d1-rs-title-see-also">See Also</title>

    <para>discover.conf(5), discover-modprobe(8)</para>

  </refsect1>

<!-- Local variables: -->
<!-- mode: xml -->
<!-- sgml-parent-document: ("guide.xml" "refentry" "refentry") -->
<!-- End: -->
<!-- vim: set ai et sts=2 sw=2 tw=65: -->
