📄 usbs-data.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>Data 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="Control Endpoints"HREF="usbs-control.html"><LINKREL="NEXT"TITLE="Writing a USB Device Driver"HREF="usbs-writing.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-control.html"ACCESSKEY="P">Prev</A></TD><TDWIDTH="80%"ALIGN="center"VALIGN="bottom"></TD><TDWIDTH="10%"ALIGN="right"VALIGN="bottom"><AHREF="usbs-writing.html"ACCESSKEY="N">Next</A></TD></TR></TABLE><HRALIGN="LEFT"WIDTH="100%"></DIV><H1><ANAME="USBS-DATA">Data Endpoints</H1><DIVCLASS="REFNAMEDIV"><ANAME="AEN16660"></A><H2>Name</H2>Data Endpoints -- Data endpoint data structures</DIV><DIVCLASS="REFSYNOPSISDIV"><ANAME="AEN16663"><H2>Synopsis</H2><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="SYNOPSIS">#include <cyg/io/usb/usbs.h>typedef struct usbs_rx_endpoint { void (*start_rx_fn)(struct usbs_rx_endpoint*); void (*set_halted_fn)(struct usbs_rx_endpoint*, cyg_bool); void (*complete_fn)(void*, int); void* complete_data; unsigned char* buffer; int buffer_size; cyg_bool halted;} usbs_rx_endpoint;typedef struct usbs_tx_endpoint { void (*start_tx_fn)(struct usbs_tx_endpoint*); void (*set_halted_fn)(struct usbs_tx_endpoint*, cyg_bool); void (*complete_fn)(void*, int); void* complete_data; const unsigned char* buffer; int buffer_size; cyg_bool halted;} usbs_tx_endpoint;</PRE></TD></TR></TABLE></DIV><DIVCLASS="REFSECT1"><ANAME="AEN16665"></A><H2>Receive and Transmit Data Structures</H2><P>In addition to a single <SPANCLASS="STRUCTNAME">usbs_control_endpoint</SPAN>data structure per USB slave device, the USB device driver should alsoprovide receive and transmit data structures corresponding to theother endpoints. The names of these are determined by the devicedriver. For example, the SA1110 USB device driver package provides<TTCLASS="LITERAL">usbs_sa11x0_ep1</TT> for receives and<TTCLASS="LITERAL">usbs_sa11x0_ep2</TT> for transmits.</P><P>Unlike control endpoints, the common USB slave package does provide anumber of utility routines to manipulate data endpoints. For example<AHREF="usbs-start-rx.html"><TTCLASS="FUNCTION">usbs_start_rx_buffer</TT></A>can be used to receive data from the host into a buffer. In additionthe USB device driver can provide devtab entries such as<TTCLASS="LITERAL">/dev/usbs1r</TT> and <TTCLASS="LITERAL">/dev/usbs2w</TT>, sohigher-level code can <TTCLASS="FUNCTION">open</TT> these devices and thenperform blocking <TTCLASS="FUNCTION">read</TT> and<TTCLASS="FUNCTION">write</TT> operations.</P><P>However, the operation of data endpoints and the variousendpoint-related functions is relatively straightforward. Firstconsider a <SPANCLASS="STRUCTNAME">usbs_rx_endpoint</SPAN> structure. Thedevice driver will provide the members<TTCLASS="STRUCTFIELD"><I>start_rx_fn</I></TT> and<TTCLASS="STRUCTFIELD"><I>set_halted_fn</I></TT>, and it will maintain the<TTCLASS="STRUCTFIELD"><I>halted</I></TT> field. To receive data, higher-levelcode sets the <TTCLASS="STRUCTFIELD"><I>buffer</I></TT>,<TTCLASS="STRUCTFIELD"><I>buffer_size</I></TT>,<TTCLASS="STRUCTFIELD"><I>complete_fn</I></TT> and optionally the<TTCLASS="STRUCTFIELD"><I>complete_data</I></TT> fields. Next the<TTCLASS="STRUCTFIELD"><I>start_rx_fn</I></TT> member should be called. Whenthe transfer has finished the device driver will invoke the completionfunction, using <TTCLASS="STRUCTFIELD"><I>complete_data</I></TT> as the firstargument and a size field for the second argument. A negative sizeindicates an error of some sort: <TTCLASS="LITERAL">-EGAIN</TT> indicatesthat the endpoint has been halted, usually at the request of the host;<TTCLASS="LITERAL">-EPIPE</TT> indicates that the connection between thehost and the peripheral has been broken. Certain device drivers maygenerate other error codes.</P><P>If higher-level code needs to halt or unhalt an endpoint then it caninvoke the <TTCLASS="STRUCTFIELD"><I>set_halted_fn</I></TT> member. When anendpoint is halted, invoking <TTCLASS="STRUCTFIELD"><I>start_rx_fn</I></TT>wit <TTCLASS="STRUCTFIELD"><I>buffer_size</I></TT> set to 0 indicates thathigher-level code wants to block until the endpoint is no longerhalted; at that point the completion function will be invoked.</P><P>USB device drivers are allowed to assume that higher-level protocolsensure that host and peripheral agree on the amount of data that willbe transferred, or at least on an upper bound. Therefore there is noneed for the device driver to maintain its own buffers, and copyoperations are avoided. If the host sends more data than expected thenthe resulting behaviour is undefined.</P><P>Transmit endpoints work in essentially the same way as receiveendpoints. Higher-level code should set the<TTCLASS="STRUCTFIELD"><I>buffer</I></TT> and<TTCLASS="STRUCTFIELD"><I>buffer_size</I></TT> fields to point at the data tobe transferred, then call <TTCLASS="STRUCTFIELD"><I>start_tx_fn</I></TT>, andthe device driver will invoked the completion function when thetransfer has completed.</P><P>USB device drivers are not expected to perform any locking. If at anytime there are two concurrent receive operations for a given endpoint,or two concurrent transmit operations, then the resulting behaviour isundefined. It is the responsibility of higher-level code to performany synchronisation that may be necessary. In practice, conflicts areunlikely because typically a given endpoint will only be accessedsequentially by just one part of the overall system.</P></DIV><DIVCLASS="NAVFOOTER"><HRALIGN="LEFT"WIDTH="100%"><TABLESUMMARY="Footer navigation table"WIDTH="100%"BORDER="0"CELLPADDING="0"CELLSPACING="0"><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top"><AHREF="usbs-control.html"ACCESSKEY="P">Prev</A></TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="ecos-ref.html"ACCESSKEY="H">Home</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top"><AHREF="usbs-writing.html"ACCESSKEY="N">Next</A></TD></TR><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top">Control Endpoints</TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="io-usb-slave.html"ACCESSKEY="U">Up</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top">Writing a USB Device Driver</TD></TR></TABLE></DIV></BODY></HTML>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -