doc/html/ref/usbseth-init.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 >Initializing the USB-ethernet Package</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 Support for Developing USB-ethernet Peripherals"
  23 HREF="io-usb-slave-eth.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Introduction"
  26 HREF="usbseth-intro.html"><LINK
  27 REL="NEXT"
  28 TITLE="USB-ethernet Data Transfers"
  29 HREF="usbseth-data.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="usbseth-intro.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="usbseth-data.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="USBSETH-INIT">Initializing the USB-ethernet Package</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN17398"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 ><TT
  91 CLASS="FUNCTION"
  92 >usbs_eth_init</TT
  93 >&nbsp;--&nbsp;Initializing the USB-ethernet Package</DIV
  94 ><DIV
  95 CLASS="REFSYNOPSISDIV"
  96 ><A
  97 NAME="AEN17402"><H2
  98 >Synopsis</H2
  99 ><DIV
 100 CLASS="FUNCSYNOPSIS"
 101 ><A
 102 NAME="AEN17403"><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_eth.h&gt;</PRE
 113 ></TD
 114 ></TR
 115 ></TABLE
 116 ><P
 117 ><CODE
 118 ><CODE
 119 CLASS="FUNCDEF"
 120 >void usbs_eth_init</CODE
 121 >(usbs_eth* usbeth, usbs_control_endpoint* ep0, usbs_rx_endpoint* ep1, usbs_tx_endpoint* ep2, unsigned char* mac_address);</CODE
 122 ></P
 123 ><P
 124 ></P
 125 ></DIV
 126 ></DIV
 127 ><DIV
 128 CLASS="REFSECT1"
 129 ><A
 130 NAME="AEN17418"
 131 ></A
 132 ><H2
 133 >Description</H2
 134 ><P
 135 >The USB-ethernet package is not tied to any specific hardware. It
 136 requires certain functionality: there must be USB-slave hardware
 137 supported by a device driver; there must also be two endpoints for
 138 bulk transfers between host and peripheral, one for each direction;
 139 there must also be a control endpoint, although of course that is
 140 implicit with any USB hardware.</P
 141 ><P
 142 >However, USB-slave hardware may well provide more endpoints than the
 143 minimum required for ethernet support. Some of those endpoints might
 144 be used by other packages, while other endpoints might be used
 145 directly by the application, or might not be needed for the peripheral
 146 being built. There is also the possibility of a USB peripheral that
 147 supports multiple configurations, with the ethernet support active in
 148 only some of those configurations. The USB-ethernet package has no
 149 knowledge about any of this, so it relies on higher-level code to tell
 150 it which endpoints should be used and other information. This is the
 151 purpose of the <TT
 152 CLASS="FUNCTION"
 153 >usbs_eth_init</TT
 154 > function.</P
 155 ><P
 156 >The first argument identifies the specific
 157 <SPAN
 158 CLASS="STRUCTNAME"
 159 >usbs_eth</SPAN
 160 > data structure that is affected. It
 161 is expected that the vast majority of affected applications will only
 162 provide a single USB-ethernet device to a single host, and the package
 163 automatically provides a suitable data structure
 164 <TT
 165 CLASS="LITERAL"
 166 >usbs_eth0</TT
 167 > to support this. If multiple
 168 <SPAN
 169 CLASS="STRUCTNAME"
 170 >usbs_eth</SPAN
 171 > structures are needed for some
 172 reason then these need to be instantiated by other code, and each one
 173 needs to be initialised by a call to
 174 <TT
 175 CLASS="FUNCTION"
 176 >usbs_eth_init()</TT
 177 >. </P
 178 ><P
 179 >The next three arguments identify the endpoints that should be used
 180 for USB communications: a control endpoint, a receive endpoint for
 181 ethernet packets coming from the host to the peripheral, and a
 182 transmit endpoint for ethernet packets going in the other direction.
 183 Obviously all three endpoints should be provided by the same USB
 184 hardware. The USB-ethernet package assumes that it has sole access to
 185 the receive and transmit endpoints, subject to the use of
 186 <TT
 187 CLASS="FUNCTION"
 188 >usbs_eth_disable</TT
 189 > and
 190 <TT
 191 CLASS="FUNCTION"
 192 >usbs_eth_enable</TT
 193 > control functions. The package
 194 also assumes that no other code is interested in USB state changes or
 195 class control messages: it installs handlers
 196 <A
 197 HREF="usbseth-control.html"
 198 ><TT
 199 CLASS="FUNCTION"
 200 >usbs_eth_state_change_handler</TT
 201 ></A
 202 >
 203 and
 204 <A
 205 HREF="usbseth-control.html"
 206 ><TT
 207 CLASS="FUNCTION"
 208 >usbs_eth_class_control_handler</TT
 209 ></A
 210 >
 211 in the control endpoint. If any other code does need to handle USB
 212 state changes or class control messages then replacement handlers
 213 should be installed after the call to
 214 <TT
 215 CLASS="FUNCTION"
 216 >usbs_eth_init</TT
 217 >, and those replacements should
 218 invoke the USB-ethernet ones when appropriate.</P
 219 ><P
 220 >The final argument to <TT
 221 CLASS="FUNCTION"
 222 >usbs_eth_init</TT
 223 > specifies
 224 the MAC address (or Ethernet Station Address) that should be provided
 225 to the host-side device driver. Since the USB-ethernet package does not
 226 interact directly with a real ethernet device it cannot obtain the MAC
 227 address from any hardware. Instead, it must be supplied by higher-level
 228 code. The details depend on the <A
 229 HREF="usbseth-intro.html#AEN17377"
 230 >scenario</A
 231 > in which the
 232 USB-ethernet package is being used.</P
 233 ><P
 234 >The call to <TT
 235 CLASS="FUNCTION"
 236 >usbs_eth_init</TT
 237 > should normally happen
 238 after the enumeration data has been provided but before the underlying
 239 USB device driver has been started. If the USB device were to be
 240 started first then a connection between host and peripheral could be
 241 established immediately, and the host-side device driver would attempt
 242 to contact the USB-ethernet package for information such as the MAC
 243 address. </P
 244 ><TABLE
 245 BORDER="5"
 246 BGCOLOR="#E0E0F0"
 247 WIDTH="70%"
 248 ><TR
 249 ><TD
 250 ><PRE
 251 CLASS="PROGRAMLISTING"
 252 >int
 253 main(int argc, char** argv)
 254 {
 255     unsigned char host_MAC[6] = { 0x40, 0x5d, 0x90, 0xa9, 0xbc, 0x02 };
 256
 257     usbs_sa11x0_ep0.enumeration_data    = &amp;usb_enum_data;
 258     &#8230;
 259     usbs_eth_init(&amp;usbs_eth0, &amp;usbs_sa11x0_ep0, &amp;usbs_sa11x0_ep1, &amp;usbs_sa11x0_ep2, host_MAC);
 260     &#8230;
 261     usbs_start(&amp;usbs_sa11x0_ep0);
 262     &#8230;
 263 }</PRE
 264 ></TD
 265 ></TR
 266 ></TABLE
 267 ></DIV
 268 ><DIV
 269 CLASS="NAVFOOTER"
 270 ><HR
 271 ALIGN="LEFT"
 272 WIDTH="100%"><TABLE
 273 SUMMARY="Footer navigation table"
 274 WIDTH="100%"
 275 BORDER="0"
 276 CELLPADDING="0"
 277 CELLSPACING="0"
 278 ><TR
 279 ><TD
 280 WIDTH="33%"
 281 ALIGN="left"
 282 VALIGN="top"
 283 ><A
 284 HREF="usbseth-intro.html"
 285 ACCESSKEY="P"
 286 >Prev</A
 287 ></TD
 288 ><TD
 289 WIDTH="34%"
 290 ALIGN="center"
 291 VALIGN="top"
 292 ><A
 293 HREF="ecos-ref.html"
 294 ACCESSKEY="H"
 295 >Home</A
 296 ></TD
 297 ><TD
 298 WIDTH="33%"
 299 ALIGN="right"
 300 VALIGN="top"
 301 ><A
 302 HREF="usbseth-data.html"
 303 ACCESSKEY="N"
 304 >Next</A
 305 ></TD
 306 ></TR
 307 ><TR
 308 ><TD
 309 WIDTH="33%"
 310 ALIGN="left"
 311 VALIGN="top"
 312 >Introduction</TD
 313 ><TD
 314 WIDTH="34%"
 315 ALIGN="center"
 316 VALIGN="top"
 317 ><A
 318 HREF="io-usb-slave-eth.html"
 319 ACCESSKEY="U"
 320 >Up</A
 321 ></TD
 322 ><TD
 323 WIDTH="33%"
 324 ALIGN="right"
 325 VALIGN="top"
 326 >USB-ethernet Data Transfers</TD
 327 ></TR
 328 ></TABLE
 329 ></DIV
 330 ></BODY
 331 ></HTML
 332 >