doc/html/ref/usbseth-host.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 >Example Host-side Device Driver</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="Network Device for the eCos TCP/IP Stack"
  26 HREF="usbseth-netdev.html"><LINK
  27 REL="NEXT"
  28 TITLE="Communication Protocol"
  29 HREF="usbseth-protocol.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-netdev.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-protocol.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-HOST">Example Host-side Device Driver</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN17593"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >Example Host-side Device Driver&nbsp;--&nbsp;Provide host-side support for the eCos USB-ethernet package</DIV
  91 ><DIV
  92 CLASS="REFSECT1"
  93 ><A
  94 NAME="AEN17596"
  95 ></A
  96 ><H2
  97 >Description</H2
  98 ><P
  99 >The USB-ethernet package is supplied with a single host-side device
 100 driver. This driver has been developed against the Linux kernel
 101 2.2.16-22, as shipped with Red Hat 7. The driver is provided as is and
 102 should not be considered production quality: for example it only
 103 checks for a bogus vendor id <TT
 104 CLASS="LITERAL"
 105 >0x4242</TT
 106 > rather than an
 107 official vendor id supplied by the <A
 108 HREF="http://www.usb.org/"
 109 TARGET="_top"
 110 >USB Implementers Forum</A
 111 >. Also, if the
 112 peripheral involves multiple configurations or multiple interfaces, it
 113 will fail to detect this. However, the driver can be used for simple
 114 testing and as the basis of a full device driver. Details of the
 115 protocol used between host and peripheral can be found in the <A
 116 HREF="usbseth-protocol.html"
 117 >Communication Protocol</A
 118 > section.</P
 119 ><P
 120 >The host-side device driver can be found in the <TT
 121 CLASS="FILENAME"
 122 >host</TT
 123 > subdirectory of the USB-ethernet
 124 package, specifically the file <TT
 125 CLASS="FILENAME"
 126 >ecos_usbeth.c</TT
 127 >, and
 128 comes with a <TT
 129 CLASS="FILENAME"
 130 >Makefile</TT
 131 >. Both files may need
 132 to be modified for specific applications. For example, the vendor id
 133 table <TT
 134 CLASS="LITERAL"
 135 >ecos_usbeth_implementations</TT
 136 > may need to be
 137 updated for the specific USB peripheral being built. The
 138 <TT
 139 CLASS="FILENAME"
 140 >Makefile</TT
 141 > assumes that the Linux kernel sources
 142 reside in <TT
 143 CLASS="FILENAME"
 144 >/usr/src/linux</TT
 145 >, and
 146 that the kernel has already been configured and built. Assuming this
 147 is the case, the device driver can be built simply by invoking
 148 <B
 149 CLASS="COMMAND"
 150 >make</B
 151 > with no additional arguments. This will result
 152 in a dynamically loadable kernel module,
 153 <TT
 154 CLASS="FILENAME"
 155 >ecos_usbeth.o</TT
 156 >, in the current directory.</P
 157 ><DIV
 158 CLASS="NOTE"
 159 ><BLOCKQUOTE
 160 CLASS="NOTE"
 161 ><P
 162 ><B
 163 >Note: </B
 164 >As normal for Linux kernel builds, the generated files such as
 165 <TT
 166 CLASS="FILENAME"
 167 >ecos_usbeth.o</TT
 168 > live in the same directory as the
 169 source tree. This is very different from eCos where the source tree
 170 (or component repository) is kept separate from any builds. There may
 171 be problems if the component repository is kept read-only or if it is
 172 put under source code control. Any such problems can be avoided by
 173 making a copy of the <TT
 174 CLASS="FILENAME"
 175 >host</TT
 176 >
 177 subdirectory and building that copy.</P
 178 ></BLOCKQUOTE
 179 ></DIV
 180 ><P
 181 >Loading the kernel module into the current system requires root
 182 privileges. If the generic USB support is also a loadable module and
 183 has not been loaded already, this must happen first:</P
 184 ><TABLE
 185 BORDER="5"
 186 BGCOLOR="#E0E0F0"
 187 WIDTH="70%"
 188 ><TR
 189 ><TD
 190 ><PRE
 191 CLASS="SCREEN"
 192 ># insmod usb-uhci
 193 Using /lib/modules/2.2.16-22/usb/usb-uhci.o</PRE
 194 ></TD
 195 ></TR
 196 ></TABLE
 197 ><P
 198 >Depending on the host hardware, the <TT
 199 CLASS="LITERAL"
 200 >uhci</TT
 201 > or
 202 <TT
 203 CLASS="LITERAL"
 204 >usb-ohci</TT
 205 > modules may be more appropriate. Loading
 206 the generic USB module will typically result in a number of messages
 207 to the logfile <TT
 208 CLASS="FILENAME"
 209 >/var/log/messages</TT
 210 >, giving details
 211 of the specific host-side hardware that has been detected plus any
 212 hubs. The next step is to load the USB-ethernet module:</P
 213 ><TABLE
 214 BORDER="5"
 215 BGCOLOR="#E0E0F0"
 216 WIDTH="70%"
 217 ><TR
 218 ><TD
 219 ><PRE
 220 CLASS="SCREEN"
 221 ># insmod ecos_usbeth.o</PRE
 222 ></TD
 223 ></TR
 224 ></TABLE
 225 ><P
 226 >This should result in a number of additional diagnostics in the
 227 logfile:</P
 228 ><TABLE
 229 BORDER="5"
 230 BGCOLOR="#E0E0F0"
 231 WIDTH="70%"
 232 ><TR
 233 ><TD
 234 ><PRE
 235 CLASS="SCREEN"
 236 >Apr 1 18:01:08 grumpy kernel: eCos USB-ethernet device driver
 237 Apr 1 18:01:08 grumpy kernel: usb.c: registered new driver ecos_usbeth</PRE
 238 ></TD
 239 ></TR
 240 ></TABLE
 241 ><P
 242 >If a suitable USB peripheral is now connected the host will detect
 243 this, assign an address in the local USB network, obtain enumeration
 244 data, and find a suitable device driver. Assuming the peripheral and
 245 device driver agree on the supported vendor ids, the
 246 <TT
 247 CLASS="FILENAME"
 248 >ecos_usbeth.o</TT
 249 > module will be selected and this
 250 will be reported in the system log:</P
 251 ><TABLE
 252 BORDER="5"
 253 BGCOLOR="#E0E0F0"
 254 WIDTH="70%"
 255 ><TR
 256 ><TD
 257 ><PRE
 258 CLASS="SCREEN"
 259 >Apr 1 18:04:12 grumpy kernel: usb.c: USB new device connect, assigned device number 3
 260 Apr 1 18:04:12 grumpy kernel: eCos-based USB ethernet peripheral active at eth1</PRE
 261 ></TD
 262 ></TR
 263 ></TABLE
 264 ><P
 265 >What can happen next depends very much on the software that is running
 266 on top of the USB-ethernet package inside the peripheral. For example,
 267 if there is a TCP/IP stack then it should be possible to bring up a
 268 network connection between host and peripheral using
 269 <B
 270 CLASS="COMMAND"
 271 >ifconfig</B
 272 >.</P
 273 ></DIV
 274 ><DIV
 275 CLASS="NAVFOOTER"
 276 ><HR
 277 ALIGN="LEFT"
 278 WIDTH="100%"><TABLE
 279 SUMMARY="Footer navigation table"
 280 WIDTH="100%"
 281 BORDER="0"
 282 CELLPADDING="0"
 283 CELLSPACING="0"
 284 ><TR
 285 ><TD
 286 WIDTH="33%"
 287 ALIGN="left"
 288 VALIGN="top"
 289 ><A
 290 HREF="usbseth-netdev.html"
 291 ACCESSKEY="P"
 292 >Prev</A
 293 ></TD
 294 ><TD
 295 WIDTH="34%"
 296 ALIGN="center"
 297 VALIGN="top"
 298 ><A
 299 HREF="ecos-ref.html"
 300 ACCESSKEY="H"
 301 >Home</A
 302 ></TD
 303 ><TD
 304 WIDTH="33%"
 305 ALIGN="right"
 306 VALIGN="top"
 307 ><A
 308 HREF="usbseth-protocol.html"
 309 ACCESSKEY="N"
 310 >Next</A
 311 ></TD
 312 ></TR
 313 ><TR
 314 ><TD
 315 WIDTH="33%"
 316 ALIGN="left"
 317 VALIGN="top"
 318 >Network Device for the eCos TCP/IP Stack</TD
 319 ><TD
 320 WIDTH="34%"
 321 ALIGN="center"
 322 VALIGN="top"
 323 ><A
 324 HREF="io-usb-slave-eth.html"
 325 ACCESSKEY="U"
 326 >Up</A
 327 ></TD
 328 ><TD
 329 WIDTH="33%"
 330 ALIGN="right"
 331 VALIGN="top"
 332 >Communication Protocol</TD
 333 ></TR
 334 ></TABLE
 335 ></DIV
 336 ></BODY
 337 ></HTML
 338 >