doc/html/ref/usbs-data.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 >Data 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="Control Endpoints"
  26 HREF="usbs-control.html"><LINK
  27 REL="NEXT"
  28 TITLE="Writing a USB Device Driver"
  29 HREF="usbs-writing.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-control.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-writing.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-DATA">Data Endpoints</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN16660"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >Data Endpoints&nbsp;--&nbsp;Data endpoint data structures</DIV
  91 ><DIV
  92 CLASS="REFSYNOPSISDIV"
  93 ><A
  94 NAME="AEN16663"><H2
  95 >Synopsis</H2
  96 ><TABLE
  97 BORDER="5"
  98 BGCOLOR="#E0E0F0"
  99 WIDTH="70%"
 100 ><TR
 101 ><TD
 102 ><PRE
 103 CLASS="SYNOPSIS"
 104 >#include &lt;cyg/io/usb/usbs.h&gt;
 105
 106 typedef struct usbs_rx_endpoint {
 107     void                 (*start_rx_fn)(struct usbs_rx_endpoint*);
 108     void                 (*set_halted_fn)(struct usbs_rx_endpoint*, cyg_bool);
 109     void                 (*complete_fn)(void*, int);
 110     void*                complete_data;
 111     unsigned char*       buffer;
 112     int                  buffer_size;
 113     cyg_bool             halted;
 114 } usbs_rx_endpoint;
 115
 116 typedef struct usbs_tx_endpoint {
 117     void                 (*start_tx_fn)(struct usbs_tx_endpoint*);
 118     void                 (*set_halted_fn)(struct usbs_tx_endpoint*, cyg_bool);
 119     void                 (*complete_fn)(void*, int);
 120     void*                complete_data;
 121     const unsigned char* buffer;
 122     int                  buffer_size;
 123     cyg_bool             halted;
 124 } usbs_tx_endpoint;</PRE
 125 ></TD
 126 ></TR
 127 ></TABLE
 128 ></DIV
 129 ><DIV
 130 CLASS="REFSECT1"
 131 ><A
 132 NAME="AEN16665"
 133 ></A
 134 ><H2
 135 >Receive and Transmit Data Structures</H2
 136 ><P
 137 >In addition to a single <SPAN
 138 CLASS="STRUCTNAME"
 139 >usbs_control_endpoint</SPAN
 140 >
 141 data structure per USB slave device, the USB device driver should also
 142 provide receive and transmit data structures corresponding to the
 143 other endpoints. The names of these are determined by the device
 144 driver. For example, the SA1110 USB device driver package provides
 145 <TT
 146 CLASS="LITERAL"
 147 >usbs_sa11x0_ep1</TT
 148 > for receives and
 149 <TT
 150 CLASS="LITERAL"
 151 >usbs_sa11x0_ep2</TT
 152 > for transmits.</P
 153 ><P
 154 >Unlike control endpoints, the common USB slave package does provide a
 155 number of utility routines to manipulate data endpoints. For example
 156 <A
 157 HREF="usbs-start-rx.html"
 158 ><TT
 159 CLASS="FUNCTION"
 160 >usbs_start_rx_buffer</TT
 161 ></A
 162 >
 163 can be used to receive data from the host into a buffer. In addition
 164 the USB device driver can provide devtab entries such as
 165 <TT
 166 CLASS="LITERAL"
 167 >/dev/usbs1r</TT
 168 > and <TT
 169 CLASS="LITERAL"
 170 >/dev/usbs2w</TT
 171 >, so
 172 higher-level code can <TT
 173 CLASS="FUNCTION"
 174 >open</TT
 175 > these devices and then
 176 perform blocking <TT
 177 CLASS="FUNCTION"
 178 >read</TT
 179 > and
 180 <TT
 181 CLASS="FUNCTION"
 182 >write</TT
 183 > operations.</P
 184 ><P
 185 >However, the operation of data endpoints and the various
 186 endpoint-related functions is relatively straightforward. First
 187 consider a <SPAN
 188 CLASS="STRUCTNAME"
 189 >usbs_rx_endpoint</SPAN
 190 > structure. The
 191 device driver will provide the members
 192 <TT
 193 CLASS="STRUCTFIELD"
 194 ><I
 195 >start_rx_fn</I
 196 ></TT
 197 > and
 198 <TT
 199 CLASS="STRUCTFIELD"
 200 ><I
 201 >set_halted_fn</I
 202 ></TT
 203 >, and it will maintain the
 204 <TT
 205 CLASS="STRUCTFIELD"
 206 ><I
 207 >halted</I
 208 ></TT
 209 > field. To receive data, higher-level
 210 code sets the <TT
 211 CLASS="STRUCTFIELD"
 212 ><I
 213 >buffer</I
 214 ></TT
 215 >,
 216 <TT
 217 CLASS="STRUCTFIELD"
 218 ><I
 219 >buffer_size</I
 220 ></TT
 221 >,
 222 <TT
 223 CLASS="STRUCTFIELD"
 224 ><I
 225 >complete_fn</I
 226 ></TT
 227 > and optionally the
 228 <TT
 229 CLASS="STRUCTFIELD"
 230 ><I
 231 >complete_data</I
 232 ></TT
 233 > fields. Next the
 234 <TT
 235 CLASS="STRUCTFIELD"
 236 ><I
 237 >start_rx_fn</I
 238 ></TT
 239 > member should be called. When
 240 the transfer has finished the device driver will invoke the completion
 241 function, using <TT
 242 CLASS="STRUCTFIELD"
 243 ><I
 244 >complete_data</I
 245 ></TT
 246 > as the first
 247 argument and a size field for the second argument. A negative size
 248 indicates an error of some sort: <TT
 249 CLASS="LITERAL"
 250 >-EGAIN</TT
 251 > indicates
 252 that the endpoint has been halted, usually at the request of the host;
 253 <TT
 254 CLASS="LITERAL"
 255 >-EPIPE</TT
 256 > indicates that the connection between the
 257 host and the peripheral has been broken. Certain device drivers may
 258 generate other error codes.</P
 259 ><P
 260 >If higher-level code needs to halt or unhalt an endpoint then it can
 261 invoke the <TT
 262 CLASS="STRUCTFIELD"
 263 ><I
 264 >set_halted_fn</I
 265 ></TT
 266 > member. When an
 267 endpoint is halted, invoking <TT
 268 CLASS="STRUCTFIELD"
 269 ><I
 270 >start_rx_fn</I
 271 ></TT
 272 >
 273 wit <TT
 274 CLASS="STRUCTFIELD"
 275 ><I
 276 >buffer_size</I
 277 ></TT
 278 > set to 0 indicates that
 279 higher-level code wants to block until the endpoint is no longer
 280 halted; at that point the completion function will be invoked.</P
 281 ><P
 282 >USB device drivers are allowed to assume that higher-level protocols
 283 ensure that host and peripheral agree on the amount of data that will
 284 be transferred, or at least on an upper bound. Therefore there is no
 285 need for the device driver to maintain its own buffers, and copy
 286 operations are avoided. If the host sends more data than expected then
 287 the resulting behaviour is undefined.</P
 288 ><P
 289 >Transmit endpoints work in essentially the same way as receive
 290 endpoints. Higher-level code should set the
 291 <TT
 292 CLASS="STRUCTFIELD"
 293 ><I
 294 >buffer</I
 295 ></TT
 296 > and
 297 <TT
 298 CLASS="STRUCTFIELD"
 299 ><I
 300 >buffer_size</I
 301 ></TT
 302 > fields to point at the data to
 303 be transferred, then call <TT
 304 CLASS="STRUCTFIELD"
 305 ><I
 306 >start_tx_fn</I
 307 ></TT
 308 >, and
 309 the device driver will invoked the completion function when the
 310 transfer has completed.</P
 311 ><P
 312 >USB device drivers are not expected to perform any locking. If at any
 313 time there are two concurrent receive operations for a given endpoint,
 314 or two concurrent transmit operations, then the resulting behaviour is
 315 undefined. It is the responsibility of higher-level code to perform
 316 any synchronisation that may be necessary. In practice, conflicts are
 317 unlikely because typically a given endpoint will only be accessed
 318 sequentially by just one part of the overall system.</P
 319 ></DIV
 320 ><DIV
 321 CLASS="NAVFOOTER"
 322 ><HR
 323 ALIGN="LEFT"
 324 WIDTH="100%"><TABLE
 325 SUMMARY="Footer navigation table"
 326 WIDTH="100%"
 327 BORDER="0"
 328 CELLPADDING="0"
 329 CELLSPACING="0"
 330 ><TR
 331 ><TD
 332 WIDTH="33%"
 333 ALIGN="left"
 334 VALIGN="top"
 335 ><A
 336 HREF="usbs-control.html"
 337 ACCESSKEY="P"
 338 >Prev</A
 339 ></TD
 340 ><TD
 341 WIDTH="34%"
 342 ALIGN="center"
 343 VALIGN="top"
 344 ><A
 345 HREF="ecos-ref.html"
 346 ACCESSKEY="H"
 347 >Home</A
 348 ></TD
 349 ><TD
 350 WIDTH="33%"
 351 ALIGN="right"
 352 VALIGN="top"
 353 ><A
 354 HREF="usbs-writing.html"
 355 ACCESSKEY="N"
 356 >Next</A
 357 ></TD
 358 ></TR
 359 ><TR
 360 ><TD
 361 WIDTH="33%"
 362 ALIGN="left"
 363 VALIGN="top"
 364 >Control Endpoints</TD
 365 ><TD
 366 WIDTH="34%"
 367 ALIGN="center"
 368 VALIGN="top"
 369 ><A
 370 HREF="io-usb-slave.html"
 371 ACCESSKEY="U"
 372 >Up</A
 373 ></TD
 374 ><TD
 375 WIDTH="33%"
 376 ALIGN="right"
 377 VALIGN="top"
 378 >Writing a USB Device Driver</TD
 379 ></TR
 380 ></TABLE
 381 ></DIV
 382 ></BODY
 383 ></HTML
 384 >