1 |
24 |
jeremybenn |
This is a loose collection of notes for people hacking on simulators.
|
2 |
|
|
If this document gets big enough it can be prettied up then.
|
3 |
|
|
|
4 |
|
|
Contents
|
5 |
|
|
|
6 |
|
|
- The "common" directory
|
7 |
|
|
- Common Makefile Support
|
8 |
|
|
- TAGS support
|
9 |
|
|
- Generating "configure" files
|
10 |
|
|
- tconfig.in
|
11 |
|
|
- C Language Assumptions
|
12 |
|
|
- "dump" commands under gdb
|
13 |
|
|
|
14 |
|
|
The "common" directory
|
15 |
|
|
======================
|
16 |
|
|
|
17 |
|
|
The common directory contains:
|
18 |
|
|
|
19 |
|
|
- common documentation files (e.g. run.1, and maybe in time .texi files)
|
20 |
|
|
- common source files (e.g. run.c)
|
21 |
|
|
- common Makefile fragment and configury (e.g. Make-common.in, aclocal.m4).
|
22 |
|
|
|
23 |
|
|
In addition "common" contains portions of the system call support
|
24 |
|
|
(e.g. callback.c, nltvals.def).
|
25 |
|
|
|
26 |
|
|
Even though no files are built in this directory, it is still configured
|
27 |
|
|
so support for regenerating nltvals.def is present.
|
28 |
|
|
|
29 |
|
|
Common Makefile Support
|
30 |
|
|
=======================
|
31 |
|
|
|
32 |
|
|
A common configuration framework is available for simulators that want
|
33 |
|
|
to use it. The common framework exists to remove a lot of duplication
|
34 |
|
|
in configure.in and Makefile.in, and it also provides a foundation for
|
35 |
|
|
enhancing the simulators uniformly (e.g. the more they share in common
|
36 |
|
|
the easier a feature added to one is added to all).
|
37 |
|
|
|
38 |
|
|
The configure.in of a simulator using the common framework should look like:
|
39 |
|
|
|
40 |
|
|
--- snip ---
|
41 |
|
|
dnl Process this file with autoconf to produce a configure script.
|
42 |
|
|
sinclude(../common/aclocal.m4)
|
43 |
|
|
AC_PREREQ(2.5)dnl
|
44 |
|
|
AC_INIT(Makefile.in)
|
45 |
|
|
|
46 |
|
|
SIM_AC_COMMON
|
47 |
|
|
|
48 |
|
|
... target specific additions ...
|
49 |
|
|
|
50 |
|
|
SIM_AC_OUTPUT
|
51 |
|
|
--- snip ---
|
52 |
|
|
|
53 |
|
|
SIM_AC_COMMON:
|
54 |
|
|
|
55 |
|
|
- invokes the autoconf macros most often used by the simulators
|
56 |
|
|
- defines --enable/--with options usable by all simulators
|
57 |
|
|
- initializes sim_link_files/sim_link_links as the set of symbolic links
|
58 |
|
|
to set up
|
59 |
|
|
|
60 |
|
|
SIM_AC_OUTPUT:
|
61 |
|
|
|
62 |
|
|
- creates the symbolic links defined in sim_link_{files,links}
|
63 |
|
|
- creates config.h
|
64 |
|
|
- creates the Makefile
|
65 |
|
|
|
66 |
|
|
The Makefile.in of a simulator using the common framework should look like:
|
67 |
|
|
|
68 |
|
|
--- snip ---
|
69 |
|
|
# Makefile for blah ...
|
70 |
|
|
# Copyright blah ...
|
71 |
|
|
|
72 |
|
|
## COMMON_PRE_CONFIG_FRAG
|
73 |
|
|
|
74 |
|
|
# These variables are given default values in COMMON_PRE_CONFIG_FRAG.
|
75 |
|
|
# We override the ones we need to here.
|
76 |
|
|
# Not all of these need to be mentioned, only the necessary ones.
|
77 |
|
|
# In fact it is better to *not* mention ones if the value is the default.
|
78 |
|
|
|
79 |
|
|
# List of object files, less common parts.
|
80 |
|
|
SIM_OBJS =
|
81 |
|
|
# List of extra dependencies.
|
82 |
|
|
# Generally this consists of simulator specific files included by sim-main.h.
|
83 |
|
|
SIM_EXTRA_DEPS =
|
84 |
|
|
# List of flags to always pass to $(CC).
|
85 |
|
|
SIM_EXTRA_CFLAGS =
|
86 |
|
|
# List of extra libraries to link with.
|
87 |
|
|
SIM_EXTRA_LIBS =
|
88 |
|
|
# List of extra program dependencies.
|
89 |
|
|
SIM_EXTRA_LIBDEPS =
|
90 |
|
|
# List of main object files for `run'.
|
91 |
|
|
SIM_RUN_OBJS = run.o
|
92 |
|
|
# Dependency of `all' to build any extra files.
|
93 |
|
|
SIM_EXTRA_ALL =
|
94 |
|
|
# Dependency of `install' to install any extra files.
|
95 |
|
|
SIM_EXTRA_INSTALL =
|
96 |
|
|
# Dependency of `clean' to clean any extra files.
|
97 |
|
|
SIM_EXTRA_CLEAN =
|
98 |
|
|
|
99 |
|
|
## COMMON_POST_CONFIG_FRAG
|
100 |
|
|
|
101 |
|
|
# Rules need to build $(SIM_OBJS), plus whatever else the target wants.
|
102 |
|
|
|
103 |
|
|
... target specific rules ...
|
104 |
|
|
--- snip ---
|
105 |
|
|
|
106 |
|
|
COMMON_{PRE,POST}_CONFIG_FRAG are markers for SIM_AC_OUTPUT to tell it
|
107 |
|
|
where to insert the two pieces of common/Make-common.in.
|
108 |
|
|
The resulting Makefile is created by doing autoconf substitions on
|
109 |
|
|
both the target's Makefile.in and Make-common.in, and inserting
|
110 |
|
|
the two pieces of Make-common.in into the target's Makefile.in at
|
111 |
|
|
COMMON_{PRE,POST}_CONFIG_FRAG.
|
112 |
|
|
|
113 |
|
|
Note that SIM_EXTRA_{INSTALL,CLEAN} could be removed and "::" targets
|
114 |
|
|
could be used instead. However, it's not clear yet whether "::" targets
|
115 |
|
|
are portable enough.
|
116 |
|
|
|
117 |
|
|
TAGS support
|
118 |
|
|
============
|
119 |
|
|
|
120 |
|
|
Many files generate program symbols at compile time.
|
121 |
|
|
Such symbols can't be found with grep nor do they normally appear in
|
122 |
|
|
the TAGS file. To get around this, source files can add the comment
|
123 |
|
|
|
124 |
|
|
/* TAGS: foo1 foo2 */
|
125 |
|
|
|
126 |
|
|
where foo1, foo2 are program symbols. Symbols found in such comments
|
127 |
|
|
are greppable and appear in the TAGS file.
|
128 |
|
|
|
129 |
|
|
Generating "configure" files
|
130 |
|
|
============================
|
131 |
|
|
|
132 |
|
|
For targets using the common framework, "configure" can be generated
|
133 |
|
|
by running `autoconf'.
|
134 |
|
|
|
135 |
|
|
To regenerate the configure files for all targets using the common framework:
|
136 |
|
|
|
137 |
|
|
$ cd devo/sim
|
138 |
|
|
$ make -f Makefile.in SHELL=/bin/sh autoconf-common
|
139 |
|
|
|
140 |
|
|
To add a change-log entry to the ChangeLog file for each updated
|
141 |
|
|
directory (WARNING - check the modified new-ChangeLog files before
|
142 |
|
|
renaming):
|
143 |
|
|
|
144 |
|
|
$ make -f Makefile.in SHELL=/bin/sh autoconf-changelog
|
145 |
|
|
$ more */new-ChangeLog
|
146 |
|
|
$ make -f Makefile.in SHELL=/bin/sh autoconf-install
|
147 |
|
|
|
148 |
|
|
In a similar vein, both the configure and config.in files can be
|
149 |
|
|
updated using the sequence:
|
150 |
|
|
|
151 |
|
|
$ cd devo/sim
|
152 |
|
|
$ make -f Makefile.in SHELL=/bin/sh autoheader-common
|
153 |
|
|
$ make -f Makefile.in SHELL=/bin/sh autoheader-changelog
|
154 |
|
|
$ more */new-ChangeLog
|
155 |
|
|
$ make -f Makefile.in SHELL=/bin/sh autoheader-install
|
156 |
|
|
|
157 |
|
|
To add the entries to an alternative ChangeLog file, use:
|
158 |
|
|
|
159 |
|
|
$ make ChangeLog=MyChangeLog ....
|
160 |
|
|
|
161 |
|
|
|
162 |
|
|
tconfig.in
|
163 |
|
|
==========
|
164 |
|
|
|
165 |
|
|
File tconfig.in defines one or more target configuration macros
|
166 |
|
|
(e.g. a tm.h file). There are very few that need defining.
|
167 |
|
|
For a list of all of them, see common/tconfig.in.
|
168 |
|
|
It contains them all, commented out.
|
169 |
|
|
The intent is that a new port can just copy this file and
|
170 |
|
|
define the ones it needs.
|
171 |
|
|
|
172 |
|
|
C Language Assumptions
|
173 |
|
|
======================
|
174 |
|
|
|
175 |
|
|
The programmer may assume that the simulator is being built using an
|
176 |
|
|
ANSI C compiler that supports a 64 bit data type. Consequently:
|
177 |
|
|
|
178 |
|
|
o prototypes can be used (although using
|
179 |
|
|
PARAMS() and K&R declarations wouldn't
|
180 |
|
|
go astray).
|
181 |
|
|
|
182 |
|
|
o If sim-types.h is included, the two
|
183 |
|
|
types signed64 and unsigned64 are
|
184 |
|
|
available.
|
185 |
|
|
|
186 |
|
|
o The type `unsigned' is valid.
|
187 |
|
|
|
188 |
|
|
However, the user should be aware of the following:
|
189 |
|
|
|
190 |
|
|
o GCC's `LL' is NOT acceptable.
|
191 |
|
|
Microsoft-C doesn't reconize it.
|
192 |
|
|
|
193 |
|
|
o MSC's `i64' is NOT acceptable.
|
194 |
|
|
GCC doesn't reconize it.
|
195 |
|
|
|
196 |
|
|
o GCC's `long long' MSC's `_int64' can
|
197 |
|
|
NOT be used to define 64 bit integer data
|
198 |
|
|
types.
|
199 |
|
|
|
200 |
|
|
o An empty array (eg int a[0]) is not valid.
|
201 |
|
|
|
202 |
|
|
When building with GCC it is effectivly a requirement that
|
203 |
|
|
--enable-build-warnings=,-Werror be specified during configuration.
|
204 |
|
|
|
205 |
|
|
"dump" commands under gdb
|
206 |
|
|
=========================
|
207 |
|
|
|
208 |
|
|
gdbinit.in contains the following
|
209 |
|
|
|
210 |
|
|
define dump
|
211 |
|
|
set sim_debug_dump ()
|
212 |
|
|
end
|
213 |
|
|
|
214 |
|
|
Simulators that define the sim_debug_dump function can then have their
|
215 |
|
|
internal state pretty printed from gdb.
|
216 |
|
|
|
217 |
|
|
FIXME: This can obviously be made more elaborate. As needed it will be.
|
218 |
|
|
|
219 |
|
|
Rebuilding nltvals.def
|
220 |
|
|
======================
|
221 |
|
|
|
222 |
|
|
Checkout a copy of the SIM and LIBGLOSS modules (Unless you've already
|
223 |
|
|
got one to hand):
|
224 |
|
|
|
225 |
|
|
$ mkdir /tmp/$$
|
226 |
|
|
$ cd /tmp/$$
|
227 |
|
|
$ cvs checkout sim-no-testsuite libgloss-no-testsuite newlib-no-testsuite
|
228 |
|
|
|
229 |
|
|
Configure things for an arbitrary simulator target (I've d10v for
|
230 |
|
|
convenience):
|
231 |
|
|
|
232 |
|
|
$ mkdir /tmp/$$/build
|
233 |
|
|
$ cd /tmp/$$/build
|
234 |
|
|
$ /tmp/$$/devo/configure --target=d10v-elf
|
235 |
|
|
|
236 |
|
|
In the sim/common directory rebuild the headers:
|
237 |
|
|
|
238 |
|
|
$ cd sim/common
|
239 |
|
|
$ make headers
|
240 |
|
|
|
241 |
|
|
To add a new target:
|
242 |
|
|
|
243 |
|
|
devo/sim/common/gennltvals.sh
|
244 |
|
|
|
245 |
|
|
Add your new processor target (you'll need to grub
|
246 |
|
|
around to find where your syscall.h lives).
|
247 |
|
|
|
248 |
|
|
devo/sim//Makefile.in
|
249 |
|
|
|
250 |
|
|
Add the definition:
|
251 |
|
|
|
252 |
|
|
``NL_TARGET = -DNL_TARGET_d10v''
|
253 |
|
|
|
254 |
|
|
just before the line COMMON_POST_CONFIG_FRAG.
|
255 |
|
|
|
256 |
|
|
devo/sim//*.[ch]
|
257 |
|
|
|
258 |
|
|
Include targ-vals.h instead of syscall.h.
|
259 |
|
|
|