This commit was generated by cvs2svn to track changes on a CVS vendor
[platform/upstream/binutils.git] / sim / README-HACKING
1 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 \f
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 \f
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 \f
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 \f
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 \f
157 tconfig.in
158 ==========
159
160 File tconfig.in defines one or more target configuration macros
161 (e.g. a tm.h file).  There are very few that need defining.
162 For a list of all of them, see common/tconfig.in.
163 It contains them all, commented out.
164 The intent is that a new port can just copy this file and
165 define the ones it needs.
166 \f
167 C Language Assumptions
168 ======================
169
170 The programmer may assume that the simulator is being built using an
171 ANSI C compiler that supports a 64 bit data type.  Consequently:
172
173         o       prototypes can be used (although using
174                 PARAMS() and K&R declarations wouldn't
175                 go astray).
176
177         o       If sim-types.h is included, the two
178                 types signed64 and unsigned64 are
179                 available.
180
181         o       The type `unsigned' is valid.
182
183 However, the user should be aware of the following:
184
185         o       GCC's `<number>LL' is NOT acceptable.
186                 Microsoft-C doesn't reconize it.
187
188         o       MSC's `<number>i64' is NOT acceptable.
189                 GCC doesn't reconize it.
190
191         o       GCC's `long long' MSC's `_int64' can
192                 NOT be used to define 64 bit integer data
193                 types.
194
195         o       An empty array (eg int a[0]) is not valid.
196
197 When building with GCC it is effectivly a requirement that
198 --enable-build-warnings=,-Werror be specified during configuration.
199 \f
200 "dump" commands under gdb
201 =========================
202
203 gdbinit.in contains the following
204
205 define dump
206 set sim_debug_dump ()
207 end
208
209 Simulators that define the sim_debug_dump function can then have their
210 internal state pretty printed from gdb.
211
212 FIXME: This can obviously be made more elaborate.  As needed it will be.
213 \f
214 Rebuilding nltvals.def
215 ======================
216
217 Checkout a copy of the SIM and LIBGLOSS modules (Unless you've already
218 got one to hand):
219
220         $  mkdir /tmp/$$
221         $  cd /tmp/$$
222         $  cvs checkout sim-no-testsuite libgloss-no-testsuite newlib-no-testsuite
223
224 Configure things for an arbitrary simulator target (I've d10v for
225 convenience):
226
227         $  mkdir /tmp/$$/build
228         $  cd /tmp/$$/build
229         $  /tmp/$$/devo/configure --target=d10v-elf
230
231 In the sim/common directory rebuild the headers:
232
233         $  cd sim/common
234         $  make headers
235
236 To add a new target:
237
238         devo/sim/common/gennltvals.sh
239
240                 Add your new processor target (you'll need to grub
241                 around to find where your syscall.h lives).
242
243         devo/sim/<processor>/Makefile.in
244
245                 Add the definition:
246
247                         ``NL_TARGET = -DNL_TARGET_d10v''
248
249                 just before the line COMMON_POST_CONFIG_FRAG.
250
251         devo/sim/<processor>/*.[ch]
252
253                 Include targ-vals.h instead of syscall.h.
254