📄 usbs-control.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>Control Endpoints</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="Halted Endpoints"HREF="usbs-halt.html"><LINKREL="NEXT"TITLE="Data Endpoints"HREF="usbs-data.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-halt.html"ACCESSKEY="P">Prev</A></TD><TDWIDTH="80%"ALIGN="center"VALIGN="bottom"></TD><TDWIDTH="10%"ALIGN="right"VALIGN="bottom"><AHREF="usbs-data.html"ACCESSKEY="N">Next</A></TD></TR></TABLE><HRALIGN="LEFT"WIDTH="100%"></DIV><H1><ANAME="USBS-CONTROL">Control Endpoints</H1><DIVCLASS="REFNAMEDIV"><ANAME="AEN16526"></A><H2>Name</H2>Control Endpoints -- Control endpoint data structure</DIV><DIVCLASS="REFSYNOPSISDIV"><ANAME="AEN16529"><H2>Synopsis</H2><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="SYNOPSIS">#include <cyg/io/usb/usbs.h>typedef struct usbs_control_endpoint { *hellip;} usbs_control_endpoint;</PRE></TD></TR></TABLE></DIV><DIVCLASS="REFSECT1"><ANAME="AEN16531"></A><H2><TTCLASS="LITERAL">usbs_control_endpoint</TT> Data Structure</H2><P>The device driver for a USB slave device should supply one<SPANCLASS="STRUCTNAME">usbs_control_endpoint</SPAN> data structure per USBdevice. This corresponds to endpoint 0 which will be used for allcontrol message interaction between the host and that device. The datastructure is also used for internal management purposes, for exampleto keep track of the current state. In a typical USB peripheral therewill only be one such data structure in the entire system, but ifthere are multiple USB slave ports, allowing the peripheral to beconnected to multiple hosts, then there will be a separate datastructure for each one. The name or names of the data structures aredetermined by the device drivers. For example, the SA11x0 USB devicedriver package provides <TTCLASS="LITERAL">usbs_sa11x0_ep0</TT>.</P><P>The operations on a control endpoint do not fit cleanly into aconventional open/read/write I/O model. For example, when the hostsends a control message to the USB peripheral this may be one of fourtypes: standard, class, vendor and reserved. Some or all of thestandard control messages will be handled automatically by the commonUSB slave package or by the device driver itself. Other standardcontrol messages and the other types of control messages may behandled by a class-specific package or by application code. Althoughit would be possible to have devtab entries such as<TTCLASS="LITERAL">/dev/usbs_ep0/standard</TT> and<TTCLASS="LITERAL">/dev/usbs_ep0/class</TT>, and then support read andwrite operations on these devtab entries, this would add significantoverhead and code complexity. Instead, all of the fields in thecontrol endpoint data structure are public and can be manipulateddirectly by higher level code if and when required. </P><P>Control endpoints involve a number of callback functions, withhigher-level code installing suitable function pointers in the controlendpoint data structure. For example, if the peripheral involvesvendor-specific control messages then a suitable handler for thesemessages should be installed. Although the exact details depend on thedevice driver, typically these callback functions will be invoked atDSR level rather than thread level. Therefore, only certain eCosfunctions can be invoked; specifically, those functions that areguaranteed not to block. If a potentially blocking function such as asemaphore wait or a mutex lock operation is invoked from inside thecallback then the resulting behaviour is undefined, and the system asa whole may fail. In addition, if one of the callback functionsinvolves significant processing effort then this may adversely affectthe system's real time characteristics. The eCos kernel documentationshould be consulted for more details of DSR handling.</P><DIVCLASS="REFSECT2"><ANAME="AEN16541"></A><H3>Initialization</H3><P>The <SPANCLASS="STRUCTNAME">usbs_control_endpoint</SPAN> data structurecontains the following fields related to initialization.</P><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="PROGRAMLISTING">typedef struct usbs_control_endpoint { … const usbs_enumeration_data* enumeration_data; void (*start_fn)(usbs_control_endpoint*); …};</PRE></TD></TR></TABLE><P>It is the responsibility of higher-level code, usually theapplication, to define the USB enumeration data. This needs to beinstalled in the control endpoint data structure early on duringsystem startup, before the USB device is actually started and anyinteraction with the host is possible. Details of the enumeration dataare supplied in the section <AHREF="usbs-enum.html">USB EnumerationData</A>. Typically, the enumeration data is constant for a givenperipheral, although it can be constructed dynamically if necessary.However, the enumeration data cannot change while the peripheral isconnected to a host: the peripheral cannot easily claim to be akeyboard one second and a printer the next.</P><P>The <TTCLASS="STRUCTFIELD"><I>start_fn</I></TT> member is normally accessedvia the utility <AHREF="usbs-start.html"><TTCLASS="FUNCTION">usbs_start</TT></A> ratherthan directly. It is provided by the device driver and should beinvoked once the system is fully initialized and interaction with thehost is possible. A typical implementation would change the USB datapins from tristated to active. If the peripheral is already pluggedinto a host then the latter should detect this change and startinteracting with the peripheral, including requesting the enumerationdata.</P></DIV><DIVCLASS="REFSECT2"><ANAME="AEN16552"></A><H3>State</H3><P>There are three <SPANCLASS="STRUCTNAME">usbs_control_endpoint</SPAN> fieldsrelated to the current state of a USB slave device, plus some stateconstants and an enumeration of the possible state changes:</P><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="PROGRAMLISTING">typedef struct usbs_control_endpoint { … int state; void (*state_change_fn)(struct usbs_control_endpoint*, void*, usbs_state_change, int); void* state_change_data; …};#define USBS_STATE_DETACHED 0x01#define USBS_STATE_ATTACHED 0x02#define USBS_STATE_POWERED 0x03#define USBS_STATE_DEFAULT 0x04#define USBS_STATE_ADDRESSED 0x05#define USBS_STATE_CONFIGURED 0x06#define USBS_STATE_MASK 0x7F#define USBS_STATE_SUSPENDED (1 << 7)typedef enum { USBS_STATE_CHANGE_DETACHED = 1, USBS_STATE_CHANGE_ATTACHED = 2, USBS_STATE_CHANGE_POWERED = 3, USBS_STATE_CHANGE_RESET = 4, USBS_STATE_CHANGE_ADDRESSED = 5, USBS_STATE_CHANGE_CONFIGURED = 6, USBS_STATE_CHANGE_DECONFIGURED = 7, USBS_STATE_CHANGE_SUSPENDED = 8, USBS_STATE_CHANGE_RESUMED = 9} usbs_state_change;</PRE></TD></TR></TABLE><P>The USB standard defines a number of states for a given USBperipheral. The initial state is <SPANCLASS="emphasis"><ICLASS="EMPHASIS">detached</I></SPAN>, wherethe peripheral is either not connected to a host at all or, from thehost's perspective, the peripheral has not started up yet because therelevant pins are tristated. The peripheral then moves viaintermediate <SPANCLASS="emphasis"><ICLASS="EMPHASIS">attached</I></SPAN> and<SPANCLASS="emphasis"><ICLASS="EMPHASIS">powered</I></SPAN> states to its default or<SPANCLASS="emphasis"><ICLASS="EMPHASIS">reset</I></SPAN> state, at which point the host andperipheral can actually start exchanging data. The first message isfrom host to peripheral and provides a unique 7-bit address within thelocal USB network, resulting in a state change to<SPANCLASS="emphasis"><ICLASS="EMPHASIS">addressed</I></SPAN>. The host then requests enumerationdata and performs other initialization. If everything succeeds thehost sends a standard set-configuration control message, after whichthe peripheral is <SPANCLASS="emphasis"><ICLASS="EMPHASIS">configured</I></SPAN> and expected to beup and running. Note that some USB device drivers may be unable todistinguish between the <SPANCLASS="emphasis"><ICLASS="EMPHASIS">detached</I></SPAN>,<SPANCLASS="emphasis"><ICLASS="EMPHASIS">attached</I></SPAN> and <SPANCLASS="emphasis"><ICLASS="EMPHASIS">powered</I></SPAN> statesbut generally this is not important to higher-level code.</P><P>A USB host should generate at least one token every millisecond. If aperipheral fails to detect any USB traffic for a period of time thentypically this indicates that the host has entered a power-savingmode, and the peripheral should do the same if possible. Thiscorresponds to the <SPANCLASS="emphasis"><ICLASS="EMPHASIS">suspended</I></SPAN> bit. The actualstate is a combination of <SPANCLASS="emphasis"><ICLASS="EMPHASIS">suspended</I></SPAN> and theprevious state, for example <SPANCLASS="emphasis"><ICLASS="EMPHASIS">configured</I></SPAN> and<SPANCLASS="emphasis"><ICLASS="EMPHASIS">suspended</I></SPAN> rather than just<SPANCLASS="emphasis"><ICLASS="EMPHASIS">suspended</I></SPAN>. When the peripheral subsequentlydetects USB traffic it would switch back to the<SPANCLASS="emphasis"><ICLASS="EMPHASIS">configured</I></SPAN> state.</P><P>The USB device driver and the common USB slave package will maintainthe current state in the control endpoint's<TTCLASS="STRUCTFIELD"><I>state</I></TT> field. There should be no need forany other code to change this field, but it can be examined wheneverappropriate. In addition whenever a state change occurs the genericcode can invoke a state change callback function. By default, no suchcallback function will be installed. Some class-specific packages suchas the USB-ethernet package will install a suitable function to keeptrack of whether or not the host-peripheral connection is up, that iswhether or not ethernet packets can be exchanged. Application code canalso update this field. If multiple parties want to be informed ofstate changes, for example both a class-specific package andapplication code, then typically the application code will install itsstate change handler after the class-specific package and isresponsible for chaining into the package's handler.</P><P>The state change callback function is invoked with four arguments. Thefirst identifies the control endpoint. The second is an arbitrarypointer: higher-level code can fill in the<TTCLASS="STRUCTFIELD"><I>state_change_data</I></TT> field to set this. Thethird argument specifies the state change that has occurred, and thelast argument supplies the previous state (the new state is readilyavailable from the control endpoint structure).</P><P>eCos does not provide any utility functions for updating or examiningthe <TTCLASS="STRUCTFIELD"><I>state_change_fn</I></TT> or<TTCLASS="STRUCTFIELD"><I>state_change_data</I></TT> fields. Instead, it isexpected that the fields in the<SPANCLASS="STRUCTNAME">usbs_control_endpoint</SPAN> data structure will bemanipulated directly. Any utility functions would do just this, butat the cost of increased code and cpu overheads.</P></DIV><DIVCLASS="REFSECT2"><ANAME="AEN16582"></A><H3>Standard Control Messages</H3><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="PROGRAMLISTING">typedef struct usbs_control_endpoint { … unsigned char control_buffer[8]; usbs_control_return (*standard_control_fn)(struct usbs_control_endpoint*, void*); void* standard_control_data; …} usbs_control_endpoint;typedef enum { USBS_CONTROL_RETURN_HANDLED = 0, USBS_CONTROL_RETURN_UNKNOWN = 1, USBS_CONTROL_RETURN_STALL = 2} usbs_control_return;extern usbs_control_return usbs_handle_standard_control(struct usbs_control_endpoint*);</PRE⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -