sim/README-HACKING

   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