packages/io/usb/slave/v2_0/doc/usbs-halt.html

   1 <!-- Copyright (C) 2002 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of substantively modified versions of this         -->
   7 <!-- document is prohibited without the explicit permission of the   -->
   8 <!-- copyright holder.                                               -->
   9 <!-- Distribution of the work or derivative of the work in any       -->
  10 <!-- standard (paper) book form is prohibited unless prior           -->
  11 <!-- permission is obtained from the copyright holder.               -->
  12 <HTML
  13 ><HEAD
  14 ><TITLE
  15 >Halted Endpoints</TITLE
  16 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  17 <META
  18 NAME="GENERATOR"
  19 CONTENT="Modular DocBook HTML Stylesheet Version 1.64
  20 "><LINK
  21 REL="HOME"
  22 TITLE="eCos USB Slave Support"
  23 HREF="io-usb-slave.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Sending Data to the Host"
  26 HREF="usbs-start-tx.html"><LINK
  27 REL="NEXT"
  28 TITLE="Control Endpoints"
  29 HREF="usbs-control.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 WIDTH="100%"
  41 BORDER="0"
  42 CELLPADDING="0"
  43 CELLSPACING="0"
  44 ><TR
  45 ><TH
  46 COLSPAN="3"
  47 ALIGN="center"
  48 >eCos USB Slave Support</TH
  49 ></TR
  50 ><TR
  51 ><TD
  52 WIDTH="10%"
  53 ALIGN="left"
  54 VALIGN="bottom"
  55 ><A
  56 HREF="usbs-start-tx.html"
  57 >Prev</A
  58 ></TD
  59 ><TD
  60 WIDTH="80%"
  61 ALIGN="center"
  62 VALIGN="bottom"
  63 ></TD
  64 ><TD
  65 WIDTH="10%"
  66 ALIGN="right"
  67 VALIGN="bottom"
  68 ><A
  69 HREF="usbs-control.html"
  70 >Next</A
  71 ></TD
  72 ></TR
  73 ></TABLE
  74 ><HR
  75 ALIGN="LEFT"
  76 WIDTH="100%"></DIV
  77 ><H1
  78 ><A
  79 NAME="USBS-HALT"
  80 >Halted Endpoints</A
  81 ></H1
  82 ><DIV
  83 CLASS="REFNAMEDIV"
  84 ><A
  85 NAME="AEN420"
  86 ></A
  87 ><H2
  88 >Name</H2
  89 >Halted Endpoints&nbsp;--&nbsp;Support for Halting and Halted Endpoints</DIV
  90 ><DIV
  91 CLASS="REFSYNOPSISDIV"
  92 ><A
  93 NAME="AEN423"
  94 ></A
  95 ><H2
  96 >Synopsis</H2
  97 ><DIV
  98 CLASS="FUNCSYNOPSIS"
  99 ><A
 100 NAME="AEN424"
 101 ></A
 102 ><P
 103 ></P
 104 ><TABLE
 105 BORDER="0"
 106 BGCOLOR="#E0E0E0"
 107 WIDTH="100%"
 108 ><TR
 109 ><TD
 110 ><PRE
 111 CLASS="FUNCSYNOPSISINFO"
 112 >#include &lt;cyg/io/usb/usbs.h&gt;</PRE
 113 ></TD
 114 ></TR
 115 ></TABLE
 116 ><P
 117 ><CODE
 118 ><CODE
 119 CLASS="FUNCDEF"
 120 >cyg_bool usbs_rx_endpoint_halted</CODE
 121 >(usbs_rx_endpoint* ep);</CODE
 122 ></P
 123 ><P
 124 ><CODE
 125 ><CODE
 126 CLASS="FUNCDEF"
 127 >void usbs_set_rx_endpoint_halted</CODE
 128 >(usbs_rx_endpoint* ep, cyg_bool new_state);</CODE
 129 ></P
 130 ><P
 131 ><CODE
 132 ><CODE
 133 CLASS="FUNCDEF"
 134 >void usbs_start_rx_endpoint_wait</CODE
 135 >(usbs_rx_endpoint* ep, void (*)(void*, int) complete_fn, void * complete_data);</CODE
 136 ></P
 137 ><P
 138 ><CODE
 139 ><CODE
 140 CLASS="FUNCDEF"
 141 >cyg_bool
 142 usbs_tx_endpoint_halted</CODE
 143 >(usbs_tx_endpoint* ep);</CODE
 144 ></P
 145 ><P
 146 ><CODE
 147 ><CODE
 148 CLASS="FUNCDEF"
 149 >void usbs_set_tx_endpoint_halted</CODE
 150 >(usbs_tx_endpoint* ep, cyg_bool new_state);</CODE
 151 ></P
 152 ><P
 153 ><CODE
 154 ><CODE
 155 CLASS="FUNCDEF"
 156 >void usbs_start_tx_endpoint_wait</CODE
 157 >(usbs_tx_endpoint* ep, void (*)(void*, int) complete_fn, void * complete_data);</CODE
 158 ></P
 159 ><P
 160 ></P
 161 ></DIV
 162 ></DIV
 163 ><DIV
 164 CLASS="REFSECT1"
 165 ><A
 166 NAME="AEN468"
 167 ></A
 168 ><H2
 169 ><TT
 170 CLASS="FUNCTION"
 171 >Description</TT
 172 ></H2
 173 ><P
 174 >Normal USB traffic involves straightforward handshakes, with either an
 175 <TT
 176 CLASS="LITERAL"
 177 >ACK</TT
 178 > to indicate that a packet was transferred
 179 without errors, or a <TT
 180 CLASS="LITERAL"
 181 >NAK</TT
 182 > if an error occurred, or
 183 if a peripheral is currently unable to process another packet from the
 184 host, or has no packet to send to the host. There is a third form of
 185 handshake, a <TT
 186 CLASS="LITERAL"
 187 >STALL</TT
 188 >, which indicates that the
 189 endpoint is currently <I
 190 CLASS="EMPHASIS"
 191 >halted</I
 192 >.</P
 193 ><P
 194 >When an endpoint is halted it means that the host-side code needs to
 195 take some sort of recovery action before communication over that
 196 endpoint can resume. The exact circumstances under which this can
 197 happen are not defined by the USB specification, but one example would
 198 be a protocol violation if say the peripheral attempted to transmit
 199 more data to the host than was permitted by the protocol in use. The
 200 host can use the standard control messages get-status, set-feature and
 201 clear-feature to examine and manipulate the halted status of a given
 202 endpoint. There are USB-specific functions which can be used inside
 203 the peripheral to achieve the same effect. Once an endpoint has been
 204 halted the host can then interact with the peripheral using class or
 205 vendor control messages to perform appropriate recovery, and then the
 206 halted condition can be cleared.</P
 207 ><P
 208 >Halting an endpoint does not constitute a device state change, and
 209 there is no mechanism by which higher-level code can be informed
 210 immediately. However, any ongoing receive or transmit operations will
 211 be aborted with an <TT
 212 CLASS="LITERAL"
 213 >-EAGAIN</TT
 214 > error, and any new
 215 receives or transmits will fail immediately with the same error.</P
 216 ><P
 217 >There are six functions to support halted endpoints, one set for
 218 receive endpoints and another for transmit endpoints, with both sets
 219 behaving in essentially the same way. The first,
 220 <TT
 221 CLASS="FUNCTION"
 222 >usbs_rx_endpoint_halted</TT
 223 >, can be used to determine
 224 whether or not an endpoint is currently halted: it takes a single
 225 argument that identifies the endpoint of interest. The second
 226 function, <TT
 227 CLASS="FUNCTION"
 228 >usbs_set_rx_endpoint_halted</TT
 229 >, can be
 230 used to change the halted condition of an endpoint: it takes two
 231 arguments; one to identify the endpoint and another to specify the new
 232 state. The last function
 233 <TT
 234 CLASS="FUNCTION"
 235 >usbs_start_rx_endpoint_wait</TT
 236 > operates in much the
 237 same way as <TT
 238 CLASS="FUNCTION"
 239 >usbs_start_rx_buffer</TT
 240 >: when the
 241 endpoint is no longer halted the device driver will invoke the
 242 supplied completion function with a status of 0. The completion
 243 function has the same signature as that for a transfer operation.
 244 Often it will be possible to use a single completion function and have
 245 the foreground code invoke either
 246 <TT
 247 CLASS="FUNCTION"
 248 >usbs_start_rx_buffer</TT
 249 > or
 250 <TT
 251 CLASS="FUNCTION"
 252 >usbs_start_rx_endpoint_wait</TT
 253 > depending on the
 254 current state of the endpoint.</P
 255 ></DIV
 256 ><DIV
 257 CLASS="NAVFOOTER"
 258 ><HR
 259 ALIGN="LEFT"
 260 WIDTH="100%"><TABLE
 261 WIDTH="100%"
 262 BORDER="0"
 263 CELLPADDING="0"
 264 CELLSPACING="0"
 265 ><TR
 266 ><TD
 267 WIDTH="33%"
 268 ALIGN="left"
 269 VALIGN="top"
 270 ><A
 271 HREF="usbs-start-tx.html"
 272 >Prev</A
 273 ></TD
 274 ><TD
 275 WIDTH="34%"
 276 ALIGN="center"
 277 VALIGN="top"
 278 ><A
 279 HREF="io-usb-slave.html"
 280 >Home</A
 281 ></TD
 282 ><TD
 283 WIDTH="33%"
 284 ALIGN="right"
 285 VALIGN="top"
 286 ><A
 287 HREF="usbs-control.html"
 288 >Next</A
 289 ></TD
 290 ></TR
 291 ><TR
 292 ><TD
 293 WIDTH="33%"
 294 ALIGN="left"
 295 VALIGN="top"
 296 >Sending Data to the Host</TD
 297 ><TD
 298 WIDTH="34%"
 299 ALIGN="center"
 300 VALIGN="top"
 301 >&nbsp;</TD
 302 ><TD
 303 WIDTH="33%"
 304 ALIGN="right"
 305 VALIGN="top"
 306 >Control Endpoints</TD
 307 ></TR
 308 ></TABLE
 309 ></DIV
 310 ></BODY
 311 ></HTML
 312 >