📄 usbs-enum.html
字号:
<!-- Copyright (C) 2003 Red Hat, Inc. -->
<!-- This material may be distributed only subject to the terms -->
<!-- and conditions set forth in the Open Publication License, v1.0 -->
<!-- or later (the latest version is presently available at -->
<!-- http://www.opencontent.org/openpub/). -->
<!-- Distribution of the work or derivative of the work in any -->
<!-- standard (paper) book form is prohibited unless prior -->
<!-- permission is obtained from the copyright holder. -->
<HTML
><HEAD
><TITLE
>USB Enumeration Data</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="eCos Reference Manual"
HREF="ecos-ref.html"><LINK
REL="UP"
TITLE="eCos USB Slave Support"
HREF="io-usb-slave.html"><LINK
REL="PREVIOUS"
TITLE="Introduction"
HREF="usbs-intro.html"><LINK
REL="NEXT"
TITLE="Starting up a USB Device"
HREF="usbs-start.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>eCos Reference Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="usbs-intro.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="usbs-start.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="USBS-ENUM">USB Enumeration Data</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN16109"
></A
><H2
>Name</H2
>Enumeration Data -- The USB enumeration data structures</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN16112"><H2
>Synopsis</H2
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SYNOPSIS"
>#include <cyg/io/usb/usb.h>
#include <cyg/io/usb/usbs.h>
typedef struct usb_device_descriptor {
…
} usb_device_descriptor __attribute__((packed));
typedef struct usb_configuration_descriptor {
…
} usb_configuration_descriptor __attribute__((packed));
typedef struct usb_interface_descriptor {
…
} usb_interface_descriptor __attribute__((packed));
typedef struct usb_endpoint_descriptor {
…
} 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;</PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN16114"
></A
><H2
>USB Enumeration Data</H2
><P
>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
<SPAN
CLASS="STRUCTNAME"
>usbs_enumeration_data</SPAN
> 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
<TT
CLASS="FUNCTION"
>usbs_start</TT
>, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>const usbs_enumeration_data usb_enum_data = {
…
};
int
main(int argc, char** argv)
{
usbs_sa11x0_ep0.enumeration_data = &usb_enum_data;
…
usbs_start(&usbs_sa11x0_ep0);
…
}</PRE
></TD
></TR
></TABLE
><P
>For most applications the enumeration data will be static, although
the <SPAN
CLASS="STRUCTNAME"
>usbs_enumeration_data</SPAN
> 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 <A
HREF="http://www.usb.org/"
TARGET="_top"
>USB Implementers Forum web
site</A
>, although the meaning of most fields is fairly obvious.
The various data structures and utility macros are defined in the
header files <TT
CLASS="FILENAME"
>cyg/io/usb/usb.h</TT
>
and <TT
CLASS="FILENAME"
>cyg/io/usb/usbs.h</TT
>. Note
that the example code below makes use of the gcc labelled element
extension.</P
><DIV
CLASS="REFSECT2"
><A
NAME="AEN16125"
></A
><H3
><SPAN
CLASS="STRUCTNAME"
>usb_device_descriptor</SPAN
></H3
><P
>The main information about a USB peripheral comes from a single
<SPAN
CLASS="STRUCTNAME"
>usb_device_descriptor</SPAN
> structure, which is
embedded in the <SPAN
CLASS="STRUCTNAME"
>usbs_enumeration_data</SPAN
>
structure. A typical example might look like this:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>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
},
…
};</PRE
></TD
></TR
></TABLE
><P
>The length and type fields are specified by the USB standard. The
<TT
CLASS="STRUCTFIELD"
><I
>usb_spec_lo</I
></TT
> and
<TT
CLASS="STRUCTFIELD"
><I
>usb_spec_hi</I
></TT
> fields identify the particular
revision of the standard that the peripheral implements, for example
revision 1.1.</P
><P
>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
<TT
CLASS="LITERAL"
>0xFF</TT
> (<TT
CLASS="LITERAL"
>VENDOR</TT
>) 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 <TT
CLASS="LITERAL"
>0x00</TT
>
(<TT
CLASS="LITERAL"
>INTERFACE</TT
>) 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.</P
><P
>The <TT
CLASS="STRUCTFIELD"
><I
>max_package_size</I
></TT
> 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.</P
><P
>The <TT
CLASS="STRUCTFIELD"
><I
>vendor_lo</I
></TT
> and
<TT
CLASS="STRUCTFIELD"
><I
>vendor_hi</I
></TT
> 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.</P
><P
>The above fields are all numerical in nature. A USB peripheral can
also provide a number of strings as described <A
HREF="usbs-enum.html#AEN16200"
>below</A
>, for example the name of the
vendor can be provided. The various <TT
CLASS="STRUCTFIELD"
><I
>_str</I
></TT
>
fields act as indices into an array of strings, with index 0
indicating that no string is available. </P
><P
>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 <A
HREF="usbs-control.html#AEN16586"
>handle</A
> the standard
set-configuration control message.</P
></DIV
><DIV
CLASS="REFSECT2"
><A
NAME="AEN16150"
></A
><H3
><SPAN
CLASS="STRUCTNAME"
>usb_configuration_descriptor</SPAN
></H3
><P
>A USB peripheral involves at least one and possible several different
configurations. The <SPAN
CLASS="STRUCTNAME"
>usbs_enumeration_data</SPAN
>
structure requires a pointer to an array, possibly of length 1, of
<SPAN
CLASS="STRUCTNAME"
>usb_configuration_descriptor</SPAN
> structures.
Usually a single structure suffices:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>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 = {
…
configurations: &usb_configuration,
…
};</PRE
></TD
></TR
></TABLE
><P
>The values for the <TT
CLASS="STRUCTFIELD"
><I
>length</I
></TT
> and
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -