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