usbs.sgml

eCos操作系统源码

<para>
If the application developer explicitly adds a class support package
such as the USB-ethernet one then this implies that the USB device is
actually needed, and the device will be enabled automatically.
However, if no suitable class package is available and the USB device
will instead be accessed by application code, it is necessary to
enable the USB device manually. Usually the easiest way to do this is
to enable the configuration option
<literal>CYGGLO_IO_USB_SLAVE_APPLICATION</literal>, and the USB device
driver and related packages will adjust accordingly. Alternatively,
the device driver may provide some configuration options to provide
more fine-grained control.
</para>
</refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ Enumeration Data               -->

<refentry id="usbs-enum">
<refmeta>
<refentrytitle>USB Enumeration Data</refentrytitle>
</refmeta>
<refnamediv>
<refname>Enumeration Data</refname>
<refpurpose>The USB enumeration data structures</refpurpose>
</refnamediv>

<refsynopsisdiv>
<synopsis>
#include &lt;cyg/io/usb/usb.h&gt;
#include &lt;cyg/io/usb/usbs.h&gt;

typedef struct usb_device_descriptor {
    &hellip;
} usb_device_descriptor __attribute__((packed));

typedef struct usb_configuration_descriptor {
    &hellip;
} usb_configuration_descriptor __attribute__((packed));

typedef struct usb_interface_descriptor {
    &hellip;
} usb_interface_descriptor __attribute__((packed));        

typedef struct usb_endpoint_descriptor {
    &hellip;
} usb_endpoint_descriptor;

typedef struct usbs_enumeration_data {
    usb_device_descriptor               device;
    int                                 total_number_interfaces;
    int                                 total_number_endpoints;
    int                                 total_number_strings;
    const usb_configuration_descriptor* configurations;
    const usb_interface_descriptor*     interfaces;
    const usb_endpoint_descriptor*      endpoints;
    const unsigned char**               strings;
} usbs_enumeration_data;
</synopsis>
</refsynopsisdiv>

<refsect1><title>USB Enumeration Data</title>
<para>
When a USB host detects that a peripheral has been plugged in or
powered up, one of the first steps is to ask the peripheral to
describe itself by supplying enumeration data. Some of this data
depends on the class of peripheral. Other fields are vendor-specific.
There is also a dependency on the hardware, specifically which
endpoints are available should be used. In general it is not possible
for generic code to provide this information, so it is the
responsibility of application code to provide a suitable
<structname>usbs_enumeration_data</structname> data structure and
install it in the endpoint 0 data structure during initialization.
This must happen before the USB device is enabled by a call to
<function>usbs_start</function>, for example:
</para>
<programlisting width=72>
const usbs_enumeration_data usb_enum_data = {
    &hellip;
};

int
main(int argc, char** argv)
{
    usbs_sa11x0_ep0.enumeration_data = &amp;usb_enum_data;
    &hellip;
    usbs_start(&amp;usbs_sa11x0_ep0);
    &hellip;
}
</programlisting>
<para>
For most applications the enumeration data will be static, although
the <structname>usbs_enumeration_data</structname> structure can be
filled in at run-time if necessary. Full details of the enumeration
data can be found in the Universal Serial Bus specification obtainable
from the <ulink url="http://www.usb.org/">USB Implementers Forum web
site</ulink>, although the meaning of most fields is fairly obvious.
The various data structures and utility macros are defined in the
header files <filename class="headerfile">cyg/io/usb/usb.h</filename>
and <filename class="headerfile">cyg/io/usb/usbs.h</filename>. Note
that the example code below makes use of the gcc labelled element
extension.
</para>

<refsect2><title><structname>usb_device_descriptor</structname></title>
<para>
The main information about a USB peripheral comes from a single
<structname>usb_device_descriptor</structname> structure, which is
embedded in the <structname>usbs_enumeration_data</structname>
structure. A typical example might look like this:
</para>
<programlisting width=72>
const usbs_enumeration_data usb_enum_data = {
    {
        length:                 USB_DEVICE_DESCRIPTOR_LENGTH,
        type:                   USB_DEVICE_DESCRIPTOR_TYPE,
        usb_spec_lo:            USB_DEVICE_DESCRIPTOR_USB11_LO,
        usb_spec_hi:            USB_DEVICE_DESCRIPTOR_USB11_HI,
        device_class:           USB_DEVICE_DESCRIPTOR_CLASS_VENDOR,
        device_subclass:        USB_DEVICE_DESCRIPTOR_SUBCLASS_VENDOR,
        device_protocol:        USB_DEVICE_DESCRIPTOR_PROTOCOL_VENDOR,
        max_packet_size:        8,
        vendor_lo:              0x42,
        vendor_hi:              0x42,
        product_lo:             0x42,
        product_hi:             0x42,
        device_lo:              0x00,
        device_hi:              0x01,
        manufacturer_str:       1,
        product_str:            2,
        serial_number_str:      0,
        number_configurations:  1
    },
    &hellip;
};
</programlisting>
<para>
The length and type fields are specified by the USB standard. The
<structfield>usb_spec_lo</structfield> and
<structfield>usb_spec_hi</structfield> fields identify the particular
revision of the standard that the peripheral implements, for example
revision 1.1.
</para>
<para>
The device class, subclass, and protocol fields are used by generic
host-side USB software to determine which host-side device driver
should be loaded to interact with the peripheral. A number of standard
classes are defined, for example mass-storage devices and
human-interface devices. If a peripheral implements one of the
standard classes then a standard existing host-side device driver may
exist, eliminating the need to write a custom driver. The value
<literal>0xFF</literal> (<literal>VENDOR</literal>) is reserved for
peripherals that implement a vendor-specific protocol rather than a
standard one. Such peripherals will require a custom host-side device
driver. The value <literal>0x00</literal>
(<literal>INTERFACE</literal>) is reserved and indicates that the
protocol used by the peripheral is defined at the interface level
rather than for the peripheral as a whole.
</para>
<para>
The <structfield>max_package_size</structfield> field specifies the
maximum length of a control message. There is a lower bound of eight
bytes, and typical hardware will not support anything larger because
control messages are usually small and not performance-critical.
</para>
<para>
The <structfield>vendor_lo</structfield> and
<structfield>vendor_hi</structfield> fields specify a vendor id, which
must be obtained from the USB Implementor's Forum. The numbers used in
the code fragment above are examples only and must not be used in real
USB peripherals. The product identifier is determined by the vendor,
and different USB peripherals should use different identifiers. The
device identifier field should indicate a release number in
binary-coded decimal.
</para>
<para>
The above fields are all numerical in nature. A USB peripheral can
also provide a number of strings as described <link
linkend="usbs-enum-strings">below</link>, for example the name of the
vendor can be provided. The various <structfield>_str</structfield>
fields act as indices into an array of strings, with index 0
indicating that no string is available. 
</para>
<para>
A typical USB peripheral involves just a single configuration. However
more complicated peripherals can support multiple configurations. Only
one configuration will be active at any one time, and the host will
switch between them as appropriate. If a peripheral does involve
multiple configurations then typically it will be the responsibility
of application code to <link
linkend="usbs-control-standard">handle</link> the standard
set-configuration control message.
</para>
</refsect2>

<refsect2><title><structname>usb_configuration_descriptor</structname></title>
<para>
A USB peripheral involves at least one and possible several different
configurations. The <structname>usbs_enumeration_data</structname>
structure requires a pointer to an array, possibly of length 1, of
<structname>usb_configuration_descriptor</structname> structures.
Usually a single structure suffices:
</para>
<programlisting width=72>
const usb_configuration_descriptor usb_configuration = {
    length:             USB_CONFIGURATION_DESCRIPTOR_LENGTH,
    type:               USB_CONFIGURATION_DESCRIPTOR_TYPE,
    total_length_lo:    USB_CONFIGURATION_DESCRIPTOR_TOTAL_LENGTH_LO(1, 2),
    total_length_hi:    USB_CONFIGURATION_DESCRIPTOR_TOTAL_LENGTH_HI(1, 2),
    number_interfaces:  1,
    configuration_id:   1,
    configuration_str:  0,
    attributes:         USB_CONFIGURATION_DESCRIPTOR_ATTR_REQUIRED |
                        USB_CONFIGURATION_DESCRIPTOR_ATTR_SELF_POWERED,
    max_power:          50
};

const usbs_enumeration_data usb_enum_data = {
    &hellip;
    configurations:             &amp;usb_configuration,
    &hellip;
};
</programlisting>
<para>
The values for the <structfield>length</structfield> and
<structfield>type</structfield> fields are determined by the standard.
The <structfield>total_length</structfield> field depends on the
number of interfaces and endpoints used by this configuration, and
convenience macros are provided to calculate this: the first argument
to the macros specify the number of interfaces, the second the number
of endpoints. The <structfield>number_interfaces</structfield> field
is self-explanatory. If the peripheral involves multiple
configurations then each one must have a unique id, and this will be
used in the set-configuration control message. The id
<literal>0</literal> is reserved, and a set-configuration control
message that uses this id indicates that the peripheral should be
inactive. Configurations can have a string description if required.
The <structfield>attributes</structfield> field must have the
<literal>REQUIRED</literal> bit set; the
<literal>SELF_POWERED</literal> bit informs the host that the
peripheral has its own power supply and will not draw any power over
the bus, leaving more bus power available to other peripherals; the
<literal>REMOTE_WAKEUP</literal> bit is used if the peripheral can
interrupt the host when the latter is in power-saving mode. For
peripherals that are not self-powered, the
<structfield>max_power</structfield> field specifies the power
requirements in units of 2mA.
</para>
</refsect2>

<refsect2><title><structname>usb_interface_descriptor</structname></title>
<para>
A USB configuration involves one or more interfaces, typically
corresponding to different streams of data. For example, one interface
might involve video data while another interface is for audio.
Multiple interfaces in a single configuration will be active at the
same time.
</para>
<programlisting width=72>
const usb_interface_descriptor usb_interface = {
    length:             USB_INTERFACE_DESCRIPTOR_LENGTH,
    type:               USB_INTERFACE_DESCRIPTOR_TYPE,
    interface_id:       0,
    alternate_setting:  0,
    number_endpoints:   2,
    interface_class:    USB_INTERFACE_DESCRIPTOR_CLASS_VENDOR,
    interface_subclass: USB_INTERFACE_DESCRIPTOR_SUBCLASS_VENDOR,
    interface_protocol: USB_INTERFACE_DESCRIPTOR_PROTOCOL_VENDOR,
    interface_str:      0
};

const usbs_enumeration_data usb_enum_data = {
    &hellip;
    total_number_interfaces:    1,
    interfaces:                 &amp;usb_interface,
    &hellip;
};
</programlisting>
<para>
Again, the <structfield>length</structfield> and
<structfield>type</structfield> fields are specified by the standard.
Each interface within a configuration requires its own id. However, a
given interface may have several alternate settings, in other words
entries in the interfaces array with the same id but different
<structfield>alternate_setting</structfield> fields. For example,
there might be one setting which requires a bandwidth of 100K/s and
another setting that only needs 50K/s. The host can use the standard
set-interface control message to choose the most appropriate setting.
The handling of this request is the responsibility of higher-level
code, so the application may have to <link
linkend="usbs-control-standard">install</link> its own handler.
</para>
<para>
The number of endpoints used by an interface is specified in the
<structfield>number_endpoints</structfield> field. Exact details of
which endpoints are used is held in a separate array of endpoint
descriptors. The class, subclass and protocol fields are used by
host-side code to determine which host-side device driver should
handle this specific interface. Usually this is determined on a
per-peripheral basis in the
<structname>usb_device_descriptor</structname> structure, but that can
defer the details to individual interfaces. A per-interface string