Mercurial > ecos-v3_0-branch

annotate packages/hal/synth/arch/current/doc/synth.sgml @ 2729:74dbf4c3f2e1 after-copyright-change-20090129

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update all copyright banners to reflect FSF ownership; fix and improve licence text.
author jlarmour
date Thu, 29 Jan 2009 17:47:46 +0000
parents fcb7cbb964ae
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
709
40890868764a * doc/overview.gif, doc/overview.fig: renamed to
jlarmour
parents: 332
diff changeset
1 <!-- DOCTYPE part PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
3 <!-- {{{ Banner -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
4
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
5 <!-- =============================================================== -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
6 <!-- -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
7 <!-- synth.sgml -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
8 <!-- -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
9 <!-- Synthetic target architectural documentation. -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
10 <!-- -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
11 <!-- =============================================================== -->
2729
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 991
diff changeset
12 <!-- ####ECOSDOCCOPYRIGHTBEGIN#### -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 991
diff changeset
13 <!-- =============================================================== -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 991
diff changeset
14 <!-- Copyright (C) 2002 Free Software Foundation, Inc. -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 991
diff changeset
15 <!-- This material may be distributed only subject to the terms -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 991
diff changeset
16 <!-- and conditions set forth in the Open Publication License, v1.0 -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 991
diff changeset
17 <!-- or later (the latest version is presently available at -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 991
diff changeset
18 <!-- http://www.opencontent.org/openpub/) -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 991
diff changeset
19 <!-- Distribution of the work or derivative of the work in any -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 991
diff changeset
20 <!-- standard (paper) book form is prohibited unless prior -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 991
diff changeset
21 <!-- permission obtained from the copyright holder -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 991
diff changeset
22 <!-- =============================================================== -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 991
diff changeset
23 <!-- ####ECOSDOCCOPYRIGHTEND#### -->
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
24 <!-- =============================================================== -->
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
25 <!-- =============================================================== -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
26 <!-- #####DESCRIPTIONBEGIN#### -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
27 <!-- -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
28 <!-- Author(s): bartv -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
29 <!-- Contact(s): bartv -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
30 <!-- Date: 2002/02/24 -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
31 <!-- Version: 0.01 -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
32 <!-- -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
33 <!-- ####DESCRIPTIONEND#### -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
34 <!-- =============================================================== -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
35
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
36 <!-- }}} -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
37
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
38 <part id="hal-synth-arch"><title>eCos Synthetic Target</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
39
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
40 <!-- {{{ Overview -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
41
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
42 <refentry id="synth">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
43 <refmeta>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
44 <refentrytitle>Overview</refentrytitle>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
45 </refmeta>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
46 <refnamediv>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
47 <refname>The eCos synthetic target</refname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
48 <refpurpose>Overview</refpurpose>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
49 </refnamediv>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
50
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
51 <refsect1 id="synth-description"><title>Description</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
52 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
53 Usually eCos runs on either a custom piece of hardware, specially
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
54 designed to meet the needs of a specific application, or on a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
55 development board of some sort that is available before the final
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
56 hardware. Such boards have a number of things in common:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
57 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
58 <orderedlist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
59 <listitem><para>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
60 Obviously there has to be at least one processor to do the work. Often
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
61 this will be a 32-bit processor, but it can be smaller or larger.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
62 Processor speed will vary widely, depending on the expected needs of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
63 the application. However the exact processor being used tends not to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
64 matter very much for most of the development process: the use of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
65 languages such as C or C++ means that the compiler will handle those
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
66 details.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
67 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
68 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
69 There needs to be memory for code and for data. A typical system will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
70 have two different types of memory. There will be some non-volatile
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
71 memory such as flash, EPROM or masked ROM. There will also be some
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
72 volatile memory such as DRAM or SRAM. Often the code for the final
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
73 application will reside in the non-volatile memory and all of the RAM
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
74 will be available for data. However updating non-volatile memory
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
75 requires a non-trivial amount of effort, so for much of the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
76 development process it is more convenient to burn suitable firmware,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
77 for example RedBoot, into the non-volatile memory and then use that to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
78 load the application being debugged into RAM, alongside the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
79 application data and a small area reserved for use by the firmware.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
80 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
81 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
82 The platform must provide certain mimimal I/O facilities. Most eCos
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
83 configurations require a clock signal of some sort. There must also be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
84 some way of outputting diagnostics to the user, often but not always
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
85 via a serial port. Unless special debug hardware is being used, source
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
86 level debugging will require bidirectional communication between a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
87 host machine and the target hardware, usually via a serial port or an
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
88 ethernet device.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
89 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
90 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
91 All the above is not actually very useful yet because there is no way
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
92 for the embedded device to interact with the rest of the world, except
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
93 by generating diagnostics. Therefore an embedded device will have
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
94 additional I/O hardware. This may be fairly standard hardware such as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
95 an ethernet or USB interface, or special hardware designed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
96 specifically for the intended application, or quite often some
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
97 combination. Standard hardware such as ethernet or USB may be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
98 supported by eCos device drivers and protocol stacks, whereas the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
99 special hardware will be driven directly by application code.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
100 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
101 </orderedlist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
102 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
103 Much of the above can be emulated on a typical PC running Linux.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
104 Instead of running the embedded application being developed on a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
105 target board of some sort, it can be run as a Linux process. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
106 processor will be the PC's own processor, for example an x86, and the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
107 memory will be the process' address space. Some I/O facilities can be
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
108 emulated directly through system calls. For example clock hardware can
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
109 be emulated by setting up a <literal>SIGALRM</literal> signal, which
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
110 will cause the process to be interrupted at regular intervals. This
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
111 emulation of real hardware will not be particularly accurate, the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
112 number of cpu cycles available to the eCos application between clock
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
113 ticks will vary widely depending on what else is running on the PC,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
114 but for much development work it will be good enough.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
115 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
116 <para>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
117 Other I/O facilities are provided through an I/O auxiliary process,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
118 ecosynth, that gets spawned by the eCos application during startup.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
119 When an eCos device driver wants to perform some I/O operation, for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
120 example send out an ethernet packet, it sends a request to the I/O
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
121 auxiliary. That is an ordinary Linux application so it has ready
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
122 access to all normal Linux I/O facilities. To emulate a device
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
123 interrupt the I/O auxiliary can raise a <literal>SIGIO</literal>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
124 signal within the eCos application. The HAL's interrupt subsystem
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
125 installs a signal handler for this, which will then invoke the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
126 standard eCos ISR/DSR mechanisms. The I/O auxiliary is based around
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
127 Tcl scripting, making it easy to extend and customize. It should be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
128 possible to configure the synthetic target so that its I/O
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
129 functionality is similar to what will be available on the final target
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
130 hardware for the application being developed.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
131 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
132 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
133 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
134 <imageobject>
991
fcb7cbb964ae * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 709
diff changeset
135 <imagedata fileref="synth-io-overview.png" Scalefit=1 Align="Center">
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
136 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
137 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
138 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
139 <para>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
140 A key requirement for synthetic target code is that the embedded
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
141 application must not be linked with any of the standard Linux
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
142 libraries such as the GNU C library: that would lead to a confusing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
143 situation where both eCos and the Linux libraries attempted to provide
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
144 functions such as <function>printf</function>. Instead the synthetic
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
145 target support must be implemented directly on top of the Linux
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
146 kernels' system call interface. For example, the kernel provides a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
147 system call for write operations. The actual function
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
148 <function>write</function> is implemented in the system's C library,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
149 but all it does is move its arguments on to the stack or into certain
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
150 registers and then execute a special trap instruction such as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
151 <literal>int&nbsp;0x80</literal>. When this instruction is executed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
152 control transfers into the kernel, which will validate the arguments
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
153 and perform the appropriate operation. Now, a synthetic target
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
154 application cannot be linked with the system's C library. Instead it
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
155 contains a function <function>cyg_hal_sys_write</function> which, like
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
156 the C library's <function>write</function> function, pushes its
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
157 arguments on to the stack and executes the trap instruction. The Linux
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
158 kernel cannot tell the difference, so it will perform the I/O
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
159 operation requested by the synthetic target. With appropriate
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
160 knowledge of what system calls are available, this makes it possible
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
161 to emulate the required I/O facilities. For example, spawning the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
162 ecosynth I/O auxiliary involves system calls
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
163 <function>cyg_hal_sys_fork</function> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
164 <function>cyg_hal_sys_execve</function>, and sending a request to the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
165 auxiliary uses <function>cyg_hal_sys_write</function>.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
166 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
167 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
168 In many ways developing for the synthetic target is no different from
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
169 developing for real embedded targets. eCos must be configured
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
170 appropriately: selecting a suitable target such as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
171 <userinput>i386linux</userinput> will cause the configuration system
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
172 to load the appropriate packages for this hardware; this includes an
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
173 architectural HAL package and a platform-specific package; the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
174 architectural package contains generic code applicable to all Linux
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
175 platforms, whereas the platform package is for specific Linux
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
176 implementations such as the x86 version and contains any
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
177 processor-specific code. Selecting this target will also bring in some
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
178 device driver packages. Other aspects of the configuration such as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
179 which API's are supported are determined by the template, by adding
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
180 and removing packages, and by fine-grained configuration.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
181 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
182 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
183 In other ways developing for the synthetic target can be much easier
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
184 than developing for a real embedded target. For example there is no
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
185 need to worry about building and installing suitable firmware on the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
186 target hardware, and then downloading and debugging the actual
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
187 application over a serial line or a similar connection. Instead an
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
188 eCos application built for the synthetic target is mostly
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
189 indistinguishable from an ordinary Linux program. It can be run simply
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
190 by typing the name of the executable file at a shell prompt.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
191 Alternatively you can debug the application using whichever version of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
192 gdb is provided by your Linux distribution. There is no need to build
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
193 or install special toolchains. Essentially using the synthetic target
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
194 means that the various problems associated with real embedded hardware
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
195 can be bypassed for much of the development process.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
196 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
197 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
198 The eCos synthetic target provides emulation, not simulation. It is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
199 possible to run eCos in suitable architectural simulators but that
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
200 involves a rather different approach to software development. For
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
201 example, when running eCos on the psim PowerPC simulator you need
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
202 appropriate cross-compilation tools that allow you to build PowerPC
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
203 executables. These are then loaded into the simulator which interprets
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
204 every instruction and attempts to simulate what would happen if the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
205 application were running on real hardware. This involves a lot of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
206 processing overhead, but depending on the functionality provided by
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
207 the simulator it can give very accurate results. When developing for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
208 the synthetic target the executable is compiled for the PC's own
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
209 processor and will be executed at full speed, with no need for a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
210 simulator or special tools. This will be much faster and somewhat
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
211 simpler than using an architectural simulator, but no attempt is made
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
212 to accurately match the behaviour of a real embedded target.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
213 </para>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
214 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
215 </refentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
216
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
217 <!-- }}} -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
218 <!-- {{{ Installation -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
219
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
220 <refentry id="synth-install">
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
221 <refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
222 <refentrytitle>Installation</refentrytitle>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
223 </refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
224 <refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
225 <refname>Installation</refname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
226 <refpurpose>Preparing to use the synthetic target</refpurpose>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
227 </refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
228
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
229 <refsect1 id="synth-install-host"><title>Host-side Software</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
230 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
231 To get the full functionality of the synthetic target, users must
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
232 build and install the I/O auxiliary ecosynth and various support
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
233 files. It is possible to develop applications for the synthetic target
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
234 without the auxiliary, but only limited I/O facilities will be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
235 available. The relevant code resides in the <filename
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
236 class="directory">host</filename> subdirectory of the synthetic target
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
237 architectural HAL package, and building it involves the standard
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
238 <command>configure</command>, <command>make</command>, and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
239 <command>make install</command> steps.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
240 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
241 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
242 There are two main ways of building the host-side software. It is
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
243 possible to build both the generic host-side software and all
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
244 package-specific host-side software, including the I/O auxiliary. in a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
245 single build tree. This involves using the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
246 <command>configure</command> script at the toplevel of the eCos
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
247 repository, which will automatically search the <filename
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
248 class="directory">packages</filename> hierarchy for host-side
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
249 software. For more information on this, see the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
250 <filename>README.host</filename> file at the top of the repository.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
251 Note that if you have an existing build tree which does not include
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
252 the synthetic target architectural HAL package then it will be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
253 necessary to rerun the toplevel configure script: the search for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
254 appropriate packages happens at configure time.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
255 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
256 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
257 The alternative is to build just the host-side for this package.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
258 This involves creating a suitable build directory and running the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
259 <command>configure</command> script. Note that building directly in
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
260 the source tree is not allowed.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
261 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
262 <screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
263 $ cd &lt;somewhere suitable&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
264 $ mkdir synth_build
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
265 $ cd synth_build
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
266 $ &lt;repo&lt;&gt;/packages/hal/synth/arch/&lt;version&gt;/host/configure &lt;options&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
267 $ make
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
268 $ make install
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
269 </screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
270 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
271 The code makes extensive use of Tcl/TK and requires version 8.3 or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
272 later. This is checked by the <command>configure</command> script. By
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
273 default it will use the system's Tcl installation in <filename
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
274 class="directory">/usr</filename>. If a different, more recent Tcl
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
275 installation should be used then its location can be specified using
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
276 the options <option>--with-tcl=&lt;path&gt;</option>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
277 <option>--with-tcl-header=&lt;path&gt;</option> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
278 <option>--with-tcl-lib=&lt;path&gt;</option>. For more information on these options
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
279 see the <filename>README.host</filename> file at the toplevel of the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
280 eCos repository.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
281 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
282 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
283 Some users may also want to specify the install location using a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
284 <option>--prefix=&lt;path&gt;</option> option. The default install
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
285 location is <filename class="directory">/usr/local</filename>. It is
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
286 essential that the <filename class="directory">bin</filename>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
287 subdirectory of the install location is on the user's search
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
288 <envar>PATH</envar>, otherwise the eCos application will be unable to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
289 locate and execute the I/O auxiliary ecosynth.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
290 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
291 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
292 Because ecosynth is run automatically by an eCos application rather
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
293 than explicitly by the user, it is not installed in the <filename
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
294 class="directory">bin</filename> subdirectory itself. Instead it is
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
295 installed below <filename class="directory">libexec</filename>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
296 together with various support files such as images. At configure time
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
297 it is usually possible to specify an alternative location for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
298 <filename class="directory">libexec</filename> using
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
299 <option>--exec-prefix=&lt;path&gt;</option> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
300 <option>--libexecdir=&lt;path&gt;</option>. These options should not
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
301 be used for this package because the eCos application is built
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
302 completely separately and does not know how the host-side was
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
303 configured.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
304 </para>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
305 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
306
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
307 <refsect1 id="synth-tools"><title>Toolchain</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
308 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
309 When developing eCos applications for a normal embedded target it is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
310 necessary to use a suitable cross-compiler and related tools such as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
311 the linker. Developing for the synthetic target is easier because you
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
312 can just use the standard GNU tools (gcc, g++, ld, &hellip;) which
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
313 were provided with your Linux distribution, or which you used to build
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
314 your own Linux setup. Any reasonably recent version of the tools, for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
315 example gcc 2.96(Red Hat) as shipped with Red Hat Linux 7, should be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
316 sufficient.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
317 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
318 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
319 There is one important limitation when using these tools: current gdb
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
320 will not support debugging of eCos threads on the synthetic target. As
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
321 far as gdb is concerned a synthetic target application is
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
322 indistinguishable from a normal Linux application, so it assumes that
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
323 any threads will be created by calls to the Linux
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
324 <function>pthread_create</function> function provided by the C
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
325 library. Obviously this is not the case since the application is never
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
326 linked with that library. Therefore gdb never notices the eCos thread
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
327 mechanisms and assumes the application is single-threaded. Fixing this
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
328 is possible but would involve non-trivial changes to gdb.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
329 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
330 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
331 Theoretically it is possible to develop synthetic target applications
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
332 on, for example, a PC running Windows and then run the resulting
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
333 executables on another machine that runs Linux. This is rarely useful:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
334 if a Linux machine is available then usually that machine will also be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
335 used for building ecos and the application. However, if for some
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
336 reason it is necessary or desirable to build on another machine then
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
337 this requires a suitable cross-compiler and related tools. If the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
338 application will be running on a typical PC with an x86 processor then
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
339 a suitable configure triplet would be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
340 <userinput>i686-pc-linux-gnu</userinput>. The installation
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
341 instructions for the various GNU tools should be consulted for further
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
342 information.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
343 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
344 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
345
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
346 <refsect1 id="synth-hardware"><title>Hardware Preparation</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
347 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
348 Preparing a real embedded target for eCos development can be tricky.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
349 Often the first step is to install suitable firmware, usually RedBoot.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
350 This means creating and building a special configuration for eCos with
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
351 the RedBoot template, then somehow updating the target's flash chips
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
352 with the resulting RedBoot image. Typically it will also be necessary
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
353 to get a working serial connection, and possibly set up ethernet as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
354 well. Although usually none of the individual steps are particularly
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
355 complicated, there are plenty of ways in which things can go wrong and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
356 it can be hard to figure out what is actually happening. Of course
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
357 some board manufacturers make life easier for their developers by
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
358 shipping hardware with RedBoot preinstalled, but even then it is still
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
359 necessary to set up communication between host and target.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
360 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
361 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
362 None of this is applicable to the synthetic target. Instead you can
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
363 just build a normal eCos configuration, link your application with the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
364 resulting libraries, and you end up with an executable that you can
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
365 run directly on your Linux machine or via gdb. A useful side effect of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
366 this is that application development can start before any real
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
367 embedded hardware is actually available.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
368 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
369 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
370 Typically the memory map for a synthetic target application will be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
371 set up such that there is a read-only ROM region containing all the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
372 code and constant data, and a read-write RAM region for the data. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
373 default locations and sizes of these regions depend on the specific
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
374 platform being used for development. Note that the application always
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
375 executes out of ROM: on a real embedded target much of the development
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
376 would involve running RedBoot firmware there, with application code
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
377 and data loaded into RAM; usually this would change for the final
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
378 system; the firmware would be replaced by the eCos application itself,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
379 configured for ROM bootstrap, and it would perform the appropriate
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
380 hardware initialization. Therefore the synthetic target actually
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
381 emulates the behaviour of a final system, not of a development
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
382 environment. In practice this is rarely significant, although having
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
383 the code in read-only memory can help catch some problems in
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
384 application code.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
385 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
386 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
387
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
388 </refentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
389
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
390 <!-- }}} -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
391 <!-- {{{ Running the application -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
392
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
393 <refentry id="synth-running">
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
394 <refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
395 <refentrytitle>Running a Synthetic Target Application</refentrytitle>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
396 </refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
397 <refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
398 <refname>Execution</refname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
399 <refpurpose>Arguments and configuration files</refpurpose>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
400 </refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
401
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
402 <refsect1 id="synth-running-description"><title>Description</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
403 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
404 The procedure for configuring and building eCos and an application for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
405 the synthetic target is the same as for any other eCos target. Once an
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
406 executable has been built it can be run like any Linux program, for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
407 example from a shell prompt,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
408 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
409 <screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
410 $ ecos_hello &lt;options&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
411 </screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
412 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
413 or using gdb:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
414 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
415 <screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
416 $ gdb --nw --quiet --args ecos_hello &lt;options&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
417 (gdb) run
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
418 Starting program: ecos_hello &lt;options&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
419 </screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
420 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
421 By default use of the I/O auxiliary is disabled. If its I/O facilities
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
422 are required then the option <option>--io</option> must be used.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
423 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
424 <note><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
425 In future the default behaviour may change, with the I/O auxiliary
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
426 being started by default. The option <option>--nio</option> can be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
427 used to prevent the auxiliary from being run.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
428 </para></note>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
429 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
430
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
431 <refsect1 id="synth-running-arguments"><title>Command-line Arguments</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
432 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
433 The syntax for running a synthetic target application is:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
434 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
435 <screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
436 $ &lt;ecos_app&gt; [options] [-- [app_options]]
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
437 </screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
438 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
439 Command line options up to the <option>--</option> are passed on to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
440 the I/O auxiliary. Subsequent arguments are not passed on to the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
441 auxiliary, and hence can be used by the eCos application itself. The
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
442 full set of arguments can be accessed through the variables
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
443 <varname>cyg_hal_sys_argc</varname> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
444 <varname>cyg_hal_sys_argv</varname>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
445 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
446 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
447 The following options are accepted as standard:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
448 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
449 <variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
450 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
451 <term><option>--io</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
452 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
453 This option causes the eCos application to spawn the I/O auxiliary
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
454 during HAL initialization. Without this option only limited I/O will
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
455 be available.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
456 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
457 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
458 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
459 <term><option>--nio</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
460 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
461 This option prevents the eCos application from spawning the I/O
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
462 auxiliary. In the current version of the software this is the default.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
463 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
464 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
465 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
466 <term><option>-nw</option>, <option>--no-windows</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
467 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
468 The I/O auxiliary can either provide a graphical user interface, or it
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
469 can run in a text-only mode. The default is to provide the graphical
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
470 interface, but this can be disabled with <option>-nw</option>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
471 Emulation of some devices, for example buttons connected to digital
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
472 inputs, requires the graphical interface.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
473 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
474 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
475 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
476 <term><option>-w</option>, <option>--windows</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
477 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
478 The <option>-w</option> causes the I/O auxiliary to provide a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
479 graphical user interface. This is the default.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
480 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
481 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
482 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
483 <term><option>-v</option>, <option>--version</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
484 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
485 The <option>-v</option> option can be used to determine the version of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
486 the I/O auxiliary being used and where it has been installed. Both the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
487 auxiliary and the eCos application will exit immediately.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
488 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
489 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
490 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
491 <term><option>-h</option>, <option>--help</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
492 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
493 <option>-h</option> causes the I/O auxiliary to list all accepted
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
494 command-line arguments. This happens after all devices have been
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
495 initialized, since the host-side support for some of the devices may
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
496 extend the list of recognised options. After this both the auxiliary
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
497 and the eCos application will exit immediately. This option implies
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
498 <option>-nw</option>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
499 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
500 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
501 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
502 <term><option>-k</option>, <option>--keep-going</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
503 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
504 If an error occurs in the I/O auxiliary while reading in any of the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
505 configuration files or initializing devices, by default both the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
506 auxiliary and the eCos application will exit. The <option>-k</option>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
507 option can be used to make the auxiliary continue in spite of errors,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
508 although obviously it may not be fully functional.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
509 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
510 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
511 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
512 <term><option>-nr</option>, <option>--no-rc</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
513 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
514 Normally the auxiliary processes two <link
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
515 linkend="synth-running-user-config">user configuration files</link>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
516 during startup: <filename>initrc.tcl</filename> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
517 <filename>mainrc.tcl</filename>. This can be suppressed using the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
518 <option>-nr</option> option.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
519 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
520 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
521 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
522 <term><option>-x</option>, <option>--exit</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
523 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
524 When providing a graphical user interface the I/O auxiliary will
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
525 normally continue running even after the eCos application has exited.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
526 This allows the user to take actions such as saving the current
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
527 contents of the main text window. If run with <option>-x</option> then
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
528 the auxiliary will exit as soon the application exits.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
529 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
530 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
531 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
532 <term><option>-nx</option>, <option>--no-exit</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
533 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
534 When the graphical user interface is disabled with
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
535 <option>-nw</option> the I/O auxiliary will normally exit immediately
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
536 when the eCos application exits. Without the graphical frontend there
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
537 is usually no way for the user to interact directly with the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
538 auxiliary, so there is no point in continuing to run once the eCos
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
539 application will no longer request any I/O operations. Specifying the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
540 <option>-nx</option> option causes the auxiliary to continue running
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
541 even after the application has exited.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
542 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
543 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
544 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
545 <term><option>-V</option>, <option>--verbose</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
546 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
547 This option causes the I/O auxiliary to output some additional
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
548 information, especially during initialization.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
549 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
550 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
551 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
552 <term><option>-l &lt;file&gt;</option>, <option>--logfile &lt;file&gt;</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
553 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
554 Much of the output of the eCos application and the I/O auxiliary is
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
555 simple text, for example resulting from eCos
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
556 <function>printf</function> or <function>diag_printf</function> calls.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
557 When running in graphical mode this output goes to a central text
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
558 window, and can be saved to a file or edited via menus. The
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
559 <option>-l</option> can be used to automatically generate an
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
560 additional logfile containing all the text. If graphical
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
561 mode is disabled then by default all the text just goes to the current
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
562 standard output. Specifying <option>-l</option> causes most of the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
563 text to go into a logfile instead, although some messages such as
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
564 errors generated by the auxiliary itself will still go to stdout as
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
565 well.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
566 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
567 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
568 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
569 <term><option>-t &lt;file&gt;</option>, <option>--target &lt;file&gt;</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
570 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
571 During initialization the I/O auxiliary reads in a target definition
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
572 file. This file holds information such as which Linux devices should
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
573 be used to emulate the various eCos devices. The <option>-t</option>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
574 option can be used to specify which target definition should be used
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
575 for the current run, defaulting to <filename>default.tdf</filename>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
576 It is not necessary to include the <filename>.tdf</filename> suffix,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
577 this will be appended automatically if necessary.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
578 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
579 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
580 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
581 <term><option>-geometry &lt;geometry&gt;</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
582 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
583 This option can be used to control the size and position of the main
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
584 window, as per X conventions.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
585 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
586 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
587 </variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
588 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
589 The I/O auxiliary loads support for the various devices dynamically
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
590 and some devices may accept additional command line arguments. Details
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
591 of these can be obtained using the <option>-h</option> option or by
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
592 consulting the device-specific documentation. If an unrecognised
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
593 command line argument is used then a warning will be issued.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
594 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
595 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
596
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
597 <refsect1 id="synth-running-tdf"><title>The Target Definition File</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
598 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
599 The eCos application will want to access devices such as
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
600 <varname>eth0</varname> or <varname>/dev/ser0</varname>. These need to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
601 be mapped on to Linux devices. For example some users may all traffic
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
602 on the eCos <varname>/dev/ser0</varname> serial device to go via the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
603 Linux serial device <varname>/dev/ttyS1</varname>, while ethernet I/O
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
604 for the eCos <varname>eth0</varname> device should be mapped to the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
605 Linux ethertap device <varname>tap3</varname>. Some devices may need
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
606 additional configuration information, for example to limit the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
607 number of packets that should be buffered within the I/O auxiliary.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
608 The target definition file provides all this information.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
609 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
610 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
611 By default the I/O auxiliary will look for a file
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
612 <filename>default.tdf</filename>. An alternative target definition can
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
613 be specified on the command line using <option>-t</option>, for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
614 example:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
615 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
616 <screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
617 $ bridge_app --io -t twineth
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
618 </screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
619 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
620 A <filename>.tdf</filename> suffix will be appended automatically if
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
621 necessary. If a relative pathname is used then the I/O auxiliary will
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
622 search for the target definition file in the current directory, then
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
623 in <filename class="directory">~/.ecos/synth/</filename>, and finally
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
624 in its install location.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
625 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
626 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
627 A typical target definition file might look like this:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
628 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
629 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
630 synth_device console {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
631 # appearance -foreground white -background black
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
632 filter trace {^TRACE:.*} -foreground HotPink1 -hide 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
633 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
634
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
635 synth_device ethernet {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
636 eth0 real eth1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
637 eth1 ethertap tap4 00:01:02:03:FE:06
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
638
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
639 ## Maximum number of packets that should be buffered per interface.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
640 ## Default 16
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
641 #max_buffer 32
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
642
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
643 ## Filters for the various recognised protocols.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
644 ## By default all filters are visible and use standard colours.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
645 filter ether -hide 0
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
646 #filter arp -hide 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
647 #filter ipv4 -hide 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
648 #filter ipv6 -hide 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
649 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
650 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
651 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
652 A target definition file is actually a Tcl script that gets run in the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
653 main interpreter of the I/O auxiliary during initialization. This
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
654 provides a lot of flexibility if necessary. For example the script
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
655 could open a socket to a resource management server of some sort to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
656 determine which hardware facilities are already in use and adapt
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
657 accordingly. Another possibility is to adapt based on <link
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
658 linkend="synth-new-host-args">command line arguments</link>. Users who
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
659 are not familiar with Tcl programming should still be able to edit a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
660 simple target definition file without too much difficulty, using a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
661 mixture of cut'n'paste, commenting or uncommenting various lines, and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
662 making small edits such as changing <literal>tap4</literal> to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
663 <literal>eth2</literal>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
664 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
665 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
666 Each type of device will have its own entry in the target definition
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
667 file, taking the form:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
668 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
669 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
670 synth_device &lt;device type&gt; {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
671 &lt;options&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
672 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
673 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
674 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
675 The documentaton for each synthetic target device should provide
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
676 details of the options available for that device, and often a suitable
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
677 fragment that can be pasted into a target definition file and edited.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
678 There is no specific set of options that a given device will always
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
679 provide. However in practice many devices will use common code
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
680 exported by the main I/O auxiliary, or their implementation will
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
681 involve some re-use of code for an existing device. Hence certain
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
682 types of option are common to many devices.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
683 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
684 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
685 A good example of this is filters, which control the appearance of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
686 text output. The above target definition file defines a filter
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
687 <varname>trace</varname> for output from the eCos application. The
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
688 regular expression will match output from the infrastructure package's
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
689 tracing facilities when <varname>CYGDBG_USE_TRACING</varname> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
690 <varname>CYGDBG_INFRA_DEBUG_TRACE_ASSERT_SIMPLE</varname> are enabled.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
691 With the current settings this output will not be visible by default,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
692 but can be made visible using the menu item <guimenuitem>System
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
693 Filters</guimenuitem>. If made visible the trace output will appear in
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
694 an unusual colour, so users can easily distinguish the trace output
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
695 from other text. All filters accept the following options:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
696 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
697 <variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
698 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
699 <term><option>-hide [0|1]</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
700 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
701 This controls whether or not text matching this filter should be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
702 invisible by default or not. At run-time the visibility of each filter
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
703 can be controlled using the <guimenuitem>System Filters</guimenuitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
704 menu item.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
705 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
706 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
707 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
708 <term><option>-foreground &lt;colour&gt;</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
709 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
710 This specifies the foreground colour for all text matching this
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
711 filter. The colour can be specified using an RGB value such as
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
712 <literal>#F08010</literal>, or a symbolic name such as
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
713 <literal>"light steel blue"</literal>. The X11 utility
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
714 <application>showrgb</application> can be used to find out
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
715 about the available colours.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
716 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
717 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
718 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
719 <term><option>-background &lt;colour&gt;</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
720 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
721 This specifies the background colour for all text matching the filter.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
722 As with <option>-foreground</option> the colour can be specified using
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
723 a symbolic name or an RGB value.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
724 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
725 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
726 </variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
727 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
728 Some devices may create their own subwindows, for example to monitor
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
729 ethernet traffic or to provide additional I/O facilities such as
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
730 emulated LED's or buttons. Usually the target definition file can be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
731 used to control the <link linkend="synth-gui-layout">layout</link> of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
732 these windows.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
733 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
734 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
735 The I/O auxiliary will not normally warn about
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
736 <command>synth_device</command> entries in the target definition file
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
737 for devices that are not actually needed by the current eCos
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
738 application. This makes it easier to use a single file for several
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
739 different applications. However it can lead to confusion if an entry
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
740 is spelled incorrectly and hence does not actually get used. The
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
741 <option>-V</option> command line option can be used to get warnings
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
742 about unused device entries in the target definition file.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
743 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
744 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
745 If the body of a <command>synth_device</command> command contains an
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
746 unrecognised option and the relevant device is in use, the I/O
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
747 auxiliary will always issue a warning about such options.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
748 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
749 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
750
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
751 <refsect1 id="synth-running-user-config"><title>User Configuration Files</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
752 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
753 During initialization the I/O auxiliary will execute two user
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
754 configuration files, <filename>initrc.tcl</filename> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
755 <filename>mainrc.tcl</filename>. It will look for these files in the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
756 directory <filename class="directory">~/.ecos/synth/</filename>. If
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
757 that directory does not yet exist it will be created and populated
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
758 with initial dummy files.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
759 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
760 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
761 Both of these configuration files are Tcl scripts and will be run in
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
762 the main interpreter used by the I/O auxiliary itself. This means that
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
763 they have full access to the internals of the auxiliary including the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
764 various Tk widgets, and they can perform file or socket I/O if
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
765 desired. The section <xref linkend="synth-new-host"> contains
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
766 information about the facilities available on the host-side for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
767 writing new device drivers, and these can also be used in the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
768 initialization scripts.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
769 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
770 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
771 The <filename>initrc.tcl</filename> script is run before the auxiliary
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
772 has processed any requests from the eCos application, and hence before
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
773 any devices have been instantiated. At this point the generic
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
774 command-line arguments has been processed, the target definition file
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
775 has been read in, and the hooks functionality has been initialized. If
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
776 running in graphical mode the main window will have been created, but
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
777 has been withdrawn from the screen to allow new widgets to be added
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
778 without annoying screen flicker. A typical
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
779 <filename>initrc.tcl</filename> script could add some menu or toolbar
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
780 options, or install a hook function that will be run when the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
781 eCos application exits.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
782 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
783 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
784 The <filename>mainrc.tcl</filename> script is run after eCos has
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
785 performed all its device initialization and after C++ static
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
786 constructors have run, and just before the call to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
787 <function>cyg_start</function> which will end up transferring control
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
788 to the application itself. A typical <filename>mainrc.tcl</filename>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
789 script could look at what interrupt vectors have been allocated to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
790 which devices and create a little monitor window that shows interrupt
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
791 activity.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
792 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
793 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
794
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
795 <refsect1 id="synth-running-session"><title>Session Information</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
796 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
797 When running in graphical mode, the I/O auxiliary will read in a file
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
798 <filename>~/.ecos/synth/guisession</filename> containing session
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
799 information. This file should not normally be edited manually, instead
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
800 it gets updated automatically when the auxiliary exits. The purpose of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
801 this file is to hold configuration options that are manipulated via
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
802 the graphical interface, for example which browser should be used to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
803 display online help.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
804 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
805 <warning><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
806 GUI session functionality is not yet available in the current release.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
807 When that functionality is fully implemented it is possible that some
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
808 target definition file options may be removed, to be replaced by
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
809 graphical editing via a suitable preferences dialog, with the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
810 current settings saved in the session file.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
811 </para></warning>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
812 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
813
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
814 </refentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
815
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
816 <!-- }}} -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
817 <!-- {{{ ecosynth user interface -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
818
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
819 <refentry id="synth-gui">
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
820 <refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
821 <refentrytitle>The I/O Auxiliary's User Interface</refentrytitle>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
822 </refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
823 <refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
824 <refname>User Interface</refname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
825 <refpurpose>Controlling the I/O Auxiliary</refpurpose>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
826 </refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
827
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
828 <refsect1 id="synth-gui-description"><title>Description</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
829 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
830 The synthetic target auxiliary is designed to support both extensions
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
831 and user customization. Support for the desired devices is dynamically
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
832 loaded, and each device can extend the user interface. For example it
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
833 is possible for a device to add menu options, place new buttons on the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
834 toolbar, create its own sub-window within the overall layout, or even
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
835 create entire new toplevel windows. These subwindows or toplevels
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
836 could show graphs of activity such as interrupts or packets being
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
837 transferred. They could also allow users to interact with the eCos
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
838 application, for example by showing a number of buttons which will be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
839 mapped on to digital inputs in the eCos application. Different
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
840 applications will have their own I/O requirements, changing the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
841 host-side support files that get loaded and that may modify the user
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
842 interface. The I/O auxiliary also reads in user configuration scripts
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
843 which can enhance the interface in the same way. Therefore the exact
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
844 user interface will depend on the user and on the eCos application
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
845 being run. However the overall layout is likely to remain the same.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
846 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
847 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
848 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
849 <imageobject>
991
fcb7cbb964ae * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 709
diff changeset
850 <imagedata fileref="screen_main.png" Scalefit=1 Align="Center">
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
851 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
852 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
853 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
854 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
855 The title bar identifies the window as belonging to an eCos synthetic
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
856 target application and lists both the application name and its process
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
857 id. The latter is especially useful if the application was started
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
858 directly from a shell prompt and the user now wants to attach a gdb
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
859 session. The window has a conventional menu bar with the usual
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
860 entries, plus a toolbar with buttons for common operations such as cut
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
861 and paste. Balloon help is supported.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
862 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
863 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
864 There is a central <link linkend="synth-gui-text">text window</link>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
865 possibly surrounded by various sub-windows for various devices. For
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
866 example there could be a row of emulated LED's above the text window,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
867 and monitors of ethernet traffic and interrupt activity on the right.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
868 At the bottom of the window is a status line, including a small
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
869 animation that shows whether or not the eCos application is still
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
870 running.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
871 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
872 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
873
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
874 <refsect1 id="synth-gui-menus"><title>Menus and the Toolbar</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
875 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
876 Usually there will be four menus on the menu bar:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
877 <guimenu>File</guimenu>, <guimenu>Edit</guimenu>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
878 <guimenu>View</guimenu> and <guimenu>Help</guimenu>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
879 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
880 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
881 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
882 <imageobject>
991
fcb7cbb964ae * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 709
diff changeset
883 <imagedata fileref="menu_file.png" Scalefit=1 Align="Center">
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
884 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
885 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
886 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
887 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
888 On the <guimenu>File</guimenu> menu there are three entries related to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
889 saving the current contents of the central text window.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
890 <guimenuitem>Save</guimenuitem> is used to save the currently visible
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
891 contents of the text window. Any text that is hidden because of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
892 filters will not be written to the savefile. If there has been a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
893 previous <guimenuitem>Save</guimenuitem> or <guimenuitem>Save
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
894 As</guimenuitem> operation then the existing savefile will be re-used,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
895 otherwise the user will be asked to select a suitable file.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
896 <guimenuitem>Save As</guimenuitem> also saves just the currently
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
897 visible contents but will always prompt the user for a filename.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
898 <guimenuitem>Save All</guimenuitem> can be used to save the full
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
899 contents of the text window, including any text that is currently
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
900 hidden. It will always prompt for a new filename, to avoid confusion
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
901 with partial savefiles.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
902 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
903 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
904 Usually the eCos application will be run from inside gdb or from a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
905 shell prompt. Killing off the application while it is being debugged
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
906 in a gdb session is not a good idea, it would be better to use gdb's
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
907 own <command>kill</command> command. Alternatively the eCos
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
908 application itself can use the <function>CYG_TEST_EXIT</function> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
909 <filename>cyg_hal_sys_exit</filename> functionality. However it is
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
910 possible to terminate the application from the I/O auxiliary using
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
911 <guimenuitem>Kill eCos</guimenuitem>. A clean shutdown will be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
912 attempted, but that can fail if the application is currently halted
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
913 inside gdb or if it has crashed completely. As a last resort
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
914 <constant>SIGKILL</constant> will be used.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
915 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
916 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
917 When operating in graphical mode the I/O auxiliary will normally
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
918 continue to run even after the eCos application has exited. This
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
919 allows the user to examine the last few lines of output, and perhaps
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
920 perform actions such as saving the output to a file. The
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
921 <guimenuitem>Exit</guimenuitem> menu item can be used to shut down the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
922 auxiliary. Note that this behaviour can be changed with command line
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
923 arguments <link
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
924 linkend="synth-running-arguments"><option>--exit</option></link> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
925 <link
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
926 linkend="synth-running-arguments"><option>--no-exit</option></link>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
927 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
928 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
929 If <guimenuitem>Exit</guimenuitem> is used while the eCos application
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
930 is still running then the I/O auxiliary will first attempt to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
931 terminate the application cleanly, and then exit.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
932 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
933 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
934 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
935 <imageobject>
991
fcb7cbb964ae * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 709
diff changeset
936 <imagedata fileref="menu_edit.png" Scalefit=1 Align="Center">
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
937 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
938 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
939 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
940 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
941 The <guimenu>Edit</guimenu> menu contains the usual entries for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
942 text manipulation: <guimenuitem>Cut</guimenuitem>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
943 <guimenuitem>Copy</guimenuitem>, <guimenuitem>Paste</guimenuitem>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
944 <guimenuitem>Clear</guimenuitem> and <guimenuitem>Select
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
945 All</guimenuitem>. These all operate on the central text window. By
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
946 default this window cannot be edited so the cut, paste and clear
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
947 operations are disabled. If the user wants to edit the contents of the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
948 text window then the <guimenuitem>Read Only</guimenuitem> checkbutton
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
949 should be toggled.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
950 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
951 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
952 The <guimenuitem>Preferences</guimenuitem> menu item brings up a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
953 miscellaneous preferences dialog. One of the preferences relates to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
954 online help: the I/O auxiliary does not currently have a built-in html
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
955 viewer; instead it will execute an external browser of some sort. With
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
956 the example settings shown, the I/O auxiliary will first attempt to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
957 interact with an existing mozilla session. If that fails it will try
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
958 to run a new mozilla instance, or as a last result use the Gnome help
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
959 viewer.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
960 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
961 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
962 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
963 <imageobject>
991
fcb7cbb964ae * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 709
diff changeset
964 <imagedata fileref="preferences.png" Scalefit=1 Align="Center">
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
965 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
966 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
967 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
968 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
969 The <guimenu>View</guimenu> menu contains the <guimenuitem>System
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
970 Filters</guimenuitem> entry, used to edit the settings for the current
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
971 <link linkend="synth-gui-text">filters</link>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
972 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
973 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
974 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
975 <imageobject>
991
fcb7cbb964ae * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 709
diff changeset
976 <imagedata fileref="menu_view.png" Scalefit=1 Align="Center">
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
977 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
978 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
979 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
980 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
981 The <guimenu>Help</guimenu> menu can be used to activate online help
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
982 for eCos generally, for the synthetic target as a whole, and for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
983 specific devices supported by the generic target. The Preferences
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
984 dialog can be used to select the browser that will be used.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
985 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
986 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
987 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
988 <imageobject>
991
fcb7cbb964ae * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 709
diff changeset
989 <imagedata fileref="menu_help.png" Scalefit=1 Align="Center">
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
990 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
991 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
992 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
993 <note><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
994 At the time of writing there is no well-defined toplevel index file
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
995 for all eCos documentation. Hence the relevant menu item is disabled.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
996 Documentation for the synthetic target and the supported devices
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
997 is stored as part of the package itself so can usually be found fairly
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
998 easily. It may be necessary to set the <envar>ECOS_REPOSITORY</envar>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
999 environment variable.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1000 </para></note>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1001
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1002 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1003
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1004 <refsect1 id="synth-gui-text"><title>The Main Text Window</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1005 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1006 The central text window holds the console output from the eCos
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1007 application: the screen shot above shows DHCP initialization data from
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1008 the TCP/IP stack, and some output from the <function>main</function>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1009 thread at the bottom. Some devices can insert text of their own, for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1010 example the ethernet device support can be configured to show details
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1011 of incoming and outgoing packets. Mixing the output from the eCos
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1012 application and the various devices can make it easier to understand
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1013 the order in which events occur.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1014 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1015 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1016 The appearance of text from different sources can be controlled by
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1017 means of filters, and it is also possible to hide some of the text.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1018 For example, if tracing is enabled in the eCos configuration then the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1019 trace output can be given its own colour scheme, making it stand out
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1020 from the rest of the output. In addition the trace output is generally
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1021 voluminous so it can be hidden by default, made visible only to find
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1022 out more about what was happening when a particular problem occurred.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1023 Similarly the ethernet device support can output details of the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1024 various packets being transferred, and using a different background
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1025 colour for this output again makes it easier to distinguish from
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1026 console output.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1027 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1028 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1029 The default appearance for most filters is controlled via the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1030 <link linkend="synth-running-tdf">target definition file</link>. An
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1031 example entry might be:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1032 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1033 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1034 filter trace {^TRACE:.*} -foreground HotPink1 -hide 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1035 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1036 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1037 The various colours and the hide flag for each filter can be changed
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1038 at run-time, using the <guimenuitem>System Filters</guimenuitem> item
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1039 on the <guimenu>View</guimenu> menu. This will bring up a dialog like
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1040 the following:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1041 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1042 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1043 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1044 <imageobject>
991
fcb7cbb964ae * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 709
diff changeset
1045 <imagedata fileref="filters.png" Scalefit=1 Align="Center">
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1046 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1047 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1048 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1049 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1050 It should be noted that the text window is line-oriented, not
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1051 character-oriented. If an eCos application sends a partial line of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1052 text then that will remain buffered until a newline character is
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1053 received, rather than being displayed immediately. This avoids
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1054 confusion when there is concurrent output from several sources.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1055 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1056 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1057 By default the text window is read-only. This means it will not allow
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1058 cut, paste and clear operations, and keyboard input will be ignored.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1059 The <guimenu>Edit</guimenu> menu has a checkbutton <guimenuitem>Read
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1060 Only</guimenuitem> which can be toggled to allow write operations. For
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1061 example, a user could type in a reminder of what was happening at this
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1062 time, or paste in part of a gdb session. Such keyboard input does not
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1063 get forwarded to the eCos application: if the latter requires keyboard
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1064 input then that should happen via a separate keyboard device.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1065 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1066 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1067
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1068 <refsect1 id="synth-gui-layout"><title>Positioning Optional Windows</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1069 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1070 Some devices may create their own subwindows, for example to monitor
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1071 ethernet traffic or to provide additional I/O facilities such as
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1072 emulated LED's or buttons. Usually the target definition file can be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1073 used to control the <link linkend="synth-gui-layout">layout</link> of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1074 these windows. This requires an understanding of the overall layout of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1075 the display.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1076 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1077 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1078 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1079 <imageobject>
991
fcb7cbb964ae * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 709
diff changeset
1080 <imagedata fileref="layout.png" Scalefit=1 Align="Center">
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1081 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1082 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1083 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1084 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1085 Subwindows are generally packed in one of eight frames surrounding the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1086 central text window: <varname>.main.nw</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1087 <varname>.main.n</varname>, <varname>.main.ne</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1088 <varname>.main.w</varname>, <varname>.main.e</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1089 <varname>.main.sw</varname>, <varname>.main.s</varname>, and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1090 <varname>.main.se</varname>. To position a row of LED's above the text
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1091 window and towards the left, a target definition file could contain an
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1092 entry such as:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1093 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1094 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1095 synth_device led {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1096 pack -in .main.n -side left
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1097 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1098 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1099 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1100 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1101 Similarly, to put a traffic monitor window on the right of the text
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1102 window would involve something like:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1103 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1104 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1105 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1106 monitor_pack -in .main.e -side bottom
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1107 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1108 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1109 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1110 Often it will be sufficient to specify a container frame and one of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1111 <constant>left</constant>, <constant>right</constant>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1112 <constant>top</constant> or <constant>bottom</constant>. Full control
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1113 over the positioning requires an understanding of Tcl/Tk and in
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1114 particular the packing algorithm, and an appropriate reference work
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1115 should be consulted.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1116 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1117 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1118
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1119 <refsect1 id="synth-gui-global-config"><title>Global Settings</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1120 <note><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1121 This section still to be written - it should document the interaction
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1122 between X resources and ecosynth, and how users can control settings
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1123 such as the main foreground and background colours.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1124 </para></note>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1125 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1126
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1127 </refentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1128
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1129 <!-- }}} -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1130 <!-- {{{ The console device -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1131
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1132 <refentry id="synth-console">
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1133 <refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1134 <refentrytitle>The Console Device</refentrytitle>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1135 </refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1136 <refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1137 <refname>The console device </refname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1138 <refpurpose>Show output from the eCos application</refpurpose>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1139 </refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1140
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1141 <refsect1 id="synth-console-description"><title>Description</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1142 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1143 The eCos application can generate text output in a variety of ways,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1144 including calling <function>printf</function> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1145 <function>diag_printf</function>. When the I/O auxiliary is enabled
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1146 the eCos startup code will instantiate a console device to process all
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1147 such output. If operating in text mode the output will simply go to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1148 standard output, or to a logfile if the <option>-l</option> command
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1149 line option is specified. If operating in graphical mode the output
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1150 will go to the central text window, and optionally to a logfile as
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1151 well. In addition it is possible to control the appearance of the main
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1152 text via the target definition file, and to install extra filters for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1153 certain types of text.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1154 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1155 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1156 It should be noted that the console device is line-oriented, not
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1157 character-oriented. This means that outputting partial lines is not
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1158 supported, and some functions such as <function>fflush</function> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1159 <function>setvbuf</function> will not operate as expected. This
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1160 limitation prevents much possible confusion when using filters to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1161 control the appearance of the text window, and has some performance
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1162 benefits - especially when the eCos application generates a great deal
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1163 of output such as when tracing is enabled. For most applications this
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1164 is not a problem, but it is something that developers should be aware
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1165 of.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1166 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1167 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1168 The console device is output-only, it does not provide any support for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1169 keyboard input. If the application requires keyboard input then that
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1170 should be handled by a separate eCos device package and matching
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1171 host-side code.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1172 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1173 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1174
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1175 <refsect1 id="synth-console-install"><title>Installation</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1176 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1177 The eCos side of the console device is implemented by the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1178 architectural HAL itself, in the source file
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1179 <filename>synth_diag.c</filename>, rather than in a separate device
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1180 package. Similarly the host-side implementation,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1181 <function>console.tcl</function>, is part of the architectural HAL's
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1182 host-side support. It gets installed automatically alongside the I/O
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1183 auxiliary itself, so no separate installation procedure is required.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1184 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1185 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1186
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1187 <refsect1 id="synth-console-tdf"><title>Target Definition File</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1188 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1189 The <link linkend="synth-running-tdf">target definition file</link>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1190 can contain a number of entries related to the console device. These
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1191 are all optional, they only control the appearance of text output. If
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1192 such control is desired then the relevant options should appear in the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1193 body of a <command>synth_device</command> entry:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1194 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1195 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1196 synth_device console {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1197 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1198 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1199 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1200 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1201 The first option is <command>appearance</command>, used to control the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1202 appearance of any text generated by the eCos application that does not
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1203 match one of the installed filters. This option takes the same
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1204 argument as any other filter, for example:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1205 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1206 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1207 synth_device console {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1208 appearance -foreground white -background black
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1209 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1210 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1211 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1212 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1213 Any number of additional filters can be created with a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1214 <command>filter</command> option, for example:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1215 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1216 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1217 synth_device console {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1218 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1219 filter trace {^TRACE:.*} -foreground HotPink1 -hide 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1220 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1221 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1222 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1223 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1224 The first argument gives the new filter a name which will be used in
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1225 the <link linkend="synth-gui-text">filters dialog</link>. Filter names
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1226 should be unique. The second argument is a Tcl regular expression. The
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1227 console support will match each line of eCos output against this
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1228 regular expression, and if a match is found then the filter will be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1229 used for this line of text. The above example matches any line of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1230 output that begins with <literal>TRACE:</literal>, which corresponds
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1231 to the eCos infrastructure's tracing facilities. The remaining options
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1232 control the desired appearance for matched text. If some eCos output
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1233 matches the regular expressions for several different filters then
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1234 only the first match will be used.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1235 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1236 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1237
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1238 <refsect1 id="synth-console-target-config"><title>Target-side
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1239 Configuration Options</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1240 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1241 There are no target-side configuration options related to the console
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1242 device.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1243 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1244 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1245
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1246 <refsect1 id="synth-console-arguments"><title>Command Line Arguments</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1247 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1248 The console device does not use any command-line arguments.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1249 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1250 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1251
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1252 <refsect1 id="synth-console-hooks"><title>Hooks</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1253 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1254 The console device does not provide any hooks.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1255 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1256 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1257
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1258 <refsect1><title>Additional Tcl Procedures</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1259 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1260 The console device does not provide any additional Tcl procedures that
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1261 can be used by other scripts.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1262 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1263 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1264
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1265 </refentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1266
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1267 <!-- }}} -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1268 <!-- {{{ System calls -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1269
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1270 <refentry id="synth-syscalls">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1271 <refmeta>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1272 <refentrytitle>System Calls</refentrytitle>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1273 </refmeta>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1274
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1275 <refnamediv>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1276 <refname>cyg_hal_sys_xyz</refname>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1277 <refpurpose>Access Linux system facilities</refpurpose>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1278 </refnamediv>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1279
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1280 <refsynopsisdiv>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1281 <funcsynopsis>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1282 <funcsynopsisinfo>
709
40890868764a * doc/overview.gif, doc/overview.fig: renamed to
jlarmour
parents: 332
diff changeset
1283 #include &lt;cyg/hal/hal_io.h&gt;
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1284 </funcsynopsisinfo>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1285 <funcprototype>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1286 <funcdef>int <function>cyg_hal_sys_xyzzy</function></funcdef>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1287 <varargs>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1288 </funcprototype>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1289 </funcsynopsis>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1290 </refsynopsisdiv>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1291
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1292 <refsect1 id="synth-syscalls-description"><title>Description</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1293 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1294 On a real embedded target eCos interacts with the hardware by peeking
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1295 and poking various registers, manipulating special regions of memory,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1296 and so on. The synthetic target does not access hardware directly.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1297 Instead I/O and other operations are emulated by making appropriate
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1298 Linux system calls. The HAL package exports a number of functions
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1299 which allow other packages, or even application code, to make these
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1300 same system calls. However this facility must be used with care: any
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1301 code which calls, for example, <function>cyg_hal_sys_write</function>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1302 will only ever run on the synthetic target; that functionality is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1303 obviously not provided on any real hardware because there is no
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1304 underlying Linux kernel to implement it.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1305 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1306 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1307 The synthetic target only provides a subset of the available system
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1308 calls, specifically those calls which have proved useful to implement
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1309 I/O emulation. This subset can be extended fairly easily if necessary.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1310 All of the available calls, plus associated data structures and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1311 macros, are defined in the header file <filename
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1312 class="headerfile">cyg/hal/hal_io.h</filename>. There is a simple
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1313 convention: given a Linux system call such as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1314 <function>open</function>, the synthetic target will prefix
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1315 <literal>cyg_hal_sys</literal> and provide a function with that name.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1316 The second argument to the <function>open</function> system call is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1317 a set of flags such as <constant>O_RDONLY</constant>, and the header
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1318 file will define a matching constant
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1319 <constant>CYG_HAL_SYS_O_RDONLY</constant>. There are also data
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1320 structures such as <structname>cyg_hal_sys_sigset_t</structname>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1321 matching the Linux data structure <structname>sigset_t</structname>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1322 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1323 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1324 In most cases the functions provided by the synthetic target behave as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1325 per the documentation for the Linux system calls, and section 2 of the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1326 Linux man pages can be consulted for more information. There is one
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1327 important difference: typically the documentation will say that a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1328 function returns <literal>-1</literal> to indicate an error, with the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1329 actual error code held in <varname>errno</varname>; the actual
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1330 underlying system call and hence the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1331 <function>cyg_hal_sys_xyz</function> provided by eCos instead returns
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1332 a negative number to indicate an error, with the absolute value of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1333 that number corresponding to the error code; usually it is the C
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1334 library which handles this and manipulates errno, but of course
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1335 synthetic target applications are not linked with that Linux library.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1336 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1337 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1338 However, there are some exceptions. The Linux kernel has evolved over
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1339 the years, and some of the original system call interfaces are no
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1340 longer appropriate. For example the original
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1341 <function>select</function> system call has been superseded by
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1342 <function>_newselect</function>, and that is what the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1343 <function>select</function> function in the C library actually uses.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1344 The old call is still available to preserve binary compatibility but,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1345 like the C library, eCos makes use of the new one because it provides
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1346 the appropriate functionality. In an attempt to reduce confusion the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1347 eCos function is called <function>cyg_hal_sys__newselect</function>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1348 in other words it matches the official system call naming scheme. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1349 authoritive source of information on such matters is the Linux kernel
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1350 sources themselves, and especially its header files.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1351 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1352 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1353 eCos packages and applications should never
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1354 <literal>#include</literal> Linux header files directly. For example,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1355 doing a <literal>#include&nbsp;&lt;/usr/include/fcntl.h&gt;</literal>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1356 to access additional macros or structure definitions, or alternatively
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1357 manipulating the header file search path, will lead to problems
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1358 because the Linux header files are likely to duplicate and clash with
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1359 definitions in the eCos headers. Instead the appropriate functionality
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1360 should be extracted from the Linux headers and moved into either
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1361 <filename class="headerfile">cyg/hal/hal_io.h</filename> or into
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1362 application code, with suitable renaming to avoid clashes with eCos
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1363 names. Users should be aware that large-scale copying may involve
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1364 licensing complications.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1365 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1366 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1367 Adding more system calls is usually straightforward and involves
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1368 adding one or more lines to the platform-specific file in the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1369 appropriate platform HAL, for example
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1370 <filename>syscall-i386-linux-1.0.S</filename>. However it is necessary
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1371 to do some research first about the exact interface implemented by the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1372 system call, because of issues such as old system calls that have been
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1373 superseded. The required information can usually be found fairly
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1374 easily by searching through the Linux kernel sources and possibly the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1375 GNU C library sources.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1376 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1377 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1378 </refentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1379
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1380 <!-- }}} -->
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1381 <!-- {{{ New devices - target-side -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1382
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1383 <refentry id="synth-new-target">
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1384 <refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1385 <refentrytitle>Writing New Devices - target</refentrytitle>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1386 </refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1387 <refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1388 <refname>Writing New Devices</refname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1389 <refpurpose>extending the synthetic target, target-side</refpurpose>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1390 </refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1391
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1392 <refsynopsisdiv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1393 <funcsynopsis>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1394 <funcsynopsisinfo>
709
40890868764a * doc/overview.gif, doc/overview.fig: renamed to
jlarmour
parents: 332
diff changeset
1395 #include &lt;cyg/hal/hal_io.h&gt;
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1396 </funcsynopsisinfo>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1397
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1398 <funcprototype>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1399 <funcdef>int <function>synth_auxiliary_instantiate</function></funcdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1400 <paramdef>const char* <parameter>package</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1401 <paramdef>const char* <parameter>version</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1402 <paramdef>const char* <parameter>device</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1403 <paramdef>const char* <parameter>instance</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1404 <paramdef>const char* <parameter>data</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1405 </funcprototype>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1406 <funcprototype>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1407 <funcdef>void <function>synth_auxiliary_xchgmsg</function></funcdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1408 <paramdef>int <parameter>device_id</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1409 <paramdef>int <parameter>request</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1410 <paramdef>int <parameter>arg1</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1411 <paramdef>int <parameter>arg2</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1412 <paramdef>const unsigned char* <parameter>txdata</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1413 <paramdef>int <parameter>txlen</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1414 <paramdef>int* <parameter>reply</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1415 <paramdef>unsigned char* <parameter>rxdata</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1416 <paramdef>int* <parameter>rxlen</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1417 <paramdef>int <parameter>max_rxlen</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1418 </funcprototype>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1419 </funcsynopsis>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1420 </refsynopsisdiv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1421
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1422 <refsect1 id="synth-new-target-description"><title>Description</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1423 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1424 In some ways writing a device driver for the synthetic target is very
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1425 similar to writing one for a real target. Obviously it has to provide
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1426 the standard interface for that class of device, so for example an
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1427 ethernet device has to provide <function>can_send</function>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1428 <function>send</function>, <function>recv</function> and similar
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1429 functions. Many devices will involve interrupts, so the driver
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1430 contains ISR and DSR functions and will call
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1431 <function>cyg_drv_interrupt_create</function>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1432 <function>cyg_drv_interrupt_acknowledge</function>, and related
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1433 functions.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1434 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1435 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1436 In other ways writing a device driver for the synthetic target is very
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1437 different. Usually the driver will not have any direct access to the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1438 underlying hardware. In fact for some devices the I/O may not involve
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1439 real hardware, instead everything is emulated by widgets on the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1440 graphical display. Therefore the driver cannot just peek and poke
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1441 device registers, instead it must interact with host-side code by
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1442 exchanging message. The synthetic target HAL provides a function
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1443 <function>synth_auxiliary_xchgmsg</function> for this purpose.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1444 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1445 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1446 Initialization of a synthetic target device driver is also very
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1447 different. On real targets the device hardware already exists when the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1448 driver's initialization routine runs. On the synthetic target it is
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1449 first necessary to instantiate the device inside the I/O auxiliary, by
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1450 a call to <function>synth_auxiliary_instantiate</function>. That
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1451 function performs a special message exchange with the I/O auxiliary,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1452 causing it to load a Tcl script for the desired type of device and run
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1453 an instantiation procedure within that script.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1454 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1455 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1456 Use of the I/O auxiliary is optional: if the user does not specify
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1457 <option>--io</option> on the command line then the auxiliary will not
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1458 be started and hence most I/O operations will not be possible. Device
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1459 drivers should allow for this possibility, for example by just
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1460 discarding any data that gets written. The HAL exports a flag
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1461 <varname>synth_auxiliary_running</varname> which should be checked.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1462 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1463 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1464
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1465 <refsect1 id="synth-new-target-instantiate"><title>Instantiating a Device</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1466 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1467 Device instantiation should happen during the C++ prioritized static
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1468 constructor phase of system initialization, before control switches to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1469 <function>cyg_user_start</function> and general application code. This
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1470 ensures that there is a clearly defined point at which the I/O
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1471 auxiliary knows that all required devices have been loaded. It can
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1472 then perform various consistency checks and clean-ups, run the user's
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1473 <filename>mainrc.tcl</filename> script, and make the main window
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1474 visible.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1475 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1476 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1477 For standard devices generic eCos I/O code will call the device
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1478 initialization routines at the right time, iterating through the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1479 <varname>DEVTAB</varname> table in a static constructor. The same
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1480 holds for network devices and file systems. For more custom devices
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1481 code like the following can be used:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1482 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1483 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1484 #include &lt;cyg/infra/cyg_type.h&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1485 class mydev_init {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1486 public:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1487 mydev_init() {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1488 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1489 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1490 };
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1491 static mydev_init mydev_init_object CYGBLD_ATTRIB_INIT_PRI(CYG_INIT_IO);
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1492 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1493 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1494 Some care has to be taken because the object
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1495 <varname>mydev_init_object</varname> will typically not be referenced
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1496 by other code, and hence may get eliminated at link-time. If the code
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1497 is part of an eCos package then problems can be avoided by putting the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1498 relevant file in <filename>libextras.a</filename>:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1499 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1500 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1501 cdl_package CYGPKG_DEVS_MINE {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1502 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1503 compile -library=libextras.a init.cxx
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1504 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1505 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1506 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1507 For devices inside application code the same can be achieved by
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1508 linking the relevant module as a <filename>.o</filename> file rather
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1509 than putting it in a <filename>.a</filename> library.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1510 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1511 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1512 In the device initialization routine the main operation is a call to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1513 <function>synth_auxiliary_instantiate</function>. This takes five
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1514 arguments, all of which should be strings:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1515 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1516 <variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1517 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1518 <term><varname>package</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1519 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1520 For device drivers which are eCos packages this should be a directory
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1521 path relative to the eCos repository, for example
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1522 <literal>devs/eth/synth/ecosynth</literal>. This will allow the I/O
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1523 auxiliary to find the various host-side support files for this package
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1524 within the install tree. If the device is application-specific and not
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1525 part of an eCos package then a NULL pointer can be used, causing the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1526 I/O auxiliary to search for the support files in the current directory
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1527 and then in <filename class="directory">~/.ecos/synth</filename>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1528 instead.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1529 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1530 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1531 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1532 <term><varname>version</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1533 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1534 For eCos packages this argument should be the version of the package
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1535 that is being used, for example <literal>current</literal>. A simple
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1536 way to get this version is to use the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1537 <function>SYNTH_MAKESTRING</function> macro on the package name.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1538 If the device is application-specific then a NULL pointer should be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1539 used.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1540 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1541 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1542 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1543 <term><varname>device</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1544 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1545 This argument specifies the type of device being instantiated, for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1546 example <literal>ethernet</literal>. More specifically the I/O
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1547 auxiliary will append a <filename>.tcl</filename> suffix, giving
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1548 the name of a Tcl script that will handle all I/O requests for the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1549 device. If the application requires several instances of a type
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1550 of device then the script will only be loaded once, but the script
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1551 will contain an instantiation procedure that will be called for each
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1552 device instance.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1553 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1554 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1555 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1556 <term><varname>instance</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1557 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1558 If it is possible to have multiple instances of a device then this
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1559 argument identifies the particular instance, for example
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1560 <literal>eth0</literal> or <literal>eth1</literal>. Otherwise a NULL
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1561 pointer can be used.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1562 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1563 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1564 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1565 <term><varname>data</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1566 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1567 This argument can be used to pass additional initialization data from
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1568 eCos to the host-side support. This is useful for devices where eCos
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1569 configury must control certain aspects of the device, rather than
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1570 host-side configury such as the target definition file, because eCos
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1571 has compile-time dependencies on some or all of the relevant options.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1572 An example might be an emulated frame buffer where eCos has been
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1573 statically configured for a particular screen size, orientation and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1574 depth. There is no fixed format for this string, it will be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1575 interpreted only by the device-specific host-side Tcl script. However
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1576 the string length should be limited to a couple of hundred bytes to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1577 avoid possible buffer overflow problems.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1578 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1579 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1580 </variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1581 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1582 Typical usage would look like:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1583 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1584 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1585 if (!synth_auxiliary_running) {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1586 return;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1587 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1588 id = synth_auxiliary_instantiate("devs/eth/synth/ecosynth",
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1589 SYNTH_MAKESTRING(CYGPKG_DEVS_ETH_ECOSYNTH),
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1590 "ethernet",
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1591 "eth0",
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1592 (const char*) 0);
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1593 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1594 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1595 The return value will be a device identifier which can be used for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1596 subsequent calls to <function>synth_auxiliary_xchgmsg</function>. If
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1597 the device could not be instantiated then <literal>-1</literal> will
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1598 be returned. It is the responsibility of the host-side software to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1599 issue suitable diagnostics explaining what went wrong, so normally the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1600 target-side code should fail silently.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1601 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1602 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1603 Once the desired device has been instantiated, often it will be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1604 necessary to do some additional initialization by a message exchange.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1605 For example an ethernet device might need information from the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1606 host-side about the MAC address, the <link
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1607 linkend="synth-new-target-interrupts">interrupt vector</link>, and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1608 whether or not multicasting is supported.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1609 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1610 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1611
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1612 <refsect1 id="synth-new-target-xchgmsg"><title>Communicating with a Device</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1613 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1614 Once a device has been instantiated it is possible to perform I/O by
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1615 sending messages to the appropriate Tcl script running inside the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1616 auxiliary, and optionally getting back replies. I/O operations are
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1617 always initiated by the eCos target-side, it is not possible for the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1618 host-side software to initiate data transfers. However the host-side
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1619 can raise interrupts, and the interrupt handler inside the target can
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1620 then exchange one or more messages with the host.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1621 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1622 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1623 There is a single function to perform I/O operations,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1624 <function>synth_auxiliary_xchgmsg</function>. This takes the following
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1625 arguments:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1626 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1627 <variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1628 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1629 <term><varname>device_id</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1630 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1631 This should be one of the identifiers returned by a previous
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1632 call to <function>synth_auxiliary_instantiate</function>, specifying the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1633 particular device which should perform some I/O.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1634 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1635 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1636 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1637 <term><varname>request</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1638 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1639 Request are just signed 32-bit integers that identify the particular
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1640 I/O operation being requested. There is no fixed set of codes, instead
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1641 each type of device can define its own.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1642 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1643 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1644 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1645 <term><varname>arg1</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1646 <term><varname>arg2</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1647 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1648 For some requests it is convenient to pass one or two additional
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1649 parameters alongside the request code. For example an ethernet device
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1650 could define a multicast-all request, with <varname>arg1</varname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1651 controlling whether this mode should be enabled or disabled. Both
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1652 <varname>arg1</varname> and <varname>arg2</varname> should be signed
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1653 32-bit integers, and their values are interpreted only by the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1654 device-specific Tcl script.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1655 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1656 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1657 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1658 <term><varname>txdata</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1659 <term><varname>txlen</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1660 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1661 Some I/O operations may involve sending additional data, for example
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1662 an ethernet packet. Alternatively a control operation may require many
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1663 more parameters than can easily be encoded in <varname>arg1</varname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1664 and <varname>arg2</varname>, so those parameters have to be placed in
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1665 a suitable buffer and extracted at the other end.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1666 <varname>txdata</varname> is an arbitrary buffer of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1667 <varname>txlen</varname> bytes that should be sent to the host-side.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1668 There is no specific upper bound on the number of bytes that can be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1669 sent, but usually it is a good idea to allocate the transmit buffer
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1670 statically and keep transfers down to at most several kilobytes.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1671 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1672 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1673 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1674 <term><varname>reply</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1675 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1676 If the host-side is expected to send a reply message then
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1677 <varname>reply</varname> should be a pointer to an integer variable
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1678 and will be updated with a reply code, a simple 32-bit integer. The
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1679 synthetic target HAL code assumes that the host-side and target-side
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1680 agree on the protocol being used: if the host-side will not send a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1681 reply to this message then the <varname>reply</varname> argument
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1682 should be a NULL pointer; otherwise the host-side must always send
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1683 a reply code and the <varname>reply</varname> argument must be valid.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1684 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1685 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1686 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1687 <term><varname>rxdata</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1688 <term><varname>rxlen</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1689 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1690 Some operations may involve additional data coming from the host-side,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1691 for example an incoming ethernet packet. <varname>rxdata</varname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1692 should be a suitably-sized buffer, and <varname>rxlen</varname> a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1693 pointer to an integer variable that will end up containing the number
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1694 of bytes that were actually received. These arguments will only be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1695 used if the host-side is expected to send a reply and hence the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1696 <varname>reply</varname> argument was not NULL.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1697 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1698 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1699 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1700 <term><varname>max_rxlen</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1701 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1702 If a reply to this message is expected and that reply may involve
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1703 additional data, <varname>max_rxlen</varname> limits the size of that
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1704 reply. In other words, it corresponds to the size of the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1705 <varname>rxdata</varname> buffer.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1706 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1707 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1708 </variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1709 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1710 Most I/O operations involve only some of the arguments. For example
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1711 transmitting an ethernet packet would use the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1712 <varname>request</varname>, <varname>txdata</varname> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1713 <varname>txlen</varname> fields (in addition to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1714 <varname>device_id</varname> which is always required), but would not
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1715 involve <varname>arg1</varname> or <varname>arg2</varname> and no
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1716 reply would be expected. Receiving an ethernet packet would involve
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1717 <varname>request</varname>, <varname>rxdata</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1718 <varname>rxlen</varname> and <varname>max_rxlen</varname>; in addition
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1719 <varname>reply</varname> is needed to get any reply from the host-side
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1720 at all, and could be used to indicate whether or not any more packets
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1721 are buffered up. A control operation such as enabling multicast mode
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1722 would involve <varname>request</varname> and <varname>arg1</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1723 but none of the remaining arguments.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1724 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1725 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1726
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1727 <refsect1 id="synth-new-target-interrupts"><title>Interrupt Handling</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1728 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1729 Interrupt handling in the synthetic target is much the same as on a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1730 real target. An interrupt object is created using
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1731 <function>cyg_drv_interrupt_create</function>, attached, and unmasked.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1732 The emulated device - in other words the Tcl script running inside the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1733 I/O auxiliary - can raise an interrupt. Subject to interrupts being
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1734 disabled and the appropriate vector being masked, the system will
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1735 invoke the specified ISR function. The synthetic target HAL
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1736 implementation does have some limitations: there is no support for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1737 nested interrupts, interrupt priorities, or a separate interrupt
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1738 stack. Supporting those might be appropriate when targetting a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1739 simulator that attempts to model real hardware accurately, but not for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1740 the simple emulation provided by the synthetic target.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1741 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1742 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1743 Of course the actual implementation of the ISR and DSR functions will
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1744 be rather different for a synthetic target device driver. For real
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1745 hardware the device driver will interact with the device by reading
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1746 and writing device registers, managing DMA engines, and the like. A
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1747 synthetic target driver will instead call
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1748 <function>synth_auxiliary_xchgmsg</function> to perform the I/O
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1749 operations.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1750 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1751 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1752 There is one other significant difference between interrupt handling
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1753 on the synthetic target and on real hardware. Usually the eCos code
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1754 will know which interrupt vectors are used for which devices. That
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1755 information is fixed when the target hardware is designed. With the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1756 synthetic target interrupt vectors are assigned to devices on the host
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1757 side, either via the target definition file or dynamically when the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1758 device is instantiated. Therefore the initialization code for a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1759 target-side device driver will need to request interrupt vector
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1760 information from the host-side, via a message exchange. Such interrupt
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1761 vectors will be in the range 1 to 31 inclusive, with interrupt 0 being
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1762 reserved for the real-time clock.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1763 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1764 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1765
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1766 </refentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1767
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1768 <!-- }}} -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1769 <!-- {{{ New devices - host-side -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1770
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1771 <refentry id="synth-new-host">
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1772 <refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1773 <refentrytitle>Writing New Devices - host</refentrytitle>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1774 </refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1775 <refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1776 <refname>Writing New Devices</refname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1777 <refpurpose>extending the synthetic target, host-side</refpurpose>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1778 </refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1779
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1780 <refsect1 id="synth-new-host-description"><title>Description</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1781 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1782 On the host-side adding a new device means writing a Tcl/Tk script
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1783 that will handle instantiation and subsequent requests from the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1784 target-side. These scripts all run in the same full interpreter,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1785 extended with various commands provided by the main I/O auxiliary
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1786 code, and running in an overall GUI framework. Some knowledge of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1787 programming with Tcl/Tk is required to implement host-side device
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1788 support.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1789 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1790 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1791 Some devices can be implemented entirely using a Tcl/Tk script. For
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1792 example, if the final system will have some buttons then those can be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1793 emulated in the synthetic target using a few Tk widgets. A simple
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1794 emulation could just have the right number of buttons in a row. A more
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1795 advanced emulation could organize the buttons with the right layout,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1796 perhaps even matching the colour scheme, the shapes, and the relative
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1797 sizes. With other devices it may be necessary for the Tcl script to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1798 interact with an external program, because the required functionality
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1799 cannot easily be accessed from a Tcl script. For example interacting
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1800 with a raw ethernet device involves some <function>ioctl</function>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1801 calls, which is easier to do in a C program. Therefore the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1802 <filename>ethernet.tcl</filename> script which implements the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1803 host-side ethernet support spawns a separate program
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1804 <filename>rawether</filename>, written in C, that performs the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1805 low-level I/O. Raw ethernet access usually also requires root
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1806 privileges, and running a small program <filename>rawether</filename>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1807 with such privileges is somewhat less of a security risk than the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1808 whole eCos application, the I/O auxiliary, and various dynamically
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1809 loaded Tcl scripts.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1810 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1811 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1812 Because all scripts run in a single interpreter, some care has
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1813 to be taken to avoid accidental sharing of global variables. The best
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1814 way to avoid problems is to have each script create its own Tcl
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1815 namespace, so for example the <filename>ethernet.tcl</filename> script
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1816 creates a namespace <varname>ethernet::</varname> and all variables
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1817 and procedures reside in this namespace. Similarly the I/O auxiliary
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1818 itself makes use of a <varname>synth::</varname> namespace.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1819 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1820 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1821
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1822 <refsect1 id="synth-new-host-build"><title>Building and Installation</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1823 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1824 When an eCos device driver or application code instantiates a device,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1825 the I/O auxiliary will attempt to load a matching Tcl script. The
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1826 third argument to <function>synth_auxiliary_instantiate</function>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1827 specifies the type of device, for example <literal>ethernet</literal>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1828 and the I/O auxiliary will append a <filename>.tcl</filename> suffix
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1829 and look for a script <filename>ethernet.tcl</filename>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1830 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1831 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1832 If the device being instantiated is application-specific rather than
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1833 part of an eCos package, the I/O auxiliary will look first in the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1834 current directory, then in <filename
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1835 class="directory">~/.ecos/synth</filename>. If it is part of an eCos
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1836 package then the auxiliary will expect to find the Tcl script and any
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1837 support files below <filename
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1838 class="directory">libexec/ecos</filename> in the install tree - note
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1839 that the same install tree must be used for the I/O auxiliary itself
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1840 and for any device driver support. The directory hierarchy below
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1841 <filename class="directory">libexec/ecos</filename> matches the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1842 structure of the eCos repository, allowing multiple versions of a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1843 package to be installed to allow for incompatible protocol changes.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1844 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1845 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1846 The preferred way to build host-side software is to use
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1847 <command>autoconf</command> and <command>automake</command>. Usually
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1848 this involves little more than copying the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1849 <filename>acinclude.m4</filename>, <filename>configure.in</filename>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1850 and <filename>Makefile.am</filename> files from an existing package,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1851 for example the synthetic target ethernet driver, and then making
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1852 minor edits. In <filename>acinclude.m4</filename> it may be necessary
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1853 to adjust the path to the root of the repository.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1854 <filename>configure.in</filename> may require a similar change, and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1855 the <function>AC_INIT</function> macro invocation will have to be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1856 changed to match one of the files in the new package. A critical macro
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1857 in this file is <filename>ECOS_PACKAGE_DIRS</filename> which will set
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1858 up the correct install directory. <filename>Makefile.am</filename> may
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1859 require some more changes, for example to specify the data files that
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1860 should be installed (including the Tcl script). These files should
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1861 then be processed using <command>aclocal</command>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1862 <command>autoconf</command> and <command>automake</command> in that
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1863 order. Actually building the software then just involves
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1864 <command>configure</command>, <command>make</command> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1865 <command>make install</command>, as per the instructions in the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1866 toplevel <filename>README.host</filename> file.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1867 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1868 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1869 To assist developers, if the environment variable
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1870 <envar>ECOSYNTH_DEVEL</envar> is set then a slightly different
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1871 algorithm is used for locating device Tcl scripts. Instead of looking
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1872 only in the install tree the I/O auxiliary will also look in the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1873 source tree, and if the script there is more recent than the installed
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1874 version it will be used in preference. This allows developers to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1875 modify the master copy without having to run <command>make
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1876 install</command> all the time.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1877 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1878 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1879 If a script needs to know where it has been installed it can examine
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1880 the Tcl variable <varname>synth::device_install_dir</varname> . This
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1881 variable gets updated whenever a script is loaded, so if the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1882 value may be needed later it should be saved away in a device-specific
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1883 variable.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1884 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1885 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1886
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1887 <refsect1 id="synth-new-host-instantiation"><title>Instantiation</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1888 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1889 The I/O auxiliary will <command>source</command> the device-specific
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1890 Tcl script when the eCos application first attempts to instantiate a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1891 device of that type. The script should return a procedure that will be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1892 invoked to instantiate a device.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1893 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1894 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1895 namespace eval ethernet {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1896 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1897 proc instantiate { id instance data } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1898 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1899 return ethernet::handle_request
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1900 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1901 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1902 return ethernet::instantiate
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1903 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1904 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1905 The <varname>id</varname> argument is a unique identifier for this
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1906 device instance. It will also be supplied on subsequent calls to the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1907 request handler, and will match the return value of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1908 <function>synth_auxiliary_instantiate</function> on the target side. A
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1909 common use for this value is as an array index to support multiple
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1910 instances of this types of device. The <varname>instance</varname> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1911 <varname>data</varname> arguments match the corresponding arguments to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1912 <function>synth_auxiliary_instantiate</function> on the target side, so
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1913 a typical value for <varname>instance</varname> would be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1914 <literal>eth0</literal>, and <varname>data</varname> is used to pass
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1915 arbitrary initialization parameters from target to host.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1916 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1917 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1918 The actual work done by the instantiation procedure is obviously
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1919 device-specific. It may involve allocating an <link
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1920 linkend="synth-new-host-interrupts">interrupt vector</link>, adding a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1921 device-specific subwindow to the display, opening a real Linux device,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1922 establishing a socket connection to some server, spawning a separate
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1923 process to handle the actual I/O, or a combination of some or all of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1924 the above.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1925 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1926 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1927 If the device is successfully instantiated then the return value
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1928 should be a handler for subsequent I/O requests. Otherwise the return
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1929 value should be an empty string, and on the target-side the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1930 <function>synth_auxiliary_instantiate</function> call will return
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1931 <literal>-1</literal>. The script is responsible for providing
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1932 <link linkend="synth-new-host-output">diagnostics</link> explaining
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1933 why the device could not be instantiated.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1934 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1935 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1936
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1937 <refsect1 id="synth-new-host-requests"><title>Handling Requests</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1938 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1939 When the target-side calls
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1940 <function>synth_auxiliary_xchgmsg</function>, the I/O auxiliary will
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1941 end up calling the request handler for the appropriate device instance
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1942 returned during instantiation:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1943 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1944 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1945 namespace eval ethernet {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1946 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1947 proc handle_request { id request arg1 arg2 txdata txlen max_rxlen } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1948 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1949 if { &lt;some condition&gt; } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1950 synth::send_reply &lt;error code&gt; 0 ""
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1951 return
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1952 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1953 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1954 synth::send_reply &lt;reply code&gt; $packet_len $packet
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1955 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1956 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1957 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1958 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1959 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1960 The <varname>id</varname> argument is the same device id that was
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1961 passed to the instantiate function, and is typically used as an array
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1962 index to access per-device data. The <varname>request</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1963 <varname>arg1</varname>, <varname>arg2</varname>, and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1964 <varname>max_rxlen</varname> are the same values that were passed to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1965 <function>synth_auxiliary_xchgmsg</function> on the target-side,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1966 although since this is a Tcl script obviously the numbers have been
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1967 converted to strings. The <varname>txdata</varname> buffer is raw data
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1968 as transmitted by the target, or an empty string if the I/O operation
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1969 does not involve any additional data. The Tcl procedures
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1970 <command>binary scan</command>, <command>string index</command> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1971 <command>string range</command> may be found especially useful when
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1972 manipulating this buffer. <varname>txlen</varname> is provided for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1973 convenience, although <command>string length $txdata</command> would
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1974 give the same information.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1975 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1976 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1977 The code for actually processing the request is of course device
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1978 specific. If the target does not expect a reply then the request
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1979 handler should just return when finished. If a reply is expected then
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1980 there should be a call to <command>synth::send_reply</command>. The
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1981 first argument is the reply code, and will be turned into a 32-bit
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1982 integer on the target side. The second argument specifies the length
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1983 of the reply data, and the third argument is the reply data itself.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1984 For some devices the Tcl procedure <command>binary format</command>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1985 may prove useful. If the reply involves just a code and no additional
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1986 data, the second and third arguments should be <literal>0</literal>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1987 and an empty string respectively.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1988 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1989 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1990 Attempts to send a reply when none is expected, fail to send a reply
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1991 when one is expected, or send a reply that is larger than the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1992 target-side expects, will all be detected by the I/O auxiliary and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1993 result in run-time error messages.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1994 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1995 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1996 It is not possible for the host-side code to send unsolicited messages
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1997 to the target. If host-side code needs attention from the target, for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1998 example because some I/O operation has completed, then an interrupt
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1999 should be raised.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2000 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2001 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2002
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2003 <refsect1 id="synth-new-host-interrupts"><title>Interrupts</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2004 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2005 The I/O auxiliary provides a number of procedures for interrupt
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2006 handling.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2007 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2008 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2009 synth::interrupt_allocate &lt;name&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2010 synth::interrupt_get_max
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2011 synth::interrupt_get_devicename &lt;vector&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2012 synth::interrupt_raise &lt;vector&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2013 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2014 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2015 <command>synth::interrupt_allocate</command> is normally called during
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2016 device instantiation, and returns the next free interrupt vector. This
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2017 can be passed on to the target-side device driver in response to a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2018 suitable request, and it can then install an interrupt handler on that
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2019 vector. Interrupt vector <literal>0</literal> is used within the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2020 target-side code for the real-time clock, so the allocated vectors
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2021 will start at <literal>1</literal>. The argument identifies the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2022 device, for example <literal>eth0</literal>. This is not actually used
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2023 internally, but can be accessed by user-initialization scripts that
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2024 provide some sort of interrupt monitoring facility (typically via the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2025 <literal>interrupt</literal> <link
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2026 linkend="synth-new-host-hooks">hook</link>). It is possible for a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2027 single device to allocate multiple interrupt vectors, but the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2028 synthetic target supports a maximum of 32 such vectors.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2029 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2030 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2031 <command>synth::interrupt_get_max</command> returns the highest
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2032 interrupt vector that has been allocated, or <literal>0</literal> if
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2033 there have been no calls to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2034 <command>synth::interrupt_allocate</command>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2035 <command>synth::interrupt_get_devicename</command> returns the string
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2036 that was passed to <command>synth::interrupt_allocate</command> when
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2037 the vector was allocated.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2038 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2039 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2040 <command>synth::interrupt_raise</command> can be called any time after
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2041 initialization. The argument should be the vector returned by
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2042 <command>synth::interrupt_allocate</command> for this device. It will
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2043 activate the normal eCos interrupt handling mechanism so, subject to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2044 interrupts being enabled and this particular interrupt not being
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2045 masked out, the appropriate ISR will run.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2046 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2047 <note><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2048 At this time it is not possible for a device to allocate a specific
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2049 interrupt vector. The order in which interrupt vectors are assigned to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2050 devices effectively depends on the order in which the eCos devices get
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2051 initialized, and that may change if the eCos application is rebuilt. A
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2052 future extension may allow devices to allocate specific vectors, thus
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2053 making things more deterministic. However that will introduce new
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2054 problems, in particular the code will have to start worrying about
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2055 requests for vectors that have already been allocated.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2056 </para></note>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2057 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2058
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2059 <refsect1 id="synth-new-host-args"><title>Flags and Command Line Arguments</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2060 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2061 The generic I/O auxiliary code will process the standard command line
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2062 arguments, and will set various flag variables accordingly. Some of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2063 these should be checked by device-specific scripts.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2064 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2065 <variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2066 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2067 <term><varname>synth::flag_gui</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2068 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2069 This is set when the I/O auxiliary is operating in graphical mode
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2070 rather than text mode. Some functionality such as filters and the GUI
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2071 layout are only available in graphical mode.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2072 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2073 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2074 if { $synth::flag_gui } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2075 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2076 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2077 </programlisting></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2078 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2079 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2080 <term><varname>synth::flag_verbose</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2081 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2082 The user has requested additional information during startup. Each
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2083 device driver can decide how much additional information, if any,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2084 should be produced.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2085 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2086 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2087 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2088 <term><varname>synth::flag_keep_going</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2089 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2090 The user has specified <option>-k</option> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2091 <option>--keep-going</option>, so even if an error occurs the I/O
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2092 auxiliary and the various device driver scripts should continue running
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2093 if at all possible. Diagnostics should still be generated.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2094 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2095 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2096 </variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2097 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2098 Some scripts may want to support additional command line arguments.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2099 This facility should be used with care since there is no way to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2100 prevent two different scripts from trying to use the same argument.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2101 The following Tcl procedures are available:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2102 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2103 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2104 synth::argv_defined &lt;name&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2105 synth::argv_get_value &lt;name&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2106 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2107 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2108 <command>synth::argv_defined</command> returns a boolean to indicate
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2109 whether or not a particular argument is present. If the argument is
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2110 the name part of a name/value pair, an <literal>=</literal> character
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2111 should be appended. Typical uses might be:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2112 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2113 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2114 if { [synth::argv_defined "-o13"] } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2115 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2116 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2117
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2118 if { [synth::argv_defined "-mark="] } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2119 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2120 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2121 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2122 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2123 The first call checks for a flag <literal>-o13</literal> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2124 <literal>--o13</literal> - the code treats options with single and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2125 double hyphens interchangeably. The second call checks for an argument
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2126 of the form <literal>-mark=&lt;value&gt;</literal> or a pair of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2127 arguments <literal>-mark &lt;value&gt;</literal>. The value part of a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2128 name/value pair can be obtained using
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2129 <command>synth::argv_get_value</command>;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2130 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2131 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2132 variable speed 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2133 if { [synth::argv_defined "-mark="] } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2134 set mark [synth::argv_get_value "-mark="]
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2135 if { ![string is integer $mark] || ($mark < 1) || ($mark > 9) } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2136 &lt;issue diagnostic&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2137 } else {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2138 set speed $mark
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2139 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2140 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2141 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2142 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2143 <command>synth::argv_get_value</command> should only be used after a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2144 successful call to <command>synth::argv_defined</command>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2145 At present there is no support for some advanced forms of command line
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2146 argument processing. For example it is not possible to repeat a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2147 certain option such as <option>-v</option> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2148 <option>--verbose</option>, with each occurrence increasing the level
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2149 of verbosity.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2150 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2151 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2152 If a script is going to have its own set of command-line arguments
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2153 then it should give appropriate details if the user specifies
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2154 <option>--help</option>. This involves a hook function:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2155 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2156 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2157 namespace eval my_device {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2158 proc help_hook { } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2159 puts " -o13 : activate the omega 13 device"
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2160 puts " -mark &lt;speed&gt; : set speed. Valid values are 1 to 9."
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2161 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2162
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2163 synth::hook_add "help" my_device::help_hook
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2164 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2165 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2166 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2167
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2168 <refsect1 id="synth-new-host-tdf"><title>The Target Definition File</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2169 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2170 Most device scripts will want to check entries in the target
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2171 definition file for run-time configuration information. The Tcl
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2172 procedures for this are as follows:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2173 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2174 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2175 synth::tdf_has_device &lt;name&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2176 synth::tdf_get_devices
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2177 synth::tdf_has_option &lt;devname&gt; &lt;option&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2178 synth::tdf_get_option &lt;devname&gt; &lt;option&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2179 synth::tdf_get_options &lt;devname&gt; &lt;option&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2180 synth::tdf_get_all_options &lt;devname&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2181 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2182 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2183 <command>synth::tdf_has_device</command> can be used to check whether
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2184 or not the target definition file had an entry
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2185 <literal>synth_device&nbsp;&lt;name&gt;</literal>. Usually the name
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2186 will match the type of device, so the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2187 <filename>console.tcl</filename> script will look for a target
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2188 definition file entry <literal>console</literal>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2189 <command>synth::tdf_get_devices</command> returns a list of all
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2190 device entries in the target definition file.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2191 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2192 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2193 Once it is known that the target definition file has an entry for a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2194 certain device, it is possible to check for options within the entry.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2195 <command>synth::tdf_has_option</command> just checks for the presence,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2196 returning a boolean:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2197 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2198 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2199 if { [synth::tdf_has_option "console" "appearance"] } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2200 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2201 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2202 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2203 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2204 <command>synth::tdf_get_option</command> returns a list of all the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2205 arguments for a given option. For example, if the target definition
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2206 file contains an entry:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2207 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2208 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2209 synth_device console {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2210 appearance -foreground white -background black
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2211 filter trace {^TRACE:.*} -foreground HotPink1 -hide 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2212 filter xyzzy {.*xyzzy.*} -foreground PapayaWhip
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2213 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2214 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2215 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2216 A call
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2217 <command>synth::tdf_get_option&nbsp;console&nbsp;appearance</command>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2218 will return the list <literal>{-foreground white -background
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2219 black}</literal>. This list can be manipulated using standard Tcl routines
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2220 such as <command>llength</command> and <command>lindex</command>. Some
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2221 options can occur multiple times in one entry, for example
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2222 <option>filter</option> in the <literal>console</literal> entry.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2223 <command>synth::tdf_get_options</command> returns a list of lists,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2224 with one entry for each option occurrence.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2225 <command>synth::tdf_get_all_options</command> returns a list of lists
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2226 of all options. This time each entry will include the option name as
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2227 well.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2228 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2229 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2230 The I/O auxiliary will not issue warnings about entries in the target
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2231 definition file for devices which were not loaded, unless the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2232 <option>-v</option> or <option>--verbose</option> command line
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2233 argument was used. This makes it easier to use a single target
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2234 definition file for different applications. However the auxiliary will
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2235 issue warnings about options within an entry that were ignored,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2236 because often these indicate a typing mistake of some sort. Hence a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2237 script should always call <command>synth::tdf_has_option</command>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2238 <command>synth:;tdf_get_option</command> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2239 <command>synth::tdf_get_options</command> for all valid options, even
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2240 if some of the options preclude the use of others.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2241 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2242 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2243
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2244 <refsect1 id="synth-new-host-hooks"><title>Hooks</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2245 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2246 Some scripts may want to take action when particular events occur, for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2247 example when the eCos application has exited and there is no need for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2248 further I/O. This is supported using hooks:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2249 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2250 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2251 namespace eval my_device {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2252 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2253 proc handle_ecos_exit { arg_list } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2254 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2255 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2256 synth::hook_add "ecos_exit" my_device::handle_ecos_exit
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2257 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2258 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2259 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2260 It is possible for device scripts to add their own hooks and call all
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2261 functions registered for those hooks. A typical use for this is by
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2262 user initialization scripts that want to monitor some types of I/O.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2263 The available Tcl procedures for manipulating hooks are:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2264 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2265 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2266 synth::hook_define &lt;name&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2267 synth::hook_defined &lt;name&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2268 synth::hook_add &lt;name&gt; &lt;function&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2269 synth::hook_call &lt;name&gt; &lt;args&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2270 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2271 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2272 <command>synth::hook_define</command> creates a new hook with the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2273 specified name. This hook must not already exist.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2274 <command>synth::hook_defined</command> can be used to check for the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2275 existence of a hook. <command>synth::hook_add</command> allows other
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2276 scripts to register a callback function for this hook, and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2277 <command>synth::hook_call</command> allows the owner script to invoke
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2278 all such callback functions. A hook must already be defined before a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2279 callback can be attached. Therefore typically device scripts will only
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2280 use standard hooks and their own hooks, not hooks created by some
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2281 other device, because the order of device initialization is not
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2282 sufficiently defined. User scripts run from
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2283 <filename>mainrc.tcl</filename> can use any hooks that have been
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2284 defined.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2285 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2286 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2287 <command>synth::hook_call</command> takes an arbitrary list of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2288 arguments, for example:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2289 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2290 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2291 synth::hook_call "ethernet_rx" "eth0" $packet
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2292 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2293 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2294 The callback function will always be invoked with a single argument,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2295 a list of the arguments that were passed to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2296 <command>synth::hook_call</command>:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2297 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2298 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2299 proc rx_callback { arg_list } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2300 set device [lindex $arg_list 0]
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2301 set packet [lindex $arg_list 1]
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2302 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2303 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2304 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2305 Although it might seem more appropriate to use Tcl's
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2306 <command>eval</command> procedure and have the callback functions
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2307 invoked with the right number of arguments rather than a single list,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2308 that would cause serious problems if any of the data contained special
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2309 characters such as <literal>[</literal> or <literal>$</literal>. The
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2310 current implementation of hooks avoids such problems, at the cost of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2311 minor inconvenience when writing callbacks.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2312 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2313 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2314 A number of hooks are defined as standard. Some devices will add
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2315 additional hooks, and the device-specific documentation should be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2316 consulted for those. User scripts can add their own hooks if desired.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2317 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2318 <variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2319 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2320 <term><literal>exit</literal></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2321 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2322 This hook is called just before the I/O auxiliary exits. Hence it
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2323 provides much the same functionality as <function>atexit</function> in
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2324 C programs. The argument list passed to the callback function will be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2325 empty.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2326 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2327 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2328 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2329 <term><literal>ecos_exit</literal></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2330 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2331 This hook is called when the eCos application has exited. It is used
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2332 mainly to shut down I/O operations: if the application is no longer
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2333 running then there is no point in raising interrupts or storing
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2334 incoming packets. The callback argument list will be empty.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2335 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2336 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2337 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2338 <term><literal>ecos_initialized</literal></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2339 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2340 The synthetic target HAL will send a request to the I/O auxiliary once
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2341 the static constructors have been run. All devices should now have been
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2342 instantiated. A script could now check how many instances there are of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2343 a given type of device, for example ethernet devices, and create a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2344 little monitor window showing traffic on all the devices. The
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2345 <literal>ecos_initialized</literal> callbacks will be run just before
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2346 the user's <filename>mainrc.tcl</filename> script. The callback
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2347 argument list will be empty.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2348 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2349 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2350 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2351 <term><literal>help</literal></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2352 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2353 This hook is also invoked once static constructors have been run, but
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2354 only if the user specified <option>-h</option> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2355 <option>--help</option>. Any scripts that add their own command line
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2356 arguments should add a callback to this hook which outputs details of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2357 the additional arguments. The callback argument list will be empty.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2358 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2359 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2360 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2361 <term><literal>interrupt</literal></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2362 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2363 Whenever a device calls <command>synth::interrupt_raise</command> the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2364 <literal>interrupt</literal> hook will be called with a single
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2365 argument, the interrupt vector. The main use for this is to allow
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2366 user scripts to monitor interrupt traffic.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2367 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2368 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2369 </variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2370 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2371
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2372 <refsect1 id="synth-new-host-output"><title>Output and Filters</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2373 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2374 Scripts can use conventional facilities for sending text output to the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2375 user, for example calling <command>puts</command> or directly
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2376 manipulating the central text widget
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2377 <varname>.main.centre.text</varname>. However in nearly all cases it
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2378 is better to use output facilities provided by the I/O auxiliary
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2379 itself:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2380 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2381 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2382 synth::report &lt;msg&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2383 synth::report_warning &lt;msg&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2384 synth::report_error &lt;msg&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2385 synth::internal_error &lt;msg&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2386 synth::output &lt;msg&gt; &lt;filter&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2387 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2388 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2389 <command>synth::report</command> is intended for messages related to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2390 the operation of the I/O auxiliary itself, especially additional
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2391 output resulting from <option>-v</option> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2392 <option>--verbose</option>. If running in text mode the output will go
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2393 to standard output. If running in graphical mode the output will go to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2394 the central text window. In both modes, use of <option>-l</option> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2395 <option>--logfile</option> will modify the behaviour.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2396 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2397 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2398 <command>synth::report_warning</command>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2399 <command>synth::report_error</command> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2400 <command>synth::internal_error</command> have the obvious meaning,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2401 including prepending strings such as <literal>Warning:</literal> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2402 <literal>Error:</literal>. When the eCos application informs the I/O
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2403 auxiliary that all static constructors have run, if at that point
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2404 there have been any calls to <command>synth::error</command> then the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2405 I/O auxiliary will exit. This can be suppressed with command line
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2406 arguments <option>-k</option> or <option>--keep-going</option>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2407 <command>synth::internal_error</command> will output some information
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2408 about the current state of the I/O auxiliary and then exit
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2409 immediately. Of course it should never be necessary to call this
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2410 function.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2411 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2412 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2413 <command>synth::output</command> is the main routine for outputting
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2414 text. The second argument identifies a filter. If running in text mode
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2415 the filter is ignored, but if running in graphical mode the filter can
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2416 be used to control the appearance of this output. A typical use would
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2417 be:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2418 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2419 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2420 synth::output $line "console"
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2421 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2422 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2423 This outputs a single line of text using the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2424 <literal>console</literal> filter. If running in graphical mode the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2425 default appearance of this text can be modified with the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2426 <option>appearance</option> option in the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2427 <command>synth_device&nbsp;console</command> entry of the target
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2428 definition file. The <guimenuitem>System filters</guimenuitem> menu
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2429 option can be used to change the appearance at run-time.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2430 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2431 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2432 Filters should be created before they are used. The procedures
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2433 available for this are:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2434 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2435 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2436 synth::filter_exists &lt;name&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2437 synth::filter_get_list
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2438 synth::filter_add &lt;name&gt; [options]
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2439 synth::filter_parse_options &lt;options&gt; &lt;parsed_options&gt; &lt;message&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2440 synth::filter_add_parsed &lt;name&gt; &lt;parsed_options&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2441 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2442 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2443 <command>synth::filter_exists</command> can be used to check whether
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2444 or not a particular filter already exists: creating two filters with
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2445 the same name is not allowed.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2446 <command>synth::filter_get_list</command> returns a list of the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2447 current known filters. <command>synth::filter_add</command> can be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2448 used to create a new filter. The first argument names the new filter,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2449 and the remaining arguments control the initial appearance. A typical
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2450 use might be:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2451 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2452 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2453 synth::filter_add "my_device_tx" -foreground yellow -hide 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2454 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2455 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2456 It is assumed that the supplied arguments are valid, which typically
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2457 means that they are hard-wired in the script. If instead the data
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2458 comes out of a configuration file and hence may be invalid, the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2459 I/O auxiliary provides a parsing utility. Typical usage would be:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2460 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2461 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2462 array set parsed_options [list]
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2463 set message ""
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2464 if { ![synth::filter_parse_options $console_appearance parsed_options message] } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2465 synth::report_error \
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2466 "Invalid entry in target definition file $synth::target_definition\
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2467 \n synth_device \"console\", entry \"appearance\"\n$message"
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2468 } else {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2469 synth::filter_add_parsed "console" parsed_options
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2470 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2471 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2472 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2473 On success <varname>parsed_options</varname> will be updated with an
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2474 internal representation of the desired appearance, which can then be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2475 used in a call to <command>synth::filter_add_parsed</command>. On
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2476 failure <varname>message</varname> will be updated with details of the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2477 parsing error that occurred.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2478 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2479 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2480
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2481 <refsect1 id="synth-new-host-gui"><title>The Graphical Interface</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2482 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2483 When the I/O auxiliary is running in graphical mode, many scripts will
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2484 want to update the user interface in some way. This may be as simple
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2485 as adding another entry to the help menu for the device, or adding a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2486 new button to the toolbar. It may also involve adding new subwindows,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2487 or even creating entire new toplevel windows. These may be simple
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2488 monitor windows, displaying additional information about what is going
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2489 on in the system in a graphical format. Alternatively they may emulate
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2490 actual I/O operations, for example button widgets could be used to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2491 emulate real physical buttons.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2492 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2493 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2494 The I/O auxiliary does not provide many procedures related to the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2495 graphical interface. Instead it is expected that scripts will just
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2496 update the widget hierarchy directly.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2497 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2498 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2499 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2500 <imageobject>
991
fcb7cbb964ae * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 709
diff changeset
2501 <imagedata fileref="layout.png" Scalefit=1 Align="Center">
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2502 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2503 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2504 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2505 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2506 So adding a new item to the <guimenu>Help</guimenu> menu involves a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2507 <command>.menubar.help&nbsp;add</command> operation with suitable
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2508 arguments. Adding a new button to the toolbar involves creating a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2509 child window in <varname>.toolbar</varname> and packing it
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2510 appropriately. Scripts can create their own subwindows and then pack
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2511 it into one of <varname>.main.nw</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2512 <varname>.main.n</varname>, <varname>.main.ne</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2513 <varname>.main.w</varname>, <varname>.main.e</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2514 <varname>.main.sw</varname>, <varname>.main.s</varname> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2515 <varname>.main.se</varname>. Normally the user should be allowed to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2516 <link linkend="synth-gui-layout">control</link> this via the target
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2517 definition file. The central window <varname>.main.centre</varname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2518 should normally be left alone by other scripts since it gets used for
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2519 text output.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2520 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2521 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2522 The following graphics-related utilities may be found useful:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2523 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2524 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2525 synth::load_image &lt;image name&gt; &lt;filename&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2526 synth::register_ballon_help &lt;widget&gt; &lt;message&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2527 synth::handle_help &lt;URL&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2528 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2529 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2530 <command>synth::load_image</command> can be used to add a new image to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2531 the current interpreter. If the specified file has a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2532 <filename>.xbm</filename> extension then the image will be a
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2533 monochrome bitmap, otherwise it will be a colour image of some sort.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2534 A boolean will be returned to indicate success or failure, and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2535 suitable diagnostics will be generated if necessary.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2536 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2537 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2538 <command>synth::register_balloon_help</command> provides balloon help
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2539 for a specific widget, usually a button on the toolbar.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2540 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2541 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2542 <command>synth::handle_help</command> is a utility routine that can be
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2543 installed as the command for displaying online help, for example:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2544 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2545 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2546 .menubar.help add command -label "my device" -command \
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2547 [list synth::handle_help "file://$path"]
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2548 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2549 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2550
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2551 </refentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2552
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2553 <!-- }}} -->
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2554 <!-- {{{ Porting -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2555
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2556 <refentry id="synth-porting">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2557 <refmeta>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2558 <refentrytitle>Porting</refentrytitle>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2559 </refmeta>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2560 <refnamediv>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2561 <refname>Porting</refname>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2562 <refpurpose>Adding support for other hosts</refpurpose>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2563 </refnamediv>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2564
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2565 <refsect1 id="synth-porting-description"><title>Description</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2566 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2567 The initial development effort of the eCos synthetic target happened
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2568 on x86 Linux machines. Porting to other platforms involves addressing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2569 a number of different issues. Some ports should be fairly
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2570 straightforward, for example a port to Linux on a processor other than
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2571 an x86. Porting to Unix or Unix-like operating systems other than
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2572 Linux may be possible, but would involve more effort. Porting to a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2573 completely different operating system such as Windows would be very
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2574 difficult. The text below complements the eCos Porting Guide.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2575 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2576 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2577
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2578 <refsect1 id="synth-porting-linux"><title>Other Linux Platforms</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2579 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2580 Porting the synthetic target to a Linux platform that uses a processor
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2581 other than x86 should be straightforward. The simplest approach is to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2582 copy the existing <filename class="directory">i386linux</filename>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2583 directory tree in the <filename class="directory">hal/synth</filename>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2584 hierarchy, then rename and edit the ten or so files in this package.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2585 Most of the changes should be pretty obvious, for example on a 64-bit
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2586 processor some new data types will be needed in the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2587 <filename>basetype.h</filename> header file. It will also be necessary
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2588 to update the toplevel <filename>ecos.db</filename> database with an
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2589 entry for the new HAL package, and a new target entry will be needed.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2590 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2591 <para>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2592 Obviously a different processor will have different register sets and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2593 calling conventions, so the code for saving and restoring thread
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2594 contexts and for implementing <function>setjmp</function> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2595 <function>longjmp</function> will need to be updated. The exact way of
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2596 performing Linux system calls will vary: on x86 linux this usually
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2597 involves pushing some registers on the stack and then executing an
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2598 <literal>int&nbsp;0x080</literal> trap instruction, but on a different
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2599 processor the arguments might be passed in registers instead and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2600 certainly a different trap instruction will be used. The startup code
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2601 is written in assembler, but needs to do little more than extract the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2602 process' argument and environment variables and then jump to the main
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2603 <function>linux_entry</function> function provided by the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2604 architectural synthetic target HAL package.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2605 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2606 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2607 The header file <filename>hal_io.h</filename> provided by the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2608 architectural HAL package provides various structure definitions,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2609 function prototypes, and macros related to system calls. These are
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2610 correct for x86 linux, but there may be problems on other processors.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2611 For example a structure field that is currently defined as a 32-bit
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2612 number may in fact may be a 64-bit number instead.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2613 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2614 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2615 The synthetic target's memory map is defined in two files in the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2616 <filename class="directory">include/pkgconf</filename> subdirectory.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2617 For x86 the default memory map involves eight megabytes of read-only
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2618 memory for the code at location 0x1000000 and another eight megabytes
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2619 for data at 0x2000000. These address ranges may be reserved for other
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2620 purposes on the new architecture, so may need changing. There may be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2621 some additional areas of memory allocated by the system for other
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2622 purposes, for example the startup stack and any environment variables,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2623 but usually eCos applications can and should ignore those.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2624 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2625 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2626 Other HAL functionality such as interrupt handling, diagnostics, and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2627 the system clock are provided by the architectural HAL package and
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2628 should work on different processors with few if any changes. There may
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2629 be some problems in the code that interacts with the I/O auxiliary
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2630 because of lurking assumptions about endianness or the sizes of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2631 various data types.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2632 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2633 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2634 When porting to other processors, a number of sources of information
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2635 are likely to prove useful. Obviously the Linux kernel sources and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2636 header files constitute the ultimate authority on how things work at
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2637 the system call level. The GNU C library sources may also prove very
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2638 useful: for a normal Linux application it is the C library that
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2639 provides the startup code and the system call interface.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2640 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2641 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2642
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2643 <refsect1 id="synth-porting-unix"><title>Other Unix Platforms</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2644 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2645 Porting to a Unix or Unix-like operating system other than Linux would
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2646 be somewhat more involved. The first requirement is toolchains: the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2647 GNU compilers, gcc and g++, must definitely be used; use of other GNU
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2648 tools such as the linker may be needed as well, because eCos depends
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2649 on functionality such as prioritizing C++ static constructors, and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2650 other linkers may not implement this or may implement it in a
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2651 different and incompatible way. A closely related requirement is the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2652 use of ELF format for binary executables: if the operating system
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2653 still uses an older format such as COFF then there are likely to be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2654 problems because they do not provide the flexibility required by eCos.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2655 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2656 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2657 In the architectural HAL there should be very little code that is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2658 specific to Linux. Instead the code should work on any operating
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2659 system that provides a reasonable implementation of the POSIX
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2660 standard. There may be some problems with program startup, but those
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2661 could be handled at the architectural level. Some changes may also be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2662 required to the exception handling code. However one file which will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2663 present a problem is <filename>hal_io.h</filename>, which contains
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2664 various structure definitions and macros used with the system call
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2665 interface. It is likely that many of these definitions will need
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2666 changing, and it may well be appropriate to implement variant HAL
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2667 packages for the different operating systems where this information
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2668 can be separated out. Another possible problem is that the generic
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2669 code assumes that system calls such as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2670 <function>cyg_hal_sys_write</function> are available. On an operating
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2671 system other than Linux it is possible that some of these are not
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2672 simple system calls, and instead wrapper functions will need to be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2673 implemented at the variant HAL level.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2674 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2675 <para>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2676 The generic I/O auxiliary code should be fairly portable to other Unix
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2677 platforms. However some of the device drivers may contain code that is
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2678 specific to Linux, for example the <literal>PF_PACKET</literal> socket
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2679 address family and the ethertap virtual tunnelling interface. These
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2680 may prove quite difficult to port.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2681 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2682 <para>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2683 The remaining porting task is to implement one or more platform HAL
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2684 packages, one per processor type that is supported. This should
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2685 involve much the same work as a port to <link
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2686 linkend="synth-porting-linux">another processor running Linux</link>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2687 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2688 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2689 When using other Unix operating systems the kernel source code may not
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2690 be available, which would make any porting effort more challenging.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2691 However there is still a good chance that the GNU C library will have
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2692 been ported already, so its source code may contain much useful
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2693 information.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2694 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2695 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2696
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2697 <refsect1 id="synth-porting-other"><title>Windows Platforms</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2698 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2699 Porting the current synthetic target code to some version of Windows
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2700 or to another non-Unix platform is likely to prove very difficult. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2701 first hurdle that needs to be crossed is the file format for binary
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2702 executables: current Windows implementations do not use ELF, instead
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2703 they use their own format PE which is a variant of the rather old and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2704 limited COFF format. It may well prove easier to first write an ELF
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2705 loader for Windows executables, rather than try to get eCos to work
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2706 within the constraints of PE. Of course that introduces new problems,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2707 for example existing source-level debuggers will still expect
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2708 executables to be in PE format.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2709 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2710 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2711 Under Linux a synthetic target application is not linked with the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2712 system's C library or any other standard system library. That would
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2713 cause confusion, for example both eCos and the system's C library
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2714 might try to define the <function>printf</function> function, and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2715 introduce complications such as working with shared libraries. For
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2716 much the same reasons, a synthetic target application under Windows
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2717 should not be linked with any Windows DLL's. If an ELF loader has been
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2718 specially written then this may not be much of a problem.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2719 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2720 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2721 The next big problem is the system call interface. Under Windows
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2722 system calls are generally made via DLL's, and it is not clear that
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2723 the underlying trap mechanism is well-documented or consistent between
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2724 different releases of Windows.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2725 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2726 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2727 The current code depends on the operating system providing an
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2728 implementation of POSIX signal handling. This is used for I/O
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2729 purposes, for example <literal>SIGALRM</literal> is used for the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2730 system clock, and for exceptions. It is not known what equivalent
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2731 functionality is available under Windows.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2732 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2733 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2734 Given the above problems a port of the synthetic target to Windows may
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2735 or may not be technically feasible, but it would certainly require a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2736 very large amount of effort.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2737 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2738 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2739
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2740 </refentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2741
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2742 <!-- }}} -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2743
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2744 </part>