| 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 | |
| 157 | To add the entries to an alternative ChangeLog file, use: |
| 158 | |
| 159 | $ make ChangeLog=MyChangeLog .... |
| 160 | |
| 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 | |