📄 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"><METANAME="GENERATOR"CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+"><LINKREL="HOME"TITLE="eCos Reference Manual"HREF="ecos-ref.html"><LINKREL="UP"TITLE="eCos USB Slave Support"HREF="io-usb-slave.html"><LINKREL="PREVIOUS"TITLE="Introduction"HREF="usbs-intro.html"><LINKREL="NEXT"TITLE="Starting up a USB Device"HREF="usbs-start.html"></HEAD><BODYCLASS="REFENTRY"BGCOLOR="#FFFFFF"TEXT="#000000"LINK="#0000FF"VLINK="#840084"ALINK="#0000FF"><DIVCLASS="NAVHEADER"><TABLESUMMARY="Header navigation table"WIDTH="100%"BORDER="0"CELLPADDING="0"CELLSPACING="0"><TR><THCOLSPAN="3"ALIGN="center">eCos Reference Manual</TH></TR><TR><TDWIDTH="10%"ALIGN="left"VALIGN="bottom"><AHREF="usbs-intro.html"ACCESSKEY="P">Prev</A></TD><TDWIDTH="80%"ALIGN="center"VALIGN="bottom"></TD><TDWIDTH="10%"ALIGN="right"VALIGN="bottom"><AHREF="usbs-start.html"ACCESSKEY="N">Next</A></TD></TR></TABLE><HRALIGN="LEFT"WIDTH="100%"></DIV><H1><ANAME="USBS-ENUM">USB Enumeration Data</H1><DIVCLASS="REFNAMEDIV"><ANAME="AEN16105"></A><H2>Name</H2>Enumeration Data -- The USB enumeration data structures</DIV><DIVCLASS="REFSYNOPSISDIV"><ANAME="AEN16108"><H2>Synopsis</H2><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="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><DIVCLASS="REFSECT1"><ANAME="AEN16110"></A><H2>USB Enumeration Data</H2><P>When a USB host detects that a peripheral has been plugged in orpowered up, one of the first steps is to ask the peripheral todescribe itself by supplying enumeration data. Some of this datadepends on the class of peripheral. Other fields are vendor-specific.There is also a dependency on the hardware, specifically whichendpoints are available should be used. In general it is not possiblefor generic code to provide this information, so it is theresponsibility of application code to provide a suitable<SPANCLASS="STRUCTNAME">usbs_enumeration_data</SPAN> data structure andinstall it in the endpoint 0 data structure during initialization.This must happen before the USB device is enabled by a call to<TTCLASS="FUNCTION">usbs_start</TT>, for example:</P><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="PROGRAMLISTING">const usbs_enumeration_data usb_enum_data = { …};intmain(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, althoughthe <SPANCLASS="STRUCTNAME">usbs_enumeration_data</SPAN> structure can befilled in at run-time if necessary. Full details of the enumerationdata can be found in the Universal Serial Bus specification obtainablefrom the <AHREF="http://www.usb.org/"TARGET="_top">USB Implementers Forum website</A>, although the meaning of most fields is fairly obvious.The various data structures and utility macros are defined in theheader files <TTCLASS="FILENAME">cyg/io/usb/usb.h</TT>and <TTCLASS="FILENAME">cyg/io/usb/usbs.h</TT>. Notethat the example code below makes use of the gcc labelled elementextension.</P><DIVCLASS="REFSECT2"><ANAME="AEN16121"></A><H3><SPANCLASS="STRUCTNAME">usb_device_descriptor</SPAN></H3><P>The main information about a USB peripheral comes from a single<SPANCLASS="STRUCTNAME">usb_device_descriptor</SPAN> structure, which isembedded in the <SPANCLASS="STRUCTNAME">usbs_enumeration_data</SPAN>structure. A typical example might look like this:</P><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="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<TTCLASS="STRUCTFIELD"><I>usb_spec_lo</I></TT> and<TTCLASS="STRUCTFIELD"><I>usb_spec_hi</I></TT> fields identify the particularrevision of the standard that the peripheral implements, for examplerevision 1.1.</P><P>The device class, subclass, and protocol fields are used by generichost-side USB software to determine which host-side device drivershould be loaded to interact with the peripheral. A number of standardclasses are defined, for example mass-storage devices andhuman-interface devices. If a peripheral implements one of thestandard classes then a standard existing host-side device driver mayexist, eliminating the need to write a custom driver. The value<TTCLASS="LITERAL">0xFF</TT> (<TTCLASS="LITERAL">VENDOR</TT>) is reserved forperipherals that implement a vendor-specific protocol rather than astandard one. Such peripherals will require a custom host-side devicedriver. The value <TTCLASS="LITERAL">0x00</TT>(<TTCLASS="LITERAL">INTERFACE</TT>) is reserved and indicates that theprotocol used by the peripheral is defined at the interface levelrather than for the peripheral as a whole.</P><P>The <TTCLASS="STRUCTFIELD"><I>max_package_size</I></TT> field specifies themaximum length of a control message. There is a lower bound of eightbytes, and typical hardware will not support anything larger becausecontrol messages are usually small and not performance-critical.</P><P>The <TTCLASS="STRUCTFIELD"><I>vendor_lo</I></TT> and<TTCLASS="STRUCTFIELD"><I>vendor_hi</I></TT> fields specify a vendor id, whichmust be obtained from the USB Implementor's Forum. The numbers used inthe code fragment above are examples only and must not be used in realUSB peripherals. The product identifier is determined by the vendor,and different USB peripherals should use different identifiers. Thedevice identifier field should indicate a release number inbinary-coded decimal.</P><P>The above fields are all numerical in nature. A USB peripheral canalso provide a number of strings as described <AHREF="usbs-enum.html#AEN16196">below</A>, for example the name of thevendor can be provided. The various <TTCLASS="STRUCTFIELD"><I>_str</I></TT>fields act as indices into an array of strings, with index 0indicating that no string is available. </P><P>A typical USB peripheral involves just a single configuration. Howevermore complicated peripherals can support multiple configurations. Onlyone configuration will be active at any one time, and the host willswitch between them as appropriate. If a peripheral does involvemultiple configurations then typically it will be the responsibilityof application code to <AHREF="usbs-control.html#AEN16582">handle</A> the standardset-configuration control message.</P></DIV><DIVCLASS="REFSECT2"><ANAME="AEN16146"></A><H3><SPANCLASS="STRUCTNAME">usb_configuration_descriptor</SPAN></H3><P>A USB peripheral involves at least one and possible several differentconfigurations. The <SPANCLASS="STRUCTNAME">usbs_enumeration_data</SPAN>structure requires a pointer to an array, possibly of length 1, of<SPANCLASS="STRUCTNAME">usb_configuration_descriptor</SPAN> structures.Usually a single structure suffices:</P><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="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 <TTCLASS="STRUCTFIELD"><I>length</I></TT> and⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -