packages/io/usb/slave/v2_0/doc/usbs-start.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 >Starting up a USB Device</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="USB Enumeration Data"
  26 HREF="usbs-enum.html"><LINK
  27 REL="NEXT"
  28 TITLE="Devtab Entries"
  29 HREF="usbs-devtab.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-enum.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-devtab.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-START"
  80 >Starting up a USB Device</A
  81 ></H1
  82 ><DIV
  83 CLASS="REFNAMEDIV"
  84 ><A
  85 NAME="AEN173"
  86 ></A
  87 ><H2
  88 >Name</H2
  89 ><TT
  90 CLASS="FUNCTION"
  91 >usbs_start</TT
  92 >&nbsp;--&nbsp;Starting up a USB Device</DIV
  93 ><DIV
  94 CLASS="REFSYNOPSISDIV"
  95 ><A
  96 NAME="AEN177"
  97 ></A
  98 ><H2
  99 >Synopsis</H2
 100 ><DIV
 101 CLASS="FUNCSYNOPSIS"
 102 ><A
 103 NAME="AEN178"
 104 ></A
 105 ><P
 106 ></P
 107 ><TABLE
 108 BORDER="0"
 109 BGCOLOR="#E0E0E0"
 110 WIDTH="100%"
 111 ><TR
 112 ><TD
 113 ><PRE
 114 CLASS="FUNCSYNOPSISINFO"
 115 >#include &lt;cyg/io/usb/usbs.h&gt;</PRE
 116 ></TD
 117 ></TR
 118 ></TABLE
 119 ><P
 120 ><CODE
 121 ><CODE
 122 CLASS="FUNCDEF"
 123 >void usbs_start</CODE
 124 >(usbs_control_endpoint* ep0);</CODE
 125 ></P
 126 ><P
 127 ></P
 128 ></DIV
 129 ></DIV
 130 ><DIV
 131 CLASS="REFSECT1"
 132 ><A
 133 NAME="AEN185"
 134 ></A
 135 ><H2
 136 >Description</H2
 137 ><P
 138 >Initializing a USB device requires some support from higher-level
 139 code, typically the application, in the form of enumeration data.
 140 Hence it is not possible for the low-level USB driver to activate a
 141 USB device itself. Instead the higher-level code has to take care of
 142 this by invoking <TT
 143 CLASS="FUNCTION"
 144 >usbs_start</TT
 145 >. This function takes
 146 a pointer to a USB control endpoint data structure. USB device drivers
 147 should provide exactly one such data structure for every USB device,
 148 so the pointer uniquely identifies the device.</P
 149 ><TABLE
 150 BORDER="0"
 151 BGCOLOR="#E0E0E0"
 152 WIDTH="100%"
 153 ><TR
 154 ><TD
 155 ><PRE
 156 CLASS="PROGRAMLISTING"
 157 >const usbs_enumeration_data usb_enum_data = {
 158     &#8230;
 159 };
 160
 161 int
 162 main(int argc, char** argv)
 163 {
 164     usbs_sa11x0_ep0.enumeration_data = &amp;usb_enum_data;
 165     &#8230;
 166     usbs_start(&amp;usbs_sa11x0_ep0);
 167     &#8230;
 168 }</PRE
 169 ></TD
 170 ></TR
 171 ></TABLE
 172 ><P
 173 >The exact behaviour of <TT
 174 CLASS="FUNCTION"
 175 >usbs_start</TT
 176 > depends on the
 177 USB hardware and the device driver. A typical implementation would
 178 change the USB data pins from tristated to active. If the peripheral
 179 is already plugged into a host then the latter should detect this
 180 change and start interacting with the peripheral, including requesting
 181 the enumeration data. Some of this may happen before
 182 <TT
 183 CLASS="FUNCTION"
 184 >usbs_start</TT
 185 > returns, but given that multiple
 186 interactions between USB host and peripheral are required it is likely
 187 that the function will return before the peripheral is fully
 188 configured. Control endpoints provide a <A
 189 HREF="usbs-control.html#AEN515"
 190 >mechanism</A
 191 > for informing
 192 higher-level code of USB state changes.
 193 <TT
 194 CLASS="FUNCTION"
 195 >usbs_start</TT
 196 > will return even if the peripheral is
 197 not currently connected to a host: it will not block until the
 198 connection is established.</P
 199 ><P
 200 ><TT
 201 CLASS="FUNCTION"
 202 >usbs_start</TT
 203 > should only be called once for a given
 204 USB device. There are no defined error conditions. Note that the
 205 function affects the entire USB device and not just the control
 206 endpoint: there is no need to start any data endpoints as well.</P
 207 ></DIV
 208 ><DIV
 209 CLASS="NAVFOOTER"
 210 ><HR
 211 ALIGN="LEFT"
 212 WIDTH="100%"><TABLE
 213 WIDTH="100%"
 214 BORDER="0"
 215 CELLPADDING="0"
 216 CELLSPACING="0"
 217 ><TR
 218 ><TD
 219 WIDTH="33%"
 220 ALIGN="left"
 221 VALIGN="top"
 222 ><A
 223 HREF="usbs-enum.html"
 224 >Prev</A
 225 ></TD
 226 ><TD
 227 WIDTH="34%"
 228 ALIGN="center"
 229 VALIGN="top"
 230 ><A
 231 HREF="io-usb-slave.html"
 232 >Home</A
 233 ></TD
 234 ><TD
 235 WIDTH="33%"
 236 ALIGN="right"
 237 VALIGN="top"
 238 ><A
 239 HREF="usbs-devtab.html"
 240 >Next</A
 241 ></TD
 242 ></TR
 243 ><TR
 244 ><TD
 245 WIDTH="33%"
 246 ALIGN="left"
 247 VALIGN="top"
 248 >USB Enumeration Data</TD
 249 ><TD
 250 WIDTH="34%"
 251 ALIGN="center"
 252 VALIGN="top"
 253 >&nbsp;</TD
 254 ><TD
 255 WIDTH="33%"
 256 ALIGN="right"
 257 VALIGN="top"
 258 >Devtab Entries</TD
 259 ></TR
 260 ></TABLE
 261 ></DIV
 262 ></BODY
 263 ></HTML
 264 >