doc/html/ref/usbseth-control.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 >USB-ethernet State Handling</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="USB-ethernet Data Transfers"
  26 HREF="usbseth-data.html"><LINK
  27 REL="NEXT"
  28 TITLE="Network Device for the eCos TCP/IP Stack"
  29 HREF="usbseth-netdev.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-data.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-netdev.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-CONTROL">USB-ethernet State Handling</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN17514"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >USB-ethernet State Handling&nbsp;--&nbsp;Maintaining the USB-ethernet connection with the host</DIV
  91 ><DIV
  92 CLASS="REFSYNOPSISDIV"
  93 ><A
  94 NAME="AEN17517"><H2
  95 >Synopsis</H2
  96 ><DIV
  97 CLASS="FUNCSYNOPSIS"
  98 ><A
  99 NAME="AEN17518"><P
 100 ></P
 101 ><TABLE
 102 BORDER="5"
 103 BGCOLOR="#E0E0F0"
 104 WIDTH="70%"
 105 ><TR
 106 ><TD
 107 ><PRE
 108 CLASS="FUNCSYNOPSISINFO"
 109 >#include &lt;cyg/io/usb/usbs_eth.h&gt;</PRE
 110 ></TD
 111 ></TR
 112 ></TABLE
 113 ><P
 114 ><CODE
 115 ><CODE
 116 CLASS="FUNCDEF"
 117 >usbs_control_return usbs_eth_class_control_handler</CODE
 118 >(usbs_control_endpoint* ep0, void* callback_data);</CODE
 119 ></P
 120 ><P
 121 ><CODE
 122 ><CODE
 123 CLASS="FUNCDEF"
 124 >void usbs_eth_state_change_handler</CODE
 125 >(usbs_control_endpoint* ep0, void* callback_data, usbs_state_change change, int old_state);</CODE
 126 ></P
 127 ><P
 128 ><CODE
 129 ><CODE
 130 CLASS="FUNCDEF"
 131 >void usbs_eth_disable</CODE
 132 >(usbs_eth* usbseth&#62;);</CODE
 133 ></P
 134 ><P
 135 ><CODE
 136 ><CODE
 137 CLASS="FUNCDEF"
 138 >void usbs_eth_enable</CODE
 139 >(usbs_eth* usbseth&#62;);</CODE
 140 ></P
 141 ><P
 142 ></P
 143 ></DIV
 144 ></DIV
 145 ><DIV
 146 CLASS="REFSECT1"
 147 ><A
 148 NAME="AEN17548"
 149 ></A
 150 ><H2
 151 >Description</H2
 152 ><P
 153 >When the USB-ethernet package is initialized by a call to <A
 154 HREF="usbseth-init.html"
 155 ><TT
 156 CLASS="FUNCTION"
 157 >usbs_eth_init</TT
 158 ></A
 159 > it
 160 installs <TT
 161 CLASS="FUNCTION"
 162 >usbs_eth_state_change_handler</TT
 163 > to handle
 164 USB state changes. This allows the package to detect when the
 165 connection between the host and the peripheral is established or
 166 broken, resulting in internal calls to
 167 <TT
 168 CLASS="FUNCTION"
 169 >usbs_eth_enable</TT
 170 > and
 171 <TT
 172 CLASS="FUNCTION"
 173 >usbs_eth_disable</TT
 174 > respectively. This is
 175 appropriate if no other code needs to access the USB device. However,
 176 if there is other code, either other USB-related packages or the
 177 application itself, that needs to perform I/O over the USB bus, then
 178 typically the USB-ethernet package should not have exclusive access to
 179 state change events. Instead, the assumption is that higher-level
 180 code, typically provided by the application, will install an
 181 alternative state change handler in the control endpoint data
 182 structure after the call to <TT
 183 CLASS="FUNCTION"
 184 >usbs_eth_init</TT
 185 >. This
 186 alternative handler will either chain into
 187 <TT
 188 CLASS="FUNCTION"
 189 >usbs_eth_state_change_handler</TT
 190 > when appropriate,
 191 or else it will invoke <TT
 192 CLASS="FUNCTION"
 193 >usbs_eth_enable</TT
 194 > and
 195 <TT
 196 CLASS="FUNCTION"
 197 >usbs_eth_disable</TT
 198 > directly. For further details of
 199 state change handlers and control endpoints generally, see the
 200 documentation for the common USB-slave package.</P
 201 ><P
 202 >Similarly, <TT
 203 CLASS="FUNCTION"
 204 >usbs_eth_init</TT
 205 > will install
 206 <TT
 207 CLASS="FUNCTION"
 208 >usbs_eth_class_control_handler</TT
 209 > in the control
 210 endpoint data structure as the appropriate handler for class-specific
 211 USB control messages. This code will handle the ethernet-specific
 212 <A
 213 HREF="usbseth-protocol.html"
 214 >control messages </A
 215 >, for example
 216 requests by the host to enable or disable promiscuous mode or to
 217 obtain the MAC address. If the USB device is not shared with any other
 218 code then this is both necessary and sufficient. However, if other code
 219 is involved and if that code also needs to process certain control
 220 messages, higher-level code should install its own handler and chain
 221 to the USB-ethernet one when appropriate. It should be noted that the
 222 request code is encoded in just a single byte, so there is a real
 223 possibility that exactly the same number will be used by different
 224 protocols for different requests. Any such problems will have to be
 225 identified and resolved by application developers, and may involve
 226 modifying the source code for the USB-ethernet package.</P
 227 ><P
 228 >As an alternative to chaining the state change handler, higher-level
 229 code can instead call <TT
 230 CLASS="FUNCTION"
 231 >usbs_eth_disable</TT
 232 > and
 233 <TT
 234 CLASS="FUNCTION"
 235 >usbs_eth_enable</TT
 236 > directly. These functions may
 237 also be called if the USB-ethernet package should become inactive for
 238 reasons not related directly to events on the USB bus. The main effect
 239 of <TT
 240 CLASS="FUNCTION"
 241 >usbs_eth_enable</TT
 242 > is to restart receive
 243 operations and to allow transmits. The main effect of
 244 <TT
 245 CLASS="FUNCTION"
 246 >usbs_eth_disable</TT
 247 > is to block further transmits:
 248 any current receive operations need to be aborted at the USB level,
 249 for example by halting the appropriate endpoint.</P
 250 ></DIV
 251 ><DIV
 252 CLASS="NAVFOOTER"
 253 ><HR
 254 ALIGN="LEFT"
 255 WIDTH="100%"><TABLE
 256 SUMMARY="Footer navigation table"
 257 WIDTH="100%"
 258 BORDER="0"
 259 CELLPADDING="0"
 260 CELLSPACING="0"
 261 ><TR
 262 ><TD
 263 WIDTH="33%"
 264 ALIGN="left"
 265 VALIGN="top"
 266 ><A
 267 HREF="usbseth-data.html"
 268 ACCESSKEY="P"
 269 >Prev</A
 270 ></TD
 271 ><TD
 272 WIDTH="34%"
 273 ALIGN="center"
 274 VALIGN="top"
 275 ><A
 276 HREF="ecos-ref.html"
 277 ACCESSKEY="H"
 278 >Home</A
 279 ></TD
 280 ><TD
 281 WIDTH="33%"
 282 ALIGN="right"
 283 VALIGN="top"
 284 ><A
 285 HREF="usbseth-netdev.html"
 286 ACCESSKEY="N"
 287 >Next</A
 288 ></TD
 289 ></TR
 290 ><TR
 291 ><TD
 292 WIDTH="33%"
 293 ALIGN="left"
 294 VALIGN="top"
 295 >USB-ethernet Data Transfers</TD
 296 ><TD
 297 WIDTH="34%"
 298 ALIGN="center"
 299 VALIGN="top"
 300 ><A
 301 HREF="io-usb-slave-eth.html"
 302 ACCESSKEY="U"
 303 >Up</A
 304 ></TD
 305 ><TD
 306 WIDTH="33%"
 307 ALIGN="right"
 308 VALIGN="top"
 309 >Network Device for the eCos TCP/IP Stack</TD
 310 ></TR
 311 ></TABLE
 312 ></DIV
 313 ></BODY
 314 ></HTML
 315 >