packages/io/usb/eth/slave/v2_0/doc/usbseth-init.html

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