doc/html/ref/usbs-halt.html

   1 <!-- Copyright (C) 2003 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 the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Halted Endpoints</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  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 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="usbs-start-tx.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="usbs-control.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><H1
  81 ><A
  82 NAME="USBS-HALT">Halted Endpoints</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN16457"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >Halted Endpoints&nbsp;--&nbsp;Support for Halting and Halted Endpoints</DIV
  91 ><DIV
  92 CLASS="REFSYNOPSISDIV"
  93 ><A
  94 NAME="AEN16460"><H2
  95 >Synopsis</H2
  96 ><DIV
  97 CLASS="FUNCSYNOPSIS"
  98 ><A
  99 NAME="AEN16461"><P
 100 ></P
 101 ><TABLE
 102 BORDER="5"
 103 BGCOLOR="#E0E0F0"
 104 WIDTH="70%"
 105 ><TR
 106 ><TD
 107 ><PRE
 108 CLASS="FUNCSYNOPSISINFO"
 109 >#include &lt;cyg/io/usb/usbs.h&gt;</PRE
 110 ></TD
 111 ></TR
 112 ></TABLE
 113 ><P
 114 ><CODE
 115 ><CODE
 116 CLASS="FUNCDEF"
 117 >cyg_bool usbs_rx_endpoint_halted</CODE
 118 >(usbs_rx_endpoint* ep);</CODE
 119 ></P
 120 ><P
 121 ><CODE
 122 ><CODE
 123 CLASS="FUNCDEF"
 124 >void usbs_set_rx_endpoint_halted</CODE
 125 >(usbs_rx_endpoint* ep, cyg_bool new_state);</CODE
 126 ></P
 127 ><P
 128 ><CODE
 129 ><CODE
 130 CLASS="FUNCDEF"
 131 >void usbs_start_rx_endpoint_wait</CODE
 132 >(usbs_rx_endpoint* ep, void (*)(void*, int) complete_fn, void * complete_data);</CODE
 133 ></P
 134 ><P
 135 ><CODE
 136 ><CODE
 137 CLASS="FUNCDEF"
 138 >cyg_bool
 139 usbs_tx_endpoint_halted</CODE
 140 >(usbs_tx_endpoint* ep);</CODE
 141 ></P
 142 ><P
 143 ><CODE
 144 ><CODE
 145 CLASS="FUNCDEF"
 146 >void usbs_set_tx_endpoint_halted</CODE
 147 >(usbs_tx_endpoint* ep, cyg_bool new_state);</CODE
 148 ></P
 149 ><P
 150 ><CODE
 151 ><CODE
 152 CLASS="FUNCDEF"
 153 >void usbs_start_tx_endpoint_wait</CODE
 154 >(usbs_tx_endpoint* ep, void (*)(void*, int) complete_fn, void * complete_data);</CODE
 155 ></P
 156 ><P
 157 ></P
 158 ></DIV
 159 ></DIV
 160 ><DIV
 161 CLASS="REFSECT1"
 162 ><A
 163 NAME="AEN16505"
 164 ></A
 165 ><H2
 166 ><TT
 167 CLASS="FUNCTION"
 168 >Description</TT
 169 ></H2
 170 ><P
 171 >Normal USB traffic involves straightforward handshakes, with either an
 172 <TT
 173 CLASS="LITERAL"
 174 >ACK</TT
 175 > to indicate that a packet was transferred
 176 without errors, or a <TT
 177 CLASS="LITERAL"
 178 >NAK</TT
 179 > if an error occurred, or
 180 if a peripheral is currently unable to process another packet from the
 181 host, or has no packet to send to the host. There is a third form of
 182 handshake, a <TT
 183 CLASS="LITERAL"
 184 >STALL</TT
 185 >, which indicates that the
 186 endpoint is currently <SPAN
 187 CLASS="emphasis"
 188 ><I
 189 CLASS="EMPHASIS"
 190 >halted</I
 191 ></SPAN
 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 SUMMARY="Footer navigation table"
 262 WIDTH="100%"
 263 BORDER="0"
 264 CELLPADDING="0"
 265 CELLSPACING="0"
 266 ><TR
 267 ><TD
 268 WIDTH="33%"
 269 ALIGN="left"
 270 VALIGN="top"
 271 ><A
 272 HREF="usbs-start-tx.html"
 273 ACCESSKEY="P"
 274 >Prev</A
 275 ></TD
 276 ><TD
 277 WIDTH="34%"
 278 ALIGN="center"
 279 VALIGN="top"
 280 ><A
 281 HREF="ecos-ref.html"
 282 ACCESSKEY="H"
 283 >Home</A
 284 ></TD
 285 ><TD
 286 WIDTH="33%"
 287 ALIGN="right"
 288 VALIGN="top"
 289 ><A
 290 HREF="usbs-control.html"
 291 ACCESSKEY="N"
 292 >Next</A
 293 ></TD
 294 ></TR
 295 ><TR
 296 ><TD
 297 WIDTH="33%"
 298 ALIGN="left"
 299 VALIGN="top"
 300 >Sending Data to the Host</TD
 301 ><TD
 302 WIDTH="34%"
 303 ALIGN="center"
 304 VALIGN="top"
 305 ><A
 306 HREF="io-usb-slave.html"
 307 ACCESSKEY="U"
 308 >Up</A
 309 ></TD
 310 ><TD
 311 WIDTH="33%"
 312 ALIGN="right"
 313 VALIGN="top"
 314 >Control Endpoints</TD
 315 ></TR
 316 ></TABLE
 317 ></DIV
 318 ></BODY
 319 ></HTML
 320 >