doc/html/ref/devs-eth-synth-ecosynth.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 >Synthetic Target Ethernet 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="Synthetic Target Ethernet Driver"
  23 HREF="devs-eth-synth-ecosynth-ref.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Synthetic Target Ethernet Driver"
  26 HREF="devs-eth-synth-ecosynth-ref.html"><LINK
  27 REL="NEXT"
  28 TITLE="Synthetic Target Watchdog Device"
  29 HREF="devs-watchdog-synth-ref.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="devs-eth-synth-ecosynth-ref.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="devs-watchdog-synth-ref.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="DEVS-ETH-SYNTH-ECOSYNTH">Synthetic Target Ethernet Driver</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN18897"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >Synthetic Target Ethernet Support&nbsp;--&nbsp;Allow synthetic target applications to perform ethernet I/O</DIV
  91 ><DIV
  92 CLASS="REFSECT1"
  93 ><A
  94 NAME="AEN18900"
  95 ></A
  96 ><H2
  97 >Overview</H2
  98 ><P
  99 >The synthetic target ethernet package can provide up to four network
 100 devices, <TT
 101 CLASS="VARNAME"
 102 >eth0</TT
 103 > to <TT
 104 CLASS="VARNAME"
 105 >eth3</TT
 106 >. These can
 107 be used directly by the eCos application or, more commonly, by a
 108 TCP/IP stack that is linked with the eCos application. Each eCos
 109 device can be mapped on to a real Linux network device. For example,
 110 if the Linux PC has two ethernet cards and <TT
 111 CLASS="VARNAME"
 112 >eth1</TT
 113 > is
 114 not currently being used by Linux itself, then one of the eCos devices
 115 can be mapped on to this Linux device. Alternatively, it is possible
 116 to map some or all of the eCos devices on to the ethertap support
 117 provided by the Linux kernel.
 118     </P
 119 ><P
 120 >The ethernet package depends on the I/O auxiliary provided by the
 121 synthetic target architectural HAL package. During initialization the
 122 eCos application will attempt to instantiate the desired devices, by
 123 sending a request to the auxiliary. This will load a Tcl script
 124 <TT
 125 CLASS="FILENAME"
 126 >ethernet.tcl</TT
 127 > that is responsible for handling the
 128 instantiation request and subsequent I/O operations, for example
 129 transmitting an ethernet packet. However, some of the low-level I/O
 130 operations cannot conveniently be done by a Tcl script so
 131 <TT
 132 CLASS="FILENAME"
 133 >ethernet.tcl</TT
 134 > will actually run a separate program
 135 <B
 136 CLASS="COMMAND"
 137 >rawether</B
 138 > to interact with the Linux network device.
 139     </P
 140 ><DIV
 141 CLASS="INFORMALFIGURE"
 142 ><A
 143 NAME="AEN18910"><P
 144 ></P
 145 ><DIV
 146 CLASS="MEDIAOBJECT"
 147 ><P
 148 ><IMG
 149 SRC="overview.png"
 150 ALIGN="CENTER"></P
 151 ></DIV
 152 ><P
 153 ></P
 154 ></DIV
 155 ><P
 156 >On the target-side there are configuration options to control which
 157 network devices should be present. For many applications a single
 158 device will be sufficient, but if the final eCos application is
 159 something like a network bridge then the package can support multiple
 160 devices. On the host-side each eCos network device needs to be mapped
 161 on to a Linux one, either a real ethernet device or an ethertap
 162 device. This is handled by an entry in the target definition file:
 163     </P
 164 ><TABLE
 165 BORDER="5"
 166 BGCOLOR="#E0E0F0"
 167 WIDTH="70%"
 168 ><TR
 169 ><TD
 170 ><PRE
 171 CLASS="PROGRAMLISTING"
 172 >synth_device ethernet {
 173     eth0 real eth1
 174     eth1 ethertap tap3 00:01:02:03:FE:05
 175     &#8230;
 176 }</PRE
 177 ></TD
 178 ></TR
 179 ></TABLE
 180 ><P
 181 >The ethernet package also comes with support for packet logging,
 182 and provides various facilities for use by user Tcl scripts.
 183     </P
 184 ></DIV
 185 ><DIV
 186 CLASS="REFSECT1"
 187 ><A
 188 NAME="DEVS-ETH-ECOSYNTH-INSTALL"
 189 ></A
 190 ><H2
 191 >Installation</H2
 192 ><P
 193 >Before a synthetic target eCos application can access ethernet devices
 194 it is necessary to build and install host-side support. The relevant
 195 code resides in the <TT
 196 CLASS="FILENAME"
 197 >host</TT
 198 >
 199 subdirectory of the synthetic target ethernet package, and building it
 200 involves the standard <B
 201 CLASS="COMMAND"
 202 >configure</B
 203 >,
 204 <B
 205 CLASS="COMMAND"
 206 >make</B
 207 > and <B
 208 CLASS="COMMAND"
 209 >make install</B
 210 > steps.
 211 The build involves a new executable <B
 212 CLASS="COMMAND"
 213 >rawether</B
 214 > which
 215 must be able to access a raw Linux network device. This is achieved by
 216 installing it suid root, so the <B
 217 CLASS="COMMAND"
 218 >make install</B
 219 > step
 220 has to be run with superuser privileges.
 221     </P
 222 ><DIV
 223 CLASS="CAUTION"
 224 ><P
 225 ></P
 226 ><TABLE
 227 CLASS="CAUTION"
 228 BORDER="1"
 229 WIDTH="100%"
 230 ><TR
 231 ><TD
 232 ALIGN="CENTER"
 233 ><B
 234 >Caution</B
 235 ></TD
 236 ></TR
 237 ><TR
 238 ><TD
 239 ALIGN="LEFT"
 240 ><P
 241 >Installing <B
 242 CLASS="COMMAND"
 243 >rawether</B
 244 > suid root introduces a
 245 potential security problem. Although normally
 246 <B
 247 CLASS="COMMAND"
 248 >rawether</B
 249 > is executed only by the I/O auxiliary,
 250 theoretically it can be run by any program. Effectively it gives any
 251 user the ability to monitor all ethernet traffic and to inject
 252 arbitrary packets into the network. Also, as with any suid root
 253 programs there may be as yet undiscovered exploits. Users and system
 254 administrators should consider the risks before running <B
 255 CLASS="COMMAND"
 256 >make
 257 install</B
 258 >.
 259     </P
 260 ></TD
 261 ></TR
 262 ></TABLE
 263 ></DIV
 264 ><P
 265 >There are two main ways of building the host-side software. It is
 266 possible to build both the generic host-side software and all
 267 package-specific host-side software, including the ethernet support,
 268 in a single build tree. This involves using the
 269 <B
 270 CLASS="COMMAND"
 271 >configure</B
 272 > script at the toplevel of the eCos
 273 repository. For more information on this, see the
 274 <TT
 275 CLASS="FILENAME"
 276 >README.host</TT
 277 > file at the top of the repository.
 278 Note that if you have an existing build tree which does not include
 279 the synthetic target ethernet support then it will be necessary to
 280 rerun the toplevel configure script: the search for appropriate
 281 packages happens at configure time.
 282     </P
 283 ><P
 284 >The alternative is to build just the host-side for this package.
 285 This requires a separate build directory, building directly in the
 286 source tree is disallowed. The <B
 287 CLASS="COMMAND"
 288 >configure</B
 289 > options
 290 are much the same as for a build from the toplevel, and the
 291 <TT
 292 CLASS="FILENAME"
 293 >README.host</TT
 294 > file can be consulted for more
 295 details. It is essential that the ethernet support be configured with
 296 the same <TT
 297 CLASS="OPTION"
 298 >--prefix</TT
 299 > option as other eCos host-side
 300 software, especially the I/O auxiliary provided by the architectural
 301 synthetic target HAL package, otherwise the I/O auxiliary will be
 302 unable to locate the ethernet support.
 303     </P
 304 ></DIV
 305 ><DIV
 306 CLASS="REFSECT1"
 307 ><A
 308 NAME="DEVS-ETH-ECOSYNTH-OPTIONS"
 309 ></A
 310 ><H2
 311 >Target-side Configuration Options</H2
 312 ><P
 313 >The target-side code can be configured to support up to four ethernet
 314 devices, <TT
 315 CLASS="VARNAME"
 316 >eth0</TT
 317 > to <TT
 318 CLASS="VARNAME"
 319 >eth3</TT
 320 >. By
 321 default <TT
 322 CLASS="VARNAME"
 323 >eth0</TT
 324 > is enabled if the configuration
 325 includes a TCP/IP stack, otherwise it is disabled. The other three
 326 devices are always disabled by default. If any of the devices are
 327 enabled then there will also be the usual configuration options
 328 related to building this package. Other options related to network
 329 devices, for example whether or not to use DHCP, are provided by
 330 the generic network device package.
 331     </P
 332 ></DIV
 333 ><DIV
 334 CLASS="REFSECT1"
 335 ><A
 336 NAME="DEVS-ETH-ECOSYNTH-REAL"
 337 ></A
 338 ><H2
 339 >Real Ethernet</H2
 340 ><P
 341 >One obvious way of providing a synthetic target eCos application with
 342 ethernet I/O is to use a real ethernet device in the PC: transmitted
 343 packets go out on a real network, and packets on the network addressed
 344 to the right MAC address are passed on to eCos. This way synthetic
 345 target networking behaves just like networking on a real target with
 346 ethernet hardware. For example, if there is a DHCP server anywhere on
 347 the network then eCos will be able to contact it during networking
 348 startup and get hold of IP address information.
 349     </P
 350 ><P
 351 >Configuring the ethernet support to use a real ethernet device
 352 requires a simple entry in the target definition file:
 353     </P
 354 ><TABLE
 355 BORDER="5"
 356 BGCOLOR="#E0E0F0"
 357 WIDTH="70%"
 358 ><TR
 359 ><TD
 360 ><PRE
 361 CLASS="PROGRAMLISTING"
 362 >synth_device ethernet {
 363     &lt;eCos device&gt; real &lt;linux device&gt;
 364     &#8230;
 365 }</PRE
 366 ></TD
 367 ></TR
 368 ></TABLE
 369 ><P
 370 >For example, to map the eCos network device <TT
 371 CLASS="VARNAME"
 372 >eth0</TT
 373 > to
 374 the Linux device <TT
 375 CLASS="VARNAME"
 376 >eth1</TT
 377 >:
 378     </P
 379 ><TABLE
 380 BORDER="5"
 381 BGCOLOR="#E0E0F0"
 382 WIDTH="70%"
 383 ><TR
 384 ><TD
 385 ><PRE
 386 CLASS="PROGRAMLISTING"
 387 >synth_device ethernet {
 388     eth0 real eth1
 389     &#8230;
 390 }</PRE
 391 ></TD
 392 ></TR
 393 ></TABLE
 394 ><P
 395 >It is not possible for an ethernet device to be shared by both the
 396 eCos TCP/IP stack and the Linux one: there would be no simple way to
 397 work out which stack incoming packets are intended for. In theory
 398 it might be possible to do some demultiplexing using distinct IP
 399 addresses, but it would be impossible to support some functionality
 400 such as DHCP. Therefore the <B
 401 CLASS="COMMAND"
 402 >rawether</B
 403 > program will
 404 refuse to access any ethernet device already in use. On a typical
 405 Linux system <TT
 406 CLASS="VARNAME"
 407 >eth0</TT
 408 > will be used for Linux
 409 networking, and the PC will have to be equipped with additional
 410 ethernet devices for use by eCos.
 411     </P
 412 ><P
 413 >The <B
 414 CLASS="COMMAND"
 415 >rawether</B
 416 > program will access the hardware via
 417 the appropriate Linux device driver, so it is important that the
 418 system is set up such that the relevant module will be automatically
 419 loaded or is already loaded. The details of this will depend on the
 420 installed distribution and version, but typically it will involve an
 421 entry in <TT
 422 CLASS="FILENAME"
 423 >/etc/modules.conf</TT
 424 >.
 425     </P
 426 ></DIV
 427 ><DIV
 428 CLASS="REFSECT1"
 429 ><A
 430 NAME="DEVS-ETH-ECOSYNTH-ETHERTAP"
 431 ></A
 432 ><H2
 433 >Ethertap</H2
 434 ><P
 435 >The Linux kernel's ethertap facility provides a virtual network
 436 interface. A Linux application, for example the
 437 <B
 438 CLASS="COMMAND"
 439 >rawether</B
 440 > program, can open a special character
 441 device <TT
 442 CLASS="FILENAME"
 443 >/dev/net/tun</TT
 444 >, perform various
 445 <TT
 446 CLASS="FUNCTION"
 447 >ioctl</TT
 448 > calls, and then <TT
 449 CLASS="FILENAME"
 450 >write</TT
 451 >
 452 and <TT
 453 CLASS="FILENAME"
 454 >read</TT
 455 > ethernet packets. When the device is
 456 opened the Linux kernel automatically creates a new network interface,
 457 for example <TT
 458 CLASS="VARNAME"
 459 >tap0</TT
 460 >. The Linux TCP/IP stack can be
 461 made to use this network interface like any other interface, receiving
 462 and transmitting ethernet packets. The net effect is a virtual network
 463 connecting just the Linux and eCos TCP/IP stacks, with no other nodes
 464 attached. By default all traffic remains inside this virtual network
 465 and is never forwarded to a real network.
 466     </P
 467 ><P
 468 >Support for the ethertap facility may or may not be provided
 469 automatically, depending on your Linux distribution and version. If
 470 your system does not have a device <TT
 471 CLASS="FILENAME"
 472 >/dev/net/tun</TT
 473 >
 474 or a module <TT
 475 CLASS="FILENAME"
 476 >tun.o</TT
 477 > then the appropriate kernel
 478 documentation should be consulted, for example
 479 <TT
 480 CLASS="FILENAME"
 481 >/usr/src/linux-2.4/Documentation/networking/tuntap.txt</TT
 482 >.
 483 If you are using an old Linux kernel then the ethertap functionality
 484 may be missing completely. When the <B
 485 CLASS="COMMAND"
 486 >rawether</B
 487 >
 488 program is configured and built, the <B
 489 CLASS="COMMAND"
 490 >configure</B
 491 >
 492 script will check for a file <TT
 493 CLASS="FILENAME"
 494 >/usr/include/linux/if_tun.h</TT
 495 >. If that
 496 file is missing then <B
 497 CLASS="COMMAND"
 498 >rawether</B
 499 > will be built without
 500 ethertap functionality, and only real ethernet interfaces will be
 501 supported.
 502     </P
 503 ><P
 504 >The target definition file is used to map eCos network devices on to
 505 ethertap devices. The simplest usage is:
 506     </P
 507 ><TABLE
 508 BORDER="5"
 509 BGCOLOR="#E0E0F0"
 510 WIDTH="70%"
 511 ><TR
 512 ><TD
 513 ><PRE
 514 CLASS="PROGRAMLISTING"
 515 >synth_device ethernet {
 516     eth0 ethertap
 517     &#8230;
 518 }</PRE
 519 ></TD
 520 ></TR
 521 ></TABLE
 522 ><P
 523 >The Linux kernel will automatically allocate the next available tap
 524 network interface. Usually this will be <TT
 525 CLASS="VARNAME"
 526 >tap0</TT
 527 > but if
 528 other software is using the ethertap facility, for example to
 529 implement a VPN, then a different number may be allocated. Usually it
 530 will be better to specify the particular tap device that should be
 531 used for each eCos device, for example:
 532     </P
 533 ><TABLE
 534 BORDER="5"
 535 BGCOLOR="#E0E0F0"
 536 WIDTH="70%"
 537 ><TR
 538 ><TD
 539 ><PRE
 540 CLASS="PROGRAMLISTING"
 541 >synth_device ethernet {
 542     eth0 ethertap tap3
 543     eth1 ethertap tap4
 544     &#8230;
 545 }</PRE
 546 ></TD
 547 ></TR
 548 ></TABLE
 549 ><P
 550 >The user now knows exactly which eCos device is mapped onto which
 551 Linux device, avoiding much potential confusion. Because the virtual
 552 devices are emulated ethernet devices, they require MAC addresses.
 553 There is no physical hardware to provide these addresses, so normally
 554 MAC addresses will be invented. That means that each time the eCos
 555 application is run it will have different MAC addresses, which makes
 556 it more difficult to compare the results of different runs. To get
 557 more deterministic behaviour it is possible to specify the MAC
 558 addresses in the target definition file:
 559     </P
 560 ><TABLE
 561 BORDER="5"
 562 BGCOLOR="#E0E0F0"
 563 WIDTH="70%"
 564 ><TR
 565 ><TD
 566 ><PRE
 567 CLASS="PROGRAMLISTING"
 568 >synth_device ethernet {
 569     eth0 ethertap tap3 00:01:02:03:FE:05
 570     eth1 ethertap tap4 00:01:02:03:FE:06
 571     &#8230;
 572 }</PRE
 573 ></TD
 574 ></TR
 575 ></TABLE
 576 ><P
 577 >During the initialization phase the eCos application will instantiate
 578 the various network devices. This will cause the I/O auxiliary to load
 579 the <TT
 580 CLASS="FILENAME"
 581 >ethernet.tcl</TT
 582 > script and spawn
 583 <B
 584 CLASS="COMMAND"
 585 >rawether</B
 586 > processes, which in turn will
 587 <TT
 588 CLASS="FUNCTION"
 589 >open</TT
 590 > <TT
 591 CLASS="FILENAME"
 592 >/dev/net/tun</TT
 593 > and
 594 perform the appropriate <TT
 595 CLASS="FILENAME"
 596 >ioctl</TT
 597 > calls. On the Linux
 598 side there will now be new network interfaces such as
 599 <TT
 600 CLASS="VARNAME"
 601 >tap3</TT
 602 >, and these can be configured like any other
 603 network interface using commands such as <B
 604 CLASS="COMMAND"
 605 >ifconfig</B
 606 >.
 607 In addition, if the Linux system is set up with hotplug support then
 608 it may be possible to arrange for the network interface to become
 609 active automatically. On a Red Hat Linux system this would require
 610 files such as
 611 <TT
 612 CLASS="FILENAME"
 613 >/etc/sysconfig/network-scripts/ifcfg-tap3</TT
 614 >,
 615 containing data like:
 616     </P
 617 ><TABLE
 618 BORDER="5"
 619 BGCOLOR="#E0E0F0"
 620 WIDTH="70%"
 621 ><TR
 622 ><TD
 623 ><PRE
 624 CLASS="PROGRAMLISTING"
 625 >DEVICE="tap3"
 626 BOOTPROTO="none"
 627 BROADCAST=10.2.2.255
 628 IPADDR="10.2.2.1"
 629 NETMASK="255.255.255.0"
 630 NETWORK=10.2.2.0
 631 ONBOOT="no"</PRE
 632 ></TD
 633 ></TR
 634 ></TABLE
 635 ><P
 636 >This gives the Linux interface the address <TT
 637 CLASS="LITERAL"
 638 >10.2.2.1</TT
 639 >
 640 on the network <TT
 641 CLASS="LITERAL"
 642 >10.2.2.0</TT
 643 >. The eCos network device
 644 should be configured with a compatible address. One way of doing this
 645 would be to enable <TT
 646 CLASS="VARNAME"
 647 >CYGHWR_NET_DRIVER_ETH0_ADDRS</TT
 648 >,
 649 set <TT
 650 CLASS="VARNAME"
 651 >CYGHWR_NET_DRIVER_ETH0_ADDRS_IP</TT
 652 > to
 653 <TT
 654 CLASS="LITERAL"
 655 >10.2.2.2</TT
 656 >, and similarly update the
 657 <TT
 658 CLASS="VARNAME"
 659 >NETMASK</TT
 660 >, <TT
 661 CLASS="VARNAME"
 662 >BROADCAST</TT
 663 >,
 664 <TT
 665 CLASS="VARNAME"
 666 >GATEWAY</TT
 667 > and <TT
 668 CLASS="VARNAME"
 669 >SERVER</TT
 670 > configuration
 671 options.
 672     </P
 673 ><P
 674 >It should be noted that the ethertap facility provides a virtual
 675 network, and any packets transmitted by the eCos application will
 676 not appear on a real network. Therefore usually there will no
 677 accessible DHCP server, and eCos cannot use DHCP or BOOTP to obtain IP
 678 address information. Instead the eCos configuration should use manual
 679 or static addresses.
 680     </P
 681 ><P
 682 >An alternative approach would be to set up the Linux box as a network
 683 bridge, using commands like <B
 684 CLASS="COMMAND"
 685 >brctl</B
 686 > to connect the
 687 virtual network interface <TT
 688 CLASS="VARNAME"
 689 >tap3</TT
 690 > to a physical
 691 network interface such as <TT
 692 CLASS="VARNAME"
 693 >eth0</TT
 694 >. Any packets sent by
 695 the eCos application will get forwarded automatically to the real
 696 network, and some packets on the real network will get forwarded over
 697 the virtual network to the eCos application. Note that the eCos
 698 application might also get some packets that were not intended for it,
 699 but usually those will just be discarded by the eCos TCP/IP stack. The
 700 exact details of setting up a network bridge are left as an exercise
 701 to the reader.
 702     </P
 703 ></DIV
 704 ><DIV
 705 CLASS="REFSECT1"
 706 ><A
 707 NAME="DEVS-ETH-ECOSYNTH-LOGGING"
 708 ></A
 709 ><H2
 710 >Packet Logging</H2
 711 ><P
 712 >The ethernet support comes with support for logging the various
 713 packets that are transferred, including a simple protocol analyser.
 714 This generates simple text output using the filter mechanisms provided
 715 by the I/O auxiliary, so it is possible to control the appearance and
 716 visibility of different types of output. For example the user might
 717 want to see IPv4 headers and all ICMPv4 and ARP operations, but not
 718 TCP headers or any of the packet data.
 719     </P
 720 ><P
 721 >The protocol analyser is not intended to be a fully functional
 722 analyser with knowledge of many different TCP/IP protocols, advanced
 723 search facilities, graphical traffic displays, and so on.
 724 Functionality like that is already provided by other tools such as
 725 <SPAN
 726 CLASS="APPLICATION"
 727 >ethereal</SPAN
 728 > and
 729 <SPAN
 730 CLASS="APPLICATION"
 731 >tcpdump</SPAN
 732 >. Achieving similar levels of
 733 functionality would require a lot of work, for very little gain. It is
 734 still useful to have some protocol analysis functionality available
 735 because the output will be interleaved with other output, for example
 736 <TT
 737 CLASS="FILENAME"
 738 >printf</TT
 739 > calls from the application. That may make
 740 it easier to understand the sequence of events.
 741     </P
 742 ><P
 743 >One problem with logging ethernet traffic is that it can involve very
 744 large amounts of data. If the application is expected to run for a
 745 long time or is very I/O intensive then it is easy to end up with many
 746 megabytes. When running in graphical mode all the logging data will be
 747 held in memory, even data that is not currently visible. At some point
 748 the system will begin to run low on memory and performance will
 749 suffer. To avoid problems, the ethernet script maintains a flag that
 750 controls whether or not packet logging is active. The default is to
 751 run with logging disabled, but this can be changed in the target
 752 definition file:
 753     </P
 754 ><TABLE
 755 BORDER="5"
 756 BGCOLOR="#E0E0F0"
 757 WIDTH="70%"
 758 ><TR
 759 ><TD
 760 ><PRE
 761 CLASS="PROGRAMLISTING"
 762 >synth_device ethernet {
 763     &#8230;
 764     logging 1
 765 }</PRE
 766 ></TD
 767 ></TR
 768 ></TABLE
 769 ><P
 770 >The ethernet script will add a toolbar button that allows this flag to
 771 be changed at run-time, allowing the user to capture traffic for
 772 certain periods of time while the application continues running.
 773     </P
 774 ><P
 775 >The target definition file can contain the following entries for the
 776 various packet logging filters:
 777     </P
 778 ><TABLE
 779 BORDER="5"
 780 BGCOLOR="#E0E0F0"
 781 WIDTH="70%"
 782 ><TR
 783 ><TD
 784 ><PRE
 785 CLASS="PROGRAMLISTING"
 786 >synth_device ethernet {
 787     &#8230;
 788     filter ether  -hide 0 -background LightBlue -foreground "#000080"
 789     filter arp    -hide 0 -background LightBlue -foreground "#000050"
 790     filter ipv4   -hide 0 -background LightBlue -foreground "#000040"
 791     filter ipv6   -hide 1 -background LightBlue -foreground "#000040"
 792     filter icmpv4 -hide 0 -background LightBlue -foreground "#000070"
 793     filter icmpv6 -hide 1 -background LightBlue -foreground "#000070"
 794     filter udp    -hide 0 -background LightBlue -foreground "#000030"
 795     filter tcp    -hide 0 -background LightBlue -foreground "#000020"
 796     filter hexdata   -hide 1 -background LightBlue -foreground "#000080"
 797     filter asciidata -hide 1 -background LightBlue -foreground "#000080"
 798 }</PRE
 799 ></TD
 800 ></TR
 801 ></TABLE
 802 ><P
 803 >All output will show the eCos network device, for example
 804 <TT
 805 CLASS="LITERAL"
 806 >eth0</TT
 807 >, and the direction relative to the eCos
 808 application. Some of the filters will show packet headers, for example
 809 <TT
 810 CLASS="LITERAL"
 811 >ether</TT
 812 > gives details of the ethernet packet header
 813 and <TT
 814 CLASS="LITERAL"
 815 >tcp</TT
 816 > gives information about TCP headers such as
 817 whether or not the SYN flag is set. The TCP and UDP filters will also
 818 show source and destination addresses, using numerical addresses and
 819 if possible host names. However, host names will only be shown if the
 820 host appears in <TT
 821 CLASS="FILENAME"
 822 >/etc/hosts</TT
 823 >: doing full DNS
 824 lookups while the data is being captured would add significantly to
 825 complexity and overhead. The <TT
 826 CLASS="LITERAL"
 827 >hexdata</TT
 828 > and
 829 <TT
 830 CLASS="LITERAL"
 831 >asciidata</TT
 832 > filters show the remainder of the packets
 833 after the ethernet, IP and TCP or UDP headers have been stripped.
 834     </P
 835 ><P
 836 >Some of the filters will provide raw dumps of some of the packet data.
 837 Showing up to 1500 bytes of data for each packet would be expensive,
 838 and often the most interesting information is near the start of the
 839 packet. Therefore it is possible to set a limit on the number of bytes
 840 that will be shown using the target definition file. The default limit
 841 is 64 bytes.
 842     </P
 843 ><TABLE
 844 BORDER="5"
 845 BGCOLOR="#E0E0F0"
 846 WIDTH="70%"
 847 ><TR
 848 ><TD
 849 ><PRE
 850 CLASS="PROGRAMLISTING"
 851 >synth_device ethernet {
 852     &#8230;
 853     max_show 128
 854 }</PRE
 855 ></TD
 856 ></TR
 857 ></TABLE
 858 ></DIV
 859 ><DIV
 860 CLASS="REFSECT1"
 861 ><A
 862 NAME="DEVS-ETH-ECOSYNTH-GUI"
 863 ></A
 864 ><H2
 865 >User Interface Additions</H2
 866 ><P
 867 >When running in graphical mode the ethernet script extends the user
 868 interface in two ways: a button is added to the toolbar so that users
 869 can enable or disable packet logging; and an entry is added to the
 870 <SPAN
 871 CLASS="GUIMENU"
 872 >Help</SPAN
 873 > menu for the ethernet-specific documentation.
 874     </P
 875 ></DIV
 876 ><DIV
 877 CLASS="REFSECT1"
 878 ><A
 879 NAME="DEVS-ETH-ECOSYNTH-ARGS"
 880 ></A
 881 ><H2
 882 >Command Line Arguments</H2
 883 ><P
 884 >The synthetic target ethernet support does not use any command line
 885 arguments. All configuration is handled through the target definition
 886 file.
 887     </P
 888 ></DIV
 889 ><DIV
 890 CLASS="REFSECT1"
 891 ><A
 892 NAME="DEVS-ETH-ECOSYNTH-HOOKS"
 893 ></A
 894 ><H2
 895 >Hooks</H2
 896 ><P
 897 >The ethernet support defines two hooks that can be used by other
 898 scripts, especially user scripts: <TT
 899 CLASS="LITERAL"
 900 >ethernet_tx</TT
 901 > and
 902 <TT
 903 CLASS="LITERAL"
 904 >ethernet_rx</TT
 905 >. The tx hook is called whenever eCos
 906 tries to transmit a packet. The rx hook is called whenever an incoming
 907 packet is passed to the eCos application. Note that this may be a
 908 little bit after the packet was actually received by the I/O auxiliary
 909 since it can buffer some packets. Both hooks are called with two
 910 arguments, the name of the network device and the packet being
 911 transferred. Typical usage might look like:
 912     </P
 913 ><TABLE
 914 BORDER="5"
 915 BGCOLOR="#E0E0F0"
 916 WIDTH="70%"
 917 ><TR
 918 ><TD
 919 ><PRE
 920 CLASS="PROGRAMLISTING"
 921 >  proc my_tx_hook { arg_list } {
 922     set dev [lindex $arg_list 0]
 923     incr ::my_ethernet_tx_packets($dev)
 924     incr ::my_ethernet_tx_bytes($dev) [string length [lindex $arg_list 1]]
 925   }
 926   proc my_rx_hook { arg_list } {
 927     set dev [lindex $arg_list 0]
 928     incr ::my_ethernet_rx_packets($dev)
 929     incr ::my_ethernet_rx_bytes($dev) [string length [lindex $arg_list 1]]
 930   }
 931   synth::hook_add "ethernet_tx" my_tx_hook
 932   synth::hook_add "ethernet_rx" my_rx_hook</PRE
 933 ></TD
 934 ></TR
 935 ></TABLE
 936 ><P
 937 >The global arrays <TT
 938 CLASS="VARNAME"
 939 >my_ethernet_tx_packets</TT
 940 > etc. will
 941 now be updated whenever there is ethernet traffic. Other code,
 942 probably running at regular intervals by use of the Tcl
 943 <B
 944 CLASS="COMMAND"
 945 >after</B
 946 > procedure, can then use this information to
 947 update a graphical monitor of some sort.
 948     </P
 949 ></DIV
 950 ><DIV
 951 CLASS="REFSECT1"
 952 ><A
 953 NAME="DEVS-ETH-ECOSYNTH-TCL"
 954 ></A
 955 ><H2
 956 >Additional Tcl Procedures</H2
 957 ><P
 958 >The ethernet support provides one additional Tcl procedure that can be
 959 used by other scripts;
 960     </P
 961 ><TABLE
 962 BORDER="5"
 963 BGCOLOR="#E0E0F0"
 964 WIDTH="70%"
 965 ><TR
 966 ><TD
 967 ><PRE
 968 CLASS="PROGRAMLISTING"
 969 >ethernet::devices_get_list    </PRE
 970 ></TD
 971 ></TR
 972 ></TABLE
 973 ><P
 974 >This procedure returns a list of the ethernet devices that have been
 975 instantiated, for example <TT
 976 CLASS="LITERAL"
 977 >{eth0 eth1}</TT
 978 >.
 979     </P
 980 ></DIV
 981 ><DIV
 982 CLASS="NAVFOOTER"
 983 ><HR
 984 ALIGN="LEFT"
 985 WIDTH="100%"><TABLE
 986 SUMMARY="Footer navigation table"
 987 WIDTH="100%"
 988 BORDER="0"
 989 CELLPADDING="0"
 990 CELLSPACING="0"
 991 ><TR
 992 ><TD
 993 WIDTH="33%"
 994 ALIGN="left"
 995 VALIGN="top"
 996 ><A
 997 HREF="devs-eth-synth-ecosynth-ref.html"
 998 ACCESSKEY="P"
 999 >Prev</A
1000 ></TD
1001 ><TD
1002 WIDTH="34%"
1003 ALIGN="center"
1004 VALIGN="top"
1005 ><A
1006 HREF="ecos-ref.html"
1007 ACCESSKEY="H"
1008 >Home</A
1009 ></TD
1010 ><TD
1011 WIDTH="33%"
1012 ALIGN="right"
1013 VALIGN="top"
1014 ><A
1015 HREF="devs-watchdog-synth-ref.html"
1016 ACCESSKEY="N"
1017 >Next</A
1018 ></TD
1019 ></TR
1020 ><TR
1021 ><TD
1022 WIDTH="33%"
1023 ALIGN="left"
1024 VALIGN="top"
1025 >Synthetic Target Ethernet Driver</TD
1026 ><TD
1027 WIDTH="34%"
1028 ALIGN="center"
1029 VALIGN="top"
1030 ><A
1031 HREF="devs-eth-synth-ecosynth-ref.html"
1032 ACCESSKEY="U"
1033 >Up</A
1034 ></TD
1035 ><TD
1036 WIDTH="33%"
1037 ALIGN="right"
1038 VALIGN="top"
1039 >Synthetic Target Watchdog Device</TD
1040 ></TR
1041 ></TABLE
1042 ></DIV
1043 ></BODY
1044 ></HTML
1045 >