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