Initial creation of sourceware repositorygdb-4_18-branchpoint

1 files changed, 254 insertions, 0 deletions

diff --git a/sim/README-HACKING b/sim/README-HACKING
new file mode 100644
index 00000000000..e4efeb155b0
--- /dev/null
+++ b/sim/README-HACKING
@@ -0,0 +1,254 @@
+This is a loose collection of notes for people hacking on simulators.
+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
+
+The "common" directory
+======================
+
+The common directory contains:
+
+- common documentation files (e.g. run.1, and maybe in time .texi files)
+- common source files (e.g. run.c)
+- common Makefile fragment and configury (e.g. Make-common.in, aclocal.m4).
+
+In addition "common" contains portions of the system call support
+(e.g. callback.c, nltvals.def).
+
+Even though no files are built in this directory, it is still configured
+so support for regenerating nltvals.def is present.
+
+Common Makefile Support
+=======================
+
+A common configuration framework is available for simulators that want
+to use it.  The common framework exists to remove a lot of duplication
+in configure.in and Makefile.in, and it also provides a foundation for
+enhancing the simulators uniformly (e.g. the more they share in common
+the easier a feature added to one is added to all).
+
+The configure.in of a simulator using the common framework should look like:
+
+--- 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)
+
+SIM_AC_COMMON
+
+... target specific additions ...
+
+SIM_AC_OUTPUT
+--- snip ---
+
+SIM_AC_COMMON:
+
+- invokes the autoconf macros most often used by the simulators
+- defines --enable/--with options usable by all simulators
+- initializes sim_link_files/sim_link_links as the set of symbolic links
+  to set up
+
+SIM_AC_OUTPUT:
+
+- creates the symbolic links defined in sim_link_{files,links}
+- creates config.h
+- creates the Makefile
+
+The Makefile.in of a simulator using the common framework should look like:
+
+--- snip ---
+# Makefile for blah ...
+# Copyright blah ...
+
+## COMMON_PRE_CONFIG_FRAG
+
+# 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.
+SIM_EXTRA_LIBS =
+# List of extra program dependencies.
+SIM_EXTRA_LIBDEPS =
+# List of main object files for `run'.
+SIM_RUN_OBJS = run.o
+# Dependency of `all' to build any extra files.
+SIM_EXTRA_ALL =
+# Dependency of `install' to install any extra files.
+SIM_EXTRA_INSTALL =
+# Dependency of `clean' to clean any extra files.
+SIM_EXTRA_CLEAN =
+
+## COMMON_POST_CONFIG_FRAG
+
+# Rules need to build $(SIM_OBJS), plus whatever else the target wants.
+
+... target specific rules ...
+--- snip ---
+
+COMMON_{PRE,POST}_CONFIG_FRAG are markers for SIM_AC_OUTPUT to tell it
+where to insert the two pieces of common/Make-common.in.
+The resulting Makefile is created by doing autoconf substitions on
+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.
+
+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.
+
+Generating "configure" files
+============================
+
+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 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 SHELL=/bin/sh autoconf-changelog
+	$  more */new-ChangeLog
+	$  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 SHELL=/bin/sh autoheader-common
+	$  make -f Makefile.in SHELL=/bin/sh autoheader-changelog
+	$  more */new-ChangeLog
+	$  make -f Makefile.in SHELL=/bin/sh autoheader-install
+
+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.
+
+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-build-warnings=,-Werror be specified during configuration.
+
+"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.
+
+Rebuilding nltvals.def
+======================
+
+Checkout a copy of the SIM and LIBGLOSS modules (Unless you've already
+got one to hand):
+
+	$  mkdir /tmp/$$
+	$  cd /tmp/$$
+	$  cvs checkout sim-no-testsuite libgloss-no-testsuite newlib-no-testsuite
+
+Configure things for an arbitrary simulator target (I've d10v for
+convenience):
+
+	$  mkdir /tmp/$$/build
+	$  cd /tmp/$$/build
+	$  /tmp/$$/devo/configure --target=d10v-elf
+
+In the sim/common directory rebuild the headers:
+
+	$  cd sim/common
+	$  make headers
+
+To add a new target:
+
+	devo/sim/common/gennltvals.sh
+
+		Add your new processor target (you'll need to grub
+		around to find where your syscall.h lives).
+
+	devo/sim/<processor>/Makefile.in
+
+		Add the definition:
+
+			``NL_TARGET = -DNL_TARGET_d10v''
+
+		just before the line COMMON_POST_CONFIG_FRAG.
+
+	devo/sim/<processor>/*.[ch]
+
+		Include targ-vals.h instead of syscall.h.
+