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