OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [packages/] [io/] [usb/] [slave/] [v2_0/] [doc/] [usbs-start-tx.html] - Diff between revs 27 and 174

Only display areas with differences | Details | Blame | View Log

Rev 27 Rev 174
<!-- Copyright (C) 2002 Red Hat, Inc.                                -->
<!-- Copyright (C) 2002 Red Hat, Inc.                                -->
<!-- This material may be distributed only subject to the terms      -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/).                           -->
<!-- http://www.opencontent.org/openpub/).                           -->
<!-- Distribution of substantively modified versions of this         -->
<!-- Distribution of substantively modified versions of this         -->
<!-- document is prohibited without the explicit permission of the   -->
<!-- document is prohibited without the explicit permission of the   -->
<!-- copyright holder.                                               -->
<!-- copyright holder.                                               -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission is obtained from the copyright holder.               -->
<!-- permission is obtained from the copyright holder.               -->
<HTML
<HTML
><HEAD
><HEAD
><TITLE
><TITLE
>Sending Data to the Host</TITLE
>Sending Data to the Host</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
<META
NAME="GENERATOR"
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.64
CONTENT="Modular DocBook HTML Stylesheet Version 1.64
"><LINK
"><LINK
REL="HOME"
REL="HOME"
TITLE="eCos USB Slave Support"
TITLE="eCos USB Slave Support"
HREF="io-usb-slave.html"><LINK
HREF="io-usb-slave.html"><LINK
REL="PREVIOUS"
REL="PREVIOUS"
TITLE="Receiving Data from the Host"
TITLE="Receiving Data from the Host"
HREF="usbs-start-rx.html"><LINK
HREF="usbs-start-rx.html"><LINK
REL="NEXT"
REL="NEXT"
TITLE="Halted Endpoints"
TITLE="Halted Endpoints"
HREF="usbs-halt.html"></HEAD
HREF="usbs-halt.html"></HEAD
><BODY
><BODY
CLASS="REFENTRY"
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
BGCOLOR="#FFFFFF"
TEXT="#000000"
TEXT="#000000"
LINK="#0000FF"
LINK="#0000FF"
VLINK="#840084"
VLINK="#840084"
ALINK="#0000FF"
ALINK="#0000FF"
><DIV
><DIV
CLASS="NAVHEADER"
CLASS="NAVHEADER"
><TABLE
><TABLE
WIDTH="100%"
WIDTH="100%"
BORDER="0"
BORDER="0"
CELLPADDING="0"
CELLPADDING="0"
CELLSPACING="0"
CELLSPACING="0"
><TR
><TR
><TH
><TH
COLSPAN="3"
COLSPAN="3"
ALIGN="center"
ALIGN="center"
>eCos USB Slave Support</TH
>eCos USB Slave Support</TH
></TR
></TR
><TR
><TR
><TD
><TD
WIDTH="10%"
WIDTH="10%"
ALIGN="left"
ALIGN="left"
VALIGN="bottom"
VALIGN="bottom"
><A
><A
HREF="usbs-start-rx.html"
HREF="usbs-start-rx.html"
>Prev</A
>Prev</A
></TD
></TD
><TD
><TD
WIDTH="80%"
WIDTH="80%"
ALIGN="center"
ALIGN="center"
VALIGN="bottom"
VALIGN="bottom"
></TD
></TD
><TD
><TD
WIDTH="10%"
WIDTH="10%"
ALIGN="right"
ALIGN="right"
VALIGN="bottom"
VALIGN="bottom"
><A
><A
HREF="usbs-halt.html"
HREF="usbs-halt.html"
>Next</A
>Next</A
></TD
></TD
></TR
></TR
></TABLE
></TABLE
><HR
><HR
ALIGN="LEFT"
ALIGN="LEFT"
WIDTH="100%"></DIV
WIDTH="100%"></DIV
><H1
><H1
><A
><A
NAME="USBS-START-TX"
NAME="USBS-START-TX"
>Sending Data to the Host</A
>Sending Data to the Host</A
></H1
></H1
><DIV
><DIV
CLASS="REFNAMEDIV"
CLASS="REFNAMEDIV"
><A
><A
NAME="AEN349"
NAME="AEN349"
></A
></A
><H2
><H2
>Name</H2
>Name</H2
><TT
><TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>usbs_start_tx_buffer</TT
>usbs_start_tx_buffer</TT
>&nbsp;--&nbsp;Sending Data to the Host</DIV
>&nbsp;--&nbsp;Sending Data to the Host</DIV
><DIV
><DIV
CLASS="REFSYNOPSISDIV"
CLASS="REFSYNOPSISDIV"
><A
><A
NAME="AEN353"
NAME="AEN353"
></A
></A
><H2
><H2
>Synopsis</H2
>Synopsis</H2
><DIV
><DIV
CLASS="FUNCSYNOPSIS"
CLASS="FUNCSYNOPSIS"
><A
><A
NAME="AEN354"
NAME="AEN354"
></A
></A
><P
><P
></P
></P
><TABLE
><TABLE
BORDER="0"
BORDER="0"
BGCOLOR="#E0E0E0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
WIDTH="100%"
><TR
><TR
><TD
><TD
><PRE
><PRE
CLASS="FUNCSYNOPSISINFO"
CLASS="FUNCSYNOPSISINFO"
>#include &lt;cyg/io/usb/usbs.h&gt;</PRE
>#include &lt;cyg/io/usb/usbs.h&gt;</PRE
></TD
></TD
></TR
></TR
></TABLE
></TABLE
><P
><P
><CODE
><CODE
><CODE
><CODE
CLASS="FUNCDEF"
CLASS="FUNCDEF"
>void usbs_start_tx_buffer</CODE
>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
>(usbs_tx_endpoint* ep, const unsigned char* buffer, int length, void (*)(void*,int) complete_fn, void * complete_data);</CODE
></P
></P
><P
><P
><CODE
><CODE
><CODE
><CODE
CLASS="FUNCDEF"
CLASS="FUNCDEF"
>void usbs_start_tx</CODE
>void usbs_start_tx</CODE
>(usbs_tx_endpoint* ep);</CODE
>(usbs_tx_endpoint* ep);</CODE
></P
></P
><P
><P
></P
></P
></DIV
></DIV
></DIV
></DIV
><DIV
><DIV
CLASS="REFSECT1"
CLASS="REFSECT1"
><A
><A
NAME="AEN374"
NAME="AEN374"
></A
></A
><H2
><H2
><TT
><TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>Description</TT
>Description</TT
></H2
></H2
><P
><P
><TT
><TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>usbs_start_tx_buffer</TT
>usbs_start_tx_buffer</TT
> is a USB-specific function
> is a USB-specific function
to transfer data from peripheral to host. It can be used for bulk,
to transfer data from peripheral to host. It can be used for bulk,
interrupt or isochronous transfers, but not for control messages;
interrupt or isochronous transfers, but not for control messages;
instead those involve manipulating the <A
instead those involve manipulating the <A
HREF="usbs-control.html"
HREF="usbs-control.html"
><SPAN
><SPAN
CLASS="STRUCTNAME"
CLASS="STRUCTNAME"
>usbs_control_endpoint</SPAN
>usbs_control_endpoint</SPAN
></A
></A
>
>
data structure directly. The function takes five arguments:</P
data structure directly. The function takes five arguments:</P
><P
><P
></P
></P
><OL
><OL
TYPE="1"
TYPE="1"
><LI
><LI
><P
><P
>The first argument identifies the specific endpoint that should be
>The first argument identifies the specific endpoint that should be
used. Different USB devices will support different sets of endpoints
used. Different USB devices will support different sets of endpoints
and the device driver will provide appropriate data structures. The
and the device driver will provide appropriate data structures. The
device driver's documentation should be consulted for details of which
device driver's documentation should be consulted for details of which
endpoints are available.</P
endpoints are available.</P
></LI
></LI
><LI
><LI
><P
><P
>The <TT
>The <TT
CLASS="PARAMETER"
CLASS="PARAMETER"
><I
><I
>buffer</I
>buffer</I
></TT
></TT
> and <TT
> and <TT
CLASS="PARAMETER"
CLASS="PARAMETER"
><I
><I
>length</I
>length</I
></TT
></TT
>
>
arguments control the actual transfer. USB device drivers are not
arguments control the actual transfer. USB device drivers are not
allowed to modify the buffer during the transfer, so the data can
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
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
specified, and it is the responsibility of higher-level code to make
sure that the host is expecting this amount of data. For isochronous
sure that the host is expecting this amount of data. For isochronous
transfers the USB specification imposes an upper bound of 1023 bytes,
transfers the USB specification imposes an upper bound of 1023 bytes,
but a smaller limit may be set in the <A
but a smaller limit may be set in the <A
HREF="usbs-enum.html#AEN142"
HREF="usbs-enum.html#AEN142"
>enumeration data</A
>enumeration data</A
>. Interrupt
>. Interrupt
transfers have an upper bound of 64 bytes or less, as per the
transfers have an upper bound of 64 bytes or less, as per the
enumeration data. Bulk transfers are more complicated because they can
enumeration data. Bulk transfers are more complicated because they can
involve multiple 64-byte packets plus a terminating packet of less
involve multiple 64-byte packets plus a terminating packet of less
than 64 bytes, so the basic USB specification does not impose an upper
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
limit on the total transfer size. Instead it is left to higher-level
protocols to specify an appropriate upper bound. If the peripheral
protocols to specify an appropriate upper bound. If the peripheral
attempts to send more data than the host is willing to accept then the
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
resulting behaviour is undefined and may well depend on the specific
host operating system being used.</P
host operating system being used.</P
><P
><P
>For bulk transfers, the USB device driver or the underlying hardware
>For bulk transfers, the USB device driver or the underlying hardware
will automatically split the transfer up into the appropriate number
will automatically split the transfer up into the appropriate number
of full-size 64-byte packets plus a single terminating packet, which
of full-size 64-byte packets plus a single terminating packet, which
may be 0 bytes.</P
may be 0 bytes.</P
></LI
></LI
><LI
><LI
><P
><P
><TT
><TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>usbs_start_tx_buffer</TT
>usbs_start_tx_buffer</TT
> is non-blocking. It merely
> is non-blocking. It merely
starts the transmit operation, and does not wait for completion. At
starts the transmit operation, and does not wait for completion. At
some later point the USB device driver will invoke the completion
some later point the USB device driver will invoke the completion
function parameter with two arguments: the completion data defined by
function parameter with two arguments: the completion data defined by
the last parameter, and a result field. This result will be either an
the last parameter, and a result field. This result will be either an
error code &lt; <TT
error code &lt; <TT
CLASS="LITERAL"
CLASS="LITERAL"
>0</TT
>0</TT
>, or the amount of data
>, or the amount of data
transferred which should correspond to the
transferred which should correspond to the
<TT
<TT
CLASS="PARAMETER"
CLASS="PARAMETER"
><I
><I
>length</I
>length</I
></TT
></TT
> argument. The most likely errors are
> argument. The most likely errors are
<TT
<TT
CLASS="LITERAL"
CLASS="LITERAL"
>-EPIPE</TT
>-EPIPE</TT
> to indicate that the connection between the
> to indicate that the connection between the
host and the target has been broken, and <TT
host and the target has been broken, and <TT
CLASS="LITERAL"
CLASS="LITERAL"
>-EAGAIN</TT
>-EAGAIN</TT
>
>
for when the endpoint has been <A
for when the endpoint has been <A
HREF="usbs-halt.html"
HREF="usbs-halt.html"
>halted</A
>halted</A
>. Specific USB device drivers may
>. Specific USB device drivers may
define additional error conditions.</P
define additional error conditions.</P
></LI
></LI
></OL
></OL
><P
><P
>The normal sequence of events is that the USB device driver will
>The normal sequence of events is that the USB device driver will
update the appropriate hardware registers. At some point after that
update the appropriate hardware registers. At some point after that
the host will attempt to fetch data by transmitting an IN token. Since
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
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
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
USB hardware will generate an interrupt, and the device driver will
service this interrupt and arrange for a DSR to be called. Isochronous
service this interrupt and arrange for a DSR to be called. Isochronous
and interrupt transfers involve just a single packet. However, bulk
and interrupt transfers involve just a single packet. However, bulk
transfers may involve multiple packets so the device driver has to
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
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
next packet. When the device driver DSR detects a complete transfer it
will inform higher-level code by invoking the supplied completion
will inform higher-level code by invoking the supplied completion
function.</P
function.</P
><P
><P
>This means that the completion function will normally be invoked by a
>This means that the completion function will normally be invoked by a
DSR and not in thread context - although some USB device drivers may
DSR and not in thread context - although some USB device drivers may
have a different implementation. Therefore the completion function is
have a different implementation. Therefore the completion function is
restricted in what it can do, in particular it must not make any
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
calls that will or may block such as locking a mutex or allocating
memory. The kernel documentation should be consulted for more details
memory. The kernel documentation should be consulted for more details
of DSR's and interrupt handling generally.</P
of DSR's and interrupt handling generally.</P
><P
><P
>It is possible that the completion function will be invoked before
>It is possible that the completion function will be invoked before
<TT
<TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>usbs_start_tx_buffer</TT
>usbs_start_tx_buffer</TT
> returns. Such an event would
> returns. Such an event would
be unusual because the transfer cannot happen until the next time the
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,
host tries to fetch data from this peripheral, but it may happen if,
for example, another interrupt happens and a higher priority thread is
for example, another interrupt happens and a higher priority thread is
scheduled to run. Also, if the endpoint is currently halted then the
scheduled to run. Also, if the endpoint is currently halted then the
completion function will be invoked immediately with
completion function will be invoked immediately with
<TT
<TT
CLASS="LITERAL"
CLASS="LITERAL"
>-EAGAIN</TT
>-EAGAIN</TT
>: typically this will happen in the current
>: typically this will happen in the current
thread rather than in a separate DSR. The completion function is
thread rather than in a separate DSR. The completion function is
allowed to start another transfer immediately by calling
allowed to start another transfer immediately by calling
<TT
<TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>usbs_start_tx_buffer</TT
>usbs_start_tx_buffer</TT
> again.</P
> again.</P
><P
><P
>USB device drivers are not expected to perform any locking. It is the
>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
responsibility of higher-level code to ensure that there is only one
transmit operation for a given endpoint in progress at any one time.
transmit operation for a given endpoint in progress at any one time.
If there are concurrent calls to
If there are concurrent calls to
<TT
<TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>usbs_start_tx_buffer</TT
>usbs_start_tx_buffer</TT
> then the resulting behaviour
> then the resulting behaviour
is undefined. For typical USB applications this does not present any
is undefined. For typical USB applications this does not present any
problems because only piece of code will access a given endpoint at
problems because only piece of code will access a given endpoint at
any particular time.</P
any particular time.</P
><P
><P
>The following code fragment illustrates a very simple use of
>The following code fragment illustrates a very simple use of
<TT
<TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>usbs_start_tx_buffer</TT
>usbs_start_tx_buffer</TT
> to implement a blocking
> to implement a blocking
transmit, using a semaphore to synchronise between the foreground
transmit, using a semaphore to synchronise between the foreground
thread and the DSR. For a simple example like this no completion data
thread and the DSR. For a simple example like this no completion data
is needed.</P
is needed.</P
><TABLE
><TABLE
BORDER="0"
BORDER="0"
BGCOLOR="#E0E0E0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
WIDTH="100%"
><TR
><TR
><TD
><TD
><PRE
><PRE
CLASS="PROGRAMLISTING"
CLASS="PROGRAMLISTING"
>static int error_code = 0;
>static int error_code = 0;
static cyg_sem_t completion_wait;
static cyg_sem_t completion_wait;
 
 
static void
static void
completion_fn(void* data, int result)
completion_fn(void* data, int result)
{
{
    error_code = result;
    error_code = result;
    cyg_semaphore_post(&amp;completion_wait);
    cyg_semaphore_post(&amp;completion_wait);
}
}
 
 
int
int
blocking_transmit(usbs_tx_endpoint* ep, const unsigned char* buf, int len)
blocking_transmit(usbs_tx_endpoint* ep, const unsigned char* buf, int len)
{
{
    error_code = 0;
    error_code = 0;
    usbs_start_tx_buffer(ep, buf, len, &amp;completion_fn, NULL);
    usbs_start_tx_buffer(ep, buf, len, &amp;completion_fn, NULL);
    cyg_semaphore_wait(&amp;completion_wait);
    cyg_semaphore_wait(&amp;completion_wait);
    return error_code;
    return error_code;
}</PRE
}</PRE
></TD
></TD
></TR
></TR
></TABLE
></TABLE
><P
><P
>There is also a utility function <TT
>There is also a utility function <TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>usbs_start</TT
>usbs_start</TT
>. This
>. This
can be used by code that wants to manipulate <A
can be used by code that wants to manipulate <A
HREF="usbs-data.html"
HREF="usbs-data.html"
>data endpoints</A
>data endpoints</A
> directly, specifically the
> directly, specifically the
<TT
<TT
CLASS="STRUCTFIELD"
CLASS="STRUCTFIELD"
><I
><I
>complete_fn</I
>complete_fn</I
></TT
></TT
>,
>,
<TT
<TT
CLASS="STRUCTFIELD"
CLASS="STRUCTFIELD"
><I
><I
>complete_data</I
>complete_data</I
></TT
></TT
>,
>,
<TT
<TT
CLASS="STRUCTFIELD"
CLASS="STRUCTFIELD"
><I
><I
>buffer</I
>buffer</I
></TT
></TT
> and
> and
<TT
<TT
CLASS="STRUCTFIELD"
CLASS="STRUCTFIELD"
><I
><I
>buffer_size</I
>buffer_size</I
></TT
></TT
> fields.
> fields.
<TT
<TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>usbs_start_tx</TT
>usbs_start_tx</TT
> just calls a function supplied by
> just calls a function supplied by
the device driver.</P
the device driver.</P
></DIV
></DIV
><DIV
><DIV
CLASS="NAVFOOTER"
CLASS="NAVFOOTER"
><HR
><HR
ALIGN="LEFT"
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"><TABLE
WIDTH="100%"
WIDTH="100%"
BORDER="0"
BORDER="0"
CELLPADDING="0"
CELLPADDING="0"
CELLSPACING="0"
CELLSPACING="0"
><TR
><TR
><TD
><TD
WIDTH="33%"
WIDTH="33%"
ALIGN="left"
ALIGN="left"
VALIGN="top"
VALIGN="top"
><A
><A
HREF="usbs-start-rx.html"
HREF="usbs-start-rx.html"
>Prev</A
>Prev</A
></TD
></TD
><TD
><TD
WIDTH="34%"
WIDTH="34%"
ALIGN="center"
ALIGN="center"
VALIGN="top"
VALIGN="top"
><A
><A
HREF="io-usb-slave.html"
HREF="io-usb-slave.html"
>Home</A
>Home</A
></TD
></TD
><TD
><TD
WIDTH="33%"
WIDTH="33%"
ALIGN="right"
ALIGN="right"
VALIGN="top"
VALIGN="top"
><A
><A
HREF="usbs-halt.html"
HREF="usbs-halt.html"
>Next</A
>Next</A
></TD
></TD
></TR
></TR
><TR
><TR
><TD
><TD
WIDTH="33%"
WIDTH="33%"
ALIGN="left"
ALIGN="left"
VALIGN="top"
VALIGN="top"
>Receiving Data from the Host</TD
>Receiving Data from the Host</TD
><TD
><TD
WIDTH="34%"
WIDTH="34%"
ALIGN="center"
ALIGN="center"
VALIGN="top"
VALIGN="top"
>&nbsp;</TD
>&nbsp;</TD
><TD
><TD
WIDTH="33%"
WIDTH="33%"
ALIGN="right"
ALIGN="right"
VALIGN="top"
VALIGN="top"
>Halted Endpoints</TD
>Halted Endpoints</TD
></TR
></TR
></TABLE
></TABLE
></DIV
></DIV
></BODY
></BODY
></HTML
></HTML
 
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.