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