usbs-enum.html

encos_rtos一款精致小巧的实时嵌入式操作系统 ＋CODEWORR 教程

<TT
CLASS="STRUCTFIELD"
><I
>type</I
></TT
> fields are determined by the standard.
The <TT
CLASS="STRUCTFIELD"
><I
>total_length</I
></TT
> 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 <TT
CLASS="STRUCTFIELD"
><I
>number_interfaces</I
></TT
> 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
<TT
CLASS="LITERAL"
>0</TT
> 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 <TT
CLASS="STRUCTFIELD"
><I
>attributes</I
></TT
> field must have the
<TT
CLASS="LITERAL"
>REQUIRED</TT
> bit set; the
<TT
CLASS="LITERAL"
>SELF_POWERED</TT
> 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
<TT
CLASS="LITERAL"
>REMOTE_WAKEUP</TT
> 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
<TT
CLASS="STRUCTFIELD"
><I
>max_power</I
></TT
> field specifies the power
requirements in units of 2mA.</P
></DIV
><DIV
CLASS="REFSECT2"
><A
NAME="AEN16164"
></A
><H3
><SPAN
CLASS="STRUCTNAME"
>usb_interface_descriptor</SPAN
></H3
><P
>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.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>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 = {
    &#8230;
    total_number_interfaces:    1,
    interfaces:                 &amp;usb_interface,
    &#8230;
};</PRE
></TD
></TR
></TABLE
><P
>Again, the <TT
CLASS="STRUCTFIELD"
><I
>length</I
></TT
> and
<TT
CLASS="STRUCTFIELD"
><I
>type</I
></TT
> 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
<TT
CLASS="STRUCTFIELD"
><I
>alternate_setting</I
></TT
> 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 <A
HREF="usbs-control.html#AEN16582"
>install</A
> its own handler.</P
><P
>The number of endpoints used by an interface is specified in the
<TT
CLASS="STRUCTFIELD"
><I
>number_endpoints</I
></TT
> 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
<SPAN
CLASS="STRUCTNAME"
>usb_device_descriptor</SPAN
> structure, but that can
defer the details to individual interfaces. A per-interface string
is allowed as well.</P
><P
>For USB peripherals involving multiple configurations, the array of
<SPAN
CLASS="STRUCTNAME"
>usb_interface_descriptor</SPAN
> structures should
first contain all the interfaces for the first configuration, then all
the interfaces for the second configuration, and so on.</P
></DIV
><DIV
CLASS="REFSECT2"
><A
NAME="AEN16179"
></A
><H3
><SPAN
CLASS="STRUCTNAME"
>usb_endpoint_descriptor</SPAN
></H3
><P
>The host also needs information about which endpoint should be used
for what. This involves an array of endpoint descriptors:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>const usb_endpoint_descriptor usb_endpoints[] = {
    {
        length:         USB_ENDPOINT_DESCRIPTOR_LENGTH,
        type:           USB_ENDPOINT_DESCRIPTOR_TYPE,
        endpoint:       USB_ENDPOINT_DESCRIPTOR_ENDPOINT_OUT | 1,
        attributes:     USB_ENDPOINT_DESCRIPTOR_ATTR_BULK,
        max_packet_lo:  64,
        max_packet_hi:  0,
        interval:       0
    },
    {
        length:         USB_ENDPOINT_DESCRIPTOR_LENGTH,
        type:           USB_ENDPOINT_DESCRIPTOR_TYPE,
        endpoint:       USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN | 2,
        attributes:     USB_ENDPOINT_DESCRIPTOR_ATTR_BULK,
        max_packet_lo:  64,
        max_packet_hi:  0,
        interval:       0
    }
};

const usbs_enumeration_data usb_enum_data = {
    &#8230;
    total_number_endpoints:     2,
    endpoints:                  usb_endpoints,
    &#8230;
};</PRE
></TD
></TR
></TABLE
><P
>As usual the values for the <TT
CLASS="STRUCTFIELD"
><I
>length</I
></TT
> and
<TT
CLASS="STRUCTFIELD"
><I
>type</I
></TT
> fields are specified by the standard.
The <TT
CLASS="STRUCTFIELD"
><I
>endpoint</I
></TT
> field gives both the endpoint
number and the direction, so in the above example endpoint 1 is used
for OUT (host to peripheral) transfers and endpoint 2 is used for IN
(peripheral to host) transfers. The
<TT
CLASS="STRUCTFIELD"
><I
>attributes</I
></TT
> field indicates the USB protocol
that should be used on this endpoint: <TT
CLASS="LITERAL"
>CONTROL</TT
>,
<TT
CLASS="LITERAL"
>ISOCHRONOUS</TT
>, <TT
CLASS="LITERAL"
>BULK</TT
> or
<TT
CLASS="LITERAL"
>INTERRUPT</TT
>. The
<TT
CLASS="STRUCTFIELD"
><I
>max_packet</I
></TT
> field specifies the maximum size
of a single USB packet. For bulk transfers this will typically be 64
bytes. For isochronous transfers this can be up to 1023 bytes. For
interrupt transfers it can be up to 64 bytes, although usually a
smaller value will be used. The <TT
CLASS="STRUCTFIELD"
><I
>interval</I
></TT
>
field is ignored for control and bulk transfers. For isochronous
transfers it should be set to 1. For interrupt transfers it can be a
value between 1 and 255, and indicates the number of milliseconds
between successive polling operations.</P
><P
>For USB peripherals involving multiple configurations or interfaces
the array of endpoint descriptors should be organized sequentially:
first the endpoints corresponding to the first interface of the first
configuration, then the second interface in that configuration, and so
on; then all the endpoints for all the interfaces in the second
configuration; etc.</P
></DIV
><DIV
CLASS="REFSECT2"
><A
NAME="AEN16196"
></A
><H3
>Strings</H3
><P
>The enumeration data can contain a number of strings with additional
information. Unicode encoding is used for the strings, and it is
possible for a peripheral to supply a given string in multiple
languages using the appropriate characters. The first two bytes of
each string give a length and type field. The first string is special;
after the two bytes header it consists of an array of 2-byte language
id codes, indicating the supported languages. The language code
0x0409 corresponds to English (United States). </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>const unsigned char* usb_strings[] = {
    "\004\003\011\004",
    "\020\003R\000e\000d\000 \000H\000a\000t\000"
};

const usbs_enumeration_data usb_enum_data = {
    &#8230;
    total_number_strings:       2,
    strings:                    usb_strings,
    &#8230;
};</PRE
></TD
></TR
></TABLE
><P
>The default handler for standard control messages assumes that the
peripheral only uses a single language. If this is not the case then
higher-level code will have to handle the standard get-descriptor
control messages when a string descriptor is requested.</P
></DIV
><DIV
CLASS="REFSECT2"
><A
NAME="AEN16201"
></A
><H3
><SPAN
CLASS="STRUCTNAME"
>usbs_enumeration_data</SPAN
></H3
><P
>The <SPAN
CLASS="STRUCTNAME"
>usbs_enumeration_data</SPAN
> data structure
collects together all the various descriptors that make up the
enumeration data. It is the responsibility of application code to
supply a suitable data structure and install it in the control
endpoints's <TT
CLASS="STRUCTFIELD"
><I
>enumeration_data</I
></TT
> field before
the USB device is started.</P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="usbs-intro.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="ecos-ref.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="usbs-start.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Introduction</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="io-usb-slave.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Starting up a USB Device</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>