packages/io/usb/slave/v2_0/doc/usbs-devtab.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 >Devtab Entries</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="Starting up a USB Device"
  26 HREF="usbs-start.html"><LINK
  27 REL="NEXT"
  28 TITLE="Receiving Data from the Host"
  29 HREF="usbs-start-rx.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.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-start-rx.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-DEVTAB"
  80 >Devtab Entries</A
  81 ></H1
  82 ><DIV
  83 CLASS="REFNAMEDIV"
  84 ><A
  85 NAME="AEN200"
  86 ></A
  87 ><H2
  88 >Name</H2
  89 >Devtab Entries&nbsp;--&nbsp;Data endpoint data structure</DIV
  90 ><DIV
  91 CLASS="REFSYNOPSISDIV"
  92 ><A
  93 NAME="AEN203"
  94 ></A
  95 ><H2
  96 >Synopsis</H2
  97 ><TABLE
  98 BORDER="0"
  99 BGCOLOR="#E0E0E0"
 100 WIDTH="100%"
 101 ><TR
 102 ><TD
 103 ><PRE
 104 CLASS="SYNOPSIS"
 105 >/dev/usb0c
 106 /dev/usb1r
 107 /dev/usb2w</PRE
 108 ></TD
 109 ></TR
 110 ></TABLE
 111 ></DIV
 112 ><DIV
 113 CLASS="REFSECT1"
 114 ><A
 115 NAME="AEN205"
 116 ></A
 117 ><H2
 118 >Devtab Entries</H2
 119 ><P
 120 >USB device drivers provide two ways of transferring data between host
 121 and peripheral. The first involves USB-specific functionality such as
 122 <A
 123 HREF="usbs-start-rx.html"
 124 ><TT
 125 CLASS="FUNCTION"
 126 >usbs_start_rx_buffer</TT
 127 ></A
 128 >.
 129 This provides non-blocking I/O: a transfer is started, and some time
 130 later the device driver will call a supplied completion function. The
 131 second uses the conventional I/O model: there are entries in the
 132 device table corresponding to the various endpoints. Standard calls
 133 such as <TT
 134 CLASS="FUNCTION"
 135 >open</TT
 136 > can then be used to get a suitable
 137 handle. Actual I/O happens via blocking <TT
 138 CLASS="FUNCTION"
 139 >read</TT
 140 > and
 141 <TT
 142 CLASS="FUNCTION"
 143 >write</TT
 144 > calls. In practice the blocking operations
 145 are simply implemented using the underlying non-blocking
 146 functionality.</P
 147 ><P
 148 >Each endpoint will have its own devtab entry. The exact names are
 149 controlled by the device driver package, but typically the root will
 150 be <TT
 151 CLASS="LITERAL"
 152 >/dev/usb</TT
 153 >. This is followed by one or more
 154 decimal digits giving the endpoint number, followed by
 155 <TT
 156 CLASS="LITERAL"
 157 >c</TT
 158 > for a control endpoint, <TT
 159 CLASS="LITERAL"
 160 >r</TT
 161 > for
 162 a receive endpoint (host to peripheral), and <TT
 163 CLASS="LITERAL"
 164 >w</TT
 165 > for
 166 a transmit endpoint (peripheral to host). If the target hardware
 167 involves more than one USB device then different roots should be used,
 168 for example <TT
 169 CLASS="LITERAL"
 170 >/dev/usb0c</TT
 171 > and
 172 <TT
 173 CLASS="LITERAL"
 174 >/dev/usb1_0c</TT
 175 >. This may require explicit
 176 manipulation of device driver configuration options by the application
 177 developer.</P
 178 ><P
 179 >At present the devtab entry for a control endpoint does not support
 180 any I/O operations. </P
 181 ><DIV
 182 CLASS="REFSECT2"
 183 ><A
 184 NAME="AEN221"
 185 ></A
 186 ><H3
 187 ><TT
 188 CLASS="FUNCTION"
 189 >write</TT
 190 > operations</H3
 191 ><P
 192 ><TT
 193 CLASS="FUNCTION"
 194 >cyg_io_write</TT
 195 > and similar functions in
 196 higher-level packages can be used to perform a transfer from
 197 peripheral to host. Successive write operations will not be coalesced.
 198 For example, when doing a 1000 byte write to an endpoint that uses the
 199 bulk transfer protocol this will involve 15 full-size 64-byte packets
 200 and a terminating 40-byte packet. USB device drivers are not expected
 201 to do any locking, and if higher-level code performs multiple
 202 concurrent write operations on a single endpoint then the resulting
 203 behaviour is undefined.</P
 204 ><P
 205 >A USB <TT
 206 CLASS="FUNCTION"
 207 >write</TT
 208 > operation will never transfer less
 209 data than specified. It is the responsibility of higher-level code to
 210 ensure that the amount of data being transferred is acceptable to the
 211 host-side code. Usually this will be defined by a higher-level
 212 protocol. If an attempt is made to transfer more data than the host
 213 expects then the resulting behaviour is undefined.</P
 214 ><P
 215 >There are two likely error conditions. <TT
 216 CLASS="LITERAL"
 217 >EPIPE</TT
 218 >
 219 indicates that the connection between host and target has been broken.
 220 <TT
 221 CLASS="LITERAL"
 222 >EAGAIN</TT
 223 > indicates that the endpoint has been
 224 stalled, either at the request of the host or by other activity
 225 inside the peripheral.</P
 226 ></DIV
 227 ><DIV
 228 CLASS="REFSECT2"
 229 ><A
 230 NAME="AEN231"
 231 ></A
 232 ><H3
 233 ><TT
 234 CLASS="FUNCTION"
 235 >read</TT
 236 > operations</H3
 237 ><P
 238 ><TT
 239 CLASS="FUNCTION"
 240 >cyg_io_read</TT
 241 > and similar functions in higher-level
 242 packages can be used to perform a transfer from host to peripheral.
 243 This should be a complete transfer: higher-level protocols should
 244 define an upper bound on the amount of data being transferred, and the
 245 <TT
 246 CLASS="FUNCTION"
 247 >read</TT
 248 > operation should involve at least this
 249 amount of data. The return value will indicate the actual transfer
 250 size, which may be less than requested.</P
 251 ><P
 252 >Some device drivers may support partial reads, but USB device drivers
 253 are not expected to perform any buffering because that involves both
 254 memory and code overheads. One technique that may work for bulk
 255 transfers is to exploit the fact that such transfers happen in 64-byte
 256 packets. It is possible to <TT
 257 CLASS="FUNCTION"
 258 >read</TT
 259 > an initial 64
 260 bytes, corresponding to the first packet in the transfer. These 64
 261 bytes can then be examined to determine the total transfer size, and
 262 the remaining data can be transferred in another
 263 <TT
 264 CLASS="FUNCTION"
 265 >read</TT
 266 > operation. This technique is not guaranteed
 267 to work with all USB hardware. Also, if the delay between accepting
 268 the first packet and the remainder of the transfer is excessive then
 269 this could cause timeout problems for the host-side software. For
 270 these reasons the use of partial reads should be avoided.</P
 271 ><P
 272 >There are two likely error conditions. <TT
 273 CLASS="LITERAL"
 274 >EPIPE</TT
 275 >
 276 indicates that the connection between host and target has been broken.
 277 <TT
 278 CLASS="LITERAL"
 279 >EAGAIN</TT
 280 > indicates that the endpoint has been
 281 stalled, either at the request of the host or by other activity
 282 inside the peripheral.</P
 283 ><P
 284 >USB device drivers are not expected to do any locking. If higher-level
 285 code performs multiple concurrent read operations on a single endpoint
 286 then the resulting behaviour is undefined.</P
 287 ></DIV
 288 ><DIV
 289 CLASS="REFSECT2"
 290 ><A
 291 NAME="AEN244"
 292 ></A
 293 ><H3
 294 ><TT
 295 CLASS="FUNCTION"
 296 >select</TT
 297 > operations</H3
 298 ><P
 299 >Typical USB device drivers will not provide any support for
 300 <TT
 301 CLASS="FUNCTION"
 302 >select</TT
 303 >. Consider bulk transfers from the host to
 304 the peripheral. At the USB device driver level there is no way of
 305 knowing in advance how large a transfer will be, so it is not feasible
 306 for the device driver to buffer the entire transfer. It may be
 307 possible to buffer part of the transfer, for example the first 64-byte
 308 packet, and copy this into application space at the start of a
 309 <TT
 310 CLASS="FUNCTION"
 311 >read</TT
 312 >, but this adds code and memory overheads.
 313 Worse, it means that there is an unknown but potentially long delay
 314 between a peripheral accepting the first packet of a transfer and the
 315 remaining packets, which could confuse or upset the host-side
 316 software.</P
 317 ><P
 318 >With some USB hardware it may be possible for the device driver to
 319 detect OUT tokens from the host without actually accepting the data,
 320 and this would indicate that a  <TT
 321 CLASS="FUNCTION"
 322 >read</TT
 323 > is likely to
 324 succeed. However, it would not be reliable since the host-side I/O
 325 operation could time out. A similar mechanism could be used to
 326 implement <TT
 327 CLASS="FUNCTION"
 328 >select</TT
 329 > for outgoing data, but again
 330 this would not be reliable.</P
 331 ><P
 332 >Some device drivers may provide partial support for
 333 <TT
 334 CLASS="FUNCTION"
 335 >select</TT
 336 > anyway, possibly under the control of a
 337 configuration option. The device driver's documentation should be
 338 consulted for further information. It is also worth noting that the
 339 USB-specific non-blocking API can often be used as an alternative to
 340 <TT
 341 CLASS="FUNCTION"
 342 >select</TT
 343 >.</P
 344 ></DIV
 345 ><DIV
 346 CLASS="REFSECT2"
 347 ><A
 348 NAME="AEN256"
 349 ></A
 350 ><H3
 351 ><TT
 352 CLASS="FUNCTION"
 353 >get_config</TT
 354 > and
 355 <TT
 356 CLASS="FUNCTION"
 357 >set_config</TT
 358 > operations</H3
 359 ><P
 360 >There are no <TT
 361 CLASS="FUNCTION"
 362 >set_config</TT
 363 > or
 364 <TT
 365 CLASS="FUNCTION"
 366 >get_config</TT
 367 > (also known as
 368 <TT
 369 CLASS="FUNCTION"
 370 >ioctl</TT
 371 >) operations defined for USB devices.
 372 Some device drivers may provide hardware-specific facilities this way. </P
 373 ><DIV
 374 CLASS="NOTE"
 375 ><BLOCKQUOTE
 376 CLASS="NOTE"
 377 ><P
 378 ><B
 379 >Note: </B
 380 >Currently the USB-specific functions related to <A
 381 HREF="usbs-halt.html"
 382 >halted endpoints</A
 383 > cannot be accessed readily
 384 via devtab entries. This functionality should probably be made
 385 available via <TT
 386 CLASS="FUNCTION"
 387 >set_config</TT
 388 > and
 389 <TT
 390 CLASS="FUNCTION"
 391 >get_config</TT
 392 >. It may also prove useful to provide
 393 a <TT
 394 CLASS="FUNCTION"
 395 >get_config</TT
 396 > operation that maps from the
 397 devtab entries to the underlying endpoint data structures.</P
 398 ></BLOCKQUOTE
 399 ></DIV
 400 ></DIV
 401 ><DIV
 402 CLASS="REFSECT2"
 403 ><A
 404 NAME="AEN270"
 405 ></A
 406 ><H3
 407 >Presence</H3
 408 ><P
 409 >The devtab entries are optional. If the USB device is accessed
 410 primarily by class-specific code such as the USB-ethernet package and
 411 that package uses the USB-specific API directly, the devtab entries
 412 are redundant. Even if application code does need to access the USB
 413 device, the non-blocking API may be more convenient than the blocking
 414 I/O provided via the devtab entries. In these cases the devtab entries
 415 serve no useful purpose, but they still impose a memory overhead. It
 416 is possible to suppress the presence of these entries by disabling the
 417 configuration option
 418 <TT
 419 CLASS="LITERAL"
 420 >CYGGLO_IO_USB_SLAVE_PROVIDE_DEVTAB_ENTRIES</TT
 421 >.</P
 422 ></DIV
 423 ></DIV
 424 ><DIV
 425 CLASS="NAVFOOTER"
 426 ><HR
 427 ALIGN="LEFT"
 428 WIDTH="100%"><TABLE
 429 WIDTH="100%"
 430 BORDER="0"
 431 CELLPADDING="0"
 432 CELLSPACING="0"
 433 ><TR
 434 ><TD
 435 WIDTH="33%"
 436 ALIGN="left"
 437 VALIGN="top"
 438 ><A
 439 HREF="usbs-start.html"
 440 >Prev</A
 441 ></TD
 442 ><TD
 443 WIDTH="34%"
 444 ALIGN="center"
 445 VALIGN="top"
 446 ><A
 447 HREF="io-usb-slave.html"
 448 >Home</A
 449 ></TD
 450 ><TD
 451 WIDTH="33%"
 452 ALIGN="right"
 453 VALIGN="top"
 454 ><A
 455 HREF="usbs-start-rx.html"
 456 >Next</A
 457 ></TD
 458 ></TR
 459 ><TR
 460 ><TD
 461 WIDTH="33%"
 462 ALIGN="left"
 463 VALIGN="top"
 464 >Starting up a USB Device</TD
 465 ><TD
 466 WIDTH="34%"
 467 ALIGN="center"
 468 VALIGN="top"
 469 >&nbsp;</TD
 470 ><TD
 471 WIDTH="33%"
 472 ALIGN="right"
 473 VALIGN="top"
 474 >Receiving Data from the Host</TD
 475 ></TR
 476 ></TABLE
 477 ></DIV
 478 ></BODY
 479 ></HTML
 480 >