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 | ||
131 | For target's using the common framework, "configure" can be generated | |
c2816431 TT |
132 | by running `autoconf -l ../common'. This will ensure that the |
133 | qaclocal.m4 from the `common' directory is found. | |
b69cc8ab AC |
134 | |
135 | To regenerate the configure files for all targets using the common framework: | |
136 | ||
137 | $ cd devo/sim | |
c2816431 | 138 | $ make -f Makefile.in SHELL=/bin/sh autoconf-common |
b69cc8ab AC |
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 | ||
c2816431 | 144 | $ make -f Makefile.in SHELL=/bin/sh autoconf-changelog |
b69cc8ab | 145 | $ more */new-ChangeLog |
c2816431 | 146 | $ make -f Makefile.in SHELL=/bin/sh autoconf-install |
b69cc8ab | 147 | |
96527c4e AC |
148 | In a similar vein, both the configure and config.in files can be |
149 | updated using the sequence: | |
150 | ||
151 | $ cd devo/sim | |
c2816431 TT |
152 | $ make -f Makefile.in SHELL=/bin/sh autoheader-common |
153 | $ make -f Makefile.in SHELL=/bin/sh autoheader-changelog | |
96527c4e | 154 | $ more */new-ChangeLog |
c2816431 | 155 | $ make -f Makefile.in SHELL=/bin/sh autoheader-install |
51037f28 DE |
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. | |
b83adf4e AC |
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 | ||
c2816431 | 183 | However, the user should be aware of the following: |
b83adf4e | 184 | |
c2816431 TT |
185 | o GCC's `<number>LL' is NOT acceptable. |
186 | Microsoft-C doesn't reconize it. | |
b83adf4e | 187 | |
c2816431 TT |
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-sim-warnings 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 | "dump" commands under gdb | |
215 | ========================= | |
216 | ||
217 | gdbinit.in contains the following | |
218 | ||
219 | define dump | |
220 | set sim_debug_dump () | |
221 | end | |
222 | ||
223 | Simulators that define the sim_debug_dump function can then have their | |
224 | internal state pretty printed from gdb. | |
225 | ||
226 | FIXME: This can obviously be made more elaborate. As needed it will be. |