packages/devs/eth/synth/ecosynth/v2_0/doc/devs-eth-synth-ecosynth.html

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