📄 usbs-start-rx.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>Receiving Data from the Host</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="Devtab Entries"HREF="usbs-devtab.html"><LINKREL="NEXT"TITLE="Sending Data to the Host"HREF="usbs-start-tx.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-devtab.html"ACCESSKEY="P">Prev</A></TD><TDWIDTH="80%"ALIGN="center"VALIGN="bottom"></TD><TDWIDTH="10%"ALIGN="right"VALIGN="bottom"><AHREF="usbs-start-tx.html"ACCESSKEY="N">Next</A></TD></TR></TABLE><HRALIGN="LEFT"WIDTH="100%"></DIV><H1><ANAME="USBS-START-RX">Receiving Data from the Host</H1><DIVCLASS="REFNAMEDIV"><ANAME="AEN16314"></A><H2>Name</H2><TTCLASS="FUNCTION">usbs_start_rx_buffer</TT> -- Receiving Data from the Host</DIV><DIVCLASS="REFSYNOPSISDIV"><ANAME="AEN16318"><H2>Synopsis</H2><DIVCLASS="FUNCSYNOPSIS"><ANAME="AEN16319"><P></P><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="FUNCSYNOPSISINFO">#include <cyg/io/usb/usbs.h></PRE></TD></TR></TABLE><P><CODE><CODECLASS="FUNCDEF">void usbs_start_rx_buffer</CODE>(usbs_rx_endpoint* ep, unsigned char* buffer, int length, void (*)(void*,int) complete_fn, void * complete_data);</CODE></P><P><CODE><CODECLASS="FUNCDEF">void usbs_start_rx</CODE>(usbs_rx_endpoint* ep);</CODE></P><P></P></DIV></DIV><DIVCLASS="REFSECT1"><ANAME="AEN16339"></A><H2><TTCLASS="FUNCTION">Description</TT></H2><P><TTCLASS="FUNCTION">usbs_start_rx_buffer</TT> is a USB-specific functionto accept a transfer from host to peripheral. It can be used for bulk,interrupt or isochronous transfers, but not for control messages.Instead those involve manipulating the <AHREF="usbs-control.html"><SPANCLASS="STRUCTNAME">usbs_control_endpoint</SPAN></A>data structure directly. The function takes five arguments:</P><P></P><OLTYPE="1"><LI><P>The first argument identifies the specific endpoint that should beused. Different USB devices will support different sets of endpointsand the device driver will provide appropriate data structures. Thedevice driver's documentation should be consulted for details of whichendpoints are available.</P></LI><LI><P>The <TTCLASS="PARAMETER"><I>buffer</I></TT> and <TTCLASS="PARAMETER"><I>length</I></TT>arguments control the actual transfer. USB device drivers are notexpected to perform any buffering or to support partial transfers, sothe length specified should correspond to the maximum transfer that iscurrently possible and the buffer should be at least this large. Forisochronous transfers the USB specification imposes an upper bound of1023 bytes, and a smaller limit may be set in the <AHREF="usbs-enum.html#AEN16179">enumeration data</A>. Interrupttransfers are similarly straightforward with an upper bound of 64bytes, or less as per the enumeration data. Bulk transfers are morecomplicated because they can involve multiple 64-byte packets plus aterminating packet of less than 64 bytes, so there is no predefinedlimit on the transfer size. Instead it is left to higher-levelprotocols to specify an appropriate upper bound.</P><P>One technique that may work for bulk transfers is to exploit the factthat such transfers happen in 64-byte packets: it may be possible toreceive an initial 64 bytes, corresponding to the first packet in thetransfer; these 64 bytes can then be examined to determine the totaltransfer size, and the remaining data can be transferred in anotherreceive operation. This technique is not guaranteed to work with allUSB hardware. Also, if the delay between accepting the first packet andthe remainder of the transfer is excessive then this could causetimeout problems for the host-side software. For these reasons thistechnique should be avoided.</P></LI><LI><P><TTCLASS="FUNCTION">usbs_start_rx_buffer</TT> is non-blocking. It merelystarts the receive operation, and does not wait for completion. Atsome later point the USB device driver will invoke the completionfunction parameter with two arguments: the completion data defined bythe last parameter and a result field. A result >=<TTCLASS="LITERAL">0</TT> indicates a successful transfer of that manybytes, which may be less than the upper bound imposed by the<TTCLASS="PARAMETER"><I>length</I></TT> argument. A result <<TTCLASS="LITERAL">0</TT> indicates an error. The most likely errors are<TTCLASS="LITERAL">-EPIPE</TT> to indicate that the connection between thehost and the target has been broken, and <TTCLASS="LITERAL">-EAGAIN</TT>for when the endpoint has been <AHREF="usbs-halt.html">halted</A>. Specific USB device drivers mayspecify additional error conditions.</P></LI></OL><P>The normal sequence of events is that the USB device driver willupdate the appropriate hardware registers. At some point after thatthe host will attempt to send data by transmitting an OUT tokenfollowed by a data packet, and since a receive operation is now inprogress the data will be accepted and ACK'd. If there were no receiveoperation then the peripheral would instead generate a NAK. The USBhardware will generate an interrupt once the whole packet has beenreceived, and the USB device driver will service this interrupt andarrange for a DSR to be called. Isochronous and interrupt transfersinvolve just a single packet. However, bulk transfers may involvemultiple packets so the device driver has to check whether the packetwas a full 64 bytes or whether it was a terminating packet of lessthan this. When the device driver DSR detects a complete transfer itwill inform higher-level code by invoking the supplied completionfunction.</P><P>This means that the completion function will normally be invoked by aDSR and not in thread context - although some USB device drivers mayhave a different implementation. Therefore the completion function isrestricted in what it can do. In particular it must not make anycalls that will or may block such as locking a mutex or allocatingmemory. The kernel documentation should be consulted for more detailsof DSR's and interrupt handling generally.</P><P>It is possible that the completion function will be invoked before<TTCLASS="FUNCTION">usbs_start_rx_buffer</TT> returns. Such an event wouldbe unusual because the transfer cannot happen until the next time thehost tries to send data to this peripheral, but it may happen if forexample another interrupt happens and a higher priority thread isscheduled to run. Also, if the endpoint is currently halted then thecompletion function will be invoked immediately with<TTCLASS="LITERAL">-EAGAIN</TT>: typically this will happen in the currentthread rather than in a separate DSR. The completion function isallowed to start another transfer immediately by calling<TTCLASS="FUNCTION">usbs_start_rx_buffer</TT> again.</P><P>USB device drivers are not expected to perform any locking. It is theresponsibility of higher-level code to ensure that there is only onereceive operation for a given endpoint in progress at any one time. Ifthere are concurrent calls to<TTCLASS="FUNCTION">usbs_start_rx_buffer</TT> then the resulting behaviouris undefined. For typical USB applications this does not present anyproblems, because only one piece of code will access a given endpointat any particular time.</P><P>The following code fragment illustrates a very simple use of<TTCLASS="FUNCTION">usbs_start_rx_buffer</TT> to implement a blockingreceive, using a semaphore to synchronise between the foregroundthread and the DSR. For a simple example like this no completion datais needed.</P><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="PROGRAMLISTING">static int error_code = 0;static cyg_sem_t completion_wait;static voidcompletion_fn(void* data, int result){ error_code = result; cyg_semaphore_post(&completion_wait);}intblocking_receive(usbs_rx_endpoint* ep, unsigned char* buf, int len){ error_code = 0; usbs_start_rx_buffer(ep, buf, len, &completion_fn, NULL); cyg_semaphore_wait(&completion_wait); return error_code;}</PRE></TD></TR></TABLE><P>There is also a utility function <TTCLASS="FUNCTION">usbs_start_rx</TT>. Thiscan be used by code that wants to manipulate <AHREF="usbs-data.html">data endpoints</A> directly, specifically the<TTCLASS="STRUCTFIELD"><I>complete_fn</I></TT>,<TTCLASS="STRUCTFIELD"><I>complete_data</I></TT>,<TTCLASS="STRUCTFIELD"><I>buffer</I></TT> and<TTCLASS="STRUCTFIELD"><I>buffer_size</I></TT> fields.<TTCLASS="FUNCTION">usbs_start_tx</TT> just invokes a functionsupplied by the device driver.</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-devtab.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-start-tx.html"ACCESSKEY="N">Next</A></TD></TR><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top">Devtab Entries</TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="io-usb-slave.html"ACCESSKEY="U">Up</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top">Sending Data to the Host</TD></TR></TABLE></DIV></BODY></HTML>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -