Mercurial > ecos-v2_0-branch

annotate packages/hal/synth/arch/current/doc/synth.sgml @ 823:19a153ac403c default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* Added execute permissions to files missed in conversion from CVS
author alexs
date Thu, 08 May 2003 17:42:17 +0000
parents 02b0482eacef
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
700
9a2b440cee5d * 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 <!-- =============================================================== -->
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
12 <!-- ####COPYRIGHTBEGIN#### -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
13 <!-- -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
14 <!-- =============================================================== -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
15 <!-- Copyright (C) 2002 Bart Veer. -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
16 <!-- Copyright (C) 2002 Red Hat, Inc. -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
17 <!-- This material may be distributed only subject to the terms -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
18 <!-- and conditions set forth in the Open Publication License, v1.0 -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
19 <!-- or later (the latest version is presently available at -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
20 <!-- http://www.opencontent.org/openpub/) -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
21 <!-- Distribution of the work or derivative of the work in any -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
22 <!-- standard (paper) book form is prohibited unless prior -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
23 <!-- permission obtained from the copyright holder -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
24 <!-- =============================================================== -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
25 <!-- -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
26 <!-- ####COPYRIGHTEND#### -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
27 <!-- =============================================================== -->
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
28 <!-- =============================================================== -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
29 <!-- #####DESCRIPTIONBEGIN#### -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
30 <!-- -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
31 <!-- Author(s): bartv -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
32 <!-- Contact(s): bartv -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
33 <!-- Date: 2002/02/24 -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
34 <!-- Version: 0.01 -->
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 <!-- ####DESCRIPTIONEND#### -->
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
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
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
41 <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
42
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
43 <!-- {{{ Overview -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
44
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
45 <refentry id="synth">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
46 <refmeta>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
47 <refentrytitle>Overview</refentrytitle>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
48 </refmeta>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
49 <refnamediv>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
50 <refname>The eCos synthetic target</refname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
51 <refpurpose>Overview</refpurpose>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
52 </refnamediv>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
53
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
54 <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
55 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
56 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
57 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
58 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
59 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
60 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
61 <orderedlist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
62 <listitem><para>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
63 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
64 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
65 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
66 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
67 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
68 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
69 details.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
70 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
71 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
72 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
73 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
74 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
75 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
76 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
77 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
78 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
79 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
80 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
81 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
82 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
83 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
84 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
85 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
86 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
87 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
88 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
89 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
90 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
91 ethernet device.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
92 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
93 <listitem><para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
94 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
95 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
96 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
97 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
98 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
99 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
100 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
101 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
102 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
103 </para></listitem>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
104 </orderedlist>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
105 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
106 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
107 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
108 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
109 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
110 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
111 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
112 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
113 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
114 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
115 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
116 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
117 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
118 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
119 <para>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
120 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
121 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
122 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
123 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
124 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
125 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
126 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
127 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
128 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
129 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
130 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
131 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
132 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
133 hardware for the application being developed.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
134 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
135 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
136 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
137 <imageobject>
815
02b0482eacef * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 700
diff changeset
138 <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
139 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
140 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
141 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
142 <para>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
143 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
144 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
145 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
146 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
147 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
148 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
149 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
150 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
151 <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
152 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
153 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
154 <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
155 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
156 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
157 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
158 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
159 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
160 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
161 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
162 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
163 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
164 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
165 ecosynth I/O auxiliary involves system calls
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
166 <function>cyg_hal_sys_fork</function> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
167 <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
168 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
169 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
170 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
171 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
172 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
173 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
174 <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
175 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
176 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
177 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
178 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
179 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
180 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
181 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
182 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
183 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
184 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
185 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
186 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
187 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
188 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
189 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
190 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
191 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
192 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
193 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
194 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
195 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
196 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
197 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
198 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
199 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
200 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
201 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
202 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
203 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
204 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
205 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
206 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
207 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
208 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
209 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
210 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
211 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
212 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
213 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
214 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
215 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
216 </para>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
217 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
218 </refentry>
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 <!-- }}} -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
221 <!-- {{{ Installation -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
222
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
223 <refentry id="synth-install">
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
224 <refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
225 <refentrytitle>Installation</refentrytitle>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
226 </refmeta>
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 <refname>Installation</refname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
229 <refpurpose>Preparing to use the synthetic target</refpurpose>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
230 </refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
231
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
232 <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
233 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
234 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
235 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
236 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
237 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
238 available. The relevant code resides in the <filename
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
239 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
240 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
241 <command>configure</command>, <command>make</command>, and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
242 <command>make install</command> steps.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
243 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
244 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
245 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
246 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
247 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
248 single build tree. This involves using the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
249 <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
250 repository, which will automatically search the <filename
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
251 class="directory">packages</filename> hierarchy for host-side
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
252 software. For more information on this, see the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
253 <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
254 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
255 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
256 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
257 appropriate packages happens at configure time.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
258 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
259 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
260 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
261 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
262 <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
263 the source tree is not allowed.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
264 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
265 <screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
266 $ cd &lt;somewhere suitable&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
267 $ mkdir synth_build
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
268 $ cd synth_build
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
269 $ &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
270 $ make
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
271 $ make install
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
272 </screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
273 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
274 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
275 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
276 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
277 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
278 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
279 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
280 <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
281 <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
282 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
283 eCos repository.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
284 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
285 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
286 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
287 <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
288 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
289 essential that the <filename class="directory">bin</filename>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
290 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
291 <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
292 locate and execute the I/O auxiliary ecosynth.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
293 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
294 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
295 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
296 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
297 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
298 installed below <filename class="directory">libexec</filename>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
299 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
300 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
301 <filename class="directory">libexec</filename> using
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
302 <option>--exec-prefix=&lt;path&gt;</option> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
303 <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
304 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
305 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
306 configured.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
307 </para>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
308 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
309
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
310 <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
311 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
312 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
313 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
314 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
315 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
316 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
317 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
318 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
319 sufficient.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
320 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
321 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
322 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
323 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
324 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
325 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
326 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
327 <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
328 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
329 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
330 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
331 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
332 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
333 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
334 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
335 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
336 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
337 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
338 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
339 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
340 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
341 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
342 a suitable configure triplet would be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
343 <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
344 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
345 information.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
346 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
347 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
348
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
349 <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
350 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
351 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
352 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
353 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
354 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
355 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
356 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
357 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
358 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
359 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
360 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
361 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
362 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
363 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
364 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
365 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
366 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
367 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
368 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
369 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
370 embedded hardware is actually available.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
371 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
372 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
373 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
374 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
375 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
376 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
377 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
378 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
379 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
380 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
381 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
382 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
383 hardware initialization. Therefore the synthetic target actually
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
384 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
385 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
386 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
387 application code.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
388 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
389 </refsect1>
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 </refentry>
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 <!-- }}} -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
394 <!-- {{{ Running the application -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
395
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
396 <refentry id="synth-running">
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
397 <refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
398 <refentrytitle>Running a Synthetic Target Application</refentrytitle>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
399 </refmeta>
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 <refname>Execution</refname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
402 <refpurpose>Arguments and configuration files</refpurpose>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
403 </refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
404
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
405 <refsect1 id="synth-running-description"><title>Description</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
406 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
407 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
408 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
409 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
410 example from a shell prompt,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
411 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
412 <screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
413 $ ecos_hello &lt;options&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
414 </screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
415 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
416 or using gdb:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
417 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
418 <screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
419 $ 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
420 (gdb) run
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
421 Starting program: ecos_hello &lt;options&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
422 </screen>
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 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
425 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
426 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
427 <note><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
428 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
429 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
430 used to prevent the auxiliary from being run.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
431 </para></note>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
432 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
433
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
434 <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
435 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
436 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
437 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
438 <screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
439 $ &lt;ecos_app&gt; [options] [-- [app_options]]
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
440 </screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
441 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
442 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
443 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
444 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
445 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
446 <varname>cyg_hal_sys_argc</varname> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
447 <varname>cyg_hal_sys_argv</varname>.
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 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
450 The following options are accepted as standard:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
451 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
452 <variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
453 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
454 <term><option>--io</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
455 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
456 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
457 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
458 be available.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
459 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
460 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
461 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
462 <term><option>--nio</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
463 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
464 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
465 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
466 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
467 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
468 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
469 <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
470 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
471 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
472 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
473 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
474 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
475 inputs, requires the graphical interface.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
476 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
477 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
478 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
479 <term><option>-w</option>, <option>--windows</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
480 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
481 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
482 graphical user interface. This is the default.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
483 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
484 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
485 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
486 <term><option>-v</option>, <option>--version</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
487 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
488 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
489 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
490 auxiliary and the eCos application will exit immediately.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
491 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
492 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
493 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
494 <term><option>-h</option>, <option>--help</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
495 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
496 <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
497 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
498 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
499 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
500 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
501 <option>-nw</option>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
502 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
503 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
504 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
505 <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
506 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
507 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
508 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
509 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
510 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
511 although obviously it may not be fully functional.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
512 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
513 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
514 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
515 <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
516 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
517 Normally the auxiliary processes two <link
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
518 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
519 during startup: <filename>initrc.tcl</filename> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
520 <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
521 <option>-nr</option> option.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
522 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
523 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
524 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
525 <term><option>-x</option>, <option>--exit</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
526 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
527 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
528 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
529 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
530 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
531 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
532 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
533 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
534 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
535 <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
536 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
537 When the graphical user interface is disabled with
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
538 <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
539 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
540 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
541 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
542 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
543 <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
544 even after the application has exited.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
545 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
546 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
547 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
548 <term><option>-V</option>, <option>--verbose</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
549 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
550 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
551 information, especially during initialization.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
552 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
553 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
554 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
555 <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
556 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
557 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
558 simple text, for example resulting from eCos
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
559 <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
560 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
561 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
562 <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
563 additional logfile containing all the text. If graphical
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
564 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
565 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
566 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
567 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
568 well.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
569 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
570 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
571 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
572 <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
573 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
574 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
575 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
576 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
577 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
578 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
579 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
580 this will be appended automatically if necessary.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
581 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
582 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
583 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
584 <term><option>-geometry &lt;geometry&gt;</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
585 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
586 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
587 window, as per X conventions.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
588 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
589 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
590 </variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
591 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
592 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
593 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
594 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
595 consulting the device-specific documentation. If an unrecognised
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
596 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
597 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
598 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
599
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
600 <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
601 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
602 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
603 <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
604 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
605 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
606 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
607 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
608 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
609 additional configuration information, for example to limit the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
610 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
611 The target definition file provides all this information.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
612 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
613 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
614 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
615 <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
616 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
617 example:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
618 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
619 <screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
620 $ bridge_app --io -t twineth
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
621 </screen>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
622 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
623 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
624 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
625 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
626 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
627 in its install location.
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 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
630 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
631 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
632 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
633 synth_device console {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
634 # appearance -foreground white -background black
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
635 filter trace {^TRACE:.*} -foreground HotPink1 -hide 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
636 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
637
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
638 synth_device ethernet {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
639 eth0 real eth1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
640 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
641
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
642 ## 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
643 ## Default 16
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
644 #max_buffer 32
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
645
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
646 ## Filters for the various recognised protocols.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
647 ## 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
648 filter ether -hide 0
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
649 #filter arp -hide 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
650 #filter ipv4 -hide 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
651 #filter ipv6 -hide 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
652 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
653 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
654 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
655 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
656 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
657 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
658 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
659 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
660 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
661 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
662 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
663 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
664 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
665 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
666 <literal>eth2</literal>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
667 </para>
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 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
670 file, taking the form:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
671 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
672 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
673 synth_device &lt;device type&gt; {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
674 &lt;options&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
675 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
676 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
677 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
678 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
679 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
680 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
681 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
682 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
683 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
684 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
685 types of option are common to many devices.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
686 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
687 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
688 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
689 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
690 <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
691 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
692 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
693 <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
694 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
695 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
696 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
697 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
698 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
699 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
700 <variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
701 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
702 <term><option>-hide [0|1]</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
703 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
704 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
705 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
706 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
707 menu item.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
708 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
709 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
710 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
711 <term><option>-foreground &lt;colour&gt;</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
712 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
713 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
714 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
715 <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
716 <literal>"light steel blue"</literal>. The X11 utility
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
717 <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
718 about the available colours.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
719 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
720 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
721 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
722 <term><option>-background &lt;colour&gt;</option></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
723 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
724 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
725 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
726 a symbolic name or an RGB value.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
727 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
728 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
729 </variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
730 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
731 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
732 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
733 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
734 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
735 these windows.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
736 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
737 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
738 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
739 <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
740 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
741 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
742 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
743 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
744 <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
745 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
746 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
747 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
748 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
749 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
750 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
751 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
752 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
753
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
754 <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
755 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
756 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
757 configuration files, <filename>initrc.tcl</filename> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
758 <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
759 directory <filename class="directory">~/.ecos/synth/</filename>. If
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
760 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
761 with initial dummy files.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
762 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
763 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
764 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
765 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
766 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
767 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
768 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
769 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
770 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
771 initialization scripts.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
772 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
773 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
774 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
775 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
776 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
777 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
778 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
779 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
780 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
781 without annoying screen flicker. A typical
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
782 <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
783 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
784 eCos application exits.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
785 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
786 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
787 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
788 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
789 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
790 <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
791 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
792 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
793 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
794 activity.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
795 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
796 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
797
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
798 <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
799 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
800 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
801 <filename>~/.ecos/synth/guisession</filename> containing session
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
802 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
803 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
804 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
805 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
806 display online help.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
807 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
808 <warning><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
809 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
810 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
811 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
812 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
813 current settings saved in the session file.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
814 </para></warning>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
815 </refsect1>
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 </refentry>
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 <!-- }}} -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
820 <!-- {{{ ecosynth user interface -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
821
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
822 <refentry id="synth-gui">
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
823 <refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
824 <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
825 </refmeta>
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 <refname>User Interface</refname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
828 <refpurpose>Controlling the I/O Auxiliary</refpurpose>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
829 </refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
830
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
831 <refsect1 id="synth-gui-description"><title>Description</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
832 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
833 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
834 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
835 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
836 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
837 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
838 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
839 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
840 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
841 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
842 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
843 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
844 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
845 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
846 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
847 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
848 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
849 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
850 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
851 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
852 <imageobject>
815
02b0482eacef * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 700
diff changeset
853 <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
854 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
855 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
856 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
857 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
858 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
859 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
860 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
861 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
862 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
863 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
864 and paste. Balloon help is supported.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
865 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
866 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
867 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
868 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
869 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
870 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
871 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
872 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
873 running.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
874 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
875 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
876
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
877 <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
878 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
879 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
880 <guimenu>File</guimenu>, <guimenu>Edit</guimenu>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
881 <guimenu>View</guimenu> and <guimenu>Help</guimenu>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
882 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
883 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
884 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
885 <imageobject>
815
02b0482eacef * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 700
diff changeset
886 <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
887 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
888 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
889 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
890 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
891 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
892 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
893 <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
894 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
895 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
896 previous <guimenuitem>Save</guimenuitem> or <guimenuitem>Save
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
897 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
898 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
899 <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
900 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
901 <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
902 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
903 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
904 with partial savefiles.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
905 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
906 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
907 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
908 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
909 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
910 own <command>kill</command> command. Alternatively the eCos
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
911 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
912 <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
913 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
914 <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
915 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
916 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
917 <constant>SIGKILL</constant> will be used.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
918 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
919 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
920 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
921 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
922 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
923 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
924 <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
925 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
926 arguments <link
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
927 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
928 <link
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
929 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
930 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
931 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
932 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
933 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
934 terminate the application cleanly, and then exit.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
935 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
936 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
937 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
938 <imageobject>
815
02b0482eacef * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 700
diff changeset
939 <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
940 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
941 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
942 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
943 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
944 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
945 text manipulation: <guimenuitem>Cut</guimenuitem>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
946 <guimenuitem>Copy</guimenuitem>, <guimenuitem>Paste</guimenuitem>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
947 <guimenuitem>Clear</guimenuitem> and <guimenuitem>Select
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
948 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
949 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
950 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
951 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
952 should be toggled.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
953 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
954 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
955 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
956 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
957 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
958 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
959 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
960 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
961 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
962 viewer.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
963 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
964 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
965 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
966 <imageobject>
815
02b0482eacef * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 700
diff changeset
967 <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
968 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
969 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
970 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
971 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
972 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
973 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
974 <link linkend="synth-gui-text">filters</link>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
975 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
976 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
977 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
978 <imageobject>
815
02b0482eacef * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 700
diff changeset
979 <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
980 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
981 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
982 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
983 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
984 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
985 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
986 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
987 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
988 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
989 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
990 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
991 <imageobject>
815
02b0482eacef * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 700
diff changeset
992 <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
993 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
994 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
995 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
996 <note><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
997 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
998 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
999 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
1000 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
1001 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
1002 environment variable.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1003 </para></note>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1004
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1005 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1006
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1007 <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
1008 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1009 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
1010 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
1011 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
1012 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
1013 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
1014 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
1015 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
1016 the order in which events occur.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1017 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1018 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1019 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
1020 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
1021 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
1022 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
1023 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
1024 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
1025 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
1026 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
1027 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
1028 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
1029 console output.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1030 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1031 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1032 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
1033 <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
1034 example entry might be:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1035 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1036 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1037 filter trace {^TRACE:.*} -foreground HotPink1 -hide 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1038 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1039 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1040 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
1041 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
1042 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
1043 the following:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1044 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1045 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1046 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1047 <imageobject>
815
02b0482eacef * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 700
diff changeset
1048 <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
1049 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1050 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1051 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1052 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1053 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
1054 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
1055 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
1056 received, rather than being displayed immediately. This avoids
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1057 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
1058 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1059 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1060 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
1061 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
1062 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
1063 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
1064 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
1065 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
1066 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
1067 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
1068 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1069 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1070
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1071 <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
1072 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1073 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
1074 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
1075 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
1076 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
1077 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
1078 the display.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1079 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1080 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1081 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1082 <imageobject>
815
02b0482eacef * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 700
diff changeset
1083 <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
1084 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1085 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1086 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1087 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1088 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
1089 central text window: <varname>.main.nw</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1090 <varname>.main.n</varname>, <varname>.main.ne</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1091 <varname>.main.w</varname>, <varname>.main.e</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1092 <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
1093 <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
1094 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
1095 entry such as:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1096 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1097 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1098 synth_device led {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1099 pack -in .main.n -side left
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1100 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1101 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1102 </programlisting>
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 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
1105 window would involve something like:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1106 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1107 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1108 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1109 monitor_pack -in .main.e -side bottom
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1110 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1111 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1112 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1113 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
1114 <constant>left</constant>, <constant>right</constant>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1115 <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
1116 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
1117 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
1118 should be consulted.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1119 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1120 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1121
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1122 <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
1123 <note><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1124 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
1125 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
1126 such as the main foreground and background colours.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1127 </para></note>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1128 </refsect1>
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 </refentry>
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 <!-- }}} -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1133 <!-- {{{ The console device -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1134
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1135 <refentry id="synth-console">
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1136 <refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1137 <refentrytitle>The Console Device</refentrytitle>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1138 </refmeta>
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 <refname>The console device </refname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1141 <refpurpose>Show output from the eCos application</refpurpose>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1142 </refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1143
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1144 <refsect1 id="synth-console-description"><title>Description</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1145 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1146 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
1147 including calling <function>printf</function> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1148 <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
1149 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
1150 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
1151 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
1152 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
1153 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
1154 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
1155 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
1156 certain types of text.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1157 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1158 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1159 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
1160 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
1161 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
1162 <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
1163 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
1164 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
1165 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
1166 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
1167 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
1168 of.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1169 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1170 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1171 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
1172 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
1173 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
1174 host-side code.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1175 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1176 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1177
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1178 <refsect1 id="synth-console-install"><title>Installation</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1179 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1180 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
1181 architectural HAL itself, in the source file
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1182 <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
1183 package. Similarly the host-side implementation,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1184 <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
1185 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
1186 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
1187 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1188 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1189
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1190 <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
1191 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1192 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
1193 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
1194 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
1195 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
1196 body of a <command>synth_device</command> entry:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1197 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1198 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1199 synth_device console {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1200 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1201 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1202 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1203 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1204 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
1205 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
1206 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
1207 argument as any other filter, for example:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1208 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1209 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1210 synth_device console {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1211 appearance -foreground white -background black
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1212 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1213 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1214 </programlisting>
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 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
1217 <command>filter</command> option, for example:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1218 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1219 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1220 synth_device console {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1221 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1222 filter trace {^TRACE:.*} -foreground HotPink1 -hide 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1223 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1224 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1225 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1226 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1227 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
1228 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
1229 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
1230 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
1231 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
1232 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
1233 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
1234 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
1235 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
1236 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
1237 only the first match will be used.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1238 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1239 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1240
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1241 <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
1242 Configuration Options</title>
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 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
1245 device.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1246 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1247 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1248
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1249 <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
1250 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1251 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
1252 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1253 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1254
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1255 <refsect1 id="synth-console-hooks"><title>Hooks</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1256 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1257 The console device does not provide any hooks.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1258 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1259 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1260
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1261 <refsect1><title>Additional Tcl Procedures</title>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1262 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1263 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
1264 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
1265 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1266 </refsect1>
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 </refentry>
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 <!-- }}} -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1271 <!-- {{{ System calls -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1272
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1273 <refentry id="synth-syscalls">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1274 <refmeta>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1275 <refentrytitle>System Calls</refentrytitle>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1276 </refmeta>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1277
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 <refname>cyg_hal_sys_xyz</refname>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1280 <refpurpose>Access Linux system facilities</refpurpose>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1281 </refnamediv>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1282
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1283 <refsynopsisdiv>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1284 <funcsynopsis>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1285 <funcsynopsisinfo>
700
9a2b440cee5d * doc/overview.gif, doc/overview.fig: renamed to
jlarmour
parents: 332
diff changeset
1286 #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
1287 </funcsynopsisinfo>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1288 <funcprototype>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1289 <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
1290 <varargs>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1291 </funcprototype>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1292 </funcsynopsis>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1293 </refsynopsisdiv>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1294
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1295 <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
1296 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1297 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
1298 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
1299 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
1300 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
1301 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
1302 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
1303 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
1304 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
1305 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
1306 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
1307 underlying Linux kernel to implement it.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1308 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1309 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1310 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
1311 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
1312 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
1313 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
1314 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
1315 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
1316 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
1317 <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
1318 <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
1319 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
1320 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
1321 file will define a matching constant
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1322 <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
1323 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
1324 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
1325 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1326 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1327 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
1328 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
1329 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
1330 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
1331 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
1332 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
1333 underlying system call and hence the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1334 <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
1335 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
1336 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
1337 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
1338 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
1339 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1340 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1341 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
1342 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
1343 longer appropriate. For example the original
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1344 <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
1345 <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
1346 <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
1347 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
1348 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
1349 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
1350 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
1351 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
1352 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
1353 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
1354 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1355 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1356 eCos packages and applications should never
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1357 <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
1358 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
1359 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
1360 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
1361 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
1362 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
1363 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
1364 <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
1365 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
1366 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
1367 licensing complications.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1368 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1369 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1370 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
1371 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
1372 appropriate platform HAL, for example
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1373 <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
1374 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
1375 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
1376 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
1377 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
1378 GNU C library sources.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1379 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1380 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1381 </refentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1382
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
1383 <!-- }}} -->
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1384 <!-- {{{ New devices - target-side -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1385
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1386 <refentry id="synth-new-target">
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1387 <refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1388 <refentrytitle>Writing New Devices - target</refentrytitle>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1389 </refmeta>
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 <refname>Writing New Devices</refname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1392 <refpurpose>extending the synthetic target, target-side</refpurpose>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1393 </refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1394
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1395 <refsynopsisdiv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1396 <funcsynopsis>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1397 <funcsynopsisinfo>
700
9a2b440cee5d * doc/overview.gif, doc/overview.fig: renamed to
jlarmour
parents: 332
diff changeset
1398 #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
1399 </funcsynopsisinfo>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1400
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1401 <funcprototype>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1402 <funcdef>int <function>synth_auxiliary_instantiate</function></funcdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1403 <paramdef>const char* <parameter>package</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1404 <paramdef>const char* <parameter>version</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1405 <paramdef>const char* <parameter>device</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1406 <paramdef>const char* <parameter>instance</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1407 <paramdef>const char* <parameter>data</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1408 </funcprototype>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1409 <funcprototype>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1410 <funcdef>void <function>synth_auxiliary_xchgmsg</function></funcdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1411 <paramdef>int <parameter>device_id</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1412 <paramdef>int <parameter>request</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1413 <paramdef>int <parameter>arg1</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1414 <paramdef>int <parameter>arg2</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1415 <paramdef>const unsigned char* <parameter>txdata</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1416 <paramdef>int <parameter>txlen</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1417 <paramdef>int* <parameter>reply</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1418 <paramdef>unsigned char* <parameter>rxdata</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1419 <paramdef>int* <parameter>rxlen</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1420 <paramdef>int <parameter>max_rxlen</parameter></paramdef>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1421 </funcprototype>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1422 </funcsynopsis>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1423 </refsynopsisdiv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1424
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1425 <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
1426 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1427 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
1428 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
1429 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
1430 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
1431 <function>send</function>, <function>recv</function> and similar
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1432 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
1433 contains ISR and DSR functions and will call
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1434 <function>cyg_drv_interrupt_create</function>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1435 <function>cyg_drv_interrupt_acknowledge</function>, and related
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1436 functions.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1437 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1438 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1439 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
1440 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
1441 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
1442 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
1443 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
1444 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
1445 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
1446 <function>synth_auxiliary_xchgmsg</function> for this purpose.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1447 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1448 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1449 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
1450 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
1451 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
1452 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
1453 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
1454 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
1455 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
1456 an instantiation procedure within that script.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1457 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1458 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1459 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
1460 <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
1461 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
1462 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
1463 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
1464 <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
1465 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1466 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1467
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1468 <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
1469 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1470 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
1471 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
1472 <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
1473 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
1474 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
1475 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
1476 <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
1477 visible.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1478 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1479 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1480 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
1481 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
1482 <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
1483 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
1484 code like the following can be used:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1485 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1486 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1487 #include &lt;cyg/infra/cyg_type.h&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1488 class mydev_init {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1489 public:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1490 mydev_init() {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1491 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1492 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1493 };
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1494 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
1495 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1496 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1497 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
1498 <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
1499 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
1500 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
1501 relevant file in <filename>libextras.a</filename>:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1502 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1503 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1504 cdl_package CYGPKG_DEVS_MINE {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1505 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1506 compile -library=libextras.a init.cxx
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1507 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1508 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1509 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1510 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
1511 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
1512 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
1513 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1514 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1515 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
1516 <function>synth_auxiliary_instantiate</function>. This takes five
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1517 arguments, all of which should be strings:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1518 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1519 <variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1520 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1521 <term><varname>package</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1522 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1523 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
1524 path relative to the eCos repository, for example
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1525 <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
1526 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
1527 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
1528 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
1529 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
1530 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
1531 instead.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1532 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1533 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1534 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1535 <term><varname>version</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1536 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1537 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
1538 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
1539 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
1540 <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
1541 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
1542 used.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1543 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1544 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1545 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1546 <term><varname>device</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1547 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1548 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
1549 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
1550 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
1551 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
1552 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
1553 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
1554 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
1555 device instance.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1556 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1557 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1558 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1559 <term><varname>instance</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1560 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1561 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
1562 argument identifies the particular instance, for example
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1563 <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
1564 pointer can be used.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1565 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1566 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1567 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1568 <term><varname>data</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1569 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1570 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
1571 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
1572 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
1573 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
1574 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
1575 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
1576 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
1577 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
1578 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
1579 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
1580 avoid possible buffer overflow problems.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1581 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1582 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1583 </variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1584 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1585 Typical usage would look like:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1586 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1587 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1588 if (!synth_auxiliary_running) {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1589 return;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1590 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1591 id = synth_auxiliary_instantiate("devs/eth/synth/ecosynth",
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1592 SYNTH_MAKESTRING(CYGPKG_DEVS_ETH_ECOSYNTH),
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1593 "ethernet",
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1594 "eth0",
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1595 (const char*) 0);
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1596 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1597 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1598 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
1599 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
1600 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
1601 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
1602 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
1603 target-side code should fail silently.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1604 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1605 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1606 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
1607 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
1608 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
1609 host-side about the MAC address, the <link
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1610 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
1611 whether or not multicasting is supported.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1612 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1613 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1614
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1615 <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
1616 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1617 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
1618 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
1619 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
1620 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
1621 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
1622 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
1623 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
1624 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1625 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1626 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
1627 <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
1628 arguments:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1629 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1630 <variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1631 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1632 <term><varname>device_id</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1633 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1634 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
1635 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
1636 particular device which should perform some I/O.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1637 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1638 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1639 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1640 <term><varname>request</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1641 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1642 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
1643 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
1644 each type of device can define its own.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1645 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1646 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1647 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1648 <term><varname>arg1</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1649 <term><varname>arg2</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1650 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1651 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
1652 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
1653 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
1654 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
1655 <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
1656 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
1657 device-specific Tcl script.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1658 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1659 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1660 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1661 <term><varname>txdata</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1662 <term><varname>txlen</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1663 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1664 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
1665 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
1666 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
1667 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
1668 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
1669 <varname>txdata</varname> is an arbitrary buffer of
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1670 <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
1671 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
1672 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
1673 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
1674 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1675 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1676 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1677 <term><varname>reply</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1678 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1679 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
1680 <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
1681 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
1682 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
1683 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
1684 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
1685 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
1686 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
1687 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1688 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1689 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1690 <term><varname>rxdata</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1691 <term><varname>rxlen</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1692 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1693 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
1694 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
1695 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
1696 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
1697 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
1698 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
1699 <varname>reply</varname> argument was not NULL.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1700 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1701 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1702 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1703 <term><varname>max_rxlen</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1704 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1705 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
1706 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
1707 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
1708 <varname>rxdata</varname> buffer.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1709 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1710 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1711 </variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1712 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1713 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
1714 transmitting an ethernet packet would use the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1715 <varname>request</varname>, <varname>txdata</varname> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1716 <varname>txlen</varname> fields (in addition to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1717 <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
1718 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
1719 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
1720 <varname>request</varname>, <varname>rxdata</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1721 <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
1722 <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
1723 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
1724 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
1725 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
1726 but none of the remaining arguments.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1727 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1728 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1729
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1730 <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
1731 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1732 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
1733 real target. An interrupt object is created using
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1734 <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
1735 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
1736 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
1737 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
1738 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
1739 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
1740 nested interrupts, interrupt priorities, or a separate interrupt
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1741 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
1742 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
1743 the simple emulation provided by the synthetic target.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1744 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1745 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1746 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
1747 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
1748 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
1749 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
1750 synthetic target driver will instead call
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1751 <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
1752 operations.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1753 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1754 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1755 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
1756 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
1757 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
1758 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
1759 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
1760 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
1761 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
1762 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
1763 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
1764 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
1765 reserved for the real-time clock.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1766 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1767 </refsect1>
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 </refentry>
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 <!-- }}} -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1772 <!-- {{{ New devices - host-side -->
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1773
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1774 <refentry id="synth-new-host">
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1775 <refmeta>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1776 <refentrytitle>Writing New Devices - host</refentrytitle>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1777 </refmeta>
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 <refname>Writing New Devices</refname>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1780 <refpurpose>extending the synthetic target, host-side</refpurpose>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1781 </refnamediv>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1782
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1783 <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
1784 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1785 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
1786 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
1787 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
1788 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
1789 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
1790 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
1791 support.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1792 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1793 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1794 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
1795 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
1796 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
1797 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
1798 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
1799 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
1800 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
1801 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
1802 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
1803 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
1804 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
1805 <filename>ethernet.tcl</filename> script which implements the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1806 host-side ethernet support spawns a separate program
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1807 <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
1808 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
1809 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
1810 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
1811 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
1812 loaded Tcl scripts.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1813 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1814 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1815 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
1816 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
1817 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
1818 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
1819 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
1820 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
1821 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
1822 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1823 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1824
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1825 <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
1826 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1827 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
1828 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
1829 third argument to <function>synth_auxiliary_instantiate</function>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1830 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
1831 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
1832 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
1833 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1834 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1835 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
1836 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
1837 current directory, then in <filename
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1838 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
1839 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
1840 support files below <filename
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1841 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
1842 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
1843 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
1844 <filename class="directory">libexec/ecos</filename> matches the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1845 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
1846 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
1847 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1848 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1849 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
1850 <command>autoconf</command> and <command>automake</command>. Usually
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1851 this involves little more than copying the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1852 <filename>acinclude.m4</filename>, <filename>configure.in</filename>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1853 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
1854 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
1855 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
1856 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
1857 <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
1858 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
1859 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
1860 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
1861 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
1862 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
1863 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
1864 then be processed using <command>aclocal</command>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1865 <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
1866 order. Actually building the software then just involves
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1867 <command>configure</command>, <command>make</command> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1868 <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
1869 toplevel <filename>README.host</filename> file.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1870 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1871 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1872 To assist developers, if the environment variable
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1873 <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
1874 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
1875 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
1876 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
1877 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
1878 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
1879 install</command> all the time.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1880 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1881 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1882 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
1883 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
1884 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
1885 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
1886 variable.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1887 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1888 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1889
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1890 <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
1891 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1892 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
1893 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
1894 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
1895 invoked to instantiate a device.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1896 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1897 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1898 namespace eval ethernet {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1899 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1900 proc instantiate { id instance data } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1901 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1902 return ethernet::handle_request
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1903 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1904 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1905 return ethernet::instantiate
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1906 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1907 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1908 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
1909 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
1910 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
1911 <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
1912 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
1913 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
1914 <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
1915 <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
1916 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
1917 <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
1918 arbitrary initialization parameters from target to host.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1919 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1920 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1921 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
1922 device-specific. It may involve allocating an <link
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1923 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
1924 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
1925 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
1926 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
1927 the above.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1928 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1929 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1930 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
1931 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
1932 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
1933 <function>synth_auxiliary_instantiate</function> call will return
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1934 <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
1935 <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
1936 why the device could not be instantiated.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1937 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1938 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1939
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1940 <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
1941 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1942 When the target-side calls
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1943 <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
1944 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
1945 returned during instantiation:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1946 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1947 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1948 namespace eval ethernet {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1949 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1950 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
1951 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1952 if { &lt;some condition&gt; } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1953 synth::send_reply &lt;error code&gt; 0 ""
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1954 return
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 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
1958 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1959 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1960 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1961 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1962 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1963 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
1964 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
1965 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
1966 <varname>arg1</varname>, <varname>arg2</varname>, and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1967 <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
1968 <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
1969 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
1970 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
1971 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
1972 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
1973 <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
1974 <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
1975 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
1976 convenience, although <command>string length $txdata</command> would
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1977 give the same information.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1978 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1979 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1980 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
1981 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
1982 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
1983 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
1984 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
1985 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
1986 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
1987 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
1988 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
1989 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
1990 and an empty string respectively.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1991 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1992 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1993 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
1994 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
1995 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
1996 result in run-time error messages.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1997 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1998 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
1999 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
2000 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
2001 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
2002 should be raised.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2003 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2004 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2005
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2006 <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
2007 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2008 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
2009 handling.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2010 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2011 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2012 synth::interrupt_allocate &lt;name&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2013 synth::interrupt_get_max
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2014 synth::interrupt_get_devicename &lt;vector&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2015 synth::interrupt_raise &lt;vector&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2016 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2017 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2018 <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
2019 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
2020 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
2021 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
2022 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
2023 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
2024 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
2025 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
2026 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
2027 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
2028 <literal>interrupt</literal> <link
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2029 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
2030 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
2031 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
2032 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2033 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2034 <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
2035 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
2036 there have been no calls to
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2037 <command>synth::interrupt_allocate</command>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2038 <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
2039 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
2040 the vector was allocated.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2041 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2042 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2043 <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
2044 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
2045 <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
2046 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
2047 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
2048 masked out, the appropriate ISR will run.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2049 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2050 <note><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2051 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
2052 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
2053 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
2054 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
2055 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
2056 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
2057 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
2058 requests for vectors that have already been allocated.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2059 </para></note>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2060 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2061
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2062 <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
2063 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2064 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
2065 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
2066 these should be checked by device-specific scripts.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2067 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2068 <variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2069 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2070 <term><varname>synth::flag_gui</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2071 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2072 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
2073 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
2074 layout are only available in graphical mode.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2075 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2076 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2077 if { $synth::flag_gui } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2078 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2079 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2080 </programlisting></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2081 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2082 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2083 <term><varname>synth::flag_verbose</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2084 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2085 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
2086 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
2087 should be produced.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2088 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2089 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2090 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2091 <term><varname>synth::flag_keep_going</varname></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2092 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2093 The user has specified <option>-k</option> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2094 <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
2095 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
2096 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
2097 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2098 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2099 </variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2100 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2101 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
2102 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
2103 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
2104 The following Tcl procedures are available:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2105 </para>
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 synth::argv_defined &lt;name&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2108 synth::argv_get_value &lt;name&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2109 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2110 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2111 <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
2112 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
2113 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
2114 should be appended. Typical uses might be:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2115 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2116 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2117 if { [synth::argv_defined "-o13"] } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2118 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2119 }
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 if { [synth::argv_defined "-mark="] } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2122 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2123 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2124 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2125 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2126 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
2127 <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
2128 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
2129 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
2130 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
2131 name/value pair can be obtained using
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2132 <command>synth::argv_get_value</command>;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2133 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2134 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2135 variable speed 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2136 if { [synth::argv_defined "-mark="] } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2137 set mark [synth::argv_get_value "-mark="]
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2138 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
2139 &lt;issue diagnostic&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2140 } else {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2141 set speed $mark
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2142 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2143 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2144 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2145 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2146 <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
2147 successful call to <command>synth::argv_defined</command>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2148 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
2149 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
2150 certain option such as <option>-v</option> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2151 <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
2152 of verbosity.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2153 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2154 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2155 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
2156 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
2157 <option>--help</option>. This involves a hook function:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2158 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2159 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2160 namespace eval my_device {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2161 proc help_hook { } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2162 puts " -o13 : activate the omega 13 device"
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2163 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
2164 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2165
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2166 synth::hook_add "help" my_device::help_hook
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 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2169 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2170
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2171 <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
2172 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2173 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
2174 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
2175 procedures for this are as follows:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2176 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2177 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2178 synth::tdf_has_device &lt;name&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2179 synth::tdf_get_devices
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2180 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
2181 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
2182 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
2183 synth::tdf_get_all_options &lt;devname&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2184 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2185 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2186 <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
2187 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
2188 <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
2189 will match the type of device, so the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2190 <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
2191 definition file entry <literal>console</literal>.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2192 <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
2193 device entries in the target definition file.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2194 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2195 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2196 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
2197 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
2198 <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
2199 returning a boolean:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2200 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2201 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2202 if { [synth::tdf_has_option "console" "appearance"] } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2203 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2204 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2205 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2206 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2207 <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
2208 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
2209 file contains an entry:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2210 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2211 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2212 synth_device console {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2213 appearance -foreground white -background black
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2214 filter trace {^TRACE:.*} -foreground HotPink1 -hide 1
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2215 filter xyzzy {.*xyzzy.*} -foreground PapayaWhip
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2216 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2217 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2218 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2219 A call
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2220 <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
2221 will return the list <literal>{-foreground white -background
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2222 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
2223 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
2224 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
2225 <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
2226 <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
2227 with one entry for each option occurrence.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2228 <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
2229 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
2230 well.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2231 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2232 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2233 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
2234 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
2235 <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
2236 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
2237 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
2238 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
2239 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
2240 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
2241 <command>synth:;tdf_get_option</command> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2242 <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
2243 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
2244 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2245 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2246
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2247 <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
2248 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2249 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
2250 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
2251 further I/O. This is supported using hooks:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2252 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2253 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2254 namespace eval my_device {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2255 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2256 proc handle_ecos_exit { arg_list } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2257 &hellip;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2258 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2259 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
2260 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2261 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2262 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2263 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
2264 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
2265 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
2266 The available Tcl procedures for manipulating hooks are:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2267 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2268 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2269 synth::hook_define &lt;name&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2270 synth::hook_defined &lt;name&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2271 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
2272 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
2273 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2274 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2275 <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
2276 specified name. This hook must not already exist.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2277 <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
2278 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
2279 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
2280 <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
2281 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
2282 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
2283 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
2284 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
2285 sufficiently defined. User scripts run from
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2286 <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
2287 defined.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2288 </para>
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 <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
2291 arguments, for example:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2292 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2293 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2294 synth::hook_call "ethernet_rx" "eth0" $packet
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2295 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2296 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2297 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
2298 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
2299 <command>synth::hook_call</command>:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2300 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2301 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2302 proc rx_callback { arg_list } {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2303 set device [lindex $arg_list 0]
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2304 set packet [lindex $arg_list 1]
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2305 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2306 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2307 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2308 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
2309 <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
2310 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
2311 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
2312 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
2313 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
2314 minor inconvenience when writing callbacks.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2315 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2316 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2317 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
2318 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
2319 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
2320 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2321 <variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2322 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2323 <term><literal>exit</literal></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2324 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2325 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
2326 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
2327 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
2328 empty.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2329 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2330 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2331 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2332 <term><literal>ecos_exit</literal></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2333 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2334 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
2335 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
2336 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
2337 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
2338 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2339 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2340 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2341 <term><literal>ecos_initialized</literal></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2342 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2343 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
2344 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
2345 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
2346 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
2347 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
2348 <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
2349 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
2350 argument list will be empty.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2351 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2352 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2353 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2354 <term><literal>help</literal></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2355 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2356 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
2357 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
2358 <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
2359 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
2360 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
2361 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2362 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2363 <varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2364 <term><literal>interrupt</literal></term>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2365 <listitem><para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2366 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
2367 <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
2368 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
2369 user scripts to monitor interrupt traffic.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2370 </para></listitem>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2371 </varlistentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2372 </variablelist>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2373 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2374
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2375 <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
2376 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2377 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
2378 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
2379 manipulating the central text widget
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2380 <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
2381 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
2382 itself:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2383 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2384 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2385 synth::report &lt;msg&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2386 synth::report_warning &lt;msg&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2387 synth::report_error &lt;msg&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2388 synth::internal_error &lt;msg&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2389 synth::output &lt;msg&gt; &lt;filter&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2390 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2391 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2392 <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
2393 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
2394 output resulting from <option>-v</option> or
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2395 <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
2396 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
2397 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
2398 <option>--logfile</option> will modify the behaviour.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2399 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2400 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2401 <command>synth::report_warning</command>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2402 <command>synth::report_error</command> and
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2403 <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
2404 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
2405 <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
2406 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
2407 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
2408 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
2409 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
2410 <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
2411 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
2412 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
2413 function.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2414 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2415 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2416 <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
2417 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
2418 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
2419 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
2420 be:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2421 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2422 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2423 synth::output $line "console"
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2424 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2425 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2426 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
2427 <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
2428 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
2429 <option>appearance</option> option in the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2430 <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
2431 definition file. The <guimenuitem>System filters</guimenuitem> menu
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2432 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
2433 </para>
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 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
2436 available for this are:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2437 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2438 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2439 synth::filter_exists &lt;name&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2440 synth::filter_get_list
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2441 synth::filter_add &lt;name&gt; [options]
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2442 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
2443 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
2444 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2445 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2446 <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
2447 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
2448 the same name is not allowed.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2449 <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
2450 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
2451 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
2452 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
2453 use might be:
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2454 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2455 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2456 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
2457 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2458 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2459 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
2460 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
2461 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
2462 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
2463 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2464 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2465 array set parsed_options [list]
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2466 set message ""
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2467 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
2468 synth::report_error \
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2469 "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
2470 \n synth_device \"console\", entry \"appearance\"\n$message"
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2471 } else {
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2472 synth::filter_add_parsed "console" parsed_options
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2473 }
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2474 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2475 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2476 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
2477 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
2478 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
2479 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
2480 parsing error that occurred.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2481 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2482 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2483
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2484 <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
2485 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2486 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
2487 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
2488 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
2489 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
2490 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
2491 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
2492 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
2493 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
2494 emulate real physical buttons.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2495 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2496 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2497 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
2498 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
2499 update the widget hierarchy directly.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2500 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2501 <informalfigure PgWide=1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2502 <mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2503 <imageobject>
815
02b0482eacef * doc/synth.sgml: Replaced .gif with .png to get PDF
jlarmour
parents: 700
diff changeset
2504 <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
2505 </imageobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2506 </mediaobject>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2507 </informalfigure>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2508 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2509 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
2510 <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
2511 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
2512 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
2513 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
2514 it into one of <varname>.main.nw</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2515 <varname>.main.n</varname>, <varname>.main.ne</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2516 <varname>.main.w</varname>, <varname>.main.e</varname>,
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2517 <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
2518 <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
2519 <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
2520 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
2521 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
2522 text output.
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 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2525 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
2526 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2527 <programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2528 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
2529 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
2530 synth::handle_help &lt;URL&gt;
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2531 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2532 <para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2533 <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
2534 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
2535 <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
2536 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
2537 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
2538 suitable diagnostics will be generated if necessary.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2539 </para>
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 <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
2542 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
2543 </para>
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 <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
2546 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
2547 </para>
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 .menubar.help add command -label "my device" -command \
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2550 [list synth::handle_help "file://$path"]
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2551 </programlisting>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2552 </refsect1>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2553
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2554 </refentry>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2555
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2556 <!-- }}} -->
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2557 <!-- {{{ Porting -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2558
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2559 <refentry id="synth-porting">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2560 <refmeta>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2561 <refentrytitle>Porting</refentrytitle>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2562 </refmeta>
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 <refname>Porting</refname>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2565 <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
2566 </refnamediv>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2567
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2568 <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
2569 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2570 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
2571 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
2572 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
2573 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
2574 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
2575 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
2576 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
2577 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
2578 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2579 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2580
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2581 <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
2582 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2583 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
2584 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
2585 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
2586 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
2587 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
2588 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
2589 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
2590 <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
2591 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
2592 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
2593 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2594 <para>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2595 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
2596 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
2597 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
2598 <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
2599 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
2600 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
2601 <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
2602 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
2603 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
2604 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
2605 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
2606 <function>linux_entry</function> function provided by the
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2607 architectural synthetic target HAL package.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2608 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2609 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2610 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
2611 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
2612 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
2613 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
2614 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
2615 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
2616 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2617 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2618 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
2619 <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
2620 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
2621 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
2622 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
2623 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
2624 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
2625 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
2626 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
2627 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2628 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2629 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
2630 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
2631 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
2632 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
2633 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
2634 various data types.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2635 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2636 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2637 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
2638 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
2639 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
2640 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
2641 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
2642 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
2643 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2644 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2645
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2646 <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
2647 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2648 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
2649 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
2650 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
2651 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
2652 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
2653 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
2654 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
2655 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
2656 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
2657 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
2658 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2659 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2660 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
2661 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
2662 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
2663 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
2664 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
2665 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
2666 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
2667 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
2668 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
2669 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
2670 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
2671 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
2672 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
2673 <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
2674 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
2675 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
2676 implemented at the variant HAL level.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2677 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2678 <para>
332
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2679 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
2680 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
2681 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
2682 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
2683 may prove quite difficult to port.
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2684 </para>
7c1c8dc43ba1 Now witness the firepower of this fully armed and operational
bartv
parents: 210
diff changeset
2685 <para>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2686 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
2687 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
2688 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
2689 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
2690 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2691 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2692 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
2693 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
2694 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
2695 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
2696 information.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2697 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2698 </refsect1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2699
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2700 <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
2701 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2702 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
2703 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
2704 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
2705 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
2706 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
2707 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
2708 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
2709 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
2710 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
2711 executables to be in PE format.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2712 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2713 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2714 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
2715 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
2716 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
2717 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
2718 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
2719 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
2720 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
2721 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
2722 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2723 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2724 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
2725 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
2726 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
2727 different releases of Windows.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2728 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2729 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2730 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
2731 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
2732 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
2733 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
2734 functionality is available under Windows.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2735 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2736 <para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2737 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
2738 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
2739 very large amount of effort.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2740 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2741 </refsect1>
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 </refentry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2744
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2745 <!-- }}} -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2746
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2747 </part>