📄 usbs-start-tx.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>Sending Data to 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="Receiving Data from the Host"HREF="usbs-start-rx.html"><LINKREL="NEXT"TITLE="Halted Endpoints"HREF="usbs-halt.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-start-rx.html"ACCESSKEY="P">Prev</A></TD><TDWIDTH="80%"ALIGN="center"VALIGN="bottom"></TD><TDWIDTH="10%"ALIGN="right"VALIGN="bottom"><AHREF="usbs-halt.html"ACCESSKEY="N">Next</A></TD></TR></TABLE><HRALIGN="LEFT"WIDTH="100%"></DIV><H1><ANAME="USBS-START-TX">Sending Data to the Host</H1><DIVCLASS="REFNAMEDIV"><ANAME="AEN16386"></A><H2>Name</H2><TTCLASS="FUNCTION">usbs_start_tx_buffer</TT> -- Sending Data to the Host</DIV><DIVCLASS="REFSYNOPSISDIV"><ANAME="AEN16390"><H2>Synopsis</H2><DIVCLASS="FUNCSYNOPSIS"><ANAME="AEN16391"><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_tx_buffer</CODE>(usbs_tx_endpoint* ep, const unsigned char* buffer, int length, void (*)(void*,int) complete_fn, void * complete_data);</CODE></P><P><CODE><CODECLASS="FUNCDEF">void usbs_start_tx</CODE>(usbs_tx_endpoint* ep);</CODE></P><P></P></DIV></DIV><DIVCLASS="REFSECT1"><ANAME="AEN16411"></A><H2><TTCLASS="FUNCTION">Description</TT></H2><P><TTCLASS="FUNCTION">usbs_start_tx_buffer</TT> is a USB-specific functionto transfer data from peripheral to host. 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 notallowed to modify the buffer during the transfer, so the data canreside in read-only memory. The transfer will be for all the dataspecified, and it is the responsibility of higher-level code to makesure that the host is expecting this amount of data. For isochronoustransfers the USB specification imposes an upper bound of 1023 bytes,but a smaller limit may be set in the <AHREF="usbs-enum.html#AEN16179">enumeration data</A>. Interrupttransfers have an upper bound of 64 bytes or less, as per theenumeration data. Bulk transfers are more complicated because they caninvolve multiple 64-byte packets plus a terminating packet of lessthan 64 bytes, so the basic USB specification does not impose an upperlimit on the total transfer size. Instead it is left to higher-levelprotocols to specify an appropriate upper bound. If the peripheralattempts to send more data than the host is willing to accept then theresulting behaviour is undefined and may well depend on the specifichost operating system being used.</P><P>For bulk transfers, the USB device driver or the underlying hardwarewill automatically split the transfer up into the appropriate numberof full-size 64-byte packets plus a single terminating packet, whichmay be 0 bytes.</P></LI><LI><P><TTCLASS="FUNCTION">usbs_start_tx_buffer</TT> is non-blocking. It merelystarts the transmit 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. This result will be either anerror code < <TTCLASS="LITERAL">0</TT>, or the amount of datatransferred which should correspond to the<TTCLASS="PARAMETER"><I>length</I></TT> argument. 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 maydefine 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 fetch data by transmitting an IN token. Sincea transmit operation is now in progress the peripheral can send apacket of data, and the host will generate an ACK. At this point theUSB hardware will generate an interrupt, and the device driver willservice this interrupt and arrange for a DSR to be called. Isochronousand interrupt transfers involve just a single packet. However, bulktransfers may involve multiple packets so the device driver has tocheck whether there is more data to send and set things up for thenext packet. 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_tx_buffer</TT> returns. Such an event wouldbe unusual because the transfer cannot happen until the next time thehost tries to fetch data from this peripheral, but it may happen if,for example, 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_tx_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 onetransmit operation for a given endpoint in progress at any one time.If there are concurrent calls to<TTCLASS="FUNCTION">usbs_start_tx_buffer</TT> then the resulting behaviouris undefined. For typical USB applications this does not present anyproblems because only piece of code will access a given endpoint atany particular time.</P><P>The following code fragment illustrates a very simple use of<TTCLASS="FUNCTION">usbs_start_tx_buffer</TT> to implement a blockingtransmit, 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_transmit(usbs_tx_endpoint* ep, const unsigned char* buf, int len){ error_code = 0; usbs_start_tx_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</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 calls a function supplied bythe 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-start-rx.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-halt.html"ACCESSKEY="N">Next</A></TD></TR><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top">Receiving Data from the Host</TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="io-usb-slave.html"ACCESSKEY="U">Up</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top">Halted Endpoints</TD></TR></TABLE></DIV></BODY></HTML>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -