+++ /dev/null
-<!-- 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">
-<META
-NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
-"><LINK
-REL="HOME"
-TITLE="eCos Reference Manual"
-HREF="ecos-ref.html"><LINK
-REL="UP"
-TITLE="eCos USB Slave Support"
-HREF="io-usb-slave.html"><LINK
-REL="PREVIOUS"
-TITLE="Receiving Data from the Host"
-HREF="usbs-start-rx.html"><LINK
-REL="NEXT"
-TITLE="Halted Endpoints"
-HREF="usbs-halt.html"></HEAD
-><BODY
-CLASS="REFENTRY"
-BGCOLOR="#FFFFFF"
-TEXT="#000000"
-LINK="#0000FF"
-VLINK="#840084"
-ALINK="#0000FF"
-><DIV
-CLASS="NAVHEADER"
-><TABLE
-SUMMARY="Header navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TH
-COLSPAN="3"
-ALIGN="center"
->eCos Reference Manual</TH
-></TR
-><TR
-><TD
-WIDTH="10%"
-ALIGN="left"
-VALIGN="bottom"
-><A
-HREF="usbs-start-rx.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="80%"
-ALIGN="center"
-VALIGN="bottom"
-></TD
-><TD
-WIDTH="10%"
-ALIGN="right"
-VALIGN="bottom"
-><A
-HREF="usbs-halt.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-></TABLE
-><HR
-ALIGN="LEFT"
-WIDTH="100%"></DIV
-><H1
-><A
-NAME="USBS-START-TX">Sending Data to the Host</H1
-><DIV
-CLASS="REFNAMEDIV"
-><A
-NAME="AEN16386"
-></A
-><H2
->Name</H2
-><TT
-CLASS="FUNCTION"
->usbs_start_tx_buffer</TT
-> -- Sending Data to the Host</DIV
-><DIV
-CLASS="REFSYNOPSISDIV"
-><A
-NAME="AEN16390"><H2
->Synopsis</H2
-><DIV
-CLASS="FUNCSYNOPSIS"
-><A
-NAME="AEN16391"><P
-></P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="FUNCSYNOPSISINFO"
->#include <cyg/io/usb/usbs.h></PRE
-></TD
-></TR
-></TABLE
-><P
-><CODE
-><CODE
-CLASS="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
-><CODE
-CLASS="FUNCDEF"
->void usbs_start_tx</CODE
->(usbs_tx_endpoint* ep);</CODE
-></P
-><P
-></P
-></DIV
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN16411"
-></A
-><H2
-><TT
-CLASS="FUNCTION"
->Description</TT
-></H2
-><P
-><TT
-CLASS="FUNCTION"
->usbs_start_tx_buffer</TT
-> is a USB-specific function
-to 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 <A
-HREF="usbs-control.html"
-><SPAN
-CLASS="STRUCTNAME"
->usbs_control_endpoint</SPAN
-></A
->
-data structure directly. The function takes five arguments:</P
-><P
-></P
-><OL
-TYPE="1"
-><LI
-><P
->The first argument identifies the specific endpoint that should be
-used. Different USB devices will support different sets of endpoints
-and the device driver will provide appropriate data structures. The
-device driver's documentation should be consulted for details of which
-endpoints are available.</P
-></LI
-><LI
-><P
->The <TT
-CLASS="PARAMETER"
-><I
->buffer</I
-></TT
-> and <TT
-CLASS="PARAMETER"
-><I
->length</I
-></TT
->
-arguments control the actual transfer. USB device drivers are not
-allowed to modify the buffer during the transfer, so the data can
-reside in read-only memory. The transfer will be for all the data
-specified, and it is the responsibility of higher-level code to make
-sure that the host is expecting this amount of data. For isochronous
-transfers the USB specification imposes an upper bound of 1023 bytes,
-but a smaller limit may be set in the <A
-HREF="usbs-enum.html#AEN16179"
->enumeration data</A
->. Interrupt
-transfers have an upper bound of 64 bytes or less, as per the
-enumeration data. Bulk transfers are more complicated because they can
-involve multiple 64-byte packets plus a terminating packet of less
-than 64 bytes, so the basic USB specification does not impose an upper
-limit on the total transfer size. Instead it is left to higher-level
-protocols to specify an appropriate upper bound. If the peripheral
-attempts to send more data than the host is willing to accept then the
-resulting behaviour is undefined and may well depend on the specific
-host operating system being used.</P
-><P
->For bulk transfers, the USB device driver or the underlying hardware
-will automatically split the transfer up into the appropriate number
-of full-size 64-byte packets plus a single terminating packet, which
-may be 0 bytes.</P
-></LI
-><LI
-><P
-><TT
-CLASS="FUNCTION"
->usbs_start_tx_buffer</TT
-> is non-blocking. It merely
-starts the transmit operation, and does not wait for completion. At
-some later point the USB device driver will invoke the completion
-function parameter with two arguments: the completion data defined by
-the last parameter, and a result field. This result will be either an
-error code < <TT
-CLASS="LITERAL"
->0</TT
->, or the amount of data
-transferred which should correspond to the
-<TT
-CLASS="PARAMETER"
-><I
->length</I
-></TT
-> argument. The most likely errors are
-<TT
-CLASS="LITERAL"
->-EPIPE</TT
-> to indicate that the connection between the
-host and the target has been broken, and <TT
-CLASS="LITERAL"
->-EAGAIN</TT
->
-for when the endpoint has been <A
-HREF="usbs-halt.html"
->halted</A
->. Specific USB device drivers may
-define additional error conditions.</P
-></LI
-></OL
-><P
->The normal sequence of events is that the USB device driver will
-update the appropriate hardware registers. At some point after that
-the host will attempt to fetch data by transmitting an IN token. Since
-a transmit operation is now in progress the peripheral can send a
-packet of data, and the host will generate an ACK. At this point the
-USB hardware will generate an interrupt, and the device driver will
-service this interrupt and arrange for a DSR to be called. Isochronous
-and interrupt transfers involve just a single packet. However, bulk
-transfers may involve multiple packets so the device driver has to
-check whether there is more data to send and set things up for the
-next packet. When the device driver DSR detects a complete transfer it
-will inform higher-level code by invoking the supplied completion
-function.</P
-><P
->This means that the completion function will normally be invoked by a
-DSR and not in thread context - although some USB device drivers may
-have a different implementation. Therefore the completion function is
-restricted in what it can do, in particular it must not make any
-calls that will or may block such as locking a mutex or allocating
-memory. The kernel documentation should be consulted for more details
-of DSR's and interrupt handling generally.</P
-><P
->It is possible that the completion function will be invoked before
-<TT
-CLASS="FUNCTION"
->usbs_start_tx_buffer</TT
-> returns. Such an event would
-be unusual because the transfer cannot happen until the next time the
-host tries to fetch data from this peripheral, but it may happen if,
-for example, another interrupt happens and a higher priority thread is
-scheduled to run. Also, if the endpoint is currently halted then the
-completion function will be invoked immediately with
-<TT
-CLASS="LITERAL"
->-EAGAIN</TT
->: typically this will happen in the current
-thread rather than in a separate DSR. The completion function is
-allowed to start another transfer immediately by calling
-<TT
-CLASS="FUNCTION"
->usbs_start_tx_buffer</TT
-> again.</P
-><P
->USB device drivers are not expected to perform any locking. It is the
-responsibility of higher-level code to ensure that there is only one
-transmit operation for a given endpoint in progress at any one time.
-If there are concurrent calls to
-<TT
-CLASS="FUNCTION"
->usbs_start_tx_buffer</TT
-> then the resulting behaviour
-is undefined. For typical USB applications this does not present any
-problems because only piece of code will access a given endpoint at
-any particular time.</P
-><P
->The following code fragment illustrates a very simple use of
-<TT
-CLASS="FUNCTION"
->usbs_start_tx_buffer</TT
-> to implement a blocking
-transmit, using a semaphore to synchronise between the foreground
-thread and the DSR. For a simple example like this no completion data
-is needed.</P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->static int error_code = 0;
-static cyg_sem_t completion_wait;
-
-static void
-completion_fn(void* data, int result)
-{
- error_code = result;
- cyg_semaphore_post(&completion_wait);
-}
-
-int
-blocking_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 <TT
-CLASS="FUNCTION"
->usbs_start</TT
->. This
-can be used by code that wants to manipulate <A
-HREF="usbs-data.html"
->data endpoints</A
-> directly, specifically the
-<TT
-CLASS="STRUCTFIELD"
-><I
->complete_fn</I
-></TT
->,
-<TT
-CLASS="STRUCTFIELD"
-><I
->complete_data</I
-></TT
->,
-<TT
-CLASS="STRUCTFIELD"
-><I
->buffer</I
-></TT
-> and
-<TT
-CLASS="STRUCTFIELD"
-><I
->buffer_size</I
-></TT
-> fields.
-<TT
-CLASS="FUNCTION"
->usbs_start_tx</TT
-> just calls a function supplied by
-the device driver.</P
-></DIV
-><DIV
-CLASS="NAVFOOTER"
-><HR
-ALIGN="LEFT"
-WIDTH="100%"><TABLE
-SUMMARY="Footer navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
-><A
-HREF="usbs-start-rx.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="ecos-ref.html"
-ACCESSKEY="H"
->Home</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
-><A
-HREF="usbs-halt.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
->Receiving Data from the Host</TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="io-usb-slave.html"
-ACCESSKEY="U"
->Up</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
->Halted Endpoints</TD
-></TR
-></TABLE
-></DIV
-></BODY
-></HTML
->
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff