OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [devs-eth-synth-ecosynth.html] - Blame information for rev 588

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback 
<!-- 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 
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.