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 |
b69cc8ab AC |
11 | \f |
12 | The "common" directory | |
13 | ====================== | |
14 | ||
15 | The common directory contains: | |
16 | ||
17 | - common documentation files (e.g. run.1, and maybe in time .texi files) | |
18 | - common source files (e.g. run.c) | |
19 | - common Makefile fragment and configury (e.g. Make-common.in, aclocal.m4). | |
20 | ||
21 | In addition "common" contains portions of the system call support | |
22 | (e.g. callback.c, nltvals.def). | |
23 | ||
24 | Even though no files are built in this directory, it is still configured | |
25 | so support for regenerating nltvals.def is present. | |
26 | \f | |
27 | Common Makefile Support | |
28 | ======================= | |
29 | ||
30 | A common configuration framework is available for simulators that want | |
31 | to use it. The common framework exists to remove a lot of duplication | |
32 | in configure.in and Makefile.in, and it also provides a foundation for | |
33 | enhancing the simulators uniformly (e.g. the more they share in common | |
34 | the easier a feature added to one is added to all). | |
35 | ||
36 | The configure.in of a simulator using the common framework should look like: | |
37 | ||
38 | --- snip --- | |
39 | dnl Process this file with autoconf to produce a configure script. | |
40 | sinclude(../common/aclocal.m4) | |
41 | AC_PREREQ(2.5)dnl | |
42 | AC_INIT(Makefile.in) | |
43 | ||
44 | SIM_AC_COMMON | |
45 | ||
46 | ... target specific additions ... | |
47 | ||
48 | SIM_AC_OUTPUT | |
49 | --- snip --- | |
50 | ||
51 | SIM_AC_COMMON: | |
52 | ||
53 | - invokes the autoconf macros most often used by the simulators | |
54 | - defines --enable/--with options usable by all simulators | |
55 | - initializes sim_link_files/sim_link_links as the set of symbolic links | |
56 | to set up | |
57 | ||
58 | SIM_AC_OUTPUT: | |
59 | ||
60 | - creates the symbolic links defined in sim_link_{files,links} | |
61 | - creates config.h | |
62 | - creates the Makefile | |
63 | ||
64 | The Makefile.in of a simulator using the common framework should look like: | |
65 | ||
66 | --- snip --- | |
67 | # Makefile for blah ... | |
68 | # Copyright blah ... | |
69 | ||
70 | ## COMMON_PRE_CONFIG_FRAG | |
71 | ||
72 | # These variables are given default values in COMMON_PRE_CONFIG_FRAG. | |
73 | # We override the ones we need to here. | |
74 | # Not all of these need to be mentioned, only the necessary ones. | |
51037f28 | 75 | # In fact it is better to *not* mention ones if the value is the default. |
b69cc8ab AC |
76 | |
77 | # List of object files, less common parts. | |
78 | SIM_OBJS = | |
51037f28 DE |
79 | # List of extra dependencies. |
80 | # Generally this consists of simulator specific files included by sim-main.h. | |
81 | SIM_EXTRA_DEPS = | |
b69cc8ab AC |
82 | # List of flags to always pass to $(CC). |
83 | SIM_EXTRA_CFLAGS = | |
84 | # List of extra libraries to link with. | |
85 | SIM_EXTRA_LIBS = | |
86 | # List of extra program dependencies. | |
87 | SIM_EXTRA_LIBDEPS = | |
88 | # List of main object files for `run'. | |
89 | SIM_RUN_OBJS = run.o | |
90 | # Dependency of `all' to build any extra files. | |
91 | SIM_EXTRA_ALL = | |
92 | # Dependency of `install' to install any extra files. | |
93 | SIM_EXTRA_INSTALL = | |
94 | # Dependency of `clean' to clean any extra files. | |
95 | SIM_EXTRA_CLEAN = | |
96 | ||
97 | ## COMMON_POST_CONFIG_FRAG | |
98 | ||
99 | # Rules need to build $(SIM_OBJS), plus whatever else the target wants. | |
100 | ||
101 | ... target specific rules ... | |
102 | --- snip --- | |
103 | ||
104 | COMMON_{PRE,POST}_CONFIG_FRAG are markers for SIM_AC_OUTPUT to tell it | |
105 | where to insert the two pieces of common/Make-common.in. | |
106 | The resulting Makefile is created by doing autoconf substitions on | |
107 | both the target's Makefile.in and Make-common.in, and inserting | |
108 | the two pieces of Make-common.in into the target's Makefile.in at | |
109 | COMMON_{PRE,POST}_CONFIG_FRAG. | |
51037f28 DE |
110 | |
111 | Note that SIM_EXTRA_{INSTALL,CLEAN} could be removed and "::" targets | |
112 | could be used instead. However, it's not clear yet whether "::" targets | |
113 | are portable enough. | |
114 | \f | |
115 | TAGS support | |
116 | ============ | |
117 | ||
118 | Many files generate program symbols at compile time. | |
119 | Such symbols can't be found with grep nor do they normally appear in | |
120 | the TAGS file. To get around this, source files can add the comment | |
121 | ||
122 | /* TAGS: foo1 foo2 */ | |
123 | ||
124 | where foo1, foo2 are program symbols. Symbols found in such comments | |
125 | are greppable and appear in the TAGS file. | |
b69cc8ab AC |
126 | \f |
127 | Generating "configure" files | |
128 | ============================ | |
129 | ||
130 | For target's using the common framework, "configure" can be generated | |
131 | by running autoconf. This works because configure.in contains | |
132 | "sinclude(../common/aclocal.m4)". | |
133 | ||
134 | To regenerate the configure files for all targets using the common framework: | |
135 | ||
136 | $ cd devo/sim | |
137 | $ make -f Makefile.in autoconf-common | |
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 | ||
143 | $ make -f Makefile.in autoconf-changelog | |
144 | $ more */new-ChangeLog | |
b04500b2 | 145 | $ make -f Makefile.in 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 | |
151 | $ make -f Makefile.in autoheader-common | |
152 | $ make -f Makefile.in autoheader-changelog | |
153 | $ more */new-ChangeLog | |
154 | $ make -f Makefile.in 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 | ||
182 | However, the user should not assume: | |
183 | ||
184 | o `<number>LL' is acceptable. Microsoft-C | |
185 | doesn't reconize it. | |
186 | ||
187 | o `long long' or `_int64' provides a 64 bit | |
188 | integer data type. |