sim: start a manual [PR sim/7582]users/vapier/sim/doc

There's a lot of content in here, but there's also a decent amount of
skeleton for filling out more.  The arch chapters need a bit of work.
But should be good enough for release now.

Bug: https://sourceware.org/PR7582

52 files changed, 6122 insertions, 484 deletions

diff --git a/sim/Makefile.am b/sim/Makefile.am
index 7197590035f..f9fe5dd6e09 100644
--- a/sim/Makefile.am
+++ b/sim/Makefile.am
@@ -15,7 +15,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-AUTOMAKE_OPTIONS = dejagnu foreign no-dist subdir-objects
+AUTOMAKE_OPTIONS = dejagnu foreign info-in-builddir no-dist subdir-objects
 ACLOCAL_AMFLAGS = -Im4 -I.. -I../config
 
 GNULIB_PARENT_DIR = ..
@@ -39,6 +39,7 @@ EXTRA_PROGRAMS =
 
 CLEANFILES =
 DISTCLEANFILES =
+MAINTAINERCLEANFILES =
 MOSTLYCLEANFILES = core
 
 AM_CFLAGS = $(WERROR_CFLAGS) $(WARN_CFLAGS)
@@ -81,6 +82,7 @@ pkginclude_HEADERS += \
 endif
 
 include common/local.mk
+include doc/local.mk
 if SIM_ENABLE_IGEN
 include igen/local.mk
 endif
diff --git a/sim/Makefile.in b/sim/Makefile.in
index 84c48c5b72c..98c316c448f 100644
--- a/sim/Makefile.in
+++ b/sim/Makefile.in
@@ -29,6 +29,22 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+#
+# Copyright (C) 1997-2021 Free Software Foundation, Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
 
 
 
@@ -650,6 +666,45 @@ SOURCES = $(common_libcommon_a_SOURCES) $(igen_libigen_a_SOURCES) \
 	testsuite/common/bits32m31.c testsuite/common/bits64m0.c \
 	testsuite/common/bits64m63.c testsuite/common/fpu-tst.c \
 	$(v850_run_SOURCES)
+AM_V_DVIPS = $(am__v_DVIPS_@AM_V@)
+am__v_DVIPS_ = $(am__v_DVIPS_@AM_DEFAULT_V@)
+am__v_DVIPS_0 = @echo "  DVIPS   " $@;
+am__v_DVIPS_1 = 
+AM_V_MAKEINFO = $(am__v_MAKEINFO_@AM_V@)
+am__v_MAKEINFO_ = $(am__v_MAKEINFO_@AM_DEFAULT_V@)
+am__v_MAKEINFO_0 = @echo "  MAKEINFO" $@;
+am__v_MAKEINFO_1 = 
+AM_V_INFOHTML = $(am__v_INFOHTML_@AM_V@)
+am__v_INFOHTML_ = $(am__v_INFOHTML_@AM_DEFAULT_V@)
+am__v_INFOHTML_0 = @echo "  INFOHTML" $@;
+am__v_INFOHTML_1 = 
+AM_V_TEXI2DVI = $(am__v_TEXI2DVI_@AM_V@)
+am__v_TEXI2DVI_ = $(am__v_TEXI2DVI_@AM_DEFAULT_V@)
+am__v_TEXI2DVI_0 = @echo "  TEXI2DVI" $@;
+am__v_TEXI2DVI_1 = 
+AM_V_TEXI2PDF = $(am__v_TEXI2PDF_@AM_V@)
+am__v_TEXI2PDF_ = $(am__v_TEXI2PDF_@AM_DEFAULT_V@)
+am__v_TEXI2PDF_0 = @echo "  TEXI2PDF" $@;
+am__v_TEXI2PDF_1 = 
+AM_V_texinfo = $(am__v_texinfo_@AM_V@)
+am__v_texinfo_ = $(am__v_texinfo_@AM_DEFAULT_V@)
+am__v_texinfo_0 = -q
+am__v_texinfo_1 = 
+AM_V_texidevnull = $(am__v_texidevnull_@AM_V@)
+am__v_texidevnull_ = $(am__v_texidevnull_@AM_DEFAULT_V@)
+am__v_texidevnull_0 = > /dev/null
+am__v_texidevnull_1 = 
+INFO_DEPS = doc/sim.info
+am__TEXINFO_TEX_DIR = $(srcdir)/doc
+DVIS = doc/sim.dvi
+PDFS = doc/sim.pdf
+PSS = doc/sim.ps
+HTMLS = doc/sim.html
+TEXINFOS = $(TEXINFO_TEX)
+TEXI2PDF = $(TEXI2DVI) --pdf --batch
+MAKEINFOHTML = $(MAKEINFO) --html
+AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS)
+DVIPS = dvips
 RECURSIVE_TARGETS = all-recursive check-recursive cscopelist-recursive \
 	ctags-recursive dvi-recursive html-recursive info-recursive \
 	install-data-recursive install-dvi-recursive \
@@ -663,6 +718,11 @@ am__can_run_installinfo = \
     n|no|NO) false;; \
     *) (install-info --version) >/dev/null 2>&1;; \
   esac
+am__installdirs = "$(DESTDIR)$(infodir)" "$(DESTDIR)$(armdocdir)" \
+	"$(DESTDIR)$(dtbdir)" "$(DESTDIR)$(erc32docdir)" \
+	"$(DESTDIR)$(frvdocdir)" "$(DESTDIR)$(or1kdocdir)" \
+	"$(DESTDIR)$(ppcdocdir)" "$(DESTDIR)$(rxdocdir)" \
+	"$(DESTDIR)$(pkgincludedir)"
 am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
 am__vpath_adj = case $$p in \
     $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \
@@ -690,10 +750,6 @@ am__uninstall_files_from_dir = { \
     || { echo " ( cd '$$dir' && rm -f" $$files ")"; \
          $(am__cd) "$$dir" && rm -f $$files; }; \
   }
-am__installdirs = "$(DESTDIR)$(armdocdir)" "$(DESTDIR)$(dtbdir)" \
-	"$(DESTDIR)$(erc32docdir)" "$(DESTDIR)$(frvdocdir)" \
-	"$(DESTDIR)$(or1kdocdir)" "$(DESTDIR)$(ppcdocdir)" \
-	"$(DESTDIR)$(rxdocdir)" "$(DESTDIR)$(pkgincludedir)"
 DATA = $(armdoc_DATA) $(dtb_DATA) $(erc32doc_DATA) $(frvdoc_DATA) \
 	$(or1kdoc_DATA) $(ppcdoc_DATA) $(rxdoc_DATA)
 am__pkginclude_HEADERS_DIST = $(srcroot)/include/sim/callback.h \
@@ -1164,7 +1220,7 @@ target_vendor = @target_vendor@
 top_build_prefix = @top_build_prefix@
 top_builddir = @top_builddir@
 top_srcdir = @top_srcdir@
-AUTOMAKE_OPTIONS = dejagnu foreign no-dist subdir-objects
+AUTOMAKE_OPTIONS = dejagnu foreign info-in-builddir no-dist subdir-objects
 ACLOCAL_AMFLAGS = -Im4 -I.. -I../config
 GNULIB_PARENT_DIR = ..
 srccom = $(srcdir)/common
@@ -1178,6 +1234,7 @@ CLEANFILES = common/version.c common/version.c-stamp \
 	testsuite/common/bits32m31.c testsuite/common/bits64m0.c \
 	testsuite/common/bits64m63.c
 DISTCLEANFILES = 
+MAINTAINERCLEANFILES = doc/sim.info
 MOSTLYCLEANFILES = core $(am__append_5) site-sim-config.exp \
 	testrun.log testrun.sum $(am__append_12) $(am__append_16) \
 	$(am__append_20) $(am__append_24) $(am__append_31) \
@@ -1224,6 +1281,49 @@ SIM_COMMON_LIBS = \
 	$(LIBGNU) \
 	$(LIBGNU_EXTRA_LIBS)
 
+TEXINFO_TEX = doc/sim.texi
+info_TEXINFOS = $(TEXINFO_TEX)
+doc_sim_TEXINFOS = \
+	doc/abi-newlib-errno.texi \
+	doc/abi-newlib-open.texi \
+	doc/abi-newlib-signal.texi \
+	doc/abi-newlib-sys.texi \
+	doc/arch-aarch64.texi \
+	doc/arch-arm.texi \
+	doc/arch-avr.texi \
+	doc/arch-bfin.texi \
+	doc/arch-bpf.texi \
+	doc/arch-cr16.texi \
+	doc/arch-cris.texi \
+	doc/arch-d10v.texi \
+	doc/arch-erc32.texi \
+	doc/arch-frv.texi \
+	doc/arch-ft32.texi \
+	doc/arch-h8300.texi \
+	doc/arch-iq2000.texi \
+	doc/arch-lm32.texi \
+	doc/arch-m32c.texi \
+	doc/arch-m32r.texi \
+	doc/arch-m68hc11.texi \
+	doc/arch-mcore.texi \
+	doc/arch-microblaze.texi \
+	doc/arch-mips.texi \
+	doc/arch-mn10300.texi \
+	doc/arch-moxie.texi \
+	doc/arch-msp430.texi \
+	doc/arch-or1k.texi \
+	doc/arch-ppc.texi \
+	doc/arch-pru.texi \
+	doc/arch-riscv.texi \
+	doc/arch-rl78.texi \
+	doc/arch-rx.texi \
+	doc/arch-sh.texi \
+	doc/arch-v850.texi \
+	doc/fdl.texi \
+	doc/simver.texi
+
+AM_MAKEINFOFLAGS = -I doc --no-split
+TEXI2DVI = texi2dvi -I doc
 
 # igen leaks memory, and therefore makes AddressSanitizer unhappy.  Disable
 # leak detection while running it.
@@ -1633,10 +1733,10 @@ all: config.h
 	$(MAKE) $(AM_MAKEFLAGS) all-recursive
 
 .SUFFIXES:
-.SUFFIXES: .c .lo .log .o .obj .test .test$(EXEEXT) .trs
+.SUFFIXES: .c .dvi .lo .log .o .obj .ps .test .test$(EXEEXT) .trs
 am--refresh: Makefile
 	@:
-$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(srcdir)/common/local.mk $(srcdir)/igen/local.mk $(srcdir)/testsuite/local.mk $(srcdir)/testsuite/common/local.mk $(srcdir)/aarch64/local.mk $(srcdir)/arm/local.mk $(srcdir)/avr/local.mk $(srcdir)/bfin/local.mk $(srcdir)/bpf/local.mk $(srcdir)/cr16/local.mk $(srcdir)/cris/local.mk $(srcdir)/d10v/local.mk $(srcdir)/erc32/local.mk $(srcdir)/example-synacor/local.mk $(srcdir)/frv/local.mk $(srcdir)/ft32/local.mk $(srcdir)/h8300/local.mk $(srcdir)/iq2000/local.mk $(srcdir)/lm32/local.mk $(srcdir)/m32c/local.mk $(srcdir)/m32r/local.mk $(srcdir)/m68hc11/local.mk $(srcdir)/mcore/local.mk $(srcdir)/microblaze/local.mk $(srcdir)/mips/local.mk $(srcdir)/mn10300/local.mk $(srcdir)/moxie/local.mk $(srcdir)/msp430/local.mk $(srcdir)/or1k/local.mk $(srcdir)/ppc/local.mk $(srcdir)/pru/local.mk $(srcdir)/riscv/local.mk $(srcdir)/rl78/local.mk $(srcdir)/rx/local.mk $(srcdir)/sh/local.mk $(srcdir)/v850/local.mk $(am__configure_deps)
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(srcdir)/common/local.mk $(srcdir)/doc/local.mk $(srcdir)/igen/local.mk $(srcdir)/testsuite/local.mk $(srcdir)/testsuite/common/local.mk $(srcdir)/aarch64/local.mk $(srcdir)/arm/local.mk $(srcdir)/avr/local.mk $(srcdir)/bfin/local.mk $(srcdir)/bpf/local.mk $(srcdir)/cr16/local.mk $(srcdir)/cris/local.mk $(srcdir)/d10v/local.mk $(srcdir)/erc32/local.mk $(srcdir)/example-synacor/local.mk $(srcdir)/frv/local.mk $(srcdir)/ft32/local.mk $(srcdir)/h8300/local.mk $(srcdir)/iq2000/local.mk $(srcdir)/lm32/local.mk $(srcdir)/m32c/local.mk $(srcdir)/m32r/local.mk $(srcdir)/m68hc11/local.mk $(srcdir)/mcore/local.mk $(srcdir)/microblaze/local.mk $(srcdir)/mips/local.mk $(srcdir)/mn10300/local.mk $(srcdir)/moxie/local.mk $(srcdir)/msp430/local.mk $(srcdir)/or1k/local.mk $(srcdir)/ppc/local.mk $(srcdir)/pru/local.mk $(srcdir)/riscv/local.mk $(srcdir)/rl78/local.mk $(srcdir)/rx/local.mk $(srcdir)/sh/local.mk $(srcdir)/v850/local.mk $(am__configure_deps)
 	@for dep in $?; do \
 	  case '$(am__configure_deps)' in \
 	    *$$dep*) \
@@ -1658,7 +1758,7 @@ Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
 	    echo ' cd $(top_builddir) && $(SHELL) ./config.status $@ $(am__depfiles_maybe)'; \
 	    cd $(top_builddir) && $(SHELL) ./config.status $@ $(am__depfiles_maybe);; \
 	esac;
-$(srcdir)/common/local.mk $(srcdir)/igen/local.mk $(srcdir)/testsuite/local.mk $(srcdir)/testsuite/common/local.mk $(srcdir)/aarch64/local.mk $(srcdir)/arm/local.mk $(srcdir)/avr/local.mk $(srcdir)/bfin/local.mk $(srcdir)/bpf/local.mk $(srcdir)/cr16/local.mk $(srcdir)/cris/local.mk $(srcdir)/d10v/local.mk $(srcdir)/erc32/local.mk $(srcdir)/example-synacor/local.mk $(srcdir)/frv/local.mk $(srcdir)/ft32/local.mk $(srcdir)/h8300/local.mk $(srcdir)/iq2000/local.mk $(srcdir)/lm32/local.mk $(srcdir)/m32c/local.mk $(srcdir)/m32r/local.mk $(srcdir)/m68hc11/local.mk $(srcdir)/mcore/local.mk $(srcdir)/microblaze/local.mk $(srcdir)/mips/local.mk $(srcdir)/mn10300/local.mk $(srcdir)/moxie/local.mk $(srcdir)/msp430/local.mk $(srcdir)/or1k/local.mk $(srcdir)/ppc/local.mk $(srcdir)/pru/local.mk $(srcdir)/riscv/local.mk $(srcdir)/rl78/local.mk $(srcdir)/rx/local.mk $(srcdir)/sh/local.mk $(srcdir)/v850/local.mk $(am__empty):
+$(srcdir)/common/local.mk $(srcdir)/doc/local.mk $(srcdir)/igen/local.mk $(srcdir)/testsuite/local.mk $(srcdir)/testsuite/common/local.mk $(srcdir)/aarch64/local.mk $(srcdir)/arm/local.mk $(srcdir)/avr/local.mk $(srcdir)/bfin/local.mk $(srcdir)/bpf/local.mk $(srcdir)/cr16/local.mk $(srcdir)/cris/local.mk $(srcdir)/d10v/local.mk $(srcdir)/erc32/local.mk $(srcdir)/example-synacor/local.mk $(srcdir)/frv/local.mk $(srcdir)/ft32/local.mk $(srcdir)/h8300/local.mk $(srcdir)/iq2000/local.mk $(srcdir)/lm32/local.mk $(srcdir)/m32c/local.mk $(srcdir)/m32r/local.mk $(srcdir)/m68hc11/local.mk $(srcdir)/mcore/local.mk $(srcdir)/microblaze/local.mk $(srcdir)/mips/local.mk $(srcdir)/mn10300/local.mk $(srcdir)/moxie/local.mk $(srcdir)/msp430/local.mk $(srcdir)/or1k/local.mk $(srcdir)/ppc/local.mk $(srcdir)/pru/local.mk $(srcdir)/riscv/local.mk $(srcdir)/rl78/local.mk $(srcdir)/rx/local.mk $(srcdir)/sh/local.mk $(srcdir)/v850/local.mk $(am__empty):
 
 $(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
 	$(SHELL) ./config.status --recheck
@@ -2377,6 +2477,143 @@ clean-libtool:
 
 distclean-libtool:
 	-rm -f libtool config.lt
+doc/$(am__dirstamp):
+	@$(MKDIR_P) doc
+	@: > doc/$(am__dirstamp)
+
+doc/sim.info: doc/sim.texi $(doc_sim_TEXINFOS)
+	@test -f doc/$(am__dirstamp) || $(MAKE) $(AM_MAKEFLAGS) doc/$(am__dirstamp)
+	$(AM_V_MAKEINFO)restore=: && backupdir="$(am__leading_dot)am$$$$" && \
+	rm -rf $$backupdir && mkdir $$backupdir && \
+	if ($(MAKEINFO) --version) >/dev/null 2>&1; then \
+	  for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \
+	    if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \
+	  done; \
+	else :; fi && \
+	if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I doc -I $(srcdir)/doc \
+	 -o $@ `test -f 'doc/sim.texi' || echo '$(srcdir)/'`doc/sim.texi; \
+	then \
+	  rc=0; \
+	else \
+	  rc=$$?; \
+	  $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \
+	fi; \
+	rm -rf $$backupdir; exit $$rc
+
+doc/sim.dvi: doc/sim.texi $(doc_sim_TEXINFOS) doc/$(am__dirstamp)
+	$(AM_V_TEXI2DVI)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
+	MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I doc -I $(srcdir)/doc' \
+	$(TEXI2DVI) $(AM_V_texinfo) --build-dir=$(@:.dvi=.t2d) -o $@ $(AM_V_texidevnull) \
+	`test -f 'doc/sim.texi' || echo '$(srcdir)/'`doc/sim.texi
+
+doc/sim.pdf: doc/sim.texi $(doc_sim_TEXINFOS) doc/$(am__dirstamp)
+	$(AM_V_TEXI2PDF)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
+	MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I doc -I $(srcdir)/doc' \
+	$(TEXI2PDF) $(AM_V_texinfo) --build-dir=$(@:.pdf=.t2p) -o $@ $(AM_V_texidevnull) \
+	`test -f 'doc/sim.texi' || echo '$(srcdir)/'`doc/sim.texi
+
+doc/sim.html: doc/sim.texi $(doc_sim_TEXINFOS) doc/$(am__dirstamp)
+	$(AM_V_MAKEINFO)rm -rf $(@:.html=.htp)
+	$(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I doc -I $(srcdir)/doc \
+	 -o $(@:.html=.htp) `test -f 'doc/sim.texi' || echo '$(srcdir)/'`doc/sim.texi; \
+	then \
+	  rm -rf $@ && mv $(@:.html=.htp) $@; \
+	else \
+	  rm -rf $(@:.html=.htp); exit 1; \
+	fi
+.dvi.ps:
+	$(AM_V_DVIPS)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
+	$(DVIPS) $(AM_V_texinfo) -o $@ $<
+
+uninstall-dvi-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(DVIS)'; test -n "$(dvidir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \
+	  rm -f "$(DESTDIR)$(dvidir)/$$f"; \
+	done
+
+uninstall-html-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(HTMLS)'; test -n "$(htmldir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \
+	  rm -rf "$(DESTDIR)$(htmldir)/$$f"; \
+	done
+
+uninstall-info-am:
+	@$(PRE_UNINSTALL)
+	@if test -d '$(DESTDIR)$(infodir)' && $(am__can_run_installinfo); then \
+	  list='$(INFO_DEPS)'; \
+	  for file in $$list; do \
+	    relfile=`echo "$$file" | sed 's|^.*/||'`; \
+	    echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \
+	    if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \
+	    then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \
+	  done; \
+	else :; fi
+	@$(NORMAL_UNINSTALL)
+	@list='$(INFO_DEPS)'; \
+	for file in $$list; do \
+	  relfile=`echo "$$file" | sed 's|^.*/||'`; \
+	  relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \
+	  (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \
+	     echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \
+	     rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \
+	   else :; fi); \
+	done
+
+uninstall-pdf-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \
+	  rm -f "$(DESTDIR)$(pdfdir)/$$f"; \
+	done
+
+uninstall-ps-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(PSS)'; test -n "$(psdir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \
+	  rm -f "$(DESTDIR)$(psdir)/$$f"; \
+	done
+
+dist-info: $(INFO_DEPS)
+	@srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
+	list='$(INFO_DEPS)'; \
+	for base in $$list; do \
+	  case $$base in \
+	    $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \
+	  esac; \
+	  if test -f $$base; then d=.; else d=$(srcdir); fi; \
+	  base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \
+	  for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \
+	    if test -f $$file; then \
+	      relfile=`expr "$$file" : "$$d/\(.*\)"`; \
+	      test -f "$(distdir)/$$relfile" || \
+		cp -p $$file "$(distdir)/$$relfile"; \
+	    else :; fi; \
+	  done; \
+	done
+
+mostlyclean-aminfo:
+	-rm -rf doc/sim.t2d doc/sim.t2p
+
+clean-aminfo:
+	-test -z "doc/sim.dvi doc/sim.pdf doc/sim.ps doc/sim.html" \
+	|| rm -rf doc/sim.dvi doc/sim.pdf doc/sim.ps doc/sim.html
+
+maintainer-clean-aminfo:
+	@list='$(INFO_DEPS)'; for i in $$list; do \
+	  i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \
+	  echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \
+	  rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \
+	done
 install-armdocDATA: $(armdoc_DATA)
 	@$(NORMAL_INSTALL)
 	@list='$(armdoc_DATA)'; test -n "$(armdocdir)" || list=; \
@@ -2878,10 +3115,11 @@ check-am: all-am
 	$(MAKE) $(AM_MAKEFLAGS) $(check_PROGRAMS)
 	$(MAKE) $(AM_MAKEFLAGS) check-DEJAGNU check-TESTS
 check: check-recursive
-all-am: Makefile $(LIBRARIES) $(PROGRAMS) $(DATA) $(HEADERS) config.h
+all-am: Makefile $(INFO_DEPS) $(LIBRARIES) $(PROGRAMS) $(DATA) \
+		$(HEADERS) config.h
 installdirs: installdirs-recursive
 installdirs-am:
-	for dir in "$(DESTDIR)$(armdocdir)" "$(DESTDIR)$(dtbdir)" "$(DESTDIR)$(erc32docdir)" "$(DESTDIR)$(frvdocdir)" "$(DESTDIR)$(or1kdocdir)" "$(DESTDIR)$(ppcdocdir)" "$(DESTDIR)$(rxdocdir)" "$(DESTDIR)$(pkgincludedir)"; do \
+	for dir in "$(DESTDIR)$(infodir)" "$(DESTDIR)$(armdocdir)" "$(DESTDIR)$(dtbdir)" "$(DESTDIR)$(erc32docdir)" "$(DESTDIR)$(frvdocdir)" "$(DESTDIR)$(or1kdocdir)" "$(DESTDIR)$(ppcdocdir)" "$(DESTDIR)$(rxdocdir)" "$(DESTDIR)$(pkgincludedir)"; do \
 	  test -z "$$dir" || $(MKDIR_P) "$$dir"; \
 	done
 install: install-recursive
@@ -2928,6 +3166,7 @@ distclean-generic:
 	-rm -f cris/$(am__dirstamp)
 	-rm -f d10v/$(DEPDIR)/$(am__dirstamp)
 	-rm -f d10v/$(am__dirstamp)
+	-rm -f doc/$(am__dirstamp)
 	-rm -f erc32/$(DEPDIR)/$(am__dirstamp)
 	-rm -f erc32/$(am__dirstamp)
 	-rm -f example-synacor/$(am__dirstamp)
@@ -2966,9 +3205,10 @@ distclean-generic:
 maintainer-clean-generic:
 	@echo "This command is intended for maintainers to use"
 	@echo "it deletes files that may require special tools to rebuild."
+	-test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES)
 clean: clean-recursive
 
-clean-am: clean-checkPROGRAMS clean-generic clean-libtool \
+clean-am: clean-aminfo clean-checkPROGRAMS clean-generic clean-libtool \
 	clean-noinstLIBRARIES clean-noinstPROGRAMS mostlyclean-am
 
 distclean: distclean-recursive
@@ -2981,44 +3221,136 @@ distclean-am: clean-am distclean-DEJAGNU distclean-compile \
 
 dvi: dvi-recursive
 
-dvi-am:
+dvi-am: $(DVIS)
 
 html: html-recursive
 
-html-am:
+html-am: $(HTMLS) html-local
 
 info: info-recursive
 
-info-am:
+info-am: $(INFO_DEPS)
 
 install-data-am: install-armdocDATA install-data-local install-dtbDATA \
-	install-erc32docDATA install-frvdocDATA install-or1kdocDATA \
-	install-pkgincludeHEADERS install-ppcdocDATA install-rxdocDATA
+	install-erc32docDATA install-frvdocDATA install-info-am \
+	install-or1kdocDATA install-pkgincludeHEADERS \
+	install-ppcdocDATA install-rxdocDATA
 
 install-dvi: install-dvi-recursive
 
-install-dvi-am:
-
+install-dvi-am: $(DVIS)
+	@$(NORMAL_INSTALL)
+	@list='$(DVIS)'; test -n "$(dvidir)" || list=; \
+	if test -n "$$list"; then \
+	  echo " $(MKDIR_P) '$(DESTDIR)$(dvidir)'"; \
+	  $(MKDIR_P) "$(DESTDIR)$(dvidir)" || exit 1; \
+	fi; \
+	for p in $$list; do \
+	  if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \
+	done
 install-exec-am: install-exec-local
 
 install-html: install-html-recursive
 
-install-html-am:
-
+install-html-am: $(HTMLS)
+	@$(NORMAL_INSTALL)
+	@list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \
+	if test -n "$$list"; then \
+	  echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)'"; \
+	  $(MKDIR_P) "$(DESTDIR)$(htmldir)" || exit 1; \
+	fi; \
+	for p in $$list; do \
+	  if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  $(am__strip_dir) \
+	  d2=$$d$$p; \
+	  if test -d "$$d2"; then \
+	    echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \
+	    $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \
+	    echo " $(INSTALL_DATA) '$$d2'/* '$(DESTDIR)$(htmldir)/$$f'"; \
+	    $(INSTALL_DATA) "$$d2"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \
+	  else \
+	    list2="$$list2 $$d2"; \
+	  fi; \
+	done; \
+	test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \
+	done; }
 install-info: install-info-recursive
 
-install-info-am:
-
+install-info-am: $(INFO_DEPS)
+	@$(NORMAL_INSTALL)
+	@srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
+	list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
+	if test -n "$$list"; then \
+	  echo " $(MKDIR_P) '$(DESTDIR)$(infodir)'"; \
+	  $(MKDIR_P) "$(DESTDIR)$(infodir)" || exit 1; \
+	fi; \
+	for file in $$list; do \
+	  case $$file in \
+	    $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \
+	  esac; \
+	  if test -f $$file; then d=.; else d=$(srcdir); fi; \
+	  file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \
+	  for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \
+	               $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \
+	    if test -f $$ifile; then \
+	      echo "$$ifile"; \
+	    else : ; fi; \
+	  done; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done
+	@$(POST_INSTALL)
+	@if $(am__can_run_installinfo); then \
+	  list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
+	  for file in $$list; do \
+	    relfile=`echo "$$file" | sed 's|^.*/||'`; \
+	    echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\
+	    install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\
+	  done; \
+	else : ; fi
 install-man:
 
 install-pdf: install-pdf-recursive
 
-install-pdf-am:
-
+install-pdf-am: $(PDFS)
+	@$(NORMAL_INSTALL)
+	@list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
+	if test -n "$$list"; then \
+	  echo " $(MKDIR_P) '$(DESTDIR)$(pdfdir)'"; \
+	  $(MKDIR_P) "$(DESTDIR)$(pdfdir)" || exit 1; \
+	fi; \
+	for p in $$list; do \
+	  if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done
 install-ps: install-ps-recursive
 
-install-ps-am:
-
+install-ps-am: $(PSS)
+	@$(NORMAL_INSTALL)
+	@list='$(PSS)'; test -n "$(psdir)" || list=; \
+	if test -n "$$list"; then \
+	  echo " $(MKDIR_P) '$(DESTDIR)$(psdir)'"; \
+	  $(MKDIR_P) "$(DESTDIR)$(psdir)" || exit 1; \
+	fi; \
+	for p in $$list; do \
+	  if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done
 installcheck-am:
 
 maintainer-clean: maintainer-clean-recursive
@@ -3026,51 +3358,56 @@ maintainer-clean: maintainer-clean-recursive
 	-rm -rf $(top_srcdir)/autom4te.cache
 	-rm -rf common/$(DEPDIR) cr16/$(DEPDIR) cris/$(DEPDIR) d10v/$(DEPDIR) erc32/$(DEPDIR) igen/$(DEPDIR) m32c/$(DEPDIR) m68hc11/$(DEPDIR) ppc/$(DEPDIR) sh/$(DEPDIR) testsuite/common/$(DEPDIR)
 	-rm -f Makefile
-maintainer-clean-am: distclean-am maintainer-clean-generic
+maintainer-clean-am: distclean-am maintainer-clean-aminfo \
+	maintainer-clean-generic
 
 mostlyclean: mostlyclean-recursive
 
-mostlyclean-am: mostlyclean-compile mostlyclean-generic \
-	mostlyclean-libtool
+mostlyclean-am: mostlyclean-aminfo mostlyclean-compile \
+	mostlyclean-generic mostlyclean-libtool
 
 pdf: pdf-recursive
 
-pdf-am:
+pdf-am: $(PDFS)
 
 ps: ps-recursive
 
-ps-am:
+ps-am: $(PSS)
 
-uninstall-am: uninstall-armdocDATA uninstall-dtbDATA \
-	uninstall-erc32docDATA uninstall-frvdocDATA uninstall-local \
-	uninstall-or1kdocDATA uninstall-pkgincludeHEADERS \
-	uninstall-ppcdocDATA uninstall-rxdocDATA
+uninstall-am: uninstall-armdocDATA uninstall-dtbDATA uninstall-dvi-am \
+	uninstall-erc32docDATA uninstall-frvdocDATA uninstall-html-am \
+	uninstall-info-am uninstall-local uninstall-or1kdocDATA \
+	uninstall-pdf-am uninstall-pkgincludeHEADERS \
+	uninstall-ppcdocDATA uninstall-ps-am uninstall-rxdocDATA
 
 .MAKE: $(am__recursive_targets) all check-am install-am install-strip
 
 .PHONY: $(am__recursive_targets) CTAGS GTAGS TAGS all all-am \
 	am--refresh check check-DEJAGNU check-TESTS check-am clean \
-	clean-checkPROGRAMS clean-cscope clean-generic clean-libtool \
-	clean-noinstLIBRARIES clean-noinstPROGRAMS cscope \
-	cscopelist-am ctags ctags-am distclean distclean-DEJAGNU \
-	distclean-compile distclean-generic distclean-hdr \
-	distclean-libtool distclean-tags dvi dvi-am html html-am info \
-	info-am install install-am install-armdocDATA install-data \
-	install-data-am install-data-local install-dtbDATA install-dvi \
-	install-dvi-am install-erc32docDATA install-exec \
-	install-exec-am install-exec-local install-frvdocDATA \
-	install-html install-html-am install-info install-info-am \
-	install-man install-or1kdocDATA install-pdf install-pdf-am \
+	clean-aminfo clean-checkPROGRAMS clean-cscope clean-generic \
+	clean-libtool clean-noinstLIBRARIES clean-noinstPROGRAMS \
+	cscope cscopelist-am ctags ctags-am dist-info distclean \
+	distclean-DEJAGNU distclean-compile distclean-generic \
+	distclean-hdr distclean-libtool distclean-tags dvi dvi-am html \
+	html-am html-local info info-am install install-am \
+	install-armdocDATA install-data install-data-am \
+	install-data-local install-dtbDATA install-dvi install-dvi-am \
+	install-erc32docDATA install-exec install-exec-am \
+	install-exec-local install-frvdocDATA install-html \
+	install-html-am install-info install-info-am install-man \
+	install-or1kdocDATA install-pdf install-pdf-am \
 	install-pkgincludeHEADERS install-ppcdocDATA install-ps \
 	install-ps-am install-rxdocDATA install-strip installcheck \
 	installcheck-am installdirs installdirs-am maintainer-clean \
-	maintainer-clean-generic mostlyclean mostlyclean-compile \
-	mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \
-	recheck tags tags-am uninstall uninstall-am \
-	uninstall-armdocDATA uninstall-dtbDATA uninstall-erc32docDATA \
-	uninstall-frvdocDATA uninstall-local uninstall-or1kdocDATA \
+	maintainer-clean-aminfo maintainer-clean-generic mostlyclean \
+	mostlyclean-aminfo mostlyclean-compile mostlyclean-generic \
+	mostlyclean-libtool pdf pdf-am ps ps-am recheck tags tags-am \
+	uninstall uninstall-am uninstall-armdocDATA uninstall-dtbDATA \
+	uninstall-dvi-am uninstall-erc32docDATA uninstall-frvdocDATA \
+	uninstall-html-am uninstall-info-am uninstall-local \
+	uninstall-or1kdocDATA uninstall-pdf-am \
 	uninstall-pkgincludeHEADERS uninstall-ppcdocDATA \
-	uninstall-rxdocDATA
+	uninstall-ps-am uninstall-rxdocDATA
 
 .PRECIOUS: Makefile
 
@@ -3089,6 +3426,19 @@ common/version.c-stamp: $(srcroot)/gdb/version.in $(srcroot)/bfd/version.h $(src
 	$(AM_V_at)$(SHELL) $(srcroot)/move-if-change $@.tmp $(@:-stamp=)
 	$(AM_V_at)touch $@
 
+doc/simver.texi: doc/simver.texi-stamp ; @true
+doc/simver.texi-stamp: $(srcroot)/gdb/version.in $(srcroot)/bfd/version.h doc/create-version.sh
+	$(AM_V_at)$(MKDIR_P) doc
+	$(AM_V_GEN)$(SHELL) $(srcdir)/doc/create-version.sh $(srcroot)/gdb $@.tmp \
+		"$(PACKAGE_URL)" "$(REPORT_BUGS_TEXI)"
+	$(AM_V_at)$(SHELL) $(srcroot)/move-if-change $@.tmp $(@:-stamp=)
+	$(AM_V_at)touch $@
+
+html-local: doc/sim/index.html
+doc/sim/index.html: $(TEXINFO_TEX) $(doc_sim_TEXINFOS)
+	$(AM_V_MAKEINFO)$(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) \
+		--output=doc/sim --split=node -I$(srcdir) $<
+
 # Alias for developers.
 @SIM_ENABLE_IGEN_TRUE@igen: $(IGEN)
 
diff --git a/sim/arm/README b/sim/arm/README
deleted file mode 100644
index adfb766451d..00000000000
--- a/sim/arm/README
+++ /dev/null
@@ -1,27 +0,0 @@
-
-This directory contains the standard release of the ARMulator from
-Advanced RISC Machines, and was ftp'd from.
-
-ftp.cl.cam.ac.uk:/arm/gnu
-
-It likes to use TCP/IP between the simulator and the host, which is
-nice, but is a pain to use under anything non-unix.
-
-I've added created a new Makefile.in (the original in Makefile.orig)
-to build a version of the simulator without the TCP/IP stuff, and a
-wrapper.c to link directly into gdb and the run command.
-
-It should be possible (barring major changes in the layout of
-the armulator) to upgrade the simulator by copying all the files
-out of a release into this directory and renaming the Makefile.
-
-(Except that I changed armos.c to work more simply with our
-simulator rigs)
-
-Steve
-
-sac@cygnus.com
-
-Mon May 15 12:03:28 PDT 1995
-
-
diff --git a/sim/common/dv-cfi.c b/sim/common/dv-cfi.c
index d63b0ed6da2..837640348c5 100644
--- a/sim/common/dv-cfi.c
+++ b/sim/common/dv-cfi.c
@@ -548,30 +548,7 @@ cfi_add_erase_region (struct hw *me, struct cfi *cfi,
   cfi->query.num_erase_regions = num_regions + 1;
 }
 
-/* Device tree options:
-     Required:
-       .../reg <addr> <len>
-       .../cmdset <primary; integer> [alt; integer]
-     Optional:
-       .../size <device size (must be pow of 2)>
-       .../width <8|16|32>
-       .../write_size <integer (must be pow of 2)>
-       .../erase_regions <number blocks> <block size> \
-                         [<number blocks> <block size> ...]
-       .../voltage <vcc min> <vcc max> <vpp min> <vpp max>
-       .../timeouts <typ unit write>  <typ buf write>  \
-                    <typ block erase> <typ chip erase> \
-                    <max unit write>  <max buf write>  \
-                    <max block erase> <max chip erase>
-       .../file <file> [ro|rw]
-     Defaults:
-       size: <len> from "reg"
-       width: 8
-       write_size: 0 (not supported)
-       erase_region: 1 (can only erase whole chip)
-       voltage: 0.0V (for all)
-       timeouts: typ: 1µs, not supported, 1ms, not supported
-                 max: 1µs, 1ms, 1ms, not supported
+/* Process the device tree options.
 
   TODO: Verify user args are valid (e.g. voltage is 8 bits).  */
 static void
diff --git a/sim/common/dv-core.c b/sim/common/dv-core.c
index 4a5f5a0eb57..66c15758070 100644
--- a/sim/common/dv-core.c
+++ b/sim/common/dv-core.c
@@ -25,28 +25,6 @@
 #include "sim-main.h"
 #include "hw-main.h"
 
-/* DEVICE
-
-   core - root of the device tree
-
-   DESCRIPTION
-
-   The core device, positioned at the root of the device tree appears
-   to its child devices as a normal device just like every other
-   device in the tree.
-
-   Internally it is implemented using a core object.  Requests to
-   attach (or detach) address spaces are passed to that core object.
-   Requests to transfer (DMA) data are reflected back down the device
-   tree using the core_map data transfer methods.
-
-   PROPERTIES
-
-   None.
-
-   */
-
-
 static void
 dv_core_attach_address_callback (struct hw *me,
 				 int level,
diff --git a/sim/common/dv-glue.c b/sim/common/dv-glue.c
index 0c7809ab073..bb0a757f5ad 100644
--- a/sim/common/dv-glue.c
+++ b/sim/common/dv-glue.c
@@ -26,129 +26,6 @@
 
 #include "hw-main.h"
 
-/* DEVICE
-
-
-   glue - glue to interconnect and test hardware ports
-
-
-   DESCRIPTION
-
-
-   The glue device provides two functions.  Firstly, it provides a
-   mechanism for inspecting and driving the port network.  Secondly,
-   it provides a set of boolean primitives that can be used to apply
-   combinatorial operations to the port network.
-
-   Glue devices have a variable number of big endian <<output>>
-   registers.  Each register is target-word sized.  The registers can
-   be read and written.
-
-   Writing to an output register results in an event being driven
-   (level determined by the value written) on the devices
-   corresponding output port.
-
-   Reading an <<output>> register returns either the last value
-   written or the most recently computed value (for that register) as
-   a result of an event ariving on that port (which ever was computed
-   last).
-
-   At present the following sub device types are available:
-
-   <<glue>>: In addition to driving its output interrupt port with any
-   value written to an interrupt input port is stored in the
-   corresponding <<output>> register.  Such input interrupts, however,
-   are not propogated to an output interrupt port.
-
-   <<glue-and>>: The bit-wise AND of the interrupt inputs is computed
-   and then both stored in <<output>> register zero and propogated to
-   output interrupt output port zero.
-
-
-   PROPERTIES
-
-
-   reg = <address> <size> (required)
-
-   Specify the address (within the parent bus) that this device is to
-   live.  The address must be 2048 * sizeof (word) (8k in a 32bit
-   simulation) aligned.
-
-
-   interrupt-ranges = <int-number> <range> (optional)
-
-   If present, this specifies the number of valid interrupt inputs (up
-   to the maximum of 2048).  By default, <<int-number>> is zero and
-   range is determined by the <<reg>> size.
-
-
-   PORTS
-
-
-   int[0..] (input, output)
-
-   Both an input and an output port.
-
-
-   EXAMPLES
-
-
-   Enable tracing of the device:
-
-   | -t glue-device \
-
-
-   Create source, bitwize-and, and sink glue devices.  Since the
-   device at address <<0x10000>> is of size <<8>> it will have two
-   output interrupt ports.
-
-   | -o '/iobus@0xf0000000/glue@0x10000/reg 0x10000 8' \
-   | -o '/iobus@0xf0000000/glue-and@0x20000/reg 0x20000 4' \
-   | -o '/iobus@0xf0000000/glue-and/interrupt-ranges 0 2' \
-   | -o '/iobus@0xf0000000/glue@0x30000/reg 0x30000 4' \
-
-
-   Wire the two source interrupts to the AND device:
-
-   | -o '/iobus@0xf0000000/glue@0x10000 > 0 0 /iobus/glue-and' \
-   | -o '/iobus@0xf0000000/glue@0x10000 > 1 1 /iobus/glue-and' \
-
-
-   Wire the AND device up to the sink so that the and's output is not
-   left open.
-
-   | -o '/iobus@0xf0000000/glue-and > 0 0 /iobus/glue@0x30000' \
-
-
-   With the above configuration.  The client program is able to
-   compute a two bit AND.  For instance the <<C>> stub below prints 1
-   AND 0.
-
-   |  unsigned *input = (void*)0xf0010000;
-   |  unsigned *output = (void*)0xf0030000;
-   |  unsigned ans;
-   |  input[0] = htonl(1);
-   |  input[1] = htonl(0);
-   |  ans = ntohl(*output);
-   |  write_string("AND is ");
-   |  write_int(ans);
-   |  write_line();
-
-
-   BUGS
-
-
-   A future implementation of this device may support multiple
-   interrupt ranges.
-
-   Some of the devices listed may not yet be fully implemented.
-
-   Additional devices such as a D flip-flop (DFF), an inverter (INV)
-   or a latch (LAT) may prove useful.
-
-   */
-
-
 enum
 {
   max_nr_ports = 2048,
diff --git a/sim/common/dv-pal.c b/sim/common/dv-pal.c
index 5f42fdab75b..89f41eb6e2a 100644
--- a/sim/common/dv-pal.c
+++ b/sim/common/dv-pal.c
@@ -36,127 +36,6 @@
    its immediate domain */
 #include "hw-tree.h"
 
-/* DEVICE
-
-
-   pal - glue logic device containing assorted junk
-
-
-   DESCRIPTION
-
-
-   Typical hardware dependant hack.  This device allows the firmware
-   to gain access to all the things the firmware needs (but the OS
-   doesn't).
-
-   The pal contains the following registers:
-
-   |0	reset register (write, 8bit)
-   |4	processor id register (read, 8bit)
-   |8	interrupt register (8 - port, 9 - level) (write, 16bit)
-   |12	processor count register (read, 8bit)
-
-   |16	tty input fifo register (read, 8bit)
-   |20	tty input status register (read, 8bit)
-   |24	tty output fifo register (write, 8bit)
-   |28	tty output status register (read, 8bit)
-
-   |32  countdown register (read/write, 32bit, big-endian)
-   |36  countdown value register (read, 32bit, big-endian)
-   |40  timer register (read/write, 32bit, big-endian)
-   |44  timer value register (read, 32bit, big-endian)
-
-   RESET (write): halts the simulator.  The value written to the
-   register is used as an exit status.
-
-   PROCESSOR ID (read): returns the processor identifier (0 .. N-1) of
-   the processor performing the read.
-
-   INTERRUPT (write): This register must be written using a two byte
-   store.  The low byte specifies a port and the upper byte specifies
-   the a level.  LEVEL is driven on the specified port.  By
-   convention, the pal's interrupt ports (int0, int1, ...) are wired
-   up to the corresponding processor's level sensative external
-   interrupt pin.  Eg: A two byte write to address 8 of 0x0102
-   (big-endian) will result in processor 2's external interrupt pin
-   being asserted.
-
-   PROCESSOR COUNT (read): returns the total number of processors
-   active in the current simulation.
-
-   TTY INPUT FIFO (read): if the TTY input status register indicates a
-   character is available by being nonzero, returns the next available
-   character from the pal's tty input port.
-
-   TTY OUTPUT FIFO (write): if the TTY output status register
-   indicates the output fifo is not full by being nonzero, outputs the
-   character written to the tty's output port.
-
-   COUNDOWN (read/write): The countdown registers provide a
-   non-repeating timed interrupt source.  Writing a 32 bit big-endian
-   zero value to this register clears the countdown timer.  Writing a
-   non-zero 32 bit big-endian value to this register sets the
-   countdown timer to expire in VALUE ticks (ticks is target
-   dependant).  Reading the countdown register returns the last value
-   writen.
-
-   COUNTDOWN VALUE (read): Reading this 32 bit big-endian register
-   returns the number of ticks remaining until the countdown timer
-   expires.
-
-   TIMER (read/write): The timer registers provide a periodic timed
-   interrupt source.  Writing a 32 bit big-endian zero value to this
-   register clears the periodic timer.  Writing a 32 bit non-zero
-   value to this register sets the periodic timer to triger every
-   VALUE ticks (ticks is target dependant).  Reading the timer
-   register returns the last value written.
-
-   TIMER VALUE (read): Reading this 32 bit big-endian register returns
-   the number of ticks until the next periodic interrupt.
-
-
-   PROPERTIES
-
-
-   reg = <address> <size> (required)
-
-   Specify the address (within the parent bus) that this device is to
-   be located.
-
-   poll? = <boolean>
-
-   If present and true, indicates that the device should poll its
-   input.
-
-
-   PORTS
-
-
-   int[0..NR_PROCESSORS] (output)
-
-   Driven as a result of a write to the interrupt-port /
-   interrupt-level register pair.
-
-
-   countdown
-
-   Driven whenever the countdown counter reaches zero.
-
-
-   timer
-
-   Driven whenever the timer counter reaches zero.
-
-
-   BUGS
-
-
-   At present the common simulator framework does not support input
-   polling.
-
-   */
-
-
 enum {
   hw_pal_reset_register = 0x0,
   hw_pal_cpu_nr_register = 0x4,
diff --git a/sim/common/gennltvals.py b/sim/common/gennltvals.py
index 8210845a246..1568d508632 100755
--- a/sim/common/gennltvals.py
+++ b/sim/common/gennltvals.py
@@ -118,6 +118,27 @@ def gentvals(output_dir: Path,
 
     syms = extract_syms(cpp, srcdir, headers, pattern, filter)
 
+    # Update the manual.
+    sortable = srctype not in {'open'}
+    manual = output_dir.parent / 'doc' / f'abi-newlib-{srctype}.texi'
+    with manual.open('w') as fp:
+        fp.write(f'@c This file is machine generated by {PROG}.\n\n')
+
+        if sortable:
+            fp.write('@subsection Sorted by name\n')
+        fp.write('@multitable @columnfractions .2 .2\n')
+        for sym, val in sorted(syms.items()):
+            fp.write(f'@item @code{{{sym}}}\n@tab @code{{{val}}}\n')
+        fp.write('@end multitable\n')
+
+        if sortable:
+            fp.write('\n')
+            fp.write('@subsection Sorted by value\n')
+            fp.write('@multitable @columnfractions .2 .2\n')
+            for sym, val in sorted(syms.items(), key=lambda x: int(x[1], base=0)):
+                fp.write(f'@item @code{{{sym}}}\n@tab @code{{{val}}}\n')
+            fp.write('@end multitable\n')
+
     target_map = output_dir / f'target-newlib-{srctype}.c'
     assert target_map.exists(), f'{target_map}: Missing skeleton'
     old_lines = target_map.read_text().splitlines()
diff --git a/sim/common/syscall.c b/sim/common/syscall.c
index c0f74198cd0..d7a19d5c4cb 100644
--- a/sim/common/syscall.c
+++ b/sim/common/syscall.c
@@ -136,7 +136,7 @@ get_path (host_callback *cb, CB_SYSCALL *sc, TADDR addr, char **bufp)
 CB_RC
 cb_syscall (host_callback *cb, CB_SYSCALL *sc)
 {
-  TWORD result = 0, errcode = 0;
+  TWORD result = 0, result2 = 0, errcode = 0;
 
   if (sc->magic != CB_SYSCALL_MAGIC)
     abort ();
@@ -270,7 +270,7 @@ cb_syscall (host_callback *cb, CB_SYSCALL *sc)
 	  goto einval;
 
 	result = argc;
-	sc->result2 = envc;
+	result2 = envc;
 	break;
 
  efault:
@@ -658,6 +658,8 @@ cb_syscall (host_callback *cb, CB_SYSCALL *sc)
 	   here down.  */
 	time_t t = (*cb->time) (cb);
 	result = t;
+	if (cb->target_sizeof_int == 32)
+	  result2 = (uint64_t)t >> 32;
 	/* It is up to target code to process the argument to time().  */
       }
       break;
@@ -675,6 +677,7 @@ cb_syscall (host_callback *cb, CB_SYSCALL *sc)
 
  FinishSyscall:
   sc->result = result;
+  sc->result2 = result2;
   if (errcode == 0)
     sc->errcode = 0;
   else
@@ -683,6 +686,7 @@ cb_syscall (host_callback *cb, CB_SYSCALL *sc)
 
  ErrorFinish:
   sc->result = result;
+  sc->result2 = result2;
   sc->errcode = (*cb->get_errno) (cb);
   return CB_RC_OK;
 }
diff --git a/sim/doc/abi-newlib-errno.texi b/sim/doc/abi-newlib-errno.texi
new file mode 100644
index 00000000000..9b0f85f518c
--- /dev/null
+++ b/sim/doc/abi-newlib-errno.texi
@@ -0,0 +1,349 @@
+@c This file is machine generated by gennltvals.py.
+
+@subsection Sorted by name
+@multitable @columnfractions .2 .2
+@item @code{E2BIG}
+@tab @code{7}
+@item @code{EACCES}
+@tab @code{13}
+@item @code{EADDRINUSE}
+@tab @code{112}
+@item @code{EADDRNOTAVAIL}
+@tab @code{125}
+@item @code{EAFNOSUPPORT}
+@tab @code{106}
+@item @code{EAGAIN}
+@tab @code{11}
+@item @code{EALREADY}
+@tab @code{120}
+@item @code{EBADF}
+@tab @code{9}
+@item @code{EBADMSG}
+@tab @code{77}
+@item @code{EBUSY}
+@tab @code{16}
+@item @code{ECANCELED}
+@tab @code{140}
+@item @code{ECHILD}
+@tab @code{10}
+@item @code{ECONNABORTED}
+@tab @code{113}
+@item @code{ECONNREFUSED}
+@tab @code{111}
+@item @code{ECONNRESET}
+@tab @code{104}
+@item @code{EDEADLK}
+@tab @code{45}
+@item @code{EDESTADDRREQ}
+@tab @code{121}
+@item @code{EDOM}
+@tab @code{33}
+@item @code{EDQUOT}
+@tab @code{132}
+@item @code{EEXIST}
+@tab @code{17}
+@item @code{EFAULT}
+@tab @code{14}
+@item @code{EFBIG}
+@tab @code{27}
+@item @code{EFTYPE}
+@tab @code{79}
+@item @code{EHOSTDOWN}
+@tab @code{117}
+@item @code{EHOSTUNREACH}
+@tab @code{118}
+@item @code{EIDRM}
+@tab @code{36}
+@item @code{EILSEQ}
+@tab @code{138}
+@item @code{EINPROGRESS}
+@tab @code{119}
+@item @code{EINTR}
+@tab @code{4}
+@item @code{EINVAL}
+@tab @code{22}
+@item @code{EIO}
+@tab @code{5}
+@item @code{EISCONN}
+@tab @code{127}
+@item @code{EISDIR}
+@tab @code{21}
+@item @code{ELOOP}
+@tab @code{92}
+@item @code{EMFILE}
+@tab @code{24}
+@item @code{EMLINK}
+@tab @code{31}
+@item @code{EMSGSIZE}
+@tab @code{122}
+@item @code{EMULTIHOP}
+@tab @code{74}
+@item @code{ENAMETOOLONG}
+@tab @code{91}
+@item @code{ENETDOWN}
+@tab @code{115}
+@item @code{ENETRESET}
+@tab @code{126}
+@item @code{ENETUNREACH}
+@tab @code{114}
+@item @code{ENFILE}
+@tab @code{23}
+@item @code{ENOBUFS}
+@tab @code{105}
+@item @code{ENODATA}
+@tab @code{61}
+@item @code{ENODEV}
+@tab @code{19}
+@item @code{ENOENT}
+@tab @code{2}
+@item @code{ENOEXEC}
+@tab @code{8}
+@item @code{ENOLCK}
+@tab @code{46}
+@item @code{ENOLINK}
+@tab @code{67}
+@item @code{ENOMEM}
+@tab @code{12}
+@item @code{ENOMSG}
+@tab @code{35}
+@item @code{ENOPROTOOPT}
+@tab @code{109}
+@item @code{ENOSPC}
+@tab @code{28}
+@item @code{ENOSR}
+@tab @code{63}
+@item @code{ENOSTR}
+@tab @code{60}
+@item @code{ENOSYS}
+@tab @code{88}
+@item @code{ENOTCONN}
+@tab @code{128}
+@item @code{ENOTDIR}
+@tab @code{20}
+@item @code{ENOTEMPTY}
+@tab @code{90}
+@item @code{ENOTRECOVERABLE}
+@tab @code{141}
+@item @code{ENOTSOCK}
+@tab @code{108}
+@item @code{ENOTSUP}
+@tab @code{134}
+@item @code{ENOTTY}
+@tab @code{25}
+@item @code{ENXIO}
+@tab @code{6}
+@item @code{EOPNOTSUPP}
+@tab @code{95}
+@item @code{EOVERFLOW}
+@tab @code{139}
+@item @code{EOWNERDEAD}
+@tab @code{142}
+@item @code{EPERM}
+@tab @code{1}
+@item @code{EPFNOSUPPORT}
+@tab @code{96}
+@item @code{EPIPE}
+@tab @code{32}
+@item @code{EPROTO}
+@tab @code{71}
+@item @code{EPROTONOSUPPORT}
+@tab @code{123}
+@item @code{EPROTOTYPE}
+@tab @code{107}
+@item @code{ERANGE}
+@tab @code{34}
+@item @code{EROFS}
+@tab @code{30}
+@item @code{ESPIPE}
+@tab @code{29}
+@item @code{ESRCH}
+@tab @code{3}
+@item @code{ESTALE}
+@tab @code{133}
+@item @code{ETIME}
+@tab @code{62}
+@item @code{ETIMEDOUT}
+@tab @code{116}
+@item @code{ETOOMANYREFS}
+@tab @code{129}
+@item @code{ETXTBSY}
+@tab @code{26}
+@item @code{EWOULDBLOCK}
+@tab @code{11}
+@item @code{EXDEV}
+@tab @code{18}
+@end multitable
+
+@subsection Sorted by value
+@multitable @columnfractions .2 .2
+@item @code{EPERM}
+@tab @code{1}
+@item @code{ENOENT}
+@tab @code{2}
+@item @code{ESRCH}
+@tab @code{3}
+@item @code{EINTR}
+@tab @code{4}
+@item @code{EIO}
+@tab @code{5}
+@item @code{ENXIO}
+@tab @code{6}
+@item @code{E2BIG}
+@tab @code{7}
+@item @code{ENOEXEC}
+@tab @code{8}
+@item @code{EBADF}
+@tab @code{9}
+@item @code{ECHILD}
+@tab @code{10}
+@item @code{EAGAIN}
+@tab @code{11}
+@item @code{EWOULDBLOCK}
+@tab @code{11}
+@item @code{ENOMEM}
+@tab @code{12}
+@item @code{EACCES}
+@tab @code{13}
+@item @code{EFAULT}
+@tab @code{14}
+@item @code{EBUSY}
+@tab @code{16}
+@item @code{EEXIST}
+@tab @code{17}
+@item @code{EXDEV}
+@tab @code{18}
+@item @code{ENODEV}
+@tab @code{19}
+@item @code{ENOTDIR}
+@tab @code{20}
+@item @code{EISDIR}
+@tab @code{21}
+@item @code{EINVAL}
+@tab @code{22}
+@item @code{ENFILE}
+@tab @code{23}
+@item @code{EMFILE}
+@tab @code{24}
+@item @code{ENOTTY}
+@tab @code{25}
+@item @code{ETXTBSY}
+@tab @code{26}
+@item @code{EFBIG}
+@tab @code{27}
+@item @code{ENOSPC}
+@tab @code{28}
+@item @code{ESPIPE}
+@tab @code{29}
+@item @code{EROFS}
+@tab @code{30}
+@item @code{EMLINK}
+@tab @code{31}
+@item @code{EPIPE}
+@tab @code{32}
+@item @code{EDOM}
+@tab @code{33}
+@item @code{ERANGE}
+@tab @code{34}
+@item @code{ENOMSG}
+@tab @code{35}
+@item @code{EIDRM}
+@tab @code{36}
+@item @code{EDEADLK}
+@tab @code{45}
+@item @code{ENOLCK}
+@tab @code{46}
+@item @code{ENOSTR}
+@tab @code{60}
+@item @code{ENODATA}
+@tab @code{61}
+@item @code{ETIME}
+@tab @code{62}
+@item @code{ENOSR}
+@tab @code{63}
+@item @code{ENOLINK}
+@tab @code{67}
+@item @code{EPROTO}
+@tab @code{71}
+@item @code{EMULTIHOP}
+@tab @code{74}
+@item @code{EBADMSG}
+@tab @code{77}
+@item @code{EFTYPE}
+@tab @code{79}
+@item @code{ENOSYS}
+@tab @code{88}
+@item @code{ENOTEMPTY}
+@tab @code{90}
+@item @code{ENAMETOOLONG}
+@tab @code{91}
+@item @code{ELOOP}
+@tab @code{92}
+@item @code{EOPNOTSUPP}
+@tab @code{95}
+@item @code{EPFNOSUPPORT}
+@tab @code{96}
+@item @code{ECONNRESET}
+@tab @code{104}
+@item @code{ENOBUFS}
+@tab @code{105}
+@item @code{EAFNOSUPPORT}
+@tab @code{106}
+@item @code{EPROTOTYPE}
+@tab @code{107}
+@item @code{ENOTSOCK}
+@tab @code{108}
+@item @code{ENOPROTOOPT}
+@tab @code{109}
+@item @code{ECONNREFUSED}
+@tab @code{111}
+@item @code{EADDRINUSE}
+@tab @code{112}
+@item @code{ECONNABORTED}
+@tab @code{113}
+@item @code{ENETUNREACH}
+@tab @code{114}
+@item @code{ENETDOWN}
+@tab @code{115}
+@item @code{ETIMEDOUT}
+@tab @code{116}
+@item @code{EHOSTDOWN}
+@tab @code{117}
+@item @code{EHOSTUNREACH}
+@tab @code{118}
+@item @code{EINPROGRESS}
+@tab @code{119}
+@item @code{EALREADY}
+@tab @code{120}
+@item @code{EDESTADDRREQ}
+@tab @code{121}
+@item @code{EMSGSIZE}
+@tab @code{122}
+@item @code{EPROTONOSUPPORT}
+@tab @code{123}
+@item @code{EADDRNOTAVAIL}
+@tab @code{125}
+@item @code{ENETRESET}
+@tab @code{126}
+@item @code{EISCONN}
+@tab @code{127}
+@item @code{ENOTCONN}
+@tab @code{128}
+@item @code{ETOOMANYREFS}
+@tab @code{129}
+@item @code{EDQUOT}
+@tab @code{132}
+@item @code{ESTALE}
+@tab @code{133}
+@item @code{ENOTSUP}
+@tab @code{134}
+@item @code{EILSEQ}
+@tab @code{138}
+@item @code{EOVERFLOW}
+@tab @code{139}
+@item @code{ECANCELED}
+@tab @code{140}
+@item @code{ENOTRECOVERABLE}
+@tab @code{141}
+@item @code{EOWNERDEAD}
+@tab @code{142}
+@end multitable
diff --git a/sim/doc/abi-newlib-open.texi b/sim/doc/abi-newlib-open.texi
new file mode 100644
index 00000000000..3ff4649fcef
--- /dev/null
+++ b/sim/doc/abi-newlib-open.texi
@@ -0,0 +1,38 @@
+@c This file is machine generated by gennltvals.py.
+
+@multitable @columnfractions .2 .2
+@item @code{O_ACCMODE}
+@tab @code{(0|1|2)}
+@item @code{O_APPEND}
+@tab @code{0x0008}
+@item @code{O_CLOEXEC}
+@tab @code{0x40000}
+@item @code{O_CREAT}
+@tab @code{0x0200}
+@item @code{O_DIRECT}
+@tab @code{0x80000}
+@item @code{O_DIRECTORY}
+@tab @code{0x200000}
+@item @code{O_EXCL}
+@tab @code{0x0800}
+@item @code{O_EXEC}
+@tab @code{0x400000}
+@item @code{O_NOCTTY}
+@tab @code{0x8000}
+@item @code{O_NOFOLLOW}
+@tab @code{0x100000}
+@item @code{O_NONBLOCK}
+@tab @code{0x4000}
+@item @code{O_RDONLY}
+@tab @code{0}
+@item @code{O_RDWR}
+@tab @code{2}
+@item @code{O_SEARCH}
+@tab @code{0x400000}
+@item @code{O_SYNC}
+@tab @code{0x2000}
+@item @code{O_TRUNC}
+@tab @code{0x0400}
+@item @code{O_WRONLY}
+@tab @code{1}
+@end multitable
diff --git a/sim/doc/abi-newlib-signal.texi b/sim/doc/abi-newlib-signal.texi
new file mode 100644
index 00000000000..462eef6295d
--- /dev/null
+++ b/sim/doc/abi-newlib-signal.texi
@@ -0,0 +1,145 @@
+@c This file is machine generated by gennltvals.py.
+
+@subsection Sorted by name
+@multitable @columnfractions .2 .2
+@item @code{SIGABRT}
+@tab @code{6}
+@item @code{SIGALRM}
+@tab @code{14}
+@item @code{SIGBUS}
+@tab @code{10}
+@item @code{SIGCHLD}
+@tab @code{20}
+@item @code{SIGCLD}
+@tab @code{20}
+@item @code{SIGCONT}
+@tab @code{19}
+@item @code{SIGEMT}
+@tab @code{7}
+@item @code{SIGFPE}
+@tab @code{8}
+@item @code{SIGHUP}
+@tab @code{1}
+@item @code{SIGILL}
+@tab @code{4}
+@item @code{SIGINT}
+@tab @code{2}
+@item @code{SIGIO}
+@tab @code{23}
+@item @code{SIGIOT}
+@tab @code{6}
+@item @code{SIGKILL}
+@tab @code{9}
+@item @code{SIGLOST}
+@tab @code{29}
+@item @code{SIGPIPE}
+@tab @code{13}
+@item @code{SIGPOLL}
+@tab @code{23}
+@item @code{SIGPROF}
+@tab @code{27}
+@item @code{SIGQUIT}
+@tab @code{3}
+@item @code{SIGSEGV}
+@tab @code{11}
+@item @code{SIGSTOP}
+@tab @code{17}
+@item @code{SIGSYS}
+@tab @code{12}
+@item @code{SIGTERM}
+@tab @code{15}
+@item @code{SIGTRAP}
+@tab @code{5}
+@item @code{SIGTSTP}
+@tab @code{18}
+@item @code{SIGTTIN}
+@tab @code{21}
+@item @code{SIGTTOU}
+@tab @code{22}
+@item @code{SIGURG}
+@tab @code{16}
+@item @code{SIGUSR1}
+@tab @code{30}
+@item @code{SIGUSR2}
+@tab @code{31}
+@item @code{SIGVTALRM}
+@tab @code{26}
+@item @code{SIGWINCH}
+@tab @code{28}
+@item @code{SIGXCPU}
+@tab @code{24}
+@item @code{SIGXFSZ}
+@tab @code{25}
+@end multitable
+
+@subsection Sorted by value
+@multitable @columnfractions .2 .2
+@item @code{SIGHUP}
+@tab @code{1}
+@item @code{SIGINT}
+@tab @code{2}
+@item @code{SIGQUIT}
+@tab @code{3}
+@item @code{SIGILL}
+@tab @code{4}
+@item @code{SIGTRAP}
+@tab @code{5}
+@item @code{SIGABRT}
+@tab @code{6}
+@item @code{SIGIOT}
+@tab @code{6}
+@item @code{SIGEMT}
+@tab @code{7}
+@item @code{SIGFPE}
+@tab @code{8}
+@item @code{SIGKILL}
+@tab @code{9}
+@item @code{SIGBUS}
+@tab @code{10}
+@item @code{SIGSEGV}
+@tab @code{11}
+@item @code{SIGSYS}
+@tab @code{12}
+@item @code{SIGPIPE}
+@tab @code{13}
+@item @code{SIGALRM}
+@tab @code{14}
+@item @code{SIGTERM}
+@tab @code{15}
+@item @code{SIGURG}
+@tab @code{16}
+@item @code{SIGSTOP}
+@tab @code{17}
+@item @code{SIGTSTP}
+@tab @code{18}
+@item @code{SIGCONT}
+@tab @code{19}
+@item @code{SIGCHLD}
+@tab @code{20}
+@item @code{SIGCLD}
+@tab @code{20}
+@item @code{SIGTTIN}
+@tab @code{21}
+@item @code{SIGTTOU}
+@tab @code{22}
+@item @code{SIGPOLL}
+@tab @code{23}
+@item @code{SIGIO}
+@tab @code{23}
+@item @code{SIGXCPU}
+@tab @code{24}
+@item @code{SIGXFSZ}
+@tab @code{25}
+@item @code{SIGVTALRM}
+@tab @code{26}
+@item @code{SIGPROF}
+@tab @code{27}
+@item @code{SIGWINCH}
+@tab @code{28}
+@item @code{SIGLOST}
+@tab @code{29}
+@item @code{SIGUSR1}
+@tab @code{30}
+@item @code{SIGUSR2}
+@tab @code{31}
+@end multitable
diff --git a/sim/doc/abi-newlib-sys.texi b/sim/doc/abi-newlib-sys.texi
new file mode 100644
index 00000000000..9635929ec7e
--- /dev/null
+++ b/sim/doc/abi-newlib-sys.texi
@@ -0,0 +1,105 @@
+@c This file is machine generated by gennltvals.py.
+
+@subsection Sorted by name
+@multitable @columnfractions .2 .2
+@item @code{SYS_argc}
+@tab @code{22}
+@item @code{SYS_argn}
+@tab @code{24}
+@item @code{SYS_argnlen}
+@tab @code{23}
+@item @code{SYS_argv}
+@tab @code{13}
+@item @code{SYS_argvlen}
+@tab @code{12}
+@item @code{SYS_chdir}
+@tab @code{14}
+@item @code{SYS_chmod}
+@tab @code{16}
+@item @code{SYS_close}
+@tab @code{3}
+@item @code{SYS_exit}
+@tab @code{1}
+@item @code{SYS_fstat}
+@tab @code{10}
+@item @code{SYS_getpid}
+@tab @code{8}
+@item @code{SYS_gettimeofday}
+@tab @code{19}
+@item @code{SYS_kill}
+@tab @code{9}
+@item @code{SYS_link}
+@tab @code{21}
+@item @code{SYS_lseek}
+@tab @code{6}
+@item @code{SYS_open}
+@tab @code{2}
+@item @code{SYS_read}
+@tab @code{4}
+@item @code{SYS_reconfig}
+@tab @code{25}
+@item @code{SYS_stat}
+@tab @code{15}
+@item @code{SYS_time}
+@tab @code{18}
+@item @code{SYS_times}
+@tab @code{20}
+@item @code{SYS_unlink}
+@tab @code{7}
+@item @code{SYS_utime}
+@tab @code{17}
+@item @code{SYS_write}
+@tab @code{5}
+@end multitable
+
+@subsection Sorted by value
+@multitable @columnfractions .2 .2
+@item @code{SYS_exit}
+@tab @code{1}
+@item @code{SYS_open}
+@tab @code{2}
+@item @code{SYS_close}
+@tab @code{3}
+@item @code{SYS_read}
+@tab @code{4}
+@item @code{SYS_write}
+@tab @code{5}
+@item @code{SYS_lseek}
+@tab @code{6}
+@item @code{SYS_unlink}
+@tab @code{7}
+@item @code{SYS_getpid}
+@tab @code{8}
+@item @code{SYS_kill}
+@tab @code{9}
+@item @code{SYS_fstat}
+@tab @code{10}
+@item @code{SYS_argvlen}
+@tab @code{12}
+@item @code{SYS_argv}
+@tab @code{13}
+@item @code{SYS_chdir}
+@tab @code{14}
+@item @code{SYS_stat}
+@tab @code{15}
+@item @code{SYS_chmod}
+@tab @code{16}
+@item @code{SYS_utime}
+@tab @code{17}
+@item @code{SYS_time}
+@tab @code{18}
+@item @code{SYS_gettimeofday}
+@tab @code{19}
+@item @code{SYS_times}
+@tab @code{20}
+@item @code{SYS_link}
+@tab @code{21}
+@item @code{SYS_argc}
+@tab @code{22}
+@item @code{SYS_argnlen}
+@tab @code{23}
+@item @code{SYS_argn}
+@tab @code{24}
+@item @code{SYS_reconfig}
+@tab @code{25}
+@end multitable
diff --git a/sim/doc/arch-aarch64.texi b/sim/doc/arch-aarch64.texi
new file mode 100644
index 00000000000..bbf6cd983c6
--- /dev/null
+++ b/sim/doc/arch-aarch64.texi
@@ -0,0 +1,28 @@
+@node AArch64
+@chapter AArch64
+Arm Ltd's 64-bit ARM64 RISC architecture.
+
+@node AArch64 Environment Support
+@section Environment Support
+Only the virtual environment is supported.
+
+@node AArch64 Virtual Environment Syscall ABI
+@subsection Virtual Environment Syscall ABI
+The syscall ABI, as used by the RDI (Angel) monitor and @value{libgloss} in the
+virtual environment, uses the interface defined in the following table.
+
+@multitable @columnfractions .2 .3 .5
+@headitem Field @tab Assembly/Register @tab Description
+@item instruction
+@tab @center @code{hlt #0xf000;}
+@tab The assembly instruction to invoke the syscall handler.
+@item (in) syscall NR
+@tab @center @code{w0}
+@tab The system call number to select which function to run.
+@item (in) parameters
+@tab @center @code{x1}
+@tab Pointer to the syscall argument array (64-bit elements).
+@item (out) return & error
+@tab @center @code{x0}
+@tab The return value (most commonly used).
+@end multitable
diff --git a/sim/doc/arch-arm.texi b/sim/doc/arch-arm.texi
new file mode 100644
index 00000000000..74e4c08ceec
--- /dev/null
+++ b/sim/doc/arch-arm.texi
@@ -0,0 +1,53 @@
+@node ARM
+@chapter ARM
+Arm Ltd's 32-bit ARM RISC architecture.
+
+Forked from the venerable ARMulator project.
+
+@node ARM ISA Support
+@section ISA Support
+ARM6, ARM7, ARM32, and Thumb are supported.
+
+@node ARM Environment Support
+@section Environment Support
+Only the virtual environment is supported.
+
+@node ARM Virtual Environment Syscall ABI
+@subsection Virtual Environment Syscall ABI
+The syscall ABI, as used by @url{https://sourceware.org/redboot/,RedBoot} and
+@value{libgloss} in the virtual environment, uses the interface defined in the
+following table.
+
+@c There is also support for syscall NR in the SWI number instead of R0, but
+@c documenting just this one interface seems easiest.
+@c The thumb "swi 0x18" does not appear to be implemented currently.
+@multitable @columnfractions .2 .3 .5
+@headitem Field @tab Assembly/Register @tab Description
+@item instruction
+@tab @center @code{swi 0x180001;}
+@tab The assembly instruction to invoke the syscall handler.
+@item (in) syscall NR
+@tab @center @code{R0}
+@tab The system call number to select which function to run.
+@item (in) arg 1
+@tab @center @code{R1}
+@tab The first syscall argument.
+@item (in) arg 2
+@tab @center @code{R2}
+@tab The second syscall argument.
+@item (in) arg 3
+@tab @center @code{R3}
+@tab The third syscall argument.
+@item (in) arg 4
+@tab @center @code{R4}
+@tab The fourth syscall argument.
+@item (in) arg 5
+@tab @center @code{R5}
+@tab The fifth syscall argument.
+@item (in) arg 6
+@tab @center @code{R6}
+@tab The sixth syscall argument.
+@item (out) return & error
+@tab @center @code{R0}
+@tab The return value (most commonly used).
+@end multitable
diff --git a/sim/doc/arch-avr.texi b/sim/doc/arch-avr.texi
new file mode 100644
index 00000000000..b699d806879
--- /dev/null
+++ b/sim/doc/arch-avr.texi
@@ -0,0 +1,7 @@
+@node AVR
+@chapter AVR
+Atmel's AVR 8-bit processors.
+
+@node AVR Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-bfin.texi b/sim/doc/arch-bfin.texi
new file mode 100644
index 00000000000..a4abdb73daf
--- /dev/null
+++ b/sim/doc/arch-bfin.texi
@@ -0,0 +1,1166 @@
+@node Blackfin
+@chapter Blackfin
+Analog Devices Inc's 32-bit Blackfin RISC processor.
+
+@node Blackfin ISA Support
+@section ISA Support
+The BF535 is not supported and never will be.
+
+BF5xx CPUs should be fully supported for all BF5xx CPUs.
+
+BF60x should be OK, but it's in-progress.
+
+BF70x has not been evaluated at all.  It might work, it might not.
+
+@node Blackfin Custom Instructions
+@section Custom Instrutions
+A few debug instructions are provided to assist developers.  These use invalid
+opcode ranges, so if executed on real hardware, they'll trigger undefined
+instruction exceptions.
+
+The GNU assembler supports these and will generate the right opcodes.
+
+@multitable @columnfractions .4 .6
+@headitem Instruction @tab Description
+@item @code{DBG @var{register}}
+@tab Dump the specified register name and value.
+@item @code{ABORT}
+@tab Halt the simulator as if an error occurred.
+@item @code{HLT}
+@tab Halt the simulator normally.
+@item @code{OUTC @var{dreg}}
+@tab Output the register character to stdout.
+@item @code{DBGHALT}
+@tab Unsupported.
+@item @code{DBGCMPLX @var{register}}
+@tab Unsupported.
+@item @code{DBG}
+@tab Unsupported.
+@item @code{PRNT @var{register}}
+@tab Unsupported.
+@end multitable
+
+@node Blackfin Environment Support
+@section Environment Support
+All environments are fully supported: virtual, user, operating.
+
+@node Blackfin Virtual Environment Syscall ABI
+@subsection Virtual Environment Syscall ABI
+The syscall ABI, as used by @value{libgloss} in the virtual environment, uses
+the interface defined in the following table.
+
+@multitable @columnfractions .2 .3 .5
+@headitem Field @tab Code/Register @tab Description
+@item instruction
+@tab @center @code{EXCPT 0;}
+@tab The assembly instruction to invoke the syscall handler.
+@item (in) syscall NR
+@tab @center @code{P0}
+@tab The system call number to select which function to run.
+@item (in) arguments
+@tab @center @code{R0}
+@tab A pointer to an array of 32-bit integers holding the syscall arguments.
+@item (in) arg 1
+@tab @center @code{((long*)R0)[0]}
+@tab The first syscall argument.
+@item (in) arg 2
+@tab @center @code{((long*)R0)[1]}
+@tab The second syscall argument.
+@item (in) arg 3
+@tab @center @code{((long*)R0)[2]}
+@tab The third syscall argument.
+@item (in) arg 4
+@tab @center @code{((long*)R0)[3]}
+@tab The fourth syscall argument.
+@item (in) arg 5
+@tab @center @code{((long*)R0)[4]}
+@tab The fifth syscall argument.
+@item (in) arg 6
+@tab @center @code{((long*)R0)[5]}
+@tab The sixth syscall argument.
+@item (out) return 1
+@tab @center @code{R0}
+@tab The first return value (most commonly used).
+@item (out) return 2
+@tab @center @code{R1}
+@tab The second return value (e.g. for 64-bit values).
+@item (out) error
+@tab @center @code{R2}
+@tab Whether an error occurred.
+@end multitable
+
+@node Blackfin Models
+@section CPU Models
+The Blackfin port includes support for many CPU models that match the stock
+ones commercially available.  Selecting a specific SoC with @option{--model}
+will construct all the corresponding devices models (peripherals) and memory
+layouts (e.g. L1 caches) so you don't have to.
+
+The BF537 is the default SoC as one of the most successful & common models on
+the market (at least at the time of the development of this port).
+
+If you want a bare environment to completely construct your own synthetic CPU
+(e.g. for prototyping a new SoC combination), use the BF500 model.
+
+@multitable @columnfractions .1 .1 .8
+@headitem Model @tab sirevs @tab Description
+@item @center bf000
+@tab 0
+@tab An ISA-only Blackfin cpu with no device models.  This means no Core or
+System MMRs will be mapped, nor any L1/L2 caches (other than the scratchpad
+SRAM).
+@item @center bf504
+@tab 0
+@tab The BF504 from the BF50x family.
+@item @center bf506
+@tab 0
+@tab The BF506 from the BF50x family.
+@item @center bf512
+@tab 0 1 2
+@tab The BF512 from the BF51x family.
+@item @center bf514
+@tab 0 1 2
+@tab The BF514 from the BF51x family.
+@item @center bf516
+@tab 0 1 2
+@tab The BF516 from the BF51x family.
+@item @center bf518
+@tab 0 1 2
+@tab The BF518 from the BF51x family.
+@item @center bf522
+@tab 0 1 2
+@tab The BF522 & BF522C from the BF52x family.
+@item @center bf523
+@tab 0 1 2
+@tab The BF523 & BF523C from the BF52x family.
+@item @center bf524
+@tab 0 1 2
+@tab The BF524 & BF524C from the BF52x family.
+@item @center bf525
+@tab 0 1 2
+@tab The BF525 & BF525C from the BF52x family.
+@item @center bf526
+@tab 0 1 2
+@tab The BF526 & BF526C from the BF52x family.
+@item @center bf527
+@tab 0 1 2
+@tab The BF527 & BF527C from the BF52x family.
+@item @center bf531
+@tab 1 2 3 4 5 6
+@tab The BF531 from the BF533 family.
+@item @center bf532
+@tab 1 2 3 4 5 6
+@tab The BF532 from the BF533 family.
+@item @center bf533
+@tab 1 2 3 4 5 6
+@tab The BF533 from the BF533 family.
+@item @center bf534
+@tab 0 1 2 3
+@tab The BF534 from the BF537 family.
+@item @center bf536
+@tab 0 1 2 3
+@tab The BF536 from the BF537 family.
+@item @center bf537
+@tab 0 1 2 3
+@tab The BF537 from the BF537 family.
+@item @center bf538
+@tab 0 1 2 3 4 5
+@tab The BF538 & BF538F.
+@item @center bf539
+@tab 0 1 2 3 4 5
+@tab The BF539 & BF539F.
+@item @center bf542
+@tab 0 1 2 4
+@tab The BF542 from the BF54x family.
+@item @center bf544
+@tab 0 1 2 4
+@tab The BF544 from the BF54x family.
+@item @center bf547
+@tab 0 1 2 4
+@tab The BF547 from the BF54x family.
+@item @center bf548
+@tab 0 1 2 4
+@tab The BF548 from the BF54x family.
+@item @center bf549
+@tab 0 1 2 4
+@tab The BF549 from the BF54x family.
+@item @center bf561
+@tab 5
+@tab The BF561 (dual-core not supported currently).
+@item @center bf592
+@tab 0 1
+@tab The BF592.
+@end multitable
+
+@node Blackfin Silicon Revisions (sirevs)
+@section Silicon Revisions (sirevs)
+The @option{--sirev} option allows for specifying the silicon revision of the
+core.  The simulator itself does not use this information to change behavior,
+only to expose it to the running software (via the @code{CHIPID} MMR).
+
+More specifically, the simulator does @b{not} implement any hardware anomalies.
+It provides a simulation of the ideal environment---one that is not buggy.
+
+The silicon revision does implicitly select the bfrom that is mapped in.
+@xref{Blackfin ROMs (bfroms)}.
+
+If no @option{--sirev} is specified, then the latest known version for the
+specified @option{--model} (@xref{Blackfin Models}) is used.
+
+@node Blackfin ROMs (bfroms)
+@section Blackfin ROMs (bfroms)
+All Blackfin CPUs come with an on-chip ROM referred to as "the Blackfin ROM"
+or "bfrom" for short.  It is (usually) the first thing executed at power-on
+as a first stage boot loader.
+
+The ROM is drastically different between processor families, and may differ
+even between silicon revisions.
+
+Dumps of many CPU & silicon revisions are available, but not shipped as part
+of the GNU Simulator due to unclear licensing terms.  Instead, a stub (zero
+filled) ROM is mapped into the corresponding memory region.
+
+Here are a list of known issues when using a stub ROM.
+
+@itemize
+@item It is not possible to boot LDR (Blackfin loader) files directly.
+Fortunately, pretty much no one ever wants to do that, and instead will execute
+Blackfin ELFs directly.  The simulator will have no problem loading them.
+
+@item Software reset (via the bfrom's @code{SYSCTRL_SOFTRESET}) for some
+processors will not work.  Attempting to do a software reset will most likely
+result in hardware exceptions & double faults.
+
+@item Accessing OTP (available on some processors) via the bfrom's APIs will
+not work.  Attempting to do so will most likely result in hardware exceptions &
+double faults.  @xref{bfin_otp}.
+
+@end itemize
+
+@node Blackfin Device Models
+@section Device Models
+Many peripherals are available.
+
+Many properties and behaviors are standardized across models:
+@itemize @bullet
+@item @code{type} is used to communicate which variant to use based on family.
+Not all models change behavior across families, so this might not be checked.
+For example, the @ref{bfin_sic} uses this to determine register layout and
+default values.
+@item @code{reg} length should match exactly the expected space that the block
+of registers require.  Short or excess mappings are not supported.
+@item Unaligned MMR access is not allowed and will trigger exceptions or
+hardware error interrupts (to match real hardware).
+@end itemize
+
+@node bfin_cec
+@subsection bfin_cec
+@dvindex bfin_cec
+@dvindex Blackfin CEC
+@dvindex Blackfin Core Event Controller
+The Blackfin Core Event Controller (CEC) model.
+
+Attaching device:
+@example
+/core/bfin_cec
+/core/bfin_cec/reg 0xffe02100 0x14
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{emu} (input): Emulation Interrupt (e.g. JTAG)
+@item @code{rst} (input): Reset Interrupt (hardware pin or watchdog)
+@item @code{nmi} (input): Nonmaskable Interrupt (hardware pin or watchdog)
+@item @code{evx} (input): Hardware Exceptions
+@item @code{ivhw} (input): Hardware Error Interrupt
+@item @code{ivtmr} (input): Core Timer Interrupt
+@item @code{ivg7} (input): General-purpose Core Interrupt
+@item @code{ivg8} (input): General-purpose Core Interrupt
+@item @code{ivg9} (input): General-purpose Core Interrupt
+@item @code{ivg10} (input): General-purpose Core Interrupt
+@item @code{ivg11} (input): General-purpose Core Interrupt
+@item @code{ivg12} (input): General-purpose Core Interrupt
+@item @code{ivg13} (input): General-purpose Core Interrupt
+@item @code{ivg14} (input): General-purpose Core Interrupt
+@item @code{ivg15} (input): General-purpose Core Interrupt
+@end itemize
+
+@node bfin_ctimer
+@subsection bfin_ctimer
+@dvindex bfin_ctimer
+@dvindex Blackfin Timers
+@dvindex Blackfin Core Timer
+The Blackfin Core Timer model.
+
+Attaching device:
+@example
+/core/bfin_ctimer
+/core/bfin_ctimer/reg 0xffe03000 0x10
+# Connect ctimer's ivtmr output port to cec's ivtmr input port.
+/core/bfin_ctimer > ivtmr ivtmr /core/bfin_cec
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{ivtmr} (output): Timer expired
+@end itemize
+
+@node bfin_dma
+@subsection bfin_dma
+@dvindex bfin_dma
+@dvindex Blackfin DMA
+@dvindex Blackfin Direct Memory Access Controller
+The Blackfin Direct Memory Access (DMA) Controller model.
+
+Ports:
+@itemize @bullet
+@item @code{di} (output): DMA finished
+@end itemize
+
+@node bfin_dmac
+@subsection bfin_dmac
+@dvindex bfin_dmac
+@dvindex Blackfin DMA
+@dvindex Blackfin DMAC
+@dvindex Blackfin Direct Memory Access Channel
+The Blackfin Direct Memory Access (DMA) Channel model.
+
+BF50x Ports:
+@itemize @bullet
+@item @code{ppi@@0} (input):
+@item @code{rsi} (input):
+@item @code{sport@@0_rx} (input):
+@item @code{sport@@0_tx} (input):
+@item @code{sport@@1_tx} (input):
+@item @code{sport@@1_rx} (input):
+@item @code{spi@@0} (input):
+@item @code{spi@@1} (input):
+@item @code{uart2@@0_rx} (input):
+@item @code{uart2@@0_tx} (input):
+@item @code{uart2@@1_rx} (input):
+@item @code{uart2@@1_tx} (input):
+@end itemize
+
+BF51x Ports:
+@itemize @bullet
+@item @code{ppi@@0} (input):
+@item @code{emac_rx} (input):
+@item @code{emac_tx} (input):
+@item @code{sport@@0_rx} (input):
+@item @code{sport@@0_tx} (input):
+@c @item @code{rsi} (input):
+@item @code{sport@@1_tx} (input):
+@c @item @code{spi@@1} (input):
+@item @code{sport@@1_rx} (input):
+@item @code{spi@@0} (input):
+@item @code{uart@@0_rx} (input):
+@item @code{uart@@0_tx} (input):
+@item @code{uart@@1_rx} (input):
+@item @code{uart@@1_tx} (input):
+@end itemize
+
+BF51x Ports:
+@itemize @bullet
+@item @code{ppi@@0} (input):
+@c @item @code{nfc} (input):
+@item @code{emac_rx} (input):
+@c @item @code{hostdp} (input):
+@item @code{emac_tx} (input):
+@c @item @code{nfc} (input):
+@item @code{sport@@0_tx} (input):
+@item @code{sport@@0_rx} (input):
+@item @code{sport@@1_tx} (input):
+@item @code{sport@@1_rx} (input):
+@item @code{spi} (input):
+@item @code{uart@@0_tx} (input):
+@item @code{uart@@0_rx} (input):
+@item @code{uart@@1_tx} (input):
+@item @code{uart@@1_rx} (input):
+@end itemize
+
+BF533 Ports:
+@itemize @bullet
+@item @code{ppi@@0} (input):
+@item @code{sport@@0_tx} (input):
+@item @code{sport@@0_rx} (input):
+@item @code{sport@@1_tx} (input):
+@item @code{sport@@1_rx} (input):
+@item @code{spi} (input):
+@item @code{uart@@0_tx} (input):
+@item @code{uart@@0_rx} (input):
+@end itemize
+
+BF537 Ports:
+@itemize @bullet
+@item @code{ppi@@0} (input):
+@item @code{emac_rx} (input):
+@item @code{emac_tx} (input):
+@item @code{sport@@0_tx} (input):
+@item @code{sport@@0_rx} (input):
+@item @code{sport@@1_tx} (input):
+@item @code{sport@@1_rx} (input):
+@item @code{spi} (input):
+@item @code{uart@@0_tx} (input):
+@item @code{uart@@0_rx} (input):
+@item @code{uart@@1_tx} (input):
+@item @code{uart@@1_rx} (input):
+@end itemize
+
+BF538 Ports (DMAC0):
+@itemize @bullet
+@item @code{ppi@@0} (input):
+@item @code{sport@@0_rx} (input):
+@item @code{sport@@0_tx} (input):
+@item @code{sport@@1_rx} (input):
+@item @code{sport@@1_tx} (input):
+@item @code{spi@@0} (input):
+@item @code{uart@@0_rx} (input):
+@item @code{uart@@0_tx} (input):
+@end itemize
+
+BF538 Ports (DMAC1):
+@itemize @bullet
+@item @code{sport@@2_rx} (input):
+@item @code{sport@@2_tx} (input):
+@item @code{sport@@3_rx} (input):
+@item @code{sport@@3_tx} (input):
+@item @code{spi@@1} (input):
+@item @code{spi@@2} (input):
+@item @code{uart@@1_rx} (input):
+@item @code{uart@@1_tx} (input):
+@item @code{uart@@2_rx} (input):
+@item @code{uart@@2_tx} (input):
+@end itemize
+
+BF54x Ports (DMAC0):
+@itemize @bullet
+@item @code{sport@@0_rx} (input):
+@item @code{sport@@0_tx} (input):
+@item @code{sport@@1_rx} (input):
+@item @code{sport@@1_tx} (input):
+@item @code{spi@@0} (input):
+@item @code{spi@@1} (input):
+@item @code{uart2@@0_rx} (input):
+@item @code{uart2@@0_tx} (input):
+@item @code{uart2@@1_rx} (input):
+@item @code{uart2@@1_tx} (input):
+@item @code{atapi} (input):
+@item @code{atapi} (input):
+@end itemize
+
+BF54x Ports (DMAC1):
+@itemize @bullet
+@item @code{eppi@@0} (input):
+@item @code{eppi@@1} (input):
+@item @code{eppi@@2} (input):
+@item @code{pixc} (input):
+@item @code{pixc} (input):
+@item @code{pixc} (input):
+@item @code{sport@@2_rx} (input):
+@item @code{sport@@2_tx} (input):
+@item @code{sport@@3_rx} (input):
+@item @code{sport@@3_tx} (input):
+@item @code{sdh} (input):
+@c @item @code{nfc} (input):
+@item @code{spi@@2} (input):
+@item @code{uart2@@2_rx} (input):
+@item @code{uart2@@2_tx} (input):
+@item @code{uart2@@3_rx} (input):
+@item @code{uart2@@3_tx} (input):
+@end itemize
+
+BF561 Ports (DMAC0):
+@itemize @bullet
+@item @code{sport@@0_rx} (input):
+@item @code{sport@@0_tx} (input):
+@item @code{sport@@1_rx} (input):
+@item @code{sport@@1_tx} (input):
+@item @code{spi@@0} (input):
+@item @code{uart@@0_rx} (input):
+@item @code{uart@@0_tx} (input):
+@end itemize
+
+BF561 Ports (DMAC1):
+@itemize @bullet
+@item @code{ppi@@0} (input):
+@item @code{ppi@@1} (input):
+@end itemize
+
+BF59x Ports:
+@itemize @bullet
+@item @code{ppi@@0} (input):
+@item @code{sport@@0_tx} (input):
+@item @code{sport@@0_rx} (input):
+@item @code{sport@@1_tx} (input):
+@item @code{sport@@1_rx} (input):
+@item @code{spi@@0} (input):
+@item @code{spi@@1} (input):
+@item @code{uart@@0_rx} (input):
+@item @code{uart@@0_tx} (input):
+@end itemize
+
+@node bfin_ebiu_amc
+@subsection bfin_ebiu_amc
+@dvindex bfin_ebiu_amc
+@dvindex Blackfin EBIU
+@dvindex Blackfin External Bus Interface Unit
+@dvindex Blackfin AMC
+@dvindex Blackfin Asynchronous Memory Controller
+The Blackfin External Bus Interface Unit (EBIU) Asynchronous Memory Controller.
+
+Attaching device:
+@example
+/core/bfin_ebiu_amc
+/core/bfin_ebiu_amc/reg 0xffc00a00 0xc
+/core/bfin_ebiu_amc/type 537
+@end example
+
+@node bfin_ebiu_ddrc
+@subsection bfin_ebiu_ddrc
+@dvindex bfin_ebiu_ddrc
+@dvindex Blackfin EBIU
+@dvindex Blackfin External Bus Interface Unit
+@dvindex Blackfin DDR
+@dvindex Blackfin DDRC
+@dvindex Blackfin Double Data Rate Memory
+The Blackfin External Bus Interface Unit (EBIU) DDR Controller (DDRC) model.
+
+Attaching device:
+@example
+/core/bfin_ebiu_ddrc
+/core/bfin_ebiu_ddrc/reg 0xffc00a20 0xb0
+/core/bfin_ebiu_ddrc/type 548
+@end example
+
+@node bfin_ebiu_sdc
+@subsection bfin_ebiu_sdc
+@dvindex bfin_ebiu_sdc
+@dvindex Blackfin EBIU
+@dvindex Blackfin External Bus Interface Unit
+@dvindex Blackfin SDRAM
+@dvindex Blackfin Synchronous Dynamic Random-Access Memory
+The Blackfin External Bus Interface Unit (EBIU) SDRAM Controller (SDC) model.
+
+Attaching device:
+@example
+/core/bfin_ebiu_sdc
+/core/bfin_ebiu_sdc/reg 0xffc00a10 0x10
+/core/bfin_ebiu_sdc/type 537
+@end example
+
+@node bfin_emac
+@subsection bfin_emac
+@dvindex bfin_emac
+@dvindex Blackfin EMAC
+@dvindex Blackfin Ethernet Media Access Controller
+The Blackfin Ethernet Media Access Controller (EMAC) model.
+
+Attaching device:
+@example
+/core/bfin_emac
+/core/bfin_emac/reg 0xffc03000 0x200
+/core/bfin_emac/type 537
+/core/bfin_emac > rx emac_rx /core/bfin_dmac@@0
+/core/bfin_emac > tx emac_tx /core/bfin_dmac@@0
+/core/bfin_emac > stat int0 /core/glue-or@@2
+/core/bfin_emac/eth_phy
+/core/bfin_emac/eth_phy/reg 0 0x20
+/core/bfin_emac/eth_phy/type 537
+/core/glue-or@@2
+/core/glue-or@@2/interrupt-ranges 0x0 0x8
+/core/glue-or@@2 > int0 int2@@0 /core/bfin_sic
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{tx} (output): Transmit finished
+@item @code{rx} (output): Receive finished
+@item @code{stat} (output): Status changed
+@end itemize
+
+@node bfin_eppi
+@subsection bfin_eppi
+@dvindex bfin_eppi
+@dvindex Blackfin PPI
+@dvindex Blackfin Parallel Port Interface
+@dvindex Blackfin EPPI
+@dvindex Blackfin Enhanced Parallel Port Interface
+The Blackfin Enhanced Parallel Port Interface (EPPI) model.
+
+Attaching device:
+@example
+/core/bfin_eppi@@0
+/core/bfin_eppi@@0/reg 0xffc01000 0x40
+/core/bfin_eppi@@0/type 548
+/core/bfin_eppi@@0 > stat int2@@0 /core/bfin_sic
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{stat} (output): Status changed
+@end itemize
+
+@node bfin_evt
+@subsection bfin_evt
+@dvindex bfin_evt
+@dvindex Blackfin EVT
+@dvindex Blackfin Event Vector Table
+The Blackfin Event Vector Table (EVT) model.
+
+Attaching device:
+@example
+/core/bfin_evt
+/core/bfin_evt/reg 0xffe02000 0x40
+@end example
+
+@node bfin_gpio
+@subsection bfin_gpio
+@dvindex bfin_gpio
+@dvindex Blackfin GPIO
+@dvindex Blackfin General Purpose Ports
+The Blackfin General Purpose Ports (GPIO) model for "older" systems.
+
+Attaching device:
+@example
+/core/bfin_gpio@@5
+/core/bfin_gpio@@5/reg 0xffc00700 0x44
+/core/bfin_gpio@@5/type 537
+/core/bfin_gpio@@5 > mask_b int0 /core/glue-or@@0x1f
+/core/bfin_gpio@@5 > mask_a int0 /core/glue-or@@0x1b
+/core/glue-or@@0x1f
+/core/glue-or@@0x1f/interrupt-ranges 0x0 0x2
+/core/glue-or@@0x1f > int0 int31@@0 /core/bfin_sic
+/core/glue-or@@0x1b
+/core/glue-or@@0x1b/interrupt-ranges 0x0 0x2
+/core/glue-or@@0x1b > int0 int27@@0 /core/bfin_sic
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{mask_a} (output):
+@item @code{mask_b} (output):
+@item @code{p0} (bidirectional):
+@item @code{p1} (bidirectional):
+@item @code{p2} (bidirectional):
+@item @code{p3} (bidirectional):
+@item @code{p4} (bidirectional):
+@item @code{p5} (bidirectional):
+@item @code{p6} (bidirectional):
+@item @code{p7} (bidirectional):
+@item @code{p8} (bidirectional):
+@item @code{p9} (bidirectional):
+@item @code{p10} (bidirectional):
+@item @code{p11} (bidirectional):
+@item @code{p12} (bidirectional):
+@item @code{p13} (bidirectional):
+@item @code{p14} (bidirectional):
+@item @code{p15} (bidirectional):
+@end itemize
+
+@node bfin_gpio2
+@subsection bfin_gpio2
+@dvindex bfin_gpio2
+@dvindex Blackfin GPIO
+@dvindex Blackfin General Purpose Ports
+The Blackfin General Purpose Ports (GPIO) model for "new style" BF54x.
+
+Attaching device:
+@example
+/core/bfin_gpio2@@0
+/core/bfin_gpio2@@0/reg 0xffc014c0 0x20
+/core/bfin_gpio2@@0/type 548
+/core/bfin_gpio2@@0 > p15 piq15@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p14 piq14@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p13 piq13@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p12 piq12@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p11 piq11@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p10 piq10@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p9 piq9@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p8 piq8@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p7 piq7@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p6 piq6@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p5 piq5@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p4 piq4@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p3 piq3@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p2 piq2@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p1 piq1@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p0 piq0@@0 /core/bfin_pint@@1
+/core/bfin_gpio2@@0 > p15 piq15@@0 /core/bfin_pint@@0
+/core/bfin_gpio2@@0 > p14 piq14@@0 /core/bfin_pint@@0
+/core/bfin_gpio2@@0 > p13 piq13@@0 /core/bfin_pint@@0
+/core/bfin_gpio2@@0 > p12 piq12@@0 /core/bfin_pint@@0
+/core/bfin_gpio2@@0 > p11 piq11@@0 /core/bfin_pint@@0
+/core/bfin_gpio2@@0 > p10 piq10@@0 /core/bfin_pint@@0
+/core/bfin_gpio2@@0 > p9 piq9@@0 /core/bfin_pint@@0
+/core/bfin_gpio2@@0 > p8 piq8@@0 /core/bfin_pint@@0
+/core/bfin_gpio2@@0 > p7 piq7@@0 /core/bfin_pint@@0
+/core/bfin_gpio2@@0 > p6 piq6@@0 /core/bfin_pint@@0
+/core/bfin_gpio2@@0 > p5 piq5@@0 /core/bfin_pint@@0
+/core/bfin_gpio2@@0 > p4 piq4@@0 /core/bfin_pint@@0
+/core/bfin_gpio2@@0 > p3 piq3@@0 /core/bfin_pint@@0
+/core/bfin_gpio2@@0 > p2 piq2@@0 /core/bfin_pint@@0
+/core/bfin_gpio2@@0 > p1 piq1@@0 /core/bfin_pint@@0
+/core/bfin_gpio2@@0 > p0 piq0@@0 /core/bfin_pint@@0
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{p0} (bidirectional):
+@item @code{p1} (bidirectional):
+@item @code{p2} (bidirectional):
+@item @code{p3} (bidirectional):
+@item @code{p4} (bidirectional):
+@item @code{p5} (bidirectional):
+@item @code{p6} (bidirectional):
+@item @code{p7} (bidirectional):
+@item @code{p8} (bidirectional):
+@item @code{p9} (bidirectional):
+@item @code{p10} (bidirectional):
+@item @code{p11} (bidirectional):
+@item @code{p12} (bidirectional):
+@item @code{p13} (bidirectional):
+@item @code{p14} (bidirectional):
+@item @code{p15} (bidirectional):
+@end itemize
+
+@node bfin_gptimer
+@subsection bfin_gptimer
+@dvindex bfin_gptimer
+@dvindex Blackfin Timers
+@dvindex Blackfin General Purpose Timers
+The Blackfin General Purpose Timers (GPtimer) model.
+
+Attaching device:
+@example
+/core/bfin_gptimer@@0
+/core/bfin_gptimer@@0/reg 0xffc00600 0x10
+/core/bfin_gptimer@@0/type 537
+/core/bfin_gptimer@@0 > stat int19@@0 /core/bfin_sic
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{stat} (output):
+@end itemize
+
+@node bfin_jtag
+@subsection bfin_jtag
+@dvindex bfin_jtag
+@dvindex Blackfin JTAG
+@dvindex Blackfin ICE
+@dvindex Blackfin Joint Test Action Group
+The Blackfin JTAG model.
+
+Attaching device:
+@example
+/core/bfin_jtag
+/core/bfin_jtag/reg 0xffe05000 0xc
+@end example
+
+@code{DSPID} is initialized from the @option{--model}.
+
+@node bfin_mmu
+@subsection bfin_mmu
+@dvindex bfin_mmu
+@dvindex Blackfin MPU
+@dvindex Blackfin Memory Protection Unit
+@dvindex Blackfin MMU
+@dvindex Blackfin Memory Management Unit
+The Blackfin Memory Management Unit (MMU) model.
+
+Attaching device:
+@example
+/core/bfin_mmu
+/core/bfin_mmu/reg 0xffe00000 0x2000
+@end example
+
+@node bfin_nfc
+@subsection bfin_nfc
+@dvindex bfin_nfc
+@dvindex Blackfin NFC
+@dvindex Blackfin NAND
+@dvindex Blackfin NAND Flash Memory Controller
+The Blackfin NAND Flash Memory Controller (NFC) model.
+
+Attaching device:
+@example
+/core/bfin_nfc
+/core/bfin_nfc/reg 0xffc03b00 0x50
+/core/bfin_nfc/type 548
+/core/bfin_nfc > stat int28@@1 /core/bfin_sic
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{stat} (output):
+@end itemize
+
+@node bfin_otp
+@subsection bfin_otp
+@dvindex bfin_otp
+@dvindex Blackfin OTP
+@dvindex Blackfin One-Time Programmable Memory
+The Blackfin One-Time Programmable Memory (OTP) model.
+
+Attaching device:
+@example
+/core/bfin_otp
+/core/bfin_otp/reg 0xffc03600 0xa0
+/core/bfin_otp/type 527
+/core/bfin_otp > stat int26@@0 /core/bfin_sic
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{stat} (output):
+@end itemize
+
+@node bfin_pfmon
+@subsection bfin_pfmon
+@dvindex bfin_pfmon
+@dvindex Blackfin Performance Monitor
+The Blackfin Performance Monitor model.
+
+Attaching device:
+@example
+/core/bfin_pfmon
+/core/bfin_pfmon/reg 0xffe08000 0x108
+@end example
+
+@node bfin_pint
+@subsection bfin_pint
+@dvindex bfin_pint
+@dvindex Blackfin Interrupt Controller
+@dvindex Blackfin Pin Interrupt Controller
+The Blackfin Pin Interrupt (PINT) model.
+
+Attaching device:
+@example
+/core/bfin_pint@@0
+/core/bfin_pint@@0/reg 0xffc01400 0x28
+/core/bfin_pint@@0/type 548
+/core/bfin_pint@@0 > stat int19@@0 /core/bfin_sic
+@end example
+
+Ports (replace @code{@@X} with @code{@@0...@@7}):
+@itemize @bullet
+@item @code{stat} (output):
+@item @code{piq0@@X} (input):
+@item @code{piq1@@X} (input):
+@item @code{piq2@@X} (input):
+@item @code{piq3@@X} (input):
+@item @code{piq4@@X} (input):
+@item @code{piq5@@X} (input):
+@item @code{piq6@@X} (input):
+@item @code{piq7@@X} (input):
+@item @code{piq8@@X} (input):
+@item @code{piq9@@X} (input):
+@item @code{piq10@@X} (input):
+@item @code{piq11@@X} (input):
+@item @code{piq12@@X} (input):
+@item @code{piq13@@X} (input):
+@item @code{piq14@@X} (input):
+@item @code{piq15@@X} (input):
+@item @code{piq16@@X} (input):
+@item @code{piq17@@X} (input):
+@item @code{piq18@@X} (input):
+@item @code{piq19@@X} (input):
+@item @code{piq20@@X} (input):
+@item @code{piq21@@X} (input):
+@item @code{piq22@@X} (input):
+@item @code{piq23@@X} (input):
+@item @code{piq24@@X} (input):
+@item @code{piq25@@X} (input):
+@item @code{piq26@@X} (input):
+@item @code{piq27@@X} (input):
+@item @code{piq28@@X} (input):
+@item @code{piq29@@X} (input):
+@item @code{piq30@@X} (input):
+@item @code{piq31@@X} (input):
+@end itemize
+
+@node bfin_pll
+@subsection bfin_pll
+@dvindex bfin_pll
+@dvindex Blackfin PLL
+@dvindex Blackfin Phase Lock Loop
+The Blackfin Phase Lock Loop (PLL) model.
+
+Attaching device:
+@example
+/core/bfin_pll
+/core/bfin_pll/reg 0xffc00000 0x18
+/core/bfin_pll/type 537
+/core/bfin_pll > pll int0@@0 /core/bfin_sic
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{pll} (output):
+@end itemize
+
+@node bfin_ppi
+@subsection bfin_ppi
+@dvindex bfin_ppi
+@dvindex Blackfin PPI
+@dvindex Blackfin Parallel Port Interface
+The Blackfin Parallel Port Interface (PPI) model.
+
+Attaching device:
+@example
+/core/bfin_ppi@@0
+/core/bfin_ppi@@0/reg 0xffc01000 0x14
+/core/bfin_ppi@@0/type 537
+/core/bfin_ppi@@0 > stat int0 /core/glue-or@@2
+/core/glue-or@@2
+/core/glue-or@@2/interrupt-ranges 0x0 0x8
+/core/glue-or@@2 > int0 int2@@0 /core/bfin_sic
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{stat} (output):
+@end itemize
+
+@node bfin_rtc
+@subsection bfin_rtc
+@dvindex bfin_rtc
+@dvindex Blackfin RTC
+@dvindex Blackfin Real Time Clock
+The Blackfin Real Time Clock (RTC) model.
+
+Attaching device:
+@example
+/core/bfin_rtc
+/core/bfin_rtc/reg 0xffc00300 0x18
+/core/bfin_rtc/type 537
+/core/bfin_rtc > rtc int7@@0 /core/bfin_sic
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{rtc} (output):
+@end itemize
+
+@node bfin_sic
+@subsection bfin_sic
+@dvindex bfin_sic
+@dvindex Blackfin Interrupt Controller
+@dvindex Blackfin System Interrupt Controller
+The Blackfin System Interrupt Controller (SIC) model.
+
+Attaching device:
+@example
+/core/bfin_sic
+/core/bfin_sic/reg 0xffc00100 0x100
+/core/bfin_sic/type 537
+/core/bfin_sic > ivg15 ivg15 /core/bfin_cec
+/core/bfin_sic > ivg14 ivg14 /core/bfin_cec
+/core/bfin_sic > ivg13 ivg13 /core/bfin_cec
+/core/bfin_sic > ivg12 ivg12 /core/bfin_cec
+/core/bfin_sic > ivg11 ivg11 /core/bfin_cec
+/core/bfin_sic > ivg10 ivg10 /core/bfin_cec
+/core/bfin_sic > ivg9 ivg9 /core/bfin_cec
+/core/bfin_sic > ivg8 ivg8 /core/bfin_cec
+/core/bfin_sic > ivg7 ivg7 /core/bfin_cec
+@end example
+
+Ports (replace @code{@@X} with @code{@@0...@@2}):
+@itemize @bullet
+@item @code{ivg7} (output):
+@item @code{ivg8} (output):
+@item @code{ivg9} (output):
+@item @code{ivg10} (output):
+@item @code{ivg11} (output):
+@item @code{ivg12} (output):
+@item @code{ivg13} (output):
+@item @code{ivg14} (output):
+@item @code{ivg15} (output):
+@item @code{int0@@X} (input):
+@item @code{int1@@X} (input):
+@item @code{int2@@X} (input):
+@item @code{int3@@X} (input):
+@item @code{int4@@X} (input):
+@item @code{int5@@X} (input):
+@item @code{int6@@X} (input):
+@item @code{int7@@X} (input):
+@item @code{int8@@X} (input):
+@item @code{int9@@X} (input):
+@item @code{int10@@X} (input):
+@item @code{int11@@X} (input):
+@item @code{int12@@X} (input):
+@item @code{int13@@X} (input):
+@item @code{int14@@X} (input):
+@item @code{int15@@X} (input):
+@item @code{int16@@X} (input):
+@item @code{int17@@X} (input):
+@item @code{int18@@X} (input):
+@item @code{int19@@X} (input):
+@item @code{int20@@X} (input):
+@item @code{int21@@X} (input):
+@item @code{int22@@X} (input):
+@item @code{int23@@X} (input):
+@item @code{int24@@X} (input):
+@item @code{int25@@X} (input):
+@item @code{int26@@X} (input):
+@item @code{int27@@X} (input):
+@item @code{int28@@X} (input):
+@item @code{int29@@X} (input):
+@item @code{int30@@X} (input):
+@item @code{int31@@X} (input):
+@item @code{sup_irq@@0} (output): (BF56x only)
+@item @code{sup_irq@@1} (output): (BF56x only)
+@end itemize
+
+@node bfin_spi
+@subsection bfin_spi
+@dvindex bfin_spi
+@dvindex Blackfin SPI
+@dvindex Blackfin Serial Peripheral Interface
+The Blackfin Serial Peripheral Interface (SPI) model.
+
+Attaching device:
+@example
+/core/bfin_spi@@0
+/core/bfin_spi@@0/reg 0xffc00500 0x1c
+/core/bfin_spi@@0/type 537
+/core/bfin_spi@@0 > stat int0 /core/glue-or@@2
+/core/glue-or@@2
+/core/glue-or@@2/interrupt-ranges 0x0 0x8
+/core/glue-or@@2 > int0 int2@@0 /core/bfin_sic
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{stat} (output):
+@end itemize
+
+@node bfin_trace
+@subsection bfin_trace
+@dvindex bfin_trace
+@dvindex Blackfin Trace
+@dvindex Blackfin Hardware Trace
+The Blackfin Trace (TBUF) model.
+
+While the buffer depth on real hardware is limited to 16 entries, the simulator
+allows up to 64 entries.  This can be changed at compile time by editing the
+source, but experience suggests that 64 entries is pretty good for most cases.
+
+Attaching device:
+@example
+/core/bfin_trace
+/core/bfin_trace/reg 0xffe06000 0x104
+@end example
+
+@node bfin_twi
+@subsection bfin_twi
+@dvindex bfin_twi
+@dvindex Blackfin I2C
+@dvindex Blackfin I@sup{2}C
+@dvindex Blackfin TWI
+@dvindex Blackfin Two Wire Interface
+The Blackfin Two Wire Interface (TWI) model (i.e. I2C).
+
+Attaching device:
+@example
+/core/bfin_twi@@0
+/core/bfin_twi@@0/reg 0xffc01400 0x90
+/core/bfin_twi@@0/type 537
+/core/bfin_twi@@0 > stat int9@@0 /core/bfin_sic
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{stat} (output):
+@end itemize
+
+@node bfin_uart
+@subsection bfin_uart
+@dvindex bfin_uart
+@dvindex Blackfin Serial port
+@dvindex Blackfin UART
+@dvindex Blackfin Universal Asynchronous Receiver/Transmitter
+The Blackfin Universal Asynchronous Receiver/Transmitter (UART) model for
+"older" systems.
+
+Attaching device:
+@example
+/core/bfin_uart@@0
+/core/bfin_uart@@0/reg 0xffc00400 0x30
+/core/bfin_uart@@0/type 537
+/core/bfin_uart@@0 > rx uart@@0_rx /core/bfin_dmac@@0
+/core/bfin_uart@@0 > tx uart@@0_tx /core/bfin_dmac@@0
+/core/bfin_uart@@0 > stat int0 /core/glue-or@@2
+/core/glue-or@@2
+/core/glue-or@@2/interrupt-ranges 0x0 0x8
+/core/glue-or@@2 > int0 int2@@0 /core/bfin_sic
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{tx} (output): Trasnmit finished
+@item @code{rx} (output): Receive finished
+@item @code{stat} (output): Status changed
+@end itemize
+
+@node bfin_uart2
+@subsection bfin_uart2
+@dvindex bfin_uart2
+@dvindex Blackfin Serial port
+@dvindex Blackfin UART
+@dvindex Blackfin Universal Asynchronous Receiver/Transmitter
+The Blackfin Universal Asynchronous Receiver/Transmitter (UART) for "new
+style" BF54x.
+
+Attaching device:
+@example
+/core/bfin_uart2@@1
+/core/bfin_uart2@@1/reg 0xffc02000 0x30
+/core/bfin_uart2@@1/type 548
+/core/bfin_uart2@@1 > rx uart2@@1_rx /core/bfin_dmac@@0
+/core/bfin_uart2@@1 > tx uart2@@1_tx /core/bfin_dmac@@0
+/core/bfin_uart2@@1 > stat int30@@0 /core/bfin_sic
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{tx} (output): Trasnmit finished
+@item @code{rx} (output): Receive finished
+@item @code{stat} (output): Status changed
+@end itemize
+
+@node bfin_wdog
+@subsection bfin_wdog
+@dvindex bfin_wdog
+@dvindex Blackfin Hardware Watchdog
+@dvindex Blackfin Watchdog
+The Blackfin Watchdog (WDOG) model.
+
+Attaching device:
+@example
+/core/bfin_wdog@@0
+/core/bfin_wdog@@0/reg 0xffc00200 0xc
+/core/bfin_wdog@@0/type 537
+/core/bfin_wdog@@0 > nmi nmi /core/bfin_cec
+/core/bfin_wdog@@0 > reset rst /core/bfin_cec
+/core/bfin_wdog@@0 > gpi int23@@0 /core/bfin_sic
+@end example
+
+Ports:
+@itemize @bullet
+@item @code{reset} (output): Watchdog expiration triggers reset
+@item @code{nmi} (output): Watchdog expiration triggers nonmaskable interrupt
+@item @code{gpi} (output): Watchdog expiration triggers general purpose interrupt
+@end itemize
+
+@node bfin_wp
+@subsection bfin_wp
+@dvindex bfin_wp
+@dvindex Blackfin Watchpoint
+The Blackfin Watchpoint (WP) model.
+
+Attaching device:
+@example
+/core/bfin_wp
+/core/bfin_wp/reg 0xffe07000 0x204
+@end example
diff --git a/sim/doc/arch-bpf.texi b/sim/doc/arch-bpf.texi
new file mode 100644
index 00000000000..6a732405fc7
--- /dev/null
+++ b/sim/doc/arch-bpf.texi
@@ -0,0 +1,7 @@
+@node BPF
+@chapter BPF
+The @abbr{eBPF,extended Berkeley Packet Filter} virtual machine.
+
+@node BPF Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-cr16.texi b/sim/doc/arch-cr16.texi
new file mode 100644
index 00000000000..e744db3676a
--- /dev/null
+++ b/sim/doc/arch-cr16.texi
@@ -0,0 +1,7 @@
+@node CR16
+@chapter CR16
+National Semiconductor's CompactRISC processor.
+
+@node CR16 Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-cris.texi b/sim/doc/arch-cris.texi
new file mode 100644
index 00000000000..9602a82186a
--- /dev/null
+++ b/sim/doc/arch-cris.texi
@@ -0,0 +1,25 @@
+@node CRIS
+@chapter CRIS
+Axis Communications' CRIS (Code Reduced Instruction Set) processors.
+
+@node CRIS ISA Support
+@section ISA Support
+Currently ETRAX 100 LX (v10) and ETRAX FS (v32) are supported.
+
+@node CRIS Environment Support
+@section Environment Support
+Only the virtual environment is supported.
+
+@c TODO what about linux?
+
+@node CRIS Device Models
+@section Device Models
+
+@node dv-cris_900000xx
+@subsection cris_900000xx
+
+@node dv-cris
+@subsection cris
+
+@node dv-rv
+@subsection rv
diff --git a/sim/doc/arch-d10v.texi b/sim/doc/arch-d10v.texi
new file mode 100644
index 00000000000..6ec0053a8d3
--- /dev/null
+++ b/sim/doc/arch-d10v.texi
@@ -0,0 +1,7 @@
+@node D10V
+@chapter D10V
+Mitsubishi Electric's dual RISC processor.
+
+@node D10V Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-erc32.texi b/sim/doc/arch-erc32.texi
new file mode 100644
index 00000000000..0143332892c
--- /dev/null
+++ b/sim/doc/arch-erc32.texi
@@ -0,0 +1,13 @@
+@node SPARC
+@chapter SPARC
+Sun Microsystems' Scalable Processor Architecture (SPARC) architectures.
+
+@node SPARC ISA Support
+@section ISA Support
+Currently only the ERC32 (SPARC V7) is supported.
+
+@node SPARC Environment Support
+@section Environment Support
+Only the virtual environment is supported.
+
+@c TODO is this true ?
diff --git a/sim/doc/arch-frv.texi b/sim/doc/arch-frv.texi
new file mode 100644
index 00000000000..4ecc6f2fc97
--- /dev/null
+++ b/sim/doc/arch-frv.texi
@@ -0,0 +1,7 @@
+@node FRV
+@chapter FRV
+Fujitsu's FR-V VLIW processor.
+
+@node FRV Environment Support
+@section Environment Support
+The virtual & operating environments are supported.
diff --git a/sim/doc/arch-ft32.texi b/sim/doc/arch-ft32.texi
new file mode 100644
index 00000000000..ca7962927a7
--- /dev/null
+++ b/sim/doc/arch-ft32.texi
@@ -0,0 +1,7 @@
+@node FT32
+@chapter FT32
+Future Technology Devices International (FTDI) Limited's FT32 processor.
+
+@node FT32 Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-h8300.texi b/sim/doc/arch-h8300.texi
new file mode 100644
index 00000000000..942fede7973
--- /dev/null
+++ b/sim/doc/arch-h8300.texi
@@ -0,0 +1,7 @@
+@node H8/300
+@chapter H8/300
+Renesas's (Hitachi's) H8 processors.
+
+@node H8/300 Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-iq2000.texi b/sim/doc/arch-iq2000.texi
new file mode 100644
index 00000000000..d531b4d6942
--- /dev/null
+++ b/sim/doc/arch-iq2000.texi
@@ -0,0 +1,7 @@
+@node IQ2000
+@chapter IQ2000
+Vitesse's IQ2000 @abbr{NPU,Network Processor Unit}.
+
+@node IQ2000 Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-lm32.texi b/sim/doc/arch-lm32.texi
new file mode 100644
index 00000000000..62b7b4063ad
--- /dev/null
+++ b/sim/doc/arch-lm32.texi
@@ -0,0 +1,19 @@
+@node LM32
+@chapter LM32
+Lattice Semiconductor's LatticeMico32 soft core for FPGAs.
+
+@node LM32 Environment Support
+@section Environment Support
+The virtual & operating environments are supported.
+
+@node LM32 Device Models
+@section Device Models
+
+@node lm32cpu
+@subsection lm32cpu
+
+@node lm32timer
+@subsection lm32timer
+
+@node lm32uart
+@subsection lm32uart
diff --git a/sim/doc/arch-m32c.texi b/sim/doc/arch-m32c.texi
new file mode 100644
index 00000000000..af1c8d5d195
--- /dev/null
+++ b/sim/doc/arch-m32c.texi
@@ -0,0 +1,7 @@
+@node M32C
+@chapter M32C
+Renesas's M16C & M32C proessors.
+
+@node M32C Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-m32r.texi b/sim/doc/arch-m32r.texi
new file mode 100644
index 00000000000..17d6507ec4b
--- /dev/null
+++ b/sim/doc/arch-m32r.texi
@@ -0,0 +1,16 @@
+@node M32R
+@chapter M32R
+Mitsubishi Electric's M32R RISC architecture.
+
+@node M32R Environment Support
+@section Environment Support
+All environments are supported: virtual, user, operating.
+
+@node M32R Device Models
+@section Device Models
+
+@node m32r_cache
+@subsection m32r_cache
+
+@node m32r_uart
+@subsection m32r_uart
diff --git a/sim/doc/arch-m68hc11.texi b/sim/doc/arch-m68hc11.texi
new file mode 100644
index 00000000000..e79458c1ba0
--- /dev/null
+++ b/sim/doc/arch-m68hc11.texi
@@ -0,0 +1,43 @@
+@node M68HC11
+@chapter M68HC11
+Motorola's 68HC11 8-bit microcontroller.
+
+@node M68HC11 Environment Support
+@section Environment Support
+Only the virtual environment is supported.
+
+@node M68HC11 Device Models
+@section Device Models
+
+@node dv-m68hc11
+@subsection m68hc11
+
+@node dv-m68hc12
+@subsection m68hc12
+
+@node dv-m68hc11eepr
+@subsection m68hc11eepr
+
+@node dv-m68hc12eepr
+@subsection m68hc12eepr
+
+@node dv-m68hc11sio
+@subsection m68hc11sio
+
+@node dv-m68hc12sio
+@subsection m68hc12sio
+
+@node dv-m68hc11spi
+@subsection m68hc11spi
+
+@node dv-m68hc12spi
+@subsection m68hc12spi
+
+@node dv-m68hc11tim
+@subsection m68hc11tim
+
+@node dv-m68hc12tim
+@subsection m68hc12tim
+
+@node dv-nvram
+@subsection nvram
diff --git a/sim/doc/arch-mcore.texi b/sim/doc/arch-mcore.texi
new file mode 100644
index 00000000000..de8c01b65f5
--- /dev/null
+++ b/sim/doc/arch-mcore.texi
@@ -0,0 +1,7 @@
+@node MCORE
+@chapter MCORE
+Motorola's microRISC M·CORE architecture.
+
+@node MCORE Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-microblaze.texi b/sim/doc/arch-microblaze.texi
new file mode 100644
index 00000000000..eb5af791489
--- /dev/null
+++ b/sim/doc/arch-microblaze.texi
@@ -0,0 +1,7 @@
+@node MicroBlaze
+@chapter MicroBlaze
+Xilinx's MicroBlaze soft core for FPGAs.
+
+@node MicroBlaze Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-mips.texi b/sim/doc/arch-mips.texi
new file mode 100644
index 00000000000..7c28449fe41
--- /dev/null
+++ b/sim/doc/arch-mips.texi
@@ -0,0 +1,22 @@
+@node MIPS
+@chapter MIPS
+MIPS Technologies's MIPS architecture.
+
+@node MIPS Environment Support
+@section Environment Support
+The virtual & operating environments are supported.
+
+@node MIPS Device Models
+@section Device Models
+
+@node dv-tx3904cpu
+@subsection tx3904cpu
+
+@node dv-tx3904irc
+@subsection tx3904irc
+
+@node dv-tx3904sio
+@subsection tx3904sio
+
+@node dv-tx3904tmr
+@subsection tx3904tmr
diff --git a/sim/doc/arch-mn10300.texi b/sim/doc/arch-mn10300.texi
new file mode 100644
index 00000000000..21279ee5fe1
--- /dev/null
+++ b/sim/doc/arch-mn10300.texi
@@ -0,0 +1,25 @@
+@node MN10300
+@chapter MN10300
+Matsushita Electric's MN103 32-bit microprocessors.
+
+@node MN10300 Environment Support
+@section Environment Support
+The virtual & operating environments are supported.
+
+@node MN10300 Device Models
+@section Device Models
+
+@node mn103cpu
+@subsection mn103cpu
+
+@node mn103int
+@subsection mn103int
+
+@node mn103iop
+@subsection mn103iop
+
+@node mn103ser
+@subsection mn103ser
+
+@node mn103tim
+@subsection mn103tim
diff --git a/sim/doc/arch-moxie.texi b/sim/doc/arch-moxie.texi
new file mode 100644
index 00000000000..8c90fc21aab
--- /dev/null
+++ b/sim/doc/arch-moxie.texi
@@ -0,0 +1,7 @@
+@node Moxie
+@chapter Moxie
+Anthony Green's open source embedded soft-core processor.
+
+@node Moxie Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-msp430.texi b/sim/doc/arch-msp430.texi
new file mode 100644
index 00000000000..b39409a0b02
--- /dev/null
+++ b/sim/doc/arch-msp430.texi
@@ -0,0 +1,7 @@
+@node MSP30
+@chapter MSP30
+Texas Instruments' 16-bit mixed-signal microcontrollers.
+
+@node MSP30 Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-or1k.texi b/sim/doc/arch-or1k.texi
new file mode 100644
index 00000000000..43654f953da
--- /dev/null
+++ b/sim/doc/arch-or1k.texi
@@ -0,0 +1,7 @@
+@node OpenRISC
+@chapter OpenRISC
+OpenCores' OpenRISC architecture.
+
+@node OpenRISC Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-ppc.texi b/sim/doc/arch-ppc.texi
new file mode 100644
index 00000000000..3610b156c0d
--- /dev/null
+++ b/sim/doc/arch-ppc.texi
@@ -0,0 +1,7 @@
+@node PowerPC
+@chapter PowerPC
+IBM's PowerPC architecture.
+
+@node PowerPC Environment Support
+@section Environment Support
+All environments are fully supported: virtual, user, operating.
diff --git a/sim/doc/arch-pru.texi b/sim/doc/arch-pru.texi
new file mode 100644
index 00000000000..9f92329ef12
--- /dev/null
+++ b/sim/doc/arch-pru.texi
@@ -0,0 +1,7 @@
+@node PRU
+@chapter PRU
+Texas Instruments' Programmable Real-time Unit processor.
+
+@node PRU Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-riscv.texi b/sim/doc/arch-riscv.texi
new file mode 100644
index 00000000000..b8038c43542
--- /dev/null
+++ b/sim/doc/arch-riscv.texi
@@ -0,0 +1,51 @@
+@node RISC-V
+@chapter RISC-V
+RISC-V Foundation's RISC-V architecture.
+
+@node RISC-V ISA Support
+@section ISA Support
+The RV32I, RV32E, RV64I, and RV64E bases are supported.
+
+The A, M, Zicsr, and Zifencei extensions are supported.
+
+The F and D extensions are planned but not yet supported.
+
+@node RISC-V Environment Support
+@section Environment Support
+Only the virtual environment is supported.
+
+@node RISC-V Virtual Environment Syscall ABI
+@subsection Virtual Environment Syscall ABI
+The syscall ABI, as used by @value{libgloss} in the virtual environment, uses
+the interface defined in the following table.
+
+@multitable @columnfractions .2 .3 .5
+@headitem Field @tab Assembly/Register @tab Description
+@item instruction
+@tab @center @code{ecall;}
+@tab The assembly instruction to invoke the syscall handler.
+@item (in) syscall NR
+@tab @center @code{a7}
+@tab The system call number to select which function to run.
+@item (in) arg 1
+@tab @center @code{a0}
+@tab The first syscall argument.
+@item (in) arg 2
+@tab @center @code{a1}
+@tab The second syscall argument.
+@item (in) arg 3
+@tab @center @code{a2}
+@tab The third syscall argument.
+@item (in) arg 4
+@tab @center @code{a3}
+@tab The fourth syscall argument.
+@item (in) arg 5
+@tab @center @code{a4}
+@tab The fifth syscall argument.
+@item (in) arg 6
+@tab @center @code{a5}
+@tab The sixth syscall argument.
+@item (out) return & error
+@tab @center @code{a0}
+@tab The return value.
+@end multitable
diff --git a/sim/doc/arch-rl78.texi b/sim/doc/arch-rl78.texi
new file mode 100644
index 00000000000..fa31299cb04
--- /dev/null
+++ b/sim/doc/arch-rl78.texi
@@ -0,0 +1,7 @@
+@node RL78
+@chapter RL78
+Renesas' 16-bit RL78 MCUs.
+
+@node RL78 Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-rx.texi b/sim/doc/arch-rx.texi
new file mode 100644
index 00000000000..b1a94f7aee5
--- /dev/null
+++ b/sim/doc/arch-rx.texi
@@ -0,0 +1,7 @@
+@node RX
+@chapter RX
+Renesas' 32-bit microcontrollers.
+
+@node RX Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-sh.texi b/sim/doc/arch-sh.texi
new file mode 100644
index 00000000000..77e6fb957a2
--- /dev/null
+++ b/sim/doc/arch-sh.texi
@@ -0,0 +1,7 @@
+@node SuperH
+@chapter SuperH
+Hitachi's SuperH architecture.
+
+@node SuperH Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/arch-v850.texi b/sim/doc/arch-v850.texi
new file mode 100644
index 00000000000..8c68630b932
--- /dev/null
+++ b/sim/doc/arch-v850.texi
@@ -0,0 +1,7 @@
+@node V850
+@chapter V850
+Renesas' 32-bit RISC architecture.
+
+@node V850 Environment Support
+@section Environment Support
+Only the virtual environment is supported.
diff --git a/sim/doc/create-version.sh b/sim/doc/create-version.sh
new file mode 100755
index 00000000000..fef9e8e3932
--- /dev/null
+++ b/sim/doc/create-version.sh
@@ -0,0 +1,37 @@
+#!/bin/sh
+
+# Copyright (C) 1989-2021 Free Software Foundation, Inc.
+
+# This file is part of GDB.
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# Create version.c from version.in.
+# Usage:
+#    create-version.sh PATH-TO-GDB-SRCDIR HOST_ALIAS \
+#        TARGET_ALIAS OUTPUT-FILE-NAME
+
+srcdir="$1"
+output="$2"
+homepage="$3"
+bugsto="$4"
+
+date=`sed -n -e 's/^.* BFD_VERSION_DATE \(.*\)$/\1/p' $srcdir/../bfd/version.h`
+ver=`sed -e "s/DATE/$date/;q" $srcdir/version.in`
+cat <<EOF >"${output}"
+@set VERSION ${ver}
+@set VERSION_PACKAGE (SIM)
+@set HOMEPAGE ${homepage}
+@set BUGURL ${bugsto}
+EOF
diff --git a/sim/doc/fdl.texi b/sim/doc/fdl.texi
new file mode 100644
index 00000000000..7c26c34b074
--- /dev/null
+++ b/sim/doc/fdl.texi
@@ -0,0 +1,505 @@
+@c The GNU Free Documentation License.
+@center Version 1.3, 3 November 2008
+
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@display
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+@uref{http://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense.  It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does.  But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book.  We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License.  Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein.  The ``Document'', below,
+refers to any such manual or work.  Any member of the public is a
+licensee, and is addressed as ``you''.  You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject.  (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.)  The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.  If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant.  The Document may contain zero
+Invariant Sections.  If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.  A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters.  A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text.  A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+@sc{ascii} without markup, Texinfo input format, La@TeX{} input
+format, @acronym{SGML} or @acronym{XML} using a publicly available
+@acronym{DTD}, and standard-conforming simple @acronym{HTML},
+PostScript or @acronym{PDF} designed for human modification.  Examples
+of transparent image formats include @acronym{PNG}, @acronym{XCF} and
+@acronym{JPG}.  Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, @acronym{SGML} or
+@acronym{XML} for which the @acronym{DTD} and/or processing tools are
+not generally available, and the machine-generated @acronym{HTML},
+PostScript or @acronym{PDF} produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page.  For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language.  (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.)  To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document.  These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License.  You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute.  However, you may accept
+compensation in exchange for copies.  If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover.  Both covers must also clearly and legibly identify
+you as the publisher of these copies.  The front cover must present
+the full title with all words of the title equally prominent and
+visible.  You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it.  In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document).  You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page.  If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on.  These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles.  Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section Entitled ``Endorsements''.  Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant.  To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version.  Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity.  If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy.  If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''.  You must delete all
+sections Entitled ``Endorsements.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections.  You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers.  In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.  See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation.  If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.  If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+@item
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works.  A
+public wiki that anybody can edit is an example of such a server.  A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+@end enumerate
+
+@page
+@heading ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+  Copyright (C)  @var{year}  @var{your name}.
+  Permission is granted to copy, distribute and/or modify this document
+  under the terms of the GNU Free Documentation License, Version 1.3
+  or any later version published by the Free Software Foundation;
+  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+  Texts.  A copy of the license is included in the section entitled ``GNU
+  Free Documentation License''.
+@end group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with@dots{}Texts.'' line with this:
+
+@smallexample
+@group
+    with the Invariant Sections being @var{list their titles}, with
+    the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+    being @var{list}.
+@end group
+@end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
diff --git a/sim/doc/local.mk b/sim/doc/local.mk
new file mode 100644
index 00000000000..ea9498cc0f2
--- /dev/null
+++ b/sim/doc/local.mk
@@ -0,0 +1,75 @@
+## See sim/Makefile.am.
+#
+# Copyright (C) 1997-2021 Free Software Foundation, Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+TEXINFO_TEX = %D%/sim.texi
+info_TEXINFOS = $(TEXINFO_TEX)
+%C%_sim_TEXINFOS = \
+	%D%/abi-newlib-errno.texi \
+	%D%/abi-newlib-open.texi \
+	%D%/abi-newlib-signal.texi \
+	%D%/abi-newlib-sys.texi \
+	%D%/arch-aarch64.texi \
+	%D%/arch-arm.texi \
+	%D%/arch-avr.texi \
+	%D%/arch-bfin.texi \
+	%D%/arch-bpf.texi \
+	%D%/arch-cr16.texi \
+	%D%/arch-cris.texi \
+	%D%/arch-d10v.texi \
+	%D%/arch-erc32.texi \
+	%D%/arch-frv.texi \
+	%D%/arch-ft32.texi \
+	%D%/arch-h8300.texi \
+	%D%/arch-iq2000.texi \
+	%D%/arch-lm32.texi \
+	%D%/arch-m32c.texi \
+	%D%/arch-m32r.texi \
+	%D%/arch-m68hc11.texi \
+	%D%/arch-mcore.texi \
+	%D%/arch-microblaze.texi \
+	%D%/arch-mips.texi \
+	%D%/arch-mn10300.texi \
+	%D%/arch-moxie.texi \
+	%D%/arch-msp430.texi \
+	%D%/arch-or1k.texi \
+	%D%/arch-ppc.texi \
+	%D%/arch-pru.texi \
+	%D%/arch-riscv.texi \
+	%D%/arch-rl78.texi \
+	%D%/arch-rx.texi \
+	%D%/arch-sh.texi \
+	%D%/arch-v850.texi \
+	%D%/fdl.texi \
+	%D%/simver.texi
+
+AM_MAKEINFOFLAGS = -I %D% --no-split
+TEXI2DVI = texi2dvi -I %D%
+
+%D%/simver.texi: %D%/simver.texi-stamp ; @true
+%D%/simver.texi-stamp: $(srcroot)/gdb/version.in $(srcroot)/bfd/version.h %D%/create-version.sh
+	$(AM_V_at)$(MKDIR_P) %D%
+	$(AM_V_GEN)$(SHELL) $(srcdir)/%D%/create-version.sh $(srcroot)/gdb $@.tmp \
+		"$(PACKAGE_URL)" "$(REPORT_BUGS_TEXI)"
+	$(AM_V_at)$(SHELL) $(srcroot)/move-if-change $@.tmp $(@:-stamp=)
+	$(AM_V_at)touch $@
+
+html-local: %D%/sim/index.html
+%D%/sim/index.html: $(TEXINFO_TEX) $(%C%_sim_TEXINFOS)
+	$(AM_V_MAKEINFO)$(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) \
+		--output=%D%/sim --split=node -I$(srcdir) $<
+
+MAINTAINERCLEANFILES += %D%/sim.info
diff --git a/sim/doc/sim.texi b/sim/doc/sim.texi
new file mode 100644
index 00000000000..a42661e33cf
--- /dev/null
+++ b/sim/doc/sim.texi
@@ -0,0 +1,2834 @@
+\input texinfo      @c -*-texinfo-*-
+@c Copyright (C) 1997-2021 Free Software Foundation, Inc.
+@c
+@c %**start of header
+@setfilename sim.info
+@settitle GNU simulator
+@documentencoding UTF-8
+@include simver.texi
+@setchapternewpage odd
+@c %**end of header
+
+@c A texinfo hack.  Pay it no mind.
+@finalout
+
+@c Summary of indexes used:
+@c cp Concept index.
+@c fn Public APIs index (functions).
+@c tp Merge public data type index into the function index.
+@syncodeindex tp fn
+@c vr Merge public variable index into the function index.
+@syncodeindex vr fn
+@c sc Syscall index.
+@defindex sc
+@c dv Device models.
+@defindex dv
+
+@c This is a dir.info fragment to support semi-automated addition of
+@c manuals to an info tree.
+@dircategory Software development
+@direntry
+* Sim: (sim).                     The GNU simulator.
+@end direntry
+
+@c Link to online POSIX documentation.
+@macro posix{section, page}
+@url{https://pubs.opengroup.org/onlinepubs/9699919799/\section\/\page\.html, \page\(P)}
+@end macro
+
+@c Link to online Linux man pages.
+@macro man{section, page}
+@url{https://man7.org/linux/man-pages/man\section\/\page\.\section\.html, \page\(\section\)}
+@end macro
+
+@c Projects that we refer to often.
+@set bfd @url{https://www.gnu.org/software/bfd/,BFD}
+@set cgen @url{https://sourceware.org/cgen/,CGEN}
+@set elf @url{https://en.wikipedia.org/wiki/Executable_and_Linkable_Format,ELF}
+@set libgloss @url{https://sourceware.org/newlib/,libgloss}
+@set linux @url{https://www.kernel.org/,Linux}
+@set man7 @url{https://man7.org/linux/man-pages/,Linux man pages}
+@set newlib @url{https://sourceware.org/newlib/,newlib}
+@set rtems @url{https://www.rtems.org/,RTEMS}
+@set uboot @url{https://en.wikipedia.org/wiki/Das_U-Boot,Das U-Boot}
+
+@c Terms that we use frequently.
+@set crt @abbr{CRT,C runtime object}
+@set cwd @abbr{cwd,current working directory}
+@set pid @abbr{PID,Process Identifier}
+
+@copying
+@c man begin COPYRIGHT
+Copyright @copyright{} 1997-2021 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled ``GNU Free Documentation License''.
+
+@c man end
+@end copying
+
+@ifnottex
+This file documents the @sc{gnu} simulator.
+
+@insertcopying
+@end ifnottex
+
+@titlepage
+@c First the title page.
+@title Simulating Systems
+@subtitle The @sc{gnu} Simulator
+@ifset VERSION_PACKAGE
+@sp 1
+@subtitle @value{VERSION_PACKAGE}
+@end ifset
+@sp 1
+@subtitle Version @value{VERSION}
+@c GNU standards say to list principal human writers of the manual as the
+@c authors, not the maintainers or authors of the Simulator itself.
+@c Everyone will be listed in the Acknowledgements chapter.
+@author Mike Frysinger
+
+@c Then the copyright page.  This must be a page by itself after the titlepage.
+@page
+(Send bugs & comments to@*@value{BUGURL}.)
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@c This is for html & pdf outputs.
+@contents
+
+@c This is for info outputs where @contents is automatically omitted.
+@node Top, Overview
+@top Simulating Systems
+
+This file describes the @sc{gnu} simulator
+@ifset VERSION_PACKAGE
+@value{VERSION_PACKAGE}
+@end ifset
+version @value{VERSION}.
+
+@node Overview
+@chapter Overview
+The GNU Simulator provides a reasonably fast functional simulation environment
+for a variety of Instruction Set Architectures (ISAs) and device models (SoCs,
+peripherals).
+
+It can provide both functional simulation as well as cycle accurate simulation
+(although the accuracy quality varies greatly by port).
+
+Common uses include, but are not limited to, the following.
+@itemize @bullet
+@item Toolchain testing (e.g. @sc{gcc} or @sc{gdb}).
+@item Bare-metal firmware development.
+@item Quick experimentation via debugger integration.
+@end itemize
+
+This manual is useful to multiple audiences: users, integrators, and developers.
+
+@node Simulation or Emulation
+@section Simulation or Emulation?
+Terminology is hard.  Depending on who you talk to and the time of day, the
+terms "simulation" and "emulation" will often be used interchangeably.  Don't
+spend too much time thinking about it.
+
+The GNU Simulator does not utilize virtualization.  It is only a simulator.
+
+@node Why Another Simulator
+@section Why Another Simulator?
+There are many simulators out there, so one might ask why do we need another?
+
+The GNU Simulator, while not well known, has been around in one form or another
+since at least 1992!  It predates many open source projects out there, even if
+it never quite gained the largely community that others enjoy.
+
+Its integration with existing GNU toolchain projects makes it a good choice for
+automated testing and new target bring-ups.
+
+Its simplicity makes it a good target for bringing up a new architecture quickly
+and proving out basic functionality.
+
+All that said, the GNU Simulator does not really aspire to be more popular or
+"better" than other open source tools.  It is maintained under the GNU banner,
+and in the hopes that others will find it useful.
+
+If another FOSS simulator works well for you, then by all means, use it instead!
+
+@node Other Simulators
+@section Other Simulators
+The currently most common open source project is of course
+@url{https://www.qemu.org/, QEMU}.  It has a much larger & active community,
+tends to support more architectures, has more device models, and is
+significantly faster than the GNU Simulator.
+
+The @url{https://sourceware.org/sid/, SID} project seemingly overlaps a lot with
+the GNU Simulator.  It is an independent code base, and was designed more for
+modeling whole systems, and providing a framework for creating new models that
+anyone could integrate.  While it was quite ahead of its time, it hasn't seen
+development in a long time, and is effectively dormant at this point.  It would
+be interesting to see if the GNU Simulator could somehow leverage its existing
+corpus of models.
+
+There are a few simulators out there that are actually forked from old versions
+of the GNU Simulator.
+
+And of course, there are a variety of proprietary (i.e. non-FOSS) simulators,
+but by their very nature, are not interesting :).
+
+Finally, remember that this is only about simulation, not virtualization.
+
+@node Contact and Support
+@section Contact and Support
+There are a number of ways you can get in touch!
+
+@itemize
+@item Homepage @url{@value{HOMEPAGE}}
+@item Wiki @url{https://sourceware.org/gdb/wiki/Sim}
+@item Issue Tracker
+@itemize
+@item New Reports @value{BUGURL}
+@item @url{https://sourceware.org/bugzilla/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=SUSPENDED&bug_status=WAITING&bug_status=REOPENED&component=sim,Existing Reports}
+@end itemize
+@item Mailing Lists @url{https://sourceware.org/gdb/mailing-lists/}
+(we use the same lists as @sc{gdb})
+@end itemize
+
+@node Contributing
+@section Contributing
+Thanks for considering helping out.  There are many ways to contribute, and many
+areas that could use your help.
+
+If you want to report a bug, either a compile failure, or runtime misbehavior,
+check out @ref{Reporting Bugs} section.
+
+If you want to request a feature or new functionality, we also use the bug
+tracker to manage things.  @xref{Contact and Support} has links.
+
+If you're looking for things to help fix, we maintain a rough TODO list in
+@url{https://sourceware.org/gdb/wiki/Sim/TODO,our wiki}.  Feel free to dive in
+to anything listed there.
+
+If you're not comfortable writing code, that's OK---we have documentation too
+(like this manual!) that can always use review and improvement.
+
+@node Free Software
+@unnumberedsec Free Software
+The GNU Simulator is @dfn{free software}, protected by the @sc{gnu} General
+Public License (GPL).  The GPL gives you the freedom to copy or adapt a licensed
+program---but every person getting a copy also gets with it the freedom to
+modify that copy (which means that they must get access to the source code), and
+the freedom to distribute further copies.  Typical software companies use
+copyrights to limit your freedoms; the Free Software Foundation uses the GPL to
+preserve these freedoms.
+
+Fundamentally, the General Public License is a license which says that you have
+these freedoms and that you cannot take these freedoms away from anyone else.
+
+@node Running The Simulator
+@chapter Running The Simulator
+The primary method for running the GNU Simulator is via the @command{run}
+program.  It usually is part of a cross-compiler toolchain which has a tool
+prefix, e.g. @command{arm-none-elf-run}.  @xref{Config Names}.
+
+It is given the program to simulate.  It understands any format that @value{bfd}
+understands---typically, this means @value{elf} programs.  You can control the
+format via the @option{--target} option---@command{binary} is a common one to
+load a blob directly into memory.
+
+The program could be a boot loader (e.g. @value{uboot}), or bare-metal programs
+you wrote (i.e. no OS), or an OS kernel itself (e.g. @value{rtems} or
+@value{linux}), or typical userland programs (e.g. @command{ls}).
+
+Another common usage pattern is via @sc{gdb} itself.  @xref{GDB Integration} for
+more details.
+
+Many simulator subsystems may be disabled at build time, so not all options
+described below may be available in your simulator.  Even if they are available,
+not all architecture backends support every specific feature.
+
+@node CLI Invocation
+@section Invocation
+Running the simulator is fairly straightforward.  It takes the basic form:
+@example
+$ run [simulator options] [VAR=VALUE|--] <program> [program options]
+
+$ run hello.elf
+$ run HOME=/tmp arm.elf
+@end example
+
+Multiple environment variables may be specified before @var{program}.  If
+@option{--} is used, then environment variable processing is halted, and the
+remaining arguments will be treated as the @var{program} and its own options.
+
+@node Common Options
+@section Common Options
+Here's the common, albeit boring, options.
+
+@table @option
+@item --
+Halt all further option processing.  This can be useful in scripts to force a
+break between simulator options and the @var{program} to run.
+
+@item -h
+@itemx --help
+Print help information.  This can show a quick summary of all the options that
+a particular build actually supports.
+
+@item --version
+Print version information.
+
+@item -v
+@itemx --verbose
+Enable more verbose output.
+
+@item --do-command <comman>
+Execute a simulator @var{command}.  These are the same as the command line
+options, but as a string and with leading dashes omitted.  This option is meant
+more as an escape hatch when scripting or integrating into other systems rather
+than used normally.
+
+For example, @samp{--version} and @samp{--do-command version} are equivalent.
+
+@item --environment <user|virtual|operating>
+Set running environment.  @xref{Runtime Environments} for more details.
+
+@item -E <B|big|L|little>
+@itemx --endian <B|big|L|little>
+Set endianness.
+
+Most architectures only support one endianness, so this option isn't that
+useful there.
+
+@item --architecture <MACHINE>
+Specify the architecture to use.  @xref{Architecture Specifics} for possible
+options.  Currently, most builds only include one architecture at a time, and
+it's selected by default, so this setting isn't useful there.
+
+@item --architecture-info
+@itemx --info-architecture
+List supported architectures.
+
+@item --target <bfdname>
+Specify the object-code format for input object files.  This is usually handled
+automatically for you by the @value{bfd} library which autodetects most formats.
+
+Binary files are a common format that is not handled automatically.  You will
+want to use @samp{binary} explicitly in that case.
+
+@item --target-info
+@itemx --info-target
+List supported @value{bfd} targets.
+
+@item --sysroot <sysroot>
+Root for system calls with absolute file-names and the initial @value{cwd}.
+
+@item --argv0 <arg>
+Set argv[0] to the specified string.  This overrides the default program name
+and can be useful when testing programs that rely on argv[0] for changing its
+behavior.
+@end table
+
+@node Environment Variables (environ)
+@section Environment Variables (environ)
+The environment variables exposed to the simulated program is distinct from the
+active environment variables the simulator itself has (which in turn tends to be
+inherited from its parent, e.g. the user's shell where @code{run} is invoked).
+
+That said, by default, the simulated program's environment variables are also
+inherited.  The options below can limit or adjust the set of variables exposed.
+
+How the environment variables are exposed to the simulated program depends
+heavily on the @ref{Runtime Environments} used, so refer to those sections for
+more details.
+
+@table @option
+@item --env-set <variable=value>
+Set the @var{variable} in the program's environment to @var{value}.  Any
+existing @var{variable} will be overridden.
+
+Environment variables may also be specified, sans @option{--env-set}, on the
+command line before the path to the program to run.  This provides a succinct
+method for setting multiple environment variables.
+
+@item --env-unset <variable|variable=value>
+Unset the @var{variable} in the program's environment.
+
+An extended syntax is supported where the value is unset only if the
+@var{value} matches.  For example, if the environment has @samp{FOO=bar}, but
+@samp{--env-unset FOO=boo} was used, @samp{FOO} would not be unset.
+
+@item --env-clear
+Clear the program's environment.
+
+The environment options stack, so this will clear all previously variables, but
+any following @option{--env-set} variables will be retained.
+@end table
+
+@node Memory Options
+@section Memory
+Manage memory settings.
+
+Options are processed in the order specified and operate on the current memory
+state.  This allows for building up the memory layout one mapping at a time.
+
+Some of these options are "stateful".  That is, they set implicit arguments
+for follow up options rather than doing anything by themselves.  For example,
+@samp{--memory-fill 0xff --memory-region 0,0x1000} will set the fill setting
+to @samp{0xff} for the @samp{--memory-region} call.
+
+Addresses are usually specified using the @code{[<space>:]<address>[@@<level>]}
+syntax.
+
+Sizes are usually specified using the @code{<bytes>[BKMG]} syntax.  Suffixes use
+base 2 sizes, not base 10, so @code{K} is a kibibyte (1024), not kilobyte
+(1000).  If no suffix is specified, bytes (@code{b}) are used.
+
+@table @option
+@item --alignment <strict|nonstrict|forced>
+@xref{Memory Alignment} for more details.
+
+@item --load-lma
+@itemx --load-vma
+Use @abbr{VMA, Virtual Memory Address} or @abbr{LMA, Load Memory Address} (the
+default) addresses when loading the inputs.
+
+@item --memory-delete <address|all>
+@itemx --delete-memory <address|all>
+Delete memory at @var{address}, or @var{all} addresses.
+
+@item --memory-region <address,size[,modulo]>
+Add a memory region starting at @var{address} with @var{size} bytes.
+
+A @var{modulo} size specifies that accesses to the region [address ...
+address+size] should be mapped onto the sub region [address ... address+modulo].
+The @var{modulo} value must be a power of two.
+
+@item --memory-alias <address,size@{,address@}>
+Add a memory shadow from one address to another.
+
+@item --memory-size <size>
+Add memory at address zero.  The @var{size} is specified in bytes, kibibytes
+(KiB) with @code{k} suffix, mebibytes (MiB) with @code{m}, or gibibytes (GiB)
+with @code{g} suffix.
+
+@item --memory-fill <value>
+Fill subsequently added memory regions.  @var{value} is a single byte (from
+@code{0-255}), and may be decimal or hexidecimal.
+
+@item --memory-clear
+Clear subsequently added memory regions.  This is equivalent to
+@option{--memory-fill 0}.
+
+@item --memory-mapfile <file>
+Have the next memory region memory-map @var{file}.  The file is opened for
+reading & writing.
+
+If the memory region size is specified, the file must be at least as big as it.
+If the memory region size is not declared explicitly, it will be calculated from
+the file's size.
+
+@item --memory-info
+@itemx --info-memory
+List configurable memory regions.  This only shows the basic memory mappings
+(e.g. RAM regions).
+
+@item --map-info
+List mapped regions.  This displays all types of address mappings and their
+read/write/execute status.  For example, this will include hardware device
+register mappings.
+@end table
+
+@node Memory Alignment
+@subsection Alignment
+Different architectures have, at different points in their evolution, taken
+different approaches to how unaligned memory accesses are handled.  The most
+common patterns are supported.
+
+The default behavior depends on the specific architecture backend (which tends
+to match the respective hardware), and may be overridden by @option{--alignment}
+at runtime.  The @option{--enable-sim-alignment} configure time option will
+override both of these if it were specified.  @xref{Configure Simulator Options}
+for more details.
+
+The alignment setting is global and affects all memory accesses.  It cannot be
+changed on a per-memory region basis.
+
+Possible alignment settings:
+@itemize @bullet
+@item @samp{strict}: Unaligned accesses cause exceptions.@*
+For example, requesting a 32-bit value at address @code{0x2} will fail.
+
+@item @samp{nonstrict}: Unaligned accesses always work.@*
+For example, requesting a 32-bit value at address @code{0x2} will work---the
+bytes from @code{0x2-0x5} will be read.
+
+@item @samp{forced}: Unaligned addresses are masked before access.@*
+For example, requesting a 32-bit value at address @code{0x2} will read the bytes
+from @code{0x0-0x3} (since @code{(0x2 & ~3) = 0x0}).
+@end itemize
+
+@node Tracing Options
+@section Tracing
+Note: Not all architecture backends support all tracing categories.
+
+@xref{Configure Simulator Options} for configure-time control over which
+categories are available.
+
+@table @option
+@item -t[on|off]
+@itemx --trace[=on|off]
+Trace useful things.  This option must be specified in order for other tracing
+options to be useful.
+
+@item --trace-insn[=on|off]
+Perform instruction tracing.  This tends to be high-level instruction family.
+
+@item --trace-disasm[=on|off]
+Disassemble instructions using the @sc{opcodes} library.  This will produce more
+accurate output, but will be slower.  This can be useful when comparing decode
+behavior between the simulator and the disassembler.
+
+@item --trace-decode[=on|off]
+Trace instruction decoding.  This tends to be for breaking down the instruction
+into its component parts.
+
+@item --trace-extract[=on|off]
+Trace instruction extraction.  This tends to be for extracting arguments or bit
+fields from the instruction.
+
+@item --trace-linenum[=on|off]
+Perform line number tracing (implies @option{--trace-insn}).
+
+@item --trace-memory[=on|off]
+Trace memory operations.  This covers loads & stores.
+
+@item --trace-alu[=on|off]
+Trace @abbr{ALU, Arithmetic Logic Unit} operations.  This tends to be basic
+integer math operations.
+
+@item --trace-fpu[=on|off]
+Trace @abbr{FPU, Floating Point Unit} operations.  Not all architectures have
+FPU's, and ones that implement them in software cannot be traced at this level
+(since there are no actual FPU instructions).
+
+@item --trace-vpu[=on|off]
+Trace @abbr{VPU, Vector Processing Unit} operations (also known as @abbr{SIMD,
+Single Instruction, Multiple Data} operations).  Not all architectures have
+VPU's or SIMD instructions, and ones that implement them in software cannot
+be traced at this level since there are no actual machine instructions).
+
+@item --trace-branch[=on|off]
+Trace branching.  These can be conditional or unconditional branches, jumps,
+returns, and exceptions.
+
+@item --trace-semantics[=on|off]
+Perform ALU, FPU, VPU, MEMORY, and BRANCH tracing.  Meant as a shortcut for
+common set of operations that users are interested in.
+
+@item --trace-model[=on|off]
+Include model performance data.
+
+@item --trace-core[=on|off]
+Trace core operations.
+
+@item --trace-events[=on|off]
+Trace simulator events.
+
+@item --trace-syscall[=on|off]
+Trace system calls.
+
+@item --trace-register[=on|off]
+Trace cpu register accesses.
+
+@item --trace-debug[=on|off]
+Add information useful for debugging the simulator to the tracing output.
+
+@item --trace-file <FILENAME>
+Specify tracing output file instead of dumping to stderr.
+@end table
+
+@node Debugging Options
+@section Debugging
+Note: The debugging subsystem is disabled at compile time by default.  You will
+have to pass @option{--enable-sim-trace} and @option{--enable-sim-debug}.
+
+Note: Not all architecture backends support all debugging categories.
+
+@table @option
+@item -D, --debug
+Print debugging messages.  This is required for any of the @option{--debug-*}
+options to have any effect.
+
+@item --debug-insn
+Print instruction debugging messages.
+
+@item --debug-file <FILENAME>
+Specify debugging output file instead of using stderr.
+@end table
+
+@node Profiling Options
+@section Profiling
+Note: Not all architecture backends support all profiling categories.
+
+@table @option
+@item -p[on|off]
+@itemx --profile[=on|off]
+Perform profiling.  This is required for any of the @option{--profile-*}
+options to have any effect.
+
+@item --profile-insn[=on|off]
+Perform instruction profiling.
+
+@item --profile-memory[=on|off]
+Perform memory profiling.
+
+@item --profile-core[=on|off]
+Perform CORE profiling.
+
+@item --profile-model[=on|off]
+Perform model profiling.
+
+@item --profile-cpu-frequency <CPU FREQUENCY>
+Specify the speed of the simulated cpu clock.
+
+@item --profile-file FILENAME
+Specify profile output file instead of using stderr.
+
+@item --profile-pc[=on|off]
+Perform PC profiling.
+
+@item -F PC PROFILE FREQUENCY
+@item --profile-pc-frequency <PC PROFILE FREQUENCY>
+Specified PC profiling frequency.
+
+@item -S <PC PROFILE SIZE>
+@itemx --profile-pc-size <PC PROFILE SIZE>
+Specify PC profiling size.
+
+@item --profile-pc-granularity <PC PROFILE GRANULARITY>
+Specify PC profiling sample coverage.
+
+@item --profile-pc-range BASE,BOUND
+Specify PC profiling address range.
+@end table
+
+@node Watchpoints Options
+@section Watchpoints
+Note: Not all architecture backends support the same set of watchpoint events
+or actions.
+
+A note on terminology: watchpoints and breakpoints tend to be synonymous.  The
+GNU Simulator uses the term "watchpoints".  These are effectively "hardware
+watchpoints" as they do not require changing the instructions executed (how
+"software breakpoints" are implemented).
+
+Watchpoint functionality is mostly meant to be used when integrating with other
+systems (for example, @sc{gdb}).  When running the simulator via @command{run},
+watchpoints will trigger @code{SIGTRAP} signals which halt the simulation and
+cause the program to exit.
+
+@table @option
+@item --watch-cycles-ACTION [+]COUNT
+Watch the simulator, take ACTION in COUNT cycles (`+' for every COUNT cycles),
+ACTION is int breakpoint.
+
+@item --watch-pc-ACTION [!]ADDRESS
+Watch the PC, take ACTION when matches ADDRESS (in range ADDRESS,ADDRESS),
+`!' negates test.
+
+@item --watch-clock-ACTION [+]MILLISECONDS
+Watch the clock, take ACTION after MILLISECONDS (`+' for every MILLISECONDS).
+
+@item --watch-delete IDENT|all|pc|cycles|clock
+Delete a watchpoint.
+
+@item --watch-info
+List scheduled watchpoints.
+@end table
+
+@node Device Models Options
+@section Device Models
+Note: Not all architecture backends support hardware/device simulation.
+
+@xref{Modeling Hardware} for more details.
+
+@table @option
+@item --hw-info
+@itemx --info-hw
+List configurable hardware regions.
+
+@item --hw-trace[=on|off]
+@itemx --trace-hw
+Trace all hardware devices.
+
+@item --hw-device <DEVICE>
+Add the specified device.  This is used to configure a single device or
+component, not an entire system.
+
+@item --hw-list
+List the current active device tree.
+
+@item --hw-file FILE
+Add the devices listed in the file.
+
+@item --model MODEL
+Specify model to simulate.  This is used to select a standard CPU or core
+architecture, and all of its associated pieces.  This is a higher level
+abstraction than the @option{--hw-device} setting.
+
+Think of this as selecting an entire SoC while @option{--hw-device} controls
+individual components or peripherals (for example, a single I2C bus).
+
+@item --model-info
+@itemx --info-model
+List selectable models.
+@end table
+
+@node Serial Socket
+@section Serial Ports Over Network Sockets
+@table @option
+@item --sockser-addr SOCKET ADDRESS
+Set serial emulation socket address.
+@end table
+
+@node GDB Integration
+@section GDB Integration
+If the simulator has been enabled and ported to the target, it should be
+available while running @sc{gdb} automatically.  This makes for quick testing
+and low level debugging starting from the very first instruction.
+
+You can check that the simulator is available by running @code{target sim
+--version} in @sc{gdb}.  If it reports @code{Undefined target command: "sim"},
+verify that @sc{gdb} has been compiled correctly.
+
+Running via @sc{gdb} has a few caveats and error reporting is terse.  Here's a
+quick example.
+
+@smallexample
+# First connect to the simulator.
+(gdb) target sim [simulator options]
+
+# You won't be able to do anything until you load a program (e.g. ELF).
+(gdb) load ./hello.elf
+
+# You then need to actually run the program to get resources (e.g. registers).
+# You might want to set some breakpoints before executing things.
+(gdb) run
+
+# You can change some simulator settings while running.  Note that the options
+# are the same as the command line options, but with no leading dashes.
+(gdb) sim help
+@end smallexample
+
+@node Runtime Environments
+@chapter Runtime Environments
+@cartouche
+Runtime environments have no relation to environment variables (e.g.
+@code{environ}).  They are completely distinct concepts, and anytime those are
+discussed, the full term @samp{environment variables} will be used to maintain
+clarity.
+@end cartouche
+
+The simulator has the concept of environments.  These define how many services
+the simulator itself provides (akin to a hypervisor), and how much the program
+itself will have to handle.
+
+This is similar to QEMU's user & system modes if you're familiar with those.
+
+Let's look at a quick summary to try and clear up confusion.  These names are
+used with the @code{--environment} option.
+
+@table @asis
+@item No environment
+Only CPU registers and memory (RAM) are available.
+@item @code{virtual}
+The simulator acts as a hypervisor by handling exceptions (e.g. syscalls), but
+the program otherwise runs as if it were in the highest CPU privilege level
+available.  This is used to run simple bare-metal programs.
+@item @code{user}
+The simulator acts as an OS kernel by handling exceptions.  The program runs as
+if it were in the lowest CPU privilege level available.  This can be used to run
+user (e.g. @value{linux}) programs.
+@item @code{operating}
+The simulator acts like real hardware.  The program runs as if it were an OS
+kernel itself on hardware, so it must handle interrupts, exceptions, devices,
+etc... all itself.  This can be used to run a Linux kernel which in turn could
+run Linux user programs).
+@end table
+
+While all ports support basic ISA simulation (e.g. registers), not all ports
+support any or all of the environments.  Be sure to consult the port specific
+section of the manual before attempting to use unsupported functionality.
+
+@node Virtual Environment
+@section Virtual Environment
+The virtual environment provides a quick way of executing bare-metal programs.
+The simulator acts as a hypervisor by servicing all exceptions.  Memory is
+available, but no interrupts or device models work.  Privileged instructions
+behavse as if the CPU is always in the highest level.  Code that would switch
+privilege levels is ignored (e.g. nop).
+
+Basic @value{libgloss} system calls will be processed by the simulator.
+
+@node Virtual Environment Variables (environ)
+@subsection Environment Variables (environ)
+Passing environment variables to the simulated program is supported.  These are
+independent of the environment variables that the GNU Simulator itself sees.
+
+The runtime support code (e.g. the @value{crt}, @code{crt0}) is responsible for
+reading the environemt settings from the simulator.  Consult the particular
+runtime's documentation for more details.  @value{libgloss} is known to only
+provide an empty stub.
+
+@node Virtual environ Access
+@subsubsection Syscall Access
+The environment variables are accessible via the @ref{sys_argv} and
+@ref{sys_argvlen} syscalls.  Currently they are not accessible indepenently from
+the @ref{Virtual Command Line Arguments (argv)}.
+
+@node Virtual Command Line Arguments (argv)
+@subsection Command Line Arguments (argv)
+Passing command line options to the simulated program is supported.  These are
+independent of the options that the GNU Simulator itself handles.  All arguments
+specified after the program will be made available.
+
+In this example, the @code{hello.elf} program will be passed three arguments:
+@code{--opt}, @code{abc}, and @code{def}.  The @code{--env virtual} will be
+consumed by the GNU Simulator itself to set the execution environment.
+@example
+$ run --env virtual ./hello.elf --opt abc def
+@end example
+
+@node Virtual argv Access
+@subsubsection Syscall Access
+There are two ways the command line may be accessed.  There's the so-called
+"old" and "new" ways.  Both are supported since they're in use by different
+@value{libgloss} ports, and at this point, trying to deprecate & remove one set
+is not really worth the effort.
+
+Originally, only the "old" set of syscalls existed: @ref{sys_argv} and
+@ref{sys_argvlen}.  The process first calls @ref{sys_argvlen} to see how many
+bytes are required to store all of the command line arguments and environment
+strings, then it allocates that space, then it calls @ref{sys_argv} to copy the
+flattened string data into the specified buffer.  Finally, the process has to
+scan the NUL delimited strings to count the number of arguments (i.e.
+@code{argc}) & build up the array of pointers (i.e. @code{argv} and
+@code{environ}).  If the space required is too large (especially if too many
+arguments or a large environment are specified), then it's impossible to access
+any of the individual elements.  Since this logic typically lives in the early
+startup code of the process, that typically would result in an early crash or
+abort.
+
+To address the memory limitations, a "new" set of syscalls were added:
+@ref{sys_argc}, @ref{sys_argnlen}, and @ref{sys_argn}.  The process calls
+@ref{sys_argc} to see how many command line arguments are available, and then
+calls @ref{sys_argnlen} on a single argument to get its individual length, and
+then calls @ref{sys_argn} to copy the single argument into its buffer.  This
+simplifies common startup code a bit, and provides the flexibility of accessing
+arguments only if and when they're needed.  There is no support for accessing
+environment variables in this scenario though.
+
+All the syscalls may be used in a single execution of course---there is no
+limitation in the simulator itself restricting things to a single set at a
+time.  It just doesn't normally happen since code is written with a certain
+pattern in mind.
+
+The command line arguments and environment variables these syscalls access are
+fixed for the entire run.  The simulated program is free to copy state in and
+then manage things however it wants, but the simulator itself will never change
+the state it makes available via the syscalls.  Consider them the "initial set".
+
+@node Virtual Filesystem
+@subsection Filesystem
+Access to the real file system is allowed when using related system calls.  The
+@option{--sysroot} option allows some control over which parts of the host file
+system is actually visible.  By default, the sysroot is set to @file{/}.
+
+File descriptors are not shared directly.  A mapping table is maintained to
+translate the file descriptors from the real ones to what the simulated
+environment sees.  This avoids leaking file descriptors used by the simulator
+itself into the simulated environment, and for cleanly managing conflicting
+file descriptors like stdio.
+
+Sockets and other services using file descriptors go through the same table.
+
+@node Virtual Processes
+@subsection Processes
+The active process settings are exposed to the simulated environment.  This
+allows the simulator to access its own @value{pid} via @ref{sys_getpid} so that
+it can send itself signals (e.g. via @ref{sys_kill}), as well as send signals to
+other processes in the system.
+
+@node Virtual Runtime ABI
+@subsection Runtime ABI
+When processing system calls, the virtual environment uses the @value{newlib}
+ABI by default (e.g., when using the GNU Simulator directly via @command{run}).
+However, projects that integrate the simulator directly are able to change these
+ABI values to whatever they want.  @xref{Integration} for more details.
+
+This covers a number of items:
+@itemize @bullet
+@item
+Error values (i.e. errno) such as @code{EINVAL}
+@item
+Signal values such as @code{SIGINT}
+@item
+Filesystem stat structures such as @code{struct st}
+@item
+File open constants such as @code{O_RDWR}
+@item
+System call numbers
+@end itemize
+
+The ABI of the simulated program does not need to match the ABI of the host
+runtime environment.  The values, flags, structures, etc... are translated on
+the fly.  This allows for independence between the simulated program (e.g. its
+architecture, bitsize, endianness, etc...) and the host runtime (e.g. its
+architecture, bitsize, endianness, etc...).
+
+@node Virtual System Calls
+@subsection System Calls
+These are the syscalls supported by the virtual environment.  For specific
+architecture syscall ABI information, @pxref{Architecture Specifics}.
+
+When using the GNU Simulator directly via @command{run}, these syscalls will
+behave as you would expect---by interacting with the current filesystem and
+overall OS runtime.  However, projects that integrate the simulator directly
+are able to hook every low-level call and choose to take a different action.
+@xref{Integration} for more details.
+
+The use of @code{long} in the definitions below is to indicate that arguments
+are passed in a single register of native word-size.  So for 32-bit CPUs,
+these are 32-bit integers, and in 64-bit CPUs, these are 64-bit integers.
+
+All syscalls have dedicated error values---one register indicates success,
+while a different pair holds result values.  This avoids the common problem of
+with using a single value to distinguish between success & failure, and the
+type of success or failure.  For example, if failure were defined as "negative
+values", and the @ref{sys_lseek} syscall was used with large files (4 GiB), the
+caller will have difficulty writing checks with 32-bit signed integers.  By
+dedicating a register to error status, there is never ambiguity, at the slight
+(but perhaps immeasurable) cost of more register usage.
+
+As noted, result values (not including the error status) come in pairs.  This
+permits, depending on the syscall, either returning 64-bit values even on a
+32-bit CPU (by splitting the value across two registers), or returning two
+independent values.
+
+No header file is currently provided to make these syscalls.  These are provided
+merely as reference for low-level implementers (e.g. @value{libgloss}
+maintainers).  Those environments might provide a raw @code{syscall()} interface
+but with a different interface more attuned for use in C or C++ languages (where
+returning multiple values can be tricky).
+
+Typographically, the @code{@{...@comma{} ...@}} return value indicates the separate
+error and result values.  The error and results are always initialized so
+callers can always check the error status before using the result.
+
+@macro defsyscall{ret, name, args, desc, returns, errors, example}
+Syscall: @{@i{long error}, @i{\ret\}@} @b{sys_\name\} (@i{\args\})
+
+\desc\
+
+Returns:
+@indentedblock
+\returns\
+@end indentedblock
+
+Errors:
+@indentedblock
+NB: Exact errors may change based on the host environment.
+
+\errors\
+@end indentedblock
+
+Example:
+@example
+\example\
+@end example
+@end macro
+
+@node sys_argc
+@subsubsection argc
+@defsyscall{long, argc, void,
+Calculates the number of command line arguments available.,
+The number of command line arguments available.  @code{0} is a valid result to
+indicate there are no arguments.,
+This call will never fail.,
+// argv = @{"abc"@comma{} "def"@}
+sys_argc()
+    @result{} 2
+
+// argv = @{@}
+sys_argc()
+    @result{} 0
+}
+
+See Also:
+@indentedblock
+Use in conjunction with @ref{sys_argn} & @ref{sys_argnlen}.@*
+@b{Not used} with @ref{sys_argvlen} or @ref{sys_argv}.@*
+@xref{Virtual argv Access} for more information.
+@end indentedblock
+
+@node sys_argnlen
+@subsubsection argnlen
+@defsyscall{long, argnlen, long @var{argn},
+Calculates the length of the command line argument @var{argn}.,
+The number of bytes@comma{} not including the trailing @code{NUL}@comma{} of
+the command line argument @var{argn}.,
+@code{EINVAL}: @var{argn} is less than zero.@*
+@code{EINVAL}: @var{argn} is greater or equal to @ref{sys_argc}.@*
+,
+// argv = @{"blah"@comma{} "abc"@}
+
+sys_argnlen(0)
+    @result{} 4
+
+sys_argnlen(1)
+    @result{} 3
+
+sys_argnlen(-1)
+    @error{} EINVAL
+
+sys_argnlen(100)
+    @error{} EINVAL
+}
+
+See Also:
+@indentedblock
+Use in conjunction with @ref{sys_argc} & @ref{sys_argn}.@*
+@b{Not used} with @ref{sys_argvlen} or @ref{sys_argv}.@*
+@xref{Virtual argv Access} for more information.
+@end indentedblock
+
+@node sys_argn
+@subsubsection argn
+
+@defsyscall{char *, argn, long @var{argn}@comma{} char *@var{arg},
+Copies the command line argument @var{argn} to the @var{arg} buffer.  The caller
+must guarantee that @var{arg} is large enough to hold the string;
+@ref{sys_argnlen} may be used beforehand.,
+The @var{arg} pointer.,
+@code{EINVAL}: @var{argn} is less than zero.@*
+@code{EINVAL}: @var{argn} is greater or equal to @ref{sys_argc}.@*
+@code{EINVAL}: @var{buffer} cannot be written (e.g. address is outside of available address space).@*
+,
+// argv = @{"blah"@comma{} "abc"@}
+// buffer = @{...@}
+
+sys_argn(0@comma{} buffer)
+    @result{} buffer
+    @result{} @point{}buffer = @{
+      // "blah\0"
+      98, 108, 97, 104, 0,
+    @}
+
+sys_argn(1@comma{} buffer)
+    @result{} buffer
+    @result{} @point{}buffer = @{
+      // "abc\0"
+      97, 98, 99, 0,
+    @}
+
+sys_argn(-1@comma{} buffer)
+    @error{} EINVAL
+
+sys_argn(100@comma{} buffer)
+    @error{} EINVAL
+}
+
+See Also:
+@indentedblock
+Use in conjunction with @ref{sys_argc} & @ref{sys_argnlen}.@*
+@b{Not used} with @ref{sys_argvlen} or @ref{sys_argv}.@*
+@xref{Virtual argv Access} for more information.
+@end indentedblock
+
+@node sys_argvlen
+@subsubsection argvlen
+@defsyscall{long, argvlen, void,
+Calculates the byte size of all command line arguments and environment strings.
+This is the sum of the string length (including the NUL byte) of every command
+line argument and environment string@comma{} plus 2 additional @code{NUL} bytes
+to mark the end of each segment (1 per segment).,
+The total byte size for use with @ref{sys_argv}.,
+This call will never fail.,
+// argv = @{@}
+// environ = @{@}
+sys_argvlen()
+    @result{} 0 + 1 + 0 + 1
+    @result{} 2
+
+// argv = @{"abc"@}
+// environ = @{@}
+sys_argc()
+    @result{} 4 + 1 + 0 + 1
+    @result{} 6
+
+// argv = @{"abc"@comma{} "blah"@}
+// environ = @{"var=value"@comma{} "HOME=/"@}
+sys_argc()
+    @result{} (4 + 5) + 1 + (10 + 7) + 1
+    @result{} 28
+}
+
+See Also:
+@indentedblock
+Use in conjunction with @ref{sys_argv}.@*
+@b{Not used} with @ref{sys_argc}, @ref{sys_argnlen}, or @ref{sys_argn}.@*
+@xref{Virtual argv Access} for more information.
+@end indentedblock
+
+@node sys_argv
+@subsubsection argv
+@defsyscall{long @var{argc}@comma{} long @var{envc}, argv, const char *@var{buffer}@comma{} long @var{size},
+Copies the command line arguments and environment strings to the @var{buffer}.,
+The number of command line arguments @var{argc} and the number of environment
+variables @var{envc}.,
+@code{EFAULT}: @var{size} is too small to hold all the data.@*
+@code{EINVAL}: @var{buffer} cannot be written (e.g. address is outside of available address space).@*
+,
+// argv = @{@}
+// environ = @{@}
+// buffer = @{...@}
+sys_argvlen(buffer@comma{} 2)
+    @result{} 0
+    @result{} @point{}buffer = @{
+        // NIL to mark end of argv.
+        0@comma{}
+        // NIL to mark end of environ.
+        0@comma{}
+    @}
+
+// argv = @{"abc"@}
+// environ = @{@}
+// buffer = @{...@}
+sys_argvlen(buffer@comma{} 200)
+    @result{} 0
+    @result{} @point{}buffer = @{
+        // "abc\0"
+        97@comma{} 98@comma{} 99@comma{} 0@comma{}
+        // NIL to mark end of argv.
+        0@comma{}
+        // NIL to mark end of environ.
+        0@comma{}
+    @}
+
+// argv = @{"abc"@comma{} "blah"@}
+// environ = @{"var=value"@comma{} "HOME=/"@}
+// buffer = @{...@}
+sys_argvlen(buffer@comma{} 200)
+    @result{} 0
+    @result{} @point{}buffer = @{
+        // "abc\0"
+        97@comma{} 98@comma{} 99@comma{} 0@comma{}
+        // "blah\0"
+        98@comma{} 108@comma{} 97@comma{} 104@comma{} 0@comma{}
+        // NIL to mark end of argv.
+        0@comma{}
+        // "var=value\0"
+        118@comma{} 97@comma{} 114@comma{} 61@comma{} 118@comma{} 97@comma{} 108@comma{} 117@comma{} 101@comma{} 0@comma{}
+        // "HOME=/\0"
+        72@comma{} 79@comma{} 77@comma{} 69@comma{} 61@comma{} 47@comma{} 0@comma{}
+        // NIL to mark end of environ.
+        0@comma{}
+    @}
+}
+
+See Also:
+@indentedblock
+Use in conjunction with @ref{sys_argv}.@*
+@b{Not used} with @ref{sys_argc}, @ref{sys_argnlen}, or @ref{sys_argn}.@*
+@xref{Virtual argv Access} for more information.
+@end indentedblock
+
+@node sys_chdir
+@subsubsection chdir
+@defsyscall{void, chdir, char *@var{path},
+Change the working directory to @var{path}.,
+@code{0} the @value{cwd} was changed to @var{path}.,
+,
+// cwd = "/"
+sys_chdir("/foo")
+    @result{} 0
+    @result{} cwd = "/foo"
+}
+
+@node sys_chmod
+@subsubsection chmod
+@defsyscall{void, chmod, const char *@var{path}@comma{} long @var{mode},
+Change @var{path}'s permissions to @var{mode}.,
+@code{0} if @var{path} had its permissions changed.,
+,
+// ./foo is 0644 (rw-r--r--)
+sys_chmod("foo"@comma{} 0755)
+    @result{} ./foo is 0755 (rwxr-xr-x)
+}
+
+@node sys_close
+@subsubsection close
+@defsyscall{void, close, long @var{fd},
+Close the open file descriptor @var{fd}.,
+@code{0} if @var{fd} was closed.,
+@code{EBADF}: @var{fd} is not a valid file descriptor.,
+// 3 is an open file descriptor.
+sys_close(3)
+    @result{} 0
+
+// 5 is not a valid file descriptor.
+sys_close(5)
+    @error{} EBADF
+}
+
+@node sys_exit
+@subsubsection exit
+@defsyscall{void, exit, long @var{status},
+Halts execution of the simulation.  Typically @code{0} is used to indicate
+"success" while non-zero values are "failure".
+@*@*
+The full value is passed back and made available to the simulator.
+However@comma{} when using @command{run}@comma{} the value callers typically see
+are still limited by the OS's @posix{functions, exit} call.  Which means the
+value is masked by @code{0xff} to get it into the [0@comma{}255] range.,
+N/A,
+This call will never fail.,
+sys_exit(0)
+    @result{} The simulation exits with status of 0.
+
+sys_exit(1)
+    @result{} The simulation exits with status of 1.
+}
+
+@node sys_fstat
+@subsubsection fstat
+@defsyscall{long, fstat, long @var{fd}@comma{} struct stat *@var{statbuf},
+Get the file status for open @var{fd} and store it in @var{statbuf}.,
+@code{0} if the file status was stored successfully.,
+@code{EBADF}: @var{fd} is not a valid file descriptor.@*
+,
+// 4 is a valid file descriptor.
+// st is a struct stat.
+sys_fstat(4@comma{} &st)
+    @result{} 0
+    @result{} st = @{
+        // The stat structure contains details on the open file.
+    @}
+}
+
+@node sys_ftruncate
+@subsubsection ftruncate
+@defsyscall{long, ftruncate, long @var{fd}@comma{} long @var{length},
+Truncates the open file @var{fd} to the byte size @var{length}.,
+@code{0} if @var{fd} was truncated to @var{length} bytes.,
+@code{EBADF}: @var{fd} is not a valid file descriptor.@*
+,
+// 4 is a valid file descriptor.
+sys_ftruncate(4@comma{} 100)
+    @result{} 0
+    @result{} The open file's size is now 100 bytes.
+}
+
+@node sys_getpid
+@subsubsection getpid
+@defsyscall{long, getpid, void,
+Gets the current process's id (PID).  When using @command{run}@comma{} this is
+the actual simulator's process id.,
+The process id.,
+This call will never fail.,
+sys_getpid()
+    @result{} 10505  // The process id will probably change between every run.
+}
+
+@node sys_kill
+@subsubsection kill
+@defsyscall{long, kill, long @var{pid}@comma{} long @var{signal},
+Send a @var{signal} to the proccess @var{pid}.,
+@code{0} if @var{signal} was sent to @var{pid}.,
+@code{EINVAL}: An invalid @var{signal} was specified.@*
+@code{EPERM}: The process may not send signals to @var{pid}.@*
+@code{ESRCH}: Process @var{pid} does not exist.@*
+,
+// Get the current process's id.
+sys_getpid()
+    @result{} 42
+
+// Send a SIGINT (i.e. @kbd{@key{CTRL}-c}) to self.
+sys_kill(42@comma{} SIGINT)
+    @result{} 0
+    @result{} The simulator will receive a SIGINT for the process.
+}
+
+@node sys_lseek
+@subsubsection lseek
+@defsyscall{int64_t, lseek, long @var{fd}@comma{} long @var{offset}@comma{} long @var{whence},
+Adjust the file offset of the open @var{fd} according to @var{whence}.,
+The new file offset.,
+@code{EBADF}: @var{fd} is not a valid file descriptor.@*
+,
+// 4 is a valid file descriptor.
+// Its current offset is 100 with a length of 300 bytes.
+
+sys_lseek(4@comma{} 20@comma{} SEEK_CUR)
+    @result{} 120
+    @result{} The file offset is now 120.
+
+sys_lseek(4@comma{} -40@comma{} SEEK_CUR)
+    @result{} 80
+    @result{} The file offset is now 80.
+
+sys_lseek(4@comma{} 0@comma{} SEEK_SET)
+    @result{} 0
+    @result{} The file offset is now 0.
+
+sys_lseek(4@comma{} -50@comma{} SEEK_END)
+    @result{} 250
+    @result{} The file offset is now 250.
+}
+
+@node sys_lstat
+@subsubsection lstat
+@defsyscall{long, lstat, const char *@var{path}@comma{} struct stat *@var{statbuf},
+Get the file status for the symlink @var{path} and store it in @var{statbuf}.,
+@code{0} if the file status was stored successfully.,
+@code{ENOENT}: @var{path} does not exist.@*
+,
+// ./foo is a symlink.
+// st is a struct stat.
+sys_lstat("foo"@comma{} &st)
+    @result{} 0
+    @result{} st = @{
+        // The stat structure contains details on the symlink ./foo.
+    @}
+}
+
+@node sys_open
+@subsubsection open
+@defsyscall{long, open, const char *@var{path}@comma{} long @var{flags}@comma{} long @var{mode},
+Open the @var{path} and return the new file descriptor.  The @var{flags} contain
+the access mode@comma{} creation flags@comma{} and other file status related
+flags.,
+The new @var{fd}.,
+,
+// ./foo is a file.
+sys_open("foo"@comma{} O_RDONLY)
+    @result{} 3  // The file descriptor may change between runs.
+
+// ./foo is a file.
+sys_open("foo"@comma{} O_WRONLY)
+    @result{} 3  // The file descriptor may change between runs.
+
+// ./foo does not exist.
+sys_open("foo"@comma{} O_RDWR|O_CREAT@comma{} 0644)
+    @result{} 3  // The file descriptor may change between runs.
+}
+
+@node sys_pipe
+@subsubsection pipe
+@defsyscall{long, pipe, long @var{fds}[2],
+Create a new unidirectional pipe and store the file descriptors in @var{fds}.
+@var{fds[0]} is the read end while @var{fds[1]} is the write end.,
+@code{0} if the pipe was successfully created.,
+,
+// long fds[2]
+sys_pipe(fds)
+    @result{} 0
+    @result{} fds[0] and fds[1] are valid file descriptors.
+}
+
+@node sys_read
+@subsubsection read
+@defsyscall{long, read, long @var{fd}@comma{} char *@var{buffer}@comma{} long @var{count},
+Read up to @var{count} bytes from @var{fd} and store them in @var{buffer}.,
+The number of bytes read.  @code{0} means end of file is reached.,
+@code{EBADF}: @var{fd} is not a valid file descriptor.@*
+,
+// 4 is a valid file descriptor for a file opened for reading.
+// It contains the string "some data".
+
+// buffer = @{...@}
+sys_read(4@comma{} buffer@comma{} 4)
+    @result{} 4
+    @result{} The file offset is now 4.
+    @result{} @point{}buffer = @{
+        // "some"
+        115, 111, 109, 101,
+    @}
+
+sys_read(4@comma{} buffer@comma{} 1000)
+    @result{} 5
+    @result{} The file offset is now 9.
+    @result{} @point{}buffer = @{
+        // " data"
+        32, 100, 97, 116, 97,
+    @}
+
+sys_read(4@comma{} buffer@comma{} 4)
+    @result{} 0
+    @result{} The file offset is still 9.
+}
+
+@node sys_rename
+@subsubsection rename
+@defsyscall{long, rename, const char *@var{old_path}@comma{} const char *@var{new_path},
+Rename the @var{old_path} to @var{new_path}.  @var{new_path} must not exist
+already nor may it be a directory.,
+@code{0} if the files were renamed correctly.,
+@code{EEXIST}: @var{new_path} already exists.@*
+@code{ENOENT}: @var{old_path} does not exist.@*
+,
+// ./foo is a file.  ./bar does not exist.
+sys_rename("foo"@comma{} "bar")
+    @result{} 0
+    @result{} "foo" has been renamed to "bar".
+}
+
+@node sys_sbrk
+@subsubsection sbrk
+@c /*#define sbrk 11 - not currently a system call, but reserved.  */
+
+@node sys_stat
+@subsubsection stat
+@defsyscall{long, stat, const char *@var{path}@comma{} struct stat *@var{statbuf},
+Get the file status for the @var{path} and store it in @var{statbuf}.  If
+@var{path} is a symlink@comma{} it is dereferenced first.,
+@code{0} if the file status was stored successfully.,
+@code{ENOENT}: @var{path} does not exist.@*
+,
+// ./foo is a path (e.g. file@comma{} directory@comma{} etc...) that exists.
+// st is a struct stat.
+sys_stat("foo"@comma{} &st)
+    @result{} 0
+    @result{} st = @{
+        // The stat structure contains details on the path ./foo.
+    @}
+}
+
+@node sys_time
+@subsubsection time
+@c TODO: Actually make time syscall handle 64-bit.
+@defsyscall{int64_t, time, void,
+Get the current UNIX time as the number of seconds since the Epoch
+(1970-01-01 00:00:00 +0000 (UTC)).  Leap seconds are never included.,
+The UNIX timestamp.,
+This call will never fail.,
+sys_time()
+    @result{} 631152000  // 1 Jan 1990
+}
+
+@node sys_truncate
+@subsubsection truncate
+@defsyscall{long, truncate, const char *@var{path}@comma{} long @var{length},
+Truncates @var{path} to the byte size @var{length}.,
+@code{0} if @var{path} was truncated to @var{length} bytes.,
+,
+// ./foo is a file.
+sys_truncate("foo"@comma{} 100)
+    @result{} 0
+    @result{} "foo" is now 100 bytes.
+}
+
+@node sys_utime
+@subsubsection utime
+@defsyscall{long, utime, const char *@var{path}@comma{} const int64_t @var{times}[2],
+Change @var{path}'s access & modify times.  @var{times[0]} is the access time
+while @var{times[1]} is the modify time.  Times are specified as the number of
+seconds since the Epoch (1970-01-01 00:00:00 +0000 (UTC)).  Leap seconds are
+never included.,
+@code{0} if @var{path}'s filesystem times were changed.,
+@code{ENOENT}: @var{path} does not exist.@*
+,
+// ./foo is a file.
+// buffer = @{0@comma{} 100@}
+sys_utime("foo"@comma{} buffer)
+    @result{} 0
+    @result{} "foo"'s access time is now 0.
+    @result{} "foo"'s modify time is now 100.
+}
+
+@node sys_write
+@subsubsection write
+@defsyscall{long, write, long @var{fd}@comma{} char *@var{buffer}@comma{} long @var{count},
+Write @var{count} bytes from @var{buffer} to @var{fd}.,
+The number of bytes written.,
+@code{EBADF}: @var{fd} is not a valid file descriptor.@*
+,
+// 4 is a valid file descriptor for a file opened for writing.
+// It contains the string "nothing".
+
+// buffer = @{115@comma{} 111@comma{} 109@comma{} 101@}  // "some"
+sys_write(4@comma{} buffer@comma{} 4)
+    @result{} 4
+    @result{} The file offset is now 4.
+    @result{} The file contains "someing".
+
+// buffer = @{32@comma{} 100@comma{} 97@comma{} 116@comma{} 97@}  // " data"
+sys_write(4@comma{} buffer@comma{} 5)
+    @result{} 5
+    @result{} The file offset is now 9.
+    @result{} The file contains "some data".
+}
+
+@node sys_unlink
+@subsubsection unlink
+@defsyscall{long, unlink, const char *@var{path},
+Remove @var{path} from the filesystem.,
+@code{0} if @var{path} was successfully removed@comma{} @code{-1} otherwise.,
+@code{ENOENT}: @var{path} does not exist.@*
+,
+// "foo" exists in the current directory.
+sys_unlink("foo")
+    @result{} 0
+    @result{} "foo" no longer exists.
+
+// "foo" no longer exists.
+sys_unlink("foo")
+    @error{} ENOENT
+}
+
+@node User Environment
+@section User Environment
+Similar to the virtual environment, the user environment makes the simulator act
+like an OS kernel by handling exceptions.  Memory is available, but no
+interrupts or device models work.  Privileged instructions behave as if the CPU
+is always in the lowest level.  Code that requires higher priveleged levels
+cause exceptions like real hardware which usually means the program exits.
+
+More featureful system call environments are supported here (e.g.
+@value{linux}).  Refer to the @value{man7} for more details.
+
+@node User Environment Variables (environ)
+@subsection Environment Variables (environ)
+Passing environment variables to the simulated program is supported.  These are
+independent of the environment variables that the GNU Simulator itself sees.
+
+The environment variables are passed via the stack like a typical operating
+system (e.g. @value{linux}) to the @value{crt}.
+
+@node User Command Line Arguments (argv)
+@subsection Command Line Arguments (argv)
+Passing command line options to the simulated program is supported.  These are
+independent of the options that the GNU Simulator itself handles.  All arguments
+specified after the program will be made available.
+
+The arguments are passed via the stack like a typical operating system (e.g.
+@value{linux}) to the @value{crt}.
+
+@node User System Calls
+@subsection System Calls
+Currently, @value{linux} system calls are supported by some architectures.
+@xref{Architecture Specifics} for more details.
+
+@node Operating Environment
+@section Operating Environment
+The operating environment is the most complete for the simulated program and
+requires the most effort for the simulator ports.  This is akin to running on
+an actual CPU with peripherals: the simulated program has to handle all
+exceptions and interrupts and privilege levels itself, and communication with
+the outside world is via device models (e.g. serial ports).
+
+This can be used to run real bootloaders or OS kernels which in turn could run
+user programs.
+
+@node Operating Environment Variables (environ)
+@subsection Environment Variables (environ)
+There is no support for passing environment variables into the operating
+environment since, conceptually, they don't make much sense.  Bare metal
+programs (e.g. bootloaders and kernels) don't usually have a lower level in the
+software stack where environment variables would live.
+
+Some programs, like @value{uboot}, have a way of storing persistent
+configuration data referred to as an environment, but the structure of it tends
+to be highly specific.  In those cases, it's better to instantiate device models
+that take the place of real hardware.  For example, @value{uboot} could be
+configured to store state in CFI flash, and use the @ref{dv-cfi} model.
+
+@node Operating Command Line Arguments (argv)
+@subsection Command Line Arguments (argv)
+There is no support for passing command line arguments into the operating
+environment since, conceptually, they don't make much sense.  Some programs,
+like @value{linux}, have a "command line", but passing that information tends
+to be highly ABI specific.
+
+@node Modeling Hardware
+@chapter Modeling Hardware
+TODO discuss models
+
+@node Common Device Models
+@section Device Models
+Many peripherals are available.
+
+@node dv-cfi
+@subsection cfi
+Common Flash Memory Interface (CFI) model.
+
+The flash memory defaults to being erased (all zeros) on every run.  The
+@code{file} property can be used for persistent storage.
+
+@subsubsection Properties
+@table @code
+@item @b{(required)} reg = <address> <size>
+Specify the @var{address} (within the parent bus) to attach the flash memory.
+The @var{size} controls how much of the flash memory is accessible.
+
+@item @b{(required)} cmdset = <primary; integer> [alt; integer]
+The CFI command set to use.  Only @code{1} (Intel) is supported currently.
+
+@item size = <device size>
+The flash @var{size} (in bytes).  Defaults to the @var{register size}.
+
+The @var{size} must be a power of 2.
+
+@item width = <8|16|32>
+The flash bus @var{width} (in bits).  Defaults to @code{8} bits.
+
+@item write_size = <integer>
+The flash maximum @var{write size} (in bytes).
+
+The @var{write size} must be a power of 2.
+
+The values specified are not interpreted and are passed directly through.  So
+the default is @code{0} which the CFI standard defines as @samp{not supported}.
+
+@item erase_regions = <number blocks> <block size> [<number blocks> <block size> ...]
+Define flash @var{erase regions}.  Defaults to 1 erase region (i.e. can only
+erase whole chip).
+
+@item voltage = <vcc min> <vcc max> <vpp min> <vpp max>
+Define flash voltage settings.  This is not used directly, but is included in
+the CFI query command responses.
+
+The values specified are not interpreted and are passed directly through.  So
+the defaults are @code{0 0 0 0} which the CFI standard defines as @samp{0.0V}.
+
+@item timeouts = <typ unit write> <typ buf write> <typ block erase> <typ chip erase> <max unit write> <max buf write> <max block erase> <max chip erase>
+Define flash timeout settings.  These are not used directly, but are included in
+the CFI query command responses.
+
+The values specified are not interpreted and are passed directly through.  So
+the defaults are @code{0 0 0 0 0 0 0 0 0} which the CFI standard defines as
+@samp{typ: 1µs, not supported, 1ms, not supported} and @samp{max: 1µs, 1ms, 1ms,
+not supported}.
+
+@item file = <file> [ro|rw]
+Use @var{file} as persistent storage of the flash memory data.  It will be
+memory mapped directly.
+
+Access mode defaults to @code{ro} (read-only).
+@end table
+
+@node dv-core
+@subsection core
+The root of the device tree.
+
+The core device, positioned at the root of the device tree appears to its child
+devices as a normal device just like every other device in the tree.
+
+Internally it is implemented using a core object.  Requests to attach (or
+detach) address spaces are passed to that core object.  Requests to transfer
+(DMA) data are reflected back down the device tree using the core_map data
+transfer methods.
+
+@subsubsection Examples
+@example
+# Define the core.
+/core
+# Attach devices below it.
+/core/glue-or@@0x11
+/core/glue-or@@0x11/interrupt-ranges 0 2
+@end example
+
+@node dv-glue
+@subsection glue
+Glue to interconnect and test hardware ports.
+
+The glue device provides two functions.  Firstly, it provides a mechanism for
+inspecting and driving the port network.  Secondly, it provides a set of boolean
+primitives that can be used to apply combinatorial operations to the port
+network.
+
+Glue devices have a variable number of big endian @code{output registers}.  Each
+register is target-word sized.  The registers can be read and written.
+
+Writing to an output register results in an event being driven (level determined
+by the value written) on the devices corresponding output port.
+
+Reading an @code{output register} returns either the last value written or the
+most recently computed value (for that register) as a result of an event ariving
+on that port (which ever was computed last).
+
+@subsubsection Device types
+At present the following device types are available:
+
+@table @code
+@item glue
+In addition to driving its output interrupt port with any value written to an
+interrupt input port is stored in the corresponding @code{output register}.
+Such input interrupts, however, are not propogated to an output interrupt port.
+
+@item glue-and
+The bit-wise AND of the interrupt inputs is computed and then both stored in
+@code{output register} zero and propogated to output interrupt output port zero.
+
+@item glue-or
+The bit-wise OR of the interrupt inputs is computed and then both stored in
+@code{output register} zero and propogated to output interrupt output port zero.
+
+@item glue-xor
+The bit-wise XOR of the interrupt inputs is computed and then both stored in
+@code{output register} zero and propogated to output interrupt output port zero.
+
+@c TODO: These are listed in the source, but not actually implemented yet.
+@c @item glue-nand
+@c @item glue-nor
+@c @item glue-not
+@end table
+
+@subsubsection Properties
+
+@table @code
+@item @b{(required)} reg = <address> <size>
+Specify the @var{address} (within the parent bus) that this device is to live.
+The address must be 2048 * sizeof (word) (8k in a 32-bit simulation) aligned.
+
+@item interrupt-ranges = <int-number> <range>
+If present, this specifies the number of valid interrupt inputs (up to the
+maximum of 2048).  By default, @var{int-number} is zero and @var{range} is
+determined by the @var{reg size}.
+@end table
+
+@subsubsection Ports
+@itemize @bullet
+@item @code{int@var{N}} (bidirectional):
+Both an input and an output port for connecting to ports on other devices.
+@end itemize
+
+@subsubsection Examples
+Create source, bitwize-and, and sink glue devices.  Since the device at address
+@var{0x10000} is of size @var{8} it will have two output interrupt ports.
+@example
+/iobus@@0xf0000000/glue@@0x10000/reg 0x10000 8
+/iobus@@0xf0000000/glue-and@@0x20000/reg 0x20000 4
+/iobus@@0xf0000000/glue-and/interrupt-ranges 0 2
+/iobus@@0xf0000000/glue@@0x30000/reg 0x30000 4
+@end example
+
+Wire the two source interrupts to the AND device:
+@example
+/iobus@@0xf0000000/glue@@0x10000 > 0 0 /iobus/glue-and
+/iobus@@0xf0000000/glue@@0x10000 > 1 1 /iobus/glue-and
+@end example
+
+Wire the AND device up to the sink so that the and's output is not left open.
+@example
+/iobus@@0xf0000000/glue-and > 0 0 /iobus/glue@@0x30000
+@end example
+
+With the above configuration, the client program is able to compute a two bit
+AND.  For instance the @var{C} stub below prints 1 AND 0.
+@example
+unsigned *input = (void*)0xf0010000;
+unsigned *output = (void*)0xf0030000;
+unsigned ans;
+input[0] = htonl(1);
+input[1] = htonl(0);
+ans = ntohl(*output);
+write_string("AND is ");
+write_int(ans);
+write_line();
+@end example
+
+@subsubsection Bugs
+
+A future implementation of this device may support multiple interrupt ranges.
+
+Some of the devices listed may not yet be fully implemented.
+
+Additional devices such as a D flip-flop (DFF), an inverter (INV) or a latch
+(LAT) may prove useful.
+
+@node dv-pal
+@subsection pal
+The @abbr{PAL, Privileged Architecture Library} for assorted device junk.
+
+Typical hardware dependant hack.  This device allows the firmware to gain access
+to all the things the firmware needs (but the OS doesn't).
+
+@subsubsection Registers
+The pal contains the following registers:
+
+@multitable @columnfractions .1 .05 .05 .05 .7
+@headitem Name @tab Address @tab Size @tab R/W @tab Description
+@item @code{RESET}
+@tab @code{0}
+@tab 8-bit
+@tab write
+@tab Halts the simulator.  The value written to the register is used as an
+exit status.
+
+@item @code{PROCESSOR ID}
+@tab @code{4}
+@tab 8-bit
+@tab read
+@tab Returns the processor identifier (0 .. N-1) of the processor performing
+the read.
+
+@item @code{INTERRUPT}
+@tab @code{8}
+@tab 16-bit
+@tab write
+@tab This register must be written using a two byte store.  The low byte
+(address @code{8}) specifies a port and the upper byte (address @code{9})
+specifies the level.  @var{level} is driven on the specified port.  By
+convention, the pal's interrupt ports (int0, int1, ...) are wired up to the
+corresponding processor's level sensative external interrupt pin.
+
+@item @code{PROCESSOR COUNT}
+@tab @code{12}
+@tab 8-bit
+@tab read
+@tab Returns the total number of processors active in the current simulation.
+
+@item @code{TTY INPUT FIFO}
+@tab @code{16}
+@tab 8-bit
+@tab read
+@tab Returns the next available character from the pal's tty input port.
+
+@item @code{TTY INPUT STATUS}
+@tab @code{20}
+@tab 8-bit
+@tab read
+@tab Nonzero if a character is available in @code{TTY INPUT FIFO}, zero
+otherwise.  Reading the register will consume the next character (if
+available).
+
+@item @code{TTY OUTPUT FIFO}
+@tab @code{24}
+@tab 8-bit
+@tab write
+@tab Queue the character to be written to the pal's tty output port.  It will
+be automatically flushed.
+
+@item @code{TTY OUTPUT STATUS}
+@tab @code{28}
+@tab 8-bit
+@tab read
+@tab Zero if the @code{TTY OUTPUT FIFO} is empty, nonzero otherwise.
+
+@item @code{COUNDOWN}
+@tab @code{32}
+@tab 32-bit BE
+@tab read/write
+@tab The countdown registers provide a non-repeating timed interrupt source.
+Writing zero to this register clears the countdown timer.  Writing a non-zero
+32-bit big-endian value to this register sets the countdown timer to expire in
+@var{value} ticks (ticks is target dependant).  Reading the countdown register
+returns the last value written.
+
+@item @code{COUNTDOWN VALUE}
+@tab @code{36}
+@tab 32-bit BE
+@tab read
+@tab Reading this 32-bit big-endian register returns the number of ticks
+remaining until the countdown timer expires.
+
+@item @code{TIMER}
+@tab @code{40}
+@tab 32-bit BE
+@tab read/write
+@tab The timer registers provide a periodic timed interrupt source.  Writing
+zero to this register clears the periodic timer.  Writing a 32-bit non-zero
+value to this register sets the periodic timer to triger every @var{value} ticks
+(ticks is target dependant).  Reading the timer register returns the last value
+written.
+
+@item @code{TIMER VALUE}
+@tab @code{44}
+@tab 32-bit BE
+@tab read
+@tab Reading this 32-bit big-endian register returns the number of ticks until
+the next periodic interrupt.
+@end multitable
+
+@itemize @bullet
+@item @code{0}: reset register (write, 8bit)
+@end itemize
+
+@subsubsection Properties
+
+@table @code
+@item @b{(required)} reg = <address> <size>
+Specify the address (within the parent bus) that this device is to be located.
+
+@item poll? = <boolean>
+If present and true, indicates that the device should poll its input.
+@end table
+
+@subsubsection Ports
+@itemize @bullet
+@item @code{int@var{N}} (output):
+Driven as a result of a write to the interrupt-port / interrupt-level register
+pair.  @var{N} is valid from @code{0} through @var{number of simulated
+processors}.
+
+@item @code{countdown} (output):
+Driven whenever the countdown counter reaches zero.
+
+@item @code{timer} (output):
+Driven whenever the timer counter reaches zero.
+@end itemize
+
+@subsubsection Examples
+@c INTERRUPT register write:
+@c Eg: A two byte write to address 8 of 0x0102
+@c   (big-endian) will result in processor 2's external interrupt pin
+@c   being asserted.
+
+@subsubsection Bugs
+At present the common simulator framework does not support input polling.
+
+@node dv-sockser
+@subsection sockser
+A pseudo device model for connecting data streams to network sockets.
+
+@node Architecture Specifics
+@chapter Architecture Specifics
+The GNU simulator has support for many different ISA's and models.
+
+@lowersections
+@include arch-aarch64.texi
+@raisesections
+@lowersections
+@include arch-arm.texi
+@raisesections
+@lowersections
+@include arch-avr.texi
+@raisesections
+@lowersections
+@include arch-bfin.texi
+@raisesections
+@lowersections
+@include arch-bpf.texi
+@raisesections
+@lowersections
+@include arch-cr16.texi
+@raisesections
+@lowersections
+@include arch-cris.texi
+@raisesections
+@lowersections
+@include arch-d10v.texi
+@raisesections
+@lowersections
+@include arch-frv.texi
+@raisesections
+@lowersections
+@include arch-ft32.texi
+@raisesections
+@lowersections
+@include arch-h8300.texi
+@raisesections
+@lowersections
+@include arch-iq2000.texi
+@raisesections
+@lowersections
+@include arch-lm32.texi
+@raisesections
+@lowersections
+@include arch-m32c.texi
+@raisesections
+@lowersections
+@include arch-m32r.texi
+@raisesections
+@lowersections
+@include arch-m68hc11.texi
+@raisesections
+@lowersections
+@include arch-mcore.texi
+@raisesections
+@lowersections
+@include arch-microblaze.texi
+@raisesections
+@lowersections
+@include arch-mips.texi
+@raisesections
+@lowersections
+@include arch-mn10300.texi
+@raisesections
+@lowersections
+@include arch-moxie.texi
+@raisesections
+@lowersections
+@include arch-msp430.texi
+@raisesections
+@lowersections
+@include arch-or1k.texi
+@raisesections
+@lowersections
+@include arch-ppc.texi
+@raisesections
+@lowersections
+@include arch-pru.texi
+@raisesections
+@lowersections
+@include arch-riscv.texi
+@raisesections
+@lowersections
+@include arch-rl78.texi
+@raisesections
+@lowersections
+@include arch-rx.texi
+@raisesections
+@lowersections
+@include arch-sh.texi
+@raisesections
+@lowersections
+@include arch-erc32.texi
+@raisesections
+@lowersections
+@include arch-v850.texi
+@raisesections
+
+@node Integration
+@chapter Integration
+Projects might want to integrate simulation directly without relying on the
+external @command{run} program.  The GNU simulator provides a libsim.a library
+for precisely this with the API defined in @file{sim/sim.h}.
+
+Multiple simulator instances may be instantiated at a time and operate
+independently.  Although not all backends support this correct and still rely
+on global state.  They are considered buggy and will be fixed one day.
+
+@node Integration API
+@section API
+The @file{sim/sim.h} header defines the entry points to the simulator library.
+
+The overall life cycle of a simulator looks something like:
+[sim_open -> sim_create_inferior -> sim_load] ->
+[sim_resume]
+[sim_close]
+
+@node Integration Core API
+@subsection Core APIs
+
+@node SIM_DESC
+@subsubsection SIM_DESC
+Each simulator instance is represented by a @code{SIM_DESC}, often abbreviated
+@code{sd}, which is the simulator descriptor.  It is an opaque handle to pass
+to the simulator APIs akin to a file descriptor.
+
+@node sim_open
+@subsubsection sim_open
+
+@node sim_create_inferior
+@subsubsection sim_create_inferior
+
+@node sim_load
+@subsubsection sim_load
+
+@node sim_resume
+@subsubsection sim_resume
+
+@node sim_close
+@subsubsection sim_close
+
+@node sim_stop
+@subsubsection sim_stop
+
+@node sim_stop_reason
+@subsubsection sim_stop_reason
+
+
+@node Integration Memory API
+@subsection Memory APIs
+
+@node sim_read
+@subsubsection sim_read
+
+@node sim_write
+@subsubsection sim_write
+
+@node sim_fetch_register
+@subsubsection sim_fetch_register
+
+@node sim_store_register
+@subsubsection sim_store_register
+
+
+@node Integration Supplemental API
+@subsection Supplemental APIs
+These APIs are not needed by most projects.  They provide functionality for
+specific use cases.
+
+@node sim_complete_command
+@subsubsection sim_complete_command
+
+
+@node sim_do_command
+@subsubsection sim_do_command
+
+@node sim_info
+@subsubsection sim_info
+
+@node sim_memory_map
+@subsubsection sim_memory_map
+
+@node Integration Callbacks
+@section Callbacks
+TODO
+- syscalls
+- stat structs
+- errno maps
+- signal maps
+- open maps
+- etc...
+
+@node Reporting Bugs
+@chapter Reporting Bugs
+
+Your bug reports play an essential role in making simulations reliable.
+
+Reporting a bug may help you by bringing a solution to your problem, or it may
+not.  But in any case the principal function of a bug report is to help the
+entire community by making the next version work better.  Bug reports are your
+contribution to the maintenance of the simulator.
+
+@node Bug Criteria
+@section Have You Found a Bug?
+@cindex bug criteria
+
+If you are not sure whether you have found a bug, here are some guidelines:
+
+@itemize @bullet
+@cindex fatal signal
+@cindex simulator crash
+@cindex crash of simulator
+@item
+If the simulator gets a fatal signal, for any input whatever, that is a bug.
+Reliable simulators never crash.
+
+@cindex error on valid input
+@item
+If @command{as} produces an error message for valid input, that is a bug.
+
+@cindex invalid input
+@item
+If @command{as} does not produce an error message for invalid input, that
+is a bug.  However, you should note that your idea of ``invalid input'' might
+be our idea of ``an extension'' or ``support for traditional practice''.
+
+@item
+If you are an experienced user of simulators, your suggestions for improvement
+of @command{as} are welcome in any case.
+@end itemize
+
+@node Bug Reporting
+@section How to Report Bugs
+@cindex bug reports
+@cindex simulator bugs, reporting
+
+A number of companies and individuals offer support for @sc{gnu} products.  If
+you obtained @command{as} from a support organization, we recommend you
+contact that organization first.
+
+You can find contact information for many support companies and
+individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
+distribution.
+
+@ifset BUGURL
+In any event, we also recommend that you send bug reports for @command{as}
+to @value{BUGURL}.
+@end ifset
+
+The fundamental principle of reporting bugs usefully is this:
+@strong{report all the facts}.  If you are not sure whether to state a
+fact or leave it out, state it!
+
+Often people omit facts because they think they know what causes the problem
+and assume that some details do not matter.  Thus, you might assume that the
+name of a symbol you use in an example does not matter.  Well, probably it does
+not, but one cannot be sure.  Perhaps the bug is a stray memory reference which
+happens to fetch from the location where that name is stored in memory;
+perhaps, if the name were different, the contents of that location would fool
+the simulator into doing the right thing despite the bug.  Play it safe and
+give a specific, complete example.  That is the easiest thing for you to do,
+and the most helpful.
+
+Keep in mind that the purpose of a bug report is to enable us to fix the bug if
+it is new to us.  Therefore, always write your bug reports on the assumption
+that the bug has not been reported previously.
+
+Sometimes people give a few sketchy facts and ask, ``Does this ring a
+bell?''  This cannot help us fix a bug, so it is basically useless.  We
+respond by asking for enough details to enable us to investigate.
+You might as well expedite matters by sending them to begin with.
+
+To enable us to fix the bug, you should include all these things:
+
+@itemize @bullet
+@item
+The version of @command{as}.  @command{as} announces it if you start
+it with the @samp{--version} argument.
+
+Without this, we will not know whether there is any point in looking for
+the bug in the current version of @command{as}.
+
+@item
+Any patches you may have applied to the @command{as} source.
+
+@item
+The type of machine you are using, and the operating system name and
+version number.
+
+@item
+What compiler (and its version) was used to compile @command{as}---e.g.
+``@code{gcc-2.7}''.
+
+@item
+The command arguments you gave the simulator to assemble your example and
+observe the bug.  To guarantee you will not omit something important, list them
+all.  A copy of the Makefile (or the output from make) is sufficient.
+
+If we were to try to guess the arguments, we would probably guess wrong
+and then we might not encounter the bug.
+
+@item
+A complete input file that will reproduce the bug.  If the bug is observed when
+the simulator is invoked via a compiler, send the simulator source, not the
+high level language source.  Most compilers will produce the simulator source
+when run with the @samp{-S} option.  If you are using @code{GCC}, use
+the options @samp{-v --save-temps}; this will save the simulator source in a
+file with an extension of @file{.s}, and also show you exactly how
+@command{as} is being run.
+
+@item
+A description of what behavior you observe that you believe is
+incorrect.  For example, ``It gets a fatal signal.''
+
+Of course, if the bug is that @command{as} gets a fatal signal, then we
+will certainly notice it.  But if the bug is incorrect output, we might not
+notice unless it is glaringly wrong.  You might as well not give us a chance to
+make a mistake.
+
+Even if the problem you experience is a fatal signal, you should still say so
+explicitly.  Suppose something strange is going on, such as, your copy of
+@command{as} is out of sync, or you have encountered a bug in the C
+library on your system.  (This has happened!)  Your copy might crash and ours
+would not.  If you told us to expect a crash, then when ours fails to crash, we
+would know that the bug was not happening for us.  If you had not told us to
+expect a crash, then we would not be able to draw any conclusion from our
+observations.
+
+@item
+If you wish to suggest changes to the @command{as} source, send us context
+diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p}
+option.  Always send diffs from the old file to the new file.  If you even
+discuss something in the @command{as} source, refer to it by context, not
+by line number.
+
+The line numbers in our development sources will not match those in your
+sources.  Your line numbers would convey no useful information to us.
+@end itemize
+
+Here are some things that are not necessary:
+
+@itemize @bullet
+@item
+A description of the envelope of the bug.
+
+Often people who encounter a bug spend a lot of time investigating
+which changes to the input file will make the bug go away and which
+changes will not affect it.
+
+This is often time consuming and not very useful, because the way we
+will find the bug is by running a single example under the debugger
+with breakpoints, not by pure deduction from a series of examples.
+We recommend that you save your time for something else.
+
+Of course, if you can find a simpler example to report @emph{instead}
+of the original one, that is a convenience for us.  Errors in the
+output will be easier to spot, running under the debugger will take
+less time, and so on.
+
+However, simplification is not vital; if you do not want to do this,
+report the bug anyway and send us the entire test case you used.
+
+@item
+A patch for the bug.
+
+A patch for the bug does help us if it is a good one.  But do not omit
+the necessary information, such as the test case, on the assumption that
+a patch is all we need.  We might see problems with your patch and decide
+to fix the problem another way, or we might not understand it at all.
+
+Sometimes with a program as complicated as @command{as} it is very hard to
+construct an example that will make the program follow a certain path through
+the code.  If you do not send us the example, we will not be able to construct
+one, so we will not be able to verify that the bug is fixed.
+
+And if we cannot understand what bug you are trying to fix, or why your
+patch should be an improvement, we will not install it.  A test case will
+help us to understand.
+
+@item
+A guess about what the bug is or what it depends on.
+
+Such guesses are usually wrong.  Even we cannot guess right about such
+things without first using the debugger to find the facts.
+@end itemize
+
+@node Acknowledgements
+@unnumbered Acknowledgements
+
+If you have contributed and your name isn't listed here, it is not meant as a
+slight.  We just don't know about it.  File a bug for us, and we'll correct the
+situation.
+
+@c List everyone (sorted).
+@author Ben Elliston
+@author Frank Ch. Eigler
+@author Andrew Burgess
+@author Mike Frysinger
+
+@c TODO: Fill in maintainers & a bit of history.
+
+@node Installing
+@appendix Installing
+@cindex installation
+
+@node Requirements
+@section Requirements for building
+@cindex building, requirements for
+
+Building requires various tools and packages to be available.
+Other packages will be used only if they are found.
+
+@heading Necessary Tools/Packages for Building
+@table @asis
+@item C11 compiler
+The GNU Simulator is written in C11.  It should be buildable with any
+recent C11 compiler, e.g.@: GCC.
+
+@end table
+
+@heading Optional Tools/Packages for Building
+@table @asis
+@item SDL
+@anchor{SDL}
+The Simple DirectMedia Layer (SDL) may be utilized if available.  This library
+may be included with your operating system distribution; if it is not, you can
+get the latest version from @url{https://www.libsdl.org/}.
+The @file{configure} script will search for this library in several standard
+locations; if it is installed in an unusual path, you can use the
+@option{SDL_CFLAGS} and @option{SDL_LIBS} options to specify the compiler &
+linker settings.
+
+The library will not be linked directly.  Instead, it will be loaded dynamically
+(via @code{dlopen}) at runtime.  This allows building with support for SDL, but
+not actually requiring it if the features aren't used.
+
+SDL 1 & SDL 2 are supported, but the version is fixed at build time.
+
+SDL is used for:
+
+@itemize @bullet
+@item
+Emulating framebuffer graphics
+(@pxref{bfin_ppi} & @pxref{bfin_eppi})
+@end itemize
+@end table
+
+@node Running Configure
+@section Invoking the @file{configure} Script
+@cindex configuring
+Releases include a @file{configure} script that automates the process of
+preparing the simulator for installation; you can then use @code{make} to build
+the @code{run} program.
+@iftex
+@c irrelevant in info file; it's as current as the code it lives with.
+@footnote{If you have a more recent simulator version than @value{VERSION},
+look at the @file{README} file in the sources; we may have improved the
+installation procedures since publishing this manual.}
+@end iftex
+
+The distribution includes all the source code you need in a single directory,
+whose name is usually composed by appending the version number to @samp{gdb}.
+That directory contains:
+
+@table @code
+@item gdb-@value{VERSION}/configure @r{(and supporting files)}
+script for configuring everything
+
+@item gdb-@value{VERSION}/sim/
+the source specific to the simulator itself
+
+@item gdb-@value{VERSION}/gdb/
+the source specific to @sc{gdb} itself
+
+@item gdb-@value{VERSION}/bfd/
+source for the Binary File Descriptor library
+
+@item gdb-@value{VERSION}/include/
+@sc{gnu} include files
+
+@item gdb-@value{VERSION}/libiberty/
+source for the @samp{-liberty} free software library
+
+@item gdb-@value{VERSION}/opcodes/
+source for the library of opcode tables and disassemblers
+
+@item gdb-@value{VERSION}/readline/
+source for the @sc{gnu} command-line interface
+@end table
+
+There may be other subdirectories as well.
+
+The simplest way to configure and build is to run @file{configure}
+from the @file{gdb-@var{version-number}} source directory, which in
+this example is the @file{gdb-@value{VERSION}} directory.
+
+First switch to the @file{gdb-@var{version-number}} source directory
+if you are not already in it; then run @file{configure}.  Pass the
+identifier for the platform on which the simulator will run as an
+argument.
+
+For example:
+
+@smallexample
+cd gdb-@value{VERSION}
+./configure
+make
+@end smallexample
+
+Running @samp{configure} and then running @code{make} builds the
+included supporting libraries, then @code{gdb} itself.  The configured
+source files, and the binaries, are left in the corresponding source
+directories.
+
+@need 750
+@file{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
+system does not recognize this automatically when you run a different
+shell, you may need to run @code{sh} on it explicitly:
+
+@smallexample
+sh configure
+@end smallexample
+
+You should run the @file{configure} script from the top directory in the
+source tree, the @file{gdb-@var{version-number}} directory.  If you run
+@file{configure} from one of the subdirectories, you will configure only
+that subdirectory.  That is usually not what you want.  In particular,
+if you run the first @file{configure} from the @file{gdb} subdirectory
+of the @file{gdb-@var{version-number}} directory, you will omit the
+configuration of @file{bfd}, @file{readline}, and other sibling
+directories of the @file{gdb} subdirectory.  This leads to build errors
+about missing include files such as @file{bfd/bfd.h}.
+
+You can install @code{run} anywhere.  The best way to do this
+is to pass the @code{--prefix} option to @code{configure}, and then
+install it with @code{make install}.
+
+@node Separate Objdir
+@section Compiling in Another Directory
+
+If you want to run simulator versions for several host or target machines,
+you need a different @code{run} compiled for each combination of
+host and target.  @file{configure} is designed to make this easy by
+allowing you to generate each configuration in a separate subdirectory,
+rather than in the source directory.  If your @code{make} program
+handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running
+@code{make} in each of these directories builds the @code{gdb}
+program specified there.
+
+To build @code{gdb} in a separate directory, run @file{configure}
+with the @samp{--srcdir} option to specify where to find the source.
+(You also need to specify a path to find @file{configure}
+itself from your working directory.  If the path to @file{configure}
+would be the same as the argument to @samp{--srcdir}, you can leave out
+the @samp{--srcdir} option; it is assumed.)
+
+For example, with version @value{VERSION}, you can build in a separate directory
+for a Sun 4 like this:
+
+@smallexample
+@group
+cd gdb-@value{VERSION}
+mkdir ../gdb-sun4
+cd ../gdb-sun4
+../gdb-@value{VERSION}/configure
+make
+@end group
+@end smallexample
+
+When @file{configure} builds a configuration using a remote source
+directory, it creates a tree for the binaries with the same structure
+(and using the same names) as the tree under the source directory.  In
+the example, you'd find the Sun 4 library @file{libiberty.a} in the
+directory @file{gdb-sun4/libiberty}, and @code{run} itself in
+@file{gdb-sun4/sim/@var{arch}/g}.
+
+Make sure that your path to the @file{configure} script has just one instance
+of @file{gdb} in it.  If your path to @file{configure} looks like
+@file{../gdb-@value{VERSION}/sim/configure}, you are configuring only one
+subdirectory, not the whole package.  This leads to build errors about missing
+include files such as @file{bfd/bfd.h}.
+
+One popular reason to build several configurations in separate directories is to
+configure for cross-compiling (where the simulator runs on one machine---the
+@dfn{host}---while debugging programs that are compiled for another
+machine---the @dfn{target}).  You specify a cross-debugging target by giving the
+@samp{--target=@var{target}} option to @file{configure}.
+
+When you run @code{make} to build a program or library, you must run it in a
+configured directory---whatever directory you were in when you called
+@file{configure} (or one of its subdirectories).
+
+The @code{Makefile} that @file{configure} generates in each source directory
+also runs recursively.  If you type @code{make} in a source directory such as
+@file{gdb-@value{VERSION}} (or in a separate configured directory configured
+with @samp{--srcdir=@var{dirname}/gdb-@value{VERSION}}), you will build all
+the required libraries, and then build the simulator.
+
+When you have multiple hosts or targets configured in separate directories, you
+can run @code{make} on them in parallel (for example, if they are NFS-mounted on
+each of the hosts); they will not interfere with each other.
+
+@node Config Names
+@section Specifying Names for Hosts and Targets
+
+The specifications used for hosts and targets in the @file{configure} script are
+based on a three-part naming scheme, but some short predefined aliases are also
+supported.  The full naming scheme encodes three pieces of information in the
+following pattern:
+
+@smallexample
+@var{architecture}-@var{vendor}-@var{os}
+@end smallexample
+
+For example, you can use the alias @code{sun4} as a @var{host} argument, or as
+the value for @var{target} in a @code{--target=@var{target}} option.  The
+equivalent full name is @samp{sparc-sun-sunos4}.
+
+The @file{configure} script does not provide any query facility to list all
+supported host and target names or aliases.  @file{configure} calls the Bourne
+shell script @code{config.sub} to map abbreviations to full names; you can read
+the script, if you wish, or you can use it to test your guesses on
+abbreviations---for example:
+
+@smallexample
+% sh config.sub i386-linux
+i386-pc-linux-gnu
+% sh config.sub alpha-linux
+alpha-unknown-linux-gnu
+% sh config.sub hp9k700
+hppa1.1-hp-hpux
+% sh config.sub sun4
+sparc-sun-sunos4.1.1
+% sh config.sub sun3
+m68k-sun-sunos4.1.1
+% sh config.sub i986v
+Invalid configuration `i986v': machine `i986v' not recognized
+@end smallexample
+
+@noindent
+@code{config.sub} is also distributed in the source directory.
+
+@node Configure Options
+@section @file{configure} Options
+
+Here is a summary of the @file{configure} options and arguments that are most
+often useful when building.  @file{configure} also has several other options
+not listed here.  @xref{Running configure Scripts,,,autoconf}, for a full
+explanation of @file{configure}.
+
+@smallexample
+configure @r{[}--help@r{]}
+          @r{[}--prefix=@var{dir}@r{]}
+          @r{[}--exec-prefix=@var{dir}@r{]}
+          @r{[}--srcdir=@var{dirname}@r{]}
+          @r{[}--target=@var{target}@r{]}
+@end smallexample
+
+@noindent
+You may introduce options with a single @samp{-} rather than
+@samp{--} if you prefer; but you may abbreviate option names if you use
+@samp{--}.
+
+@node Configure Common Options
+@subsection Common Options
+These are the generic configure options that apply to all projects and are
+frequently useful to people building from source.
+
+@table @option
+@item --help
+Display a quick summary of how to invoke @file{configure}.
+
+@item --prefix=@var{dir}
+Configure the source to install programs and files under directory
+@file{@var{dir}}.
+
+@item --exec-prefix=@var{dir}
+Configure the source to install programs under directory
+@file{@var{dir}}.
+
+@c avoid splitting the warning from the explanation:
+@need 2000
+@item --srcdir=@var{dirname}
+Use this option to make configurations in directories separate from the source
+directories.  Among other things, you can use this to build (or maintain)
+several configurations simultaneously, in separate directories.
+@file{configure} writes configuration-specific files in the current directory,
+but arranges for them to use the source in the directory @var{dirname}.
+@file{configure} creates directories under the working directory in parallel to
+the source directories below @var{dirname}.
+
+@item --target=@var{target}
+Configure for cross-debugging programs running on the specified @var{target}.
+Without this option, the simulator is configured to debug programs that run on
+the same machine (@var{host}) as the simulator itself.
+
+There is no convenient way to generate a list of all available targets.  Also
+see the @code{--enable-targets} option, below.
+
+@item --enable-targets=@r{[}@var{target}@r{]}@dots{}
+@itemx --enable-targets=all
+Configure for cross-debugging programs running on the specified list of targets.
+The special value @samp{all} configures for debugging programs running on any
+target it supports.
+
+@item --with-relocated-sources=@var{dir}
+Sets up the default source path substitution rule so that directory names
+recorded in debug information will be automatically adjusted for any directory
+under @var{dir}.  @var{dir} should be a subdirectory of the configured prefix,
+the one mentioned in the @code{--prefix} or @code{--exec-prefix} options to
+configure.  This option is useful if installing to a different place after it
+is built.
+
+@item --enable-64-bit-bfd
+Enable 64-bit support in BFD on 32-bit hosts.
+
+@item --with-sysroot=@var{dir}
+Use @var{dir} as the default system root directory for libraries whose file
+names begin with @file{/lib}' or @file{/usr/lib'}.  (The value of @var{dir} can
+be modified at run time by using the @command{--sysroot} option.)  If @var{dir}
+is under the configured prefix (set with @code{--prefix} or @code{--exec-prefix
+options}, the default system root will be automatically adjusted if and when
+everything is moved to a different location.
+
+@end table
+
+@node Configure Simulator Options
+@subsection Simulator Options
+These are the GNU Simulator specific options.  None of them are required to get
+a working build---many options can already be controlled at runtime instead.
+These are provided to help fine tune overall execution in case you need to shave
+off a bit of execution time.
+
+@table @option
+@item --enable-sim
+Enable or disable the GNU Simulator specifically.
+
+@item --enable-sim-alignment=@var{align}
+Force the @ref{Memory Alignment} behavior.  This will always override the
+runtime selections.
+
+@item --enable-sim-assert
+Whether to enable extra internal asserts that keep track of general health of
+simulator runtime and its data structures.  These can be helpful when tracking
+down bugs, but are not required for correct functioning, and can provide a minor
+speed boost when they're disabled.
+
+@item --enable-sim-endian=@var{endian}
+Force the target byte endian orientation.  This will always override the runtime
+selections.
+
+The default depends on the specific architecture backend (which tends to match
+the hardware, and @ref{Config Names}), and may be overridden by
+@option{--endian}.
+
+Possible @var{endian} settings:
+@itemize @bullet
+@item @samp{big}: Big byte endian orientation.
+@item @samp{little}: Little byte endian orientation.
+@end itemize
+
+@item --enable-sim-environment=@var{environment}
+Force one of the @ref{Runtime Environments}.  This will always override the
+runtime selections.
+
+@item --enable-sim-hardware
+Whether to enable hardware/device simulation.  This is normally enabled as it
+doesn't incur runtime overhead unless devices are actually used.
+
+@item --enable-sim-inline=@var{inlines}
+A comma separated list of which sim modules should be inlined.  By default, no
+modules are inlined.
+
+This often will greatly increase the code size of the program, but may increase
+the speed at the same time.
+
+Specifying @samp{yes} will inline all modules.
+
+@item --enable-sim-profile=opts
+A comma separated list of which profile subsystems to support.  By default, all
+subsystems are enabled except for debug.
+
+@xref{Profiling Options} for available subsystem names.
+
+@item --enable-sim-reserved-bits
+Specify whether to check reserved bits in instruction.
+
+This option should not be specified by most users.
+
+@item --enable-sim-scache=@var{size}
+@i{Only for backends using @value{cgen}.}
+
+The size (in bytes) of the semantic cache.  The default is 16384 (16KiB).
+
+@item --enable-sim-stdio
+Whether input/output is routed through callbacks to the C library stdio layers
+(the default), or directly to the underlying file descriptors.  Most people will
+never change this.
+
+@item --enable-sim-trace=@var{opts}
+A comma separated list of which trace subsystems to support.  The default is all
+subsystems except for debug (see @option{--enable-sim-debug} for more info).
+
+@xref{Tracing Options} for available subsystem names.
+
+@item --enable-sim-frv-trapdump
+@i{For the @ref{FRV} architecture only.}
+
+Make unknown traps dump CPU registers for easier debugging.
+
+@item --disable-sim-rx-cycle-accurate
+@i{For the @ref{RX} architecture only.}
+
+Disable cycle accurate simulation which speeds up overall runtime.  If you
+don't need cycle accuracy (e.g. for performance tuning), then you should turn
+this option off.
+
+@end table
+
+@node Configure Developer Options
+@subsection Developer Options
+These are largely meant for developers of the GNU Simulator itself.
+
+@table @option
+@item --enable-build-warnings
+When building the sources, ask the compiler to warn about any code which looks
+even vaguely suspicious.  It passes many different warning flags, depending on
+the exact version of the compiler you are using.
+
+This option applies to all projects in the source tree, not just the simulator.
+
+@item --enable-sim-build-warnings
+When building the simulator sources, ask the compiler to warn about any code
+which looks even vaguely suspicious.  It passes many different warning flags,
+depending on the exact version of the compiler you are using.
+
+This option applies only to the simulator.  It allows building all the other
+projects with one set of warnings, but the simulator with a different set.
+
+@item --enable-werror
+Treat compiler warnings as errors.  It adds the @code{-Werror} flag
+to the compiler, which will fail the compilation if the compiler
+outputs any warning messages.
+
+@item --enable-example-sims
+Enable example simulator backends.  If your target does not have an architecture
+backend, these will provide simple toy CPUs for reference.  Useful when porting
+to a new architecture.
+
+@item --enable-maintainer-mode
+Enable build rules and dependencies only useful to simulator developers.  For
+example, turn on automatic regeneration of build scripts and source files.
+These are often expensive operations and require additional tools.
+
+@item --enable-cgen-maint=@var{dir}
+Enable build rules and dependencies, specific to @value{cgen}, only useful to
+simulator developers.  If you're working on an architecture backend that uses
+@value{cgen}, then this is a necessity.
+
+Normally @value{cgen} will be checked out in the top level of the source tree
+(alongside the @file{sim/} directory).  The optional @var{dir} setting allows
+specifying any path to the @value{cgen} source tree.
+
+@item --enable-sim-debug=opts
+A comma separated list of which debug subsystems to support.  By default, none
+are enabled.  This setting first requires that @code{debug} be enabled with the
+@option{--enable-sim-trace} option.
+
+@xref{Debugging Options} for available subsystem names.
+@end table
+
+@node Newlib ABI
+@appendix Newlib ABI
+These are the ABI constants & structures that @value{newlib} uses.  They are
+autogenerated from the @value{newlib} source tree.
+
+@node Newlib ABI Errno
+@section Errno Values
+@include abi-newlib-errno.texi
+
+@node Newlib ABI Signal Numbers
+@section Signal Numbers
+@include abi-newlib-signal.texi
+
+@node Newlib ABI Open Flags
+@section Open Flags
+@include abi-newlib-open.texi
+
+@node Newlib ABI Syscalls
+@section Syscall Numbers
+@include abi-newlib-sys.texi
+
+@node Porting
+@appendix Porting
+Porting the GNU Simulator to a new architecture can be fun!
+
+This information is maintained in the wiki.@*
+@url{https://sourceware.org/gdb/wiki/Sim/Porting}
+
+Documentation is maintained only for the latest source tree, not for releases.
+If you need to work on an old release, the source is probably your best bet.
+
+@node Internals
+@appendix Internals
+Adding new features to the GNU Simulator can be fun!
+
+This information is maintained in the wiki.@*
+@url{https://sourceware.org/gdb/wiki/Sim/Internals}
+
+Documentation is maintained only for the latest source tree, not for releases.
+If you need to work on an old release, the source is probably your best bet.
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include fdl.texi
+
+@c To avoid filename clashes between index.html and Index.html on systems with
+@c case-insentivie filesystems, we avoid the chapter name "Index".
+
+@node Concept Index
+@unnumbered Concept Index
+@printindex cp
+
+@node Syscall Index
+@unnumbered Syscall Index
+@printindex sc
+
+@node Device Model Index
+@unnumbered Device Model Index
+@printindex dv
+
+@node Public API Index
+@unnumbered Public API Index
+@printindex fn
+
+@bye
diff --git a/sim/example-synacor/README b/sim/example-synacor/README
deleted file mode 100644
index 93ffd53d5a4..00000000000
--- a/sim/example-synacor/README
+++ /dev/null
@@ -1,15 +0,0 @@
-= OVERVIEW =
-
-The Synacor Challenge is a fun programming exercise with a number of puzzles
-built into it.  You can find more details about it here:
-https://challenge.synacor.com/
-
-The first puzzle is writing an interpreter for their custom ISA.  This is a
-simulator for that custom CPU.  The CPU is quite basic: it's 16-bit with only
-8 registers and a limited set of instructions.  This means the port will never
-grow new features.  See README.arch-spec for more details.
-
-Implementing it here ends up being quite useful: it acts as a simple constrained
-"real world" example for people who want to implement a new simulator for their
-own architecture.  We demonstrate all the basic fundamentals (registers, memory,
-branches, and tracing) that all ports should have.
diff --git a/sim/example-synacor/README.arch-spec b/sim/example-synacor/README.arch-spec
deleted file mode 100644
index da2d9d00367..00000000000
--- a/sim/example-synacor/README.arch-spec
+++ /dev/null
@@ -1,73 +0,0 @@
-== architecture ==
-- three storage regions
-  - memory with 15-bit address space storing 16-bit values
-  - eight registers
-  - an unbounded stack which holds individual 16-bit values
-- all numbers are unsigned integers 0..32767 (15-bit)
-- all math is modulo 32768; 32758 + 15 => 5
-
-== binary format ==
-- each number is stored as a 16-bit little-endian pair (low byte, high byte)
-- numbers 0..32767 mean a literal value
-- numbers 32768..32775 instead mean registers 0..7
-- numbers 32776..65535 are invalid
-- programs are loaded into memory starting at address 0
-- address 0 is the first 16-bit value, address 1 is the second 16-bit value, etc
-
-== execution ==
-- After an operation is executed, the next instruction to read is immediately after the last argument of the current operation.
-  If a jump was performed, the next operation is instead the exact destination of the jump.
-- Encountering a register as an operation argument should be taken as reading from the register or setting into the register as appropriate.
-
-== hints ==
-- Start with operations 0, 19, and 21.
-- Here's a code for the challenge website: jTTockJlJiOC
-- The program "9,32768,32769,4,19,32768" occupies six memory addresses and should:
-  - Store into register 0 the sum of 4 and the value contained in register 1.
-  - Output to the terminal the character with the ascii code contained in register 0.
-
-== opcode listing ==
-halt: 0
-  stop execution and terminate the program
-set: 1 a b
-  set register <a> to the value of <b>
-push: 2 a
-  push <a> onto the stack
-pop: 3 a
-  remove the top element from the stack and write it into <a>; empty stack = error
-eq: 4 a b c
-  set <a> to 1 if <b> is equal to <c>; set it to 0 otherwise
-gt: 5 a b c
-  set <a> to 1 if <b> is greater than <c>; set it to 0 otherwise
-jmp: 6 a
-  jump to <a>
-jt: 7 a b
-  if <a> is nonzero, jump to <b>
-jf: 8 a b
-  if <a> is zero, jump to <b>
-add: 9 a b c
-  assign into <a> the sum of <b> and <c> (modulo 32768)
-mult: 10 a b c
-  store into <a> the product of <b> and <c> (modulo 32768)
-mod: 11 a b c
-  store into <a> the remainder of <b> divided by <c>
-and: 12 a b c
-  stores into <a> the bitwise and of <b> and <c>
-or: 13 a b c
-  stores into <a> the bitwise or of <b> and <c>
-not: 14 a b
-  stores 15-bit bitwise inverse of <b> in <a>
-rmem: 15 a b
-  read memory at address <b> and write it to <a>
-wmem: 16 a b
-  write the value from <b> into memory at address <a>
-call: 17 a
-  write the address of the next instruction to the stack and jump to <a>
-ret: 18
-  remove the top element from the stack and jump to it; empty stack = halt
-out: 19 a
-  write the character represented by ascii code <a> to the terminal
-in: 20 a
-  read a character from the terminal and write its ascii code to <a>; it can be assumed that once input starts, it will continue until a newline is encountered; this means that you can safely read whole lines from the keyboard and trust that they will be fully read
-noop: 21
-  no operation
diff --git a/sim/frv/README b/sim/frv/README
deleted file mode 100644
index a88ea1922c0..00000000000
--- a/sim/frv/README
+++ /dev/null
@@ -1,10 +0,0 @@
-This is the frv simulator directory.
-
-It is still work-in-progress.  The current sources are
-well tested and lots of features are in.
-
-There are lots of machine generated files in the source directory!
-They are only generated if you configure with --enable-cgen-maint,
-similar in behaviour to Makefile.in, configure under automake/autoconf.
-
-For details on the generator, see ../../cgen.
diff --git a/sim/m32r/README b/sim/m32r/README
deleted file mode 100644
index bbc3f509fba..00000000000
--- a/sim/m32r/README
+++ /dev/null
@@ -1,14 +0,0 @@
-This is the m32r simulator directory.
-
-It is still work-in-progress.  The current sources are reasonably
-well tested and lots of features are in.  However, there's lots
-more yet to come.
-
-There are lots of machine generated files in the source directory!
-They are only generated if you configure with --enable-cgen-maint,
-similar in behaviour to Makefile.in, configure under automake/autoconf.
-
-For details on the generator, see ../../cgen.
-
-devo/cgen isn't part of the comp-tools module yet.
-You'll need to check it out manually (also akin to automake/autoconf).