Commit | Line | Data |
---|---|---|
c906108c SS |
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 | |
c93abbcc AC |
156 | |
157 | To add the entries to an alternative ChangeLog file, use: | |
158 | ||
159 | $ make ChangeLog=MyChangeLog .... | |
160 | ||
c906108c SS |
161 | \f |
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 | \f | |
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 `<number>LL' is NOT acceptable. | |
191 | Microsoft-C doesn't reconize it. | |
192 | ||
193 | o MSC's `<number>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 | \f | |
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 | \f | |
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/<processor>/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/<processor>/*.[ch] | |
257 | ||
258 | Include targ-vals.h instead of syscall.h. | |
259 |