This is a loose collection of notes for people hacking on simulators.
-If this document gets big enough it can be prettied it up then.
+If this document gets big enough it can be prettied up then.
Contents
- The "common" directory
- Common Makefile Support
+- TAGS support
- Generating "configure" files
+- tconfig.in
+- C Language Assumptions
+- "dump" commands under gdb
\f
The "common" directory
======================
--- snip ---
dnl Process this file with autoconf to produce a configure script.
-sinclude(../common/aclocal.m4)
AC_PREREQ(2.5)dnl
AC_INIT(Makefile.in)
# These variables are given default values in COMMON_PRE_CONFIG_FRAG.
# We override the ones we need to here.
# Not all of these need to be mentioned, only the necessary ones.
+# In fact it is better to *not* mention ones if the value is the default.
# List of object files, less common parts.
SIM_OBJS =
+# List of extra dependencies.
+# Generally this consists of simulator specific files included by sim-main.h.
+SIM_EXTRA_DEPS =
# List of flags to always pass to $(CC).
SIM_EXTRA_CFLAGS =
# List of extra libraries to link with.
both the target's Makefile.in and Make-common.in, and inserting
the two pieces of Make-common.in into the target's Makefile.in at
COMMON_{PRE,POST}_CONFIG_FRAG.
+
+Note that SIM_EXTRA_{INSTALL,CLEAN} could be removed and "::" targets
+could be used instead. However, it's not clear yet whether "::" targets
+are portable enough.
+\f
+TAGS support
+============
+
+Many files generate program symbols at compile time.
+Such symbols can't be found with grep nor do they normally appear in
+the TAGS file. To get around this, source files can add the comment
+
+/* TAGS: foo1 foo2 */
+
+where foo1, foo2 are program symbols. Symbols found in such comments
+are greppable and appear in the TAGS file.
\f
Generating "configure" files
============================
-For target's using the common framework, "configure" can be generated
-by running autoconf. This works because configure.in contains
-"sinclude(../common/aclocal.m4)".
+For targets using the common framework, "configure" can be generated
+by running `autoconf'.
To regenerate the configure files for all targets using the common framework:
$ cd devo/sim
- $ make -f Makefile.in autoconf-common
+ $ make -f Makefile.in SHELL=/bin/sh autoconf-common
To add a change-log entry to the ChangeLog file for each updated
directory (WARNING - check the modified new-ChangeLog files before
renaming):
- $ make -f Makefile.in autoconf-changelog
+ $ make -f Makefile.in SHELL=/bin/sh autoconf-changelog
$ more */new-ChangeLog
- $ make -f Makefile.in autoconf-install
+ $ make -f Makefile.in SHELL=/bin/sh autoconf-install
In a similar vein, both the configure and config.in files can be
updated using the sequence:
$ cd devo/sim
- $ make -f Makefile.in autoheader-common
- $ make -f Makefile.in autoheader-changelog
+ $ make -f Makefile.in SHELL=/bin/sh autoheader-common
+ $ make -f Makefile.in SHELL=/bin/sh autoheader-changelog
$ more */new-ChangeLog
- $ make -f Makefile.in autoheader-install
+ $ make -f Makefile.in SHELL=/bin/sh autoheader-install
+\f
+tconfig.in
+==========
+
+File tconfig.in defines one or more target configuration macros
+(e.g. a tm.h file). There are very few that need defining.
+For a list of all of them, see common/tconfig.in.
+It contains them all, commented out.
+The intent is that a new port can just copy this file and
+define the ones it needs.
+\f
+C Language Assumptions
+======================
+
+The programmer may assume that the simulator is being built using an
+ANSI C compiler that supports a 64 bit data type. Consequently:
+
+ o prototypes can be used (although using
+ PARAMS() and K&R declarations wouldn't
+ go astray).
+
+ o If sim-types.h is included, the two
+ types signed64 and unsigned64 are
+ available.
+
+ o The type `unsigned' is valid.
+
+However, the user should be aware of the following:
+
+ o GCC's `<number>LL' is NOT acceptable.
+ Microsoft-C doesn't reconize it.
+
+ o MSC's `<number>i64' is NOT acceptable.
+ GCC doesn't reconize it.
+
+ o GCC's `long long' MSC's `_int64' can
+ NOT be used to define 64 bit integer data
+ types.
+
+ o An empty array (eg int a[0]) is not valid.
+
+When building with GCC it is effectivly a requirement that
+--enable-sim-warnings be specified during configuration.
+\f
+"dump" commands under gdb
+=========================
+
+gdbinit.in contains the following
+
+define dump
+set sim_debug_dump ()
+end
+
+Simulators that define the sim_debug_dump function can then have their
+internal state pretty printed from gdb.
+
+FIXME: This can obviously be made more elaborate. As needed it will be.
+\f
+"dump" commands under gdb
+=========================
+
+gdbinit.in contains the following
+
+define dump
+set sim_debug_dump ()
+end
+
+Simulators that define the sim_debug_dump function can then have their
+internal state pretty printed from gdb.
+FIXME: This can obviously be made more elaborate. As needed it will be.
projects / deliverable / binutils-gdb.git / blobdiff