From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 7850) id 9539939484B6; Tue, 15 Nov 2022 23:58:12 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 9539939484B6 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1668556692; bh=nY3PQgdih9nUZF6tg6V1h9Fe7gDMhNCqHfKG21xmC+I=; h=From:To:Subject:Date:From; b=iVsk9YGu6X84jNKkzo5g0SO94Jgp1/NqvwxEUwWMCHTzraFyfNZeCq+3FCfqczoMb bmBjJoYG1A9Du/3Sw23DZlVhlTvKrNgufTwYm+t+9pxQpAzeMXPMZfon6oEb8HadDT Jd1H5eNlRuH9Ik1J1gUKP2OPk6B7AxbCENdE1T4Q= Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable From: Indu Bhagat To: bfd-cvs@sourceware.org, gdb-cvs@sourceware.org Subject: [binutils-gdb] doc: add SFrame spec file X-Act-Checkin: binutils-gdb X-Git-Author: Indu Bhagat X-Git-Refname: refs/heads/master X-Git-Oldrev: b2cb03d5c3bb0a61d07d00c497a4256f83a894fd X-Git-Newrev: c1c57352f56b802393453cfa76326922fd8da2f9 Message-Id: <20221115235812.9539939484B6@sourceware.org> Date: Tue, 15 Nov 2022 23:58:12 +0000 (GMT) List-Id: https://sourceware.org/git/gitweb.cgi?p=3Dbinutils-gdb.git;h=3Dc1c57352f56b= 802393453cfa76326922fd8da2f9 commit c1c57352f56b802393453cfa76326922fd8da2f9 Author: Indu Bhagat Date: Tue Nov 15 15:07:28 2022 -0800 doc: add SFrame spec file =20 ChangeLog: =20 * libsframe/Makefile.am: Add info-in-builddir to AUTOMAKE_OPTIONS. Include doc/local.mk. * libsframe/Makefile.in: Regenerated. * libsframe/configure: Likewise. * libsframe/configure.ac: Check for makeinfo and set BUILD_INFO. * libsframe/doc/local.mk: New file. * libsframe/doc/sframe-spec.texi: Likewise. Diff: --- libsframe/Makefile.am | 9 +- libsframe/Makefile.in | 418 ++++++++++++++++++++++++---- libsframe/configure | 81 +++++- libsframe/configure.ac | 21 ++ libsframe/doc/local.mk | 40 +++ libsframe/doc/sframe-spec.texi | 619 +++++++++++++++++++++++++++++++++++++= ++++ 6 files changed, 1137 insertions(+), 51 deletions(-) diff --git a/libsframe/Makefile.am b/libsframe/Makefile.am index d8198a166c5..a976a7e6090 100644 --- a/libsframe/Makefile.am +++ b/libsframe/Makefile.am @@ -18,7 +18,12 @@ # ACLOCAL_AMFLAGS =3D -I .. -I ../config -I ../bfd =20 -AUTOMAKE_OPTIONS =3D dejagnu foreign no-texinfo.tex subdir-objects +AUTOMAKE_OPTIONS =3D dejagnu foreign no-texinfo.tex info-in-builddir subdi= r-objects + +# Variables that we might accumulate conditionally or in subdirs. +info_TEXINFOS =3D +DISTCLEANFILES =3D +MAINTAINERCLEANFILES =3D =20 INCDIR =3D $(srcdir)/../include # include libctf for swap.h @@ -36,4 +41,6 @@ endif libsframe_la_SOURCES =3D sframe.c sframe-dump.c sframe-error.c libsframe_la_CPPFLAGS =3D $(AM_CPPFLAGS) =20 +include doc/local.mk + include testsuite/local.mk diff --git a/libsframe/Makefile.in b/libsframe/Makefile.in index 340bfe88060..8622d8bb688 100644 --- a/libsframe/Makefile.in +++ b/libsframe/Makefile.in @@ -14,6 +14,24 @@ =20 @SET_MAKE@ =20 +# +# Copyright (C) 2019-2022 Free Software Foundation, Inc. +# +# This file 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 2 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; see the file COPYING. If not see +# . +# + =20 VPATH =3D @srcdir@ am__is_gnu_make =3D { \ @@ -89,8 +107,11 @@ PRE_UNINSTALL =3D : POST_UNINSTALL =3D : build_triplet =3D @build@ host_triplet =3D @host@ +@BUILD_INFO_TRUE@am__append_1 =3D doc/sframe-spec.texi +@BUILD_INFO_TRUE@am__append_2 =3D texput.log +@BUILD_INFO_TRUE@am__append_3 =3D doc/sframe-spec.info check_PROGRAMS =3D $(am__EXEEXT_1) -@HAVE_COMPAT_DEJAGNU_TRUE@am__append_1 =3D testsuite/libsframe.decode/be-f= lipping \ +@HAVE_COMPAT_DEJAGNU_TRUE@am__append_4 =3D testsuite/libsframe.decode/be-f= lipping \ @HAVE_COMPAT_DEJAGNU_TRUE@ testsuite/libsframe.decode/frecnt-1 \ @HAVE_COMPAT_DEJAGNU_TRUE@ testsuite/libsframe.decode/frecnt-2 \ @HAVE_COMPAT_DEJAGNU_TRUE@ testsuite/libsframe.encode/encode-1 @@ -145,7 +166,8 @@ am__uninstall_files_from_dir =3D { \ || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ $(am__cd) "$$dir" && rm -f $$files; }; \ } -am__installdirs =3D "$(DESTDIR)$(libdir)" "$(DESTDIR)$(includedir)" +am__installdirs =3D "$(DESTDIR)$(libdir)" "$(DESTDIR)$(infodir)" \ + "$(DESTDIR)$(includedir)" LTLIBRARIES =3D $(lib_LTLIBRARIES) $(noinst_LTLIBRARIES) libsframe_la_LIBADD =3D am_libsframe_la_OBJECTS =3D libsframe_la-sframe.lo \ @@ -226,6 +248,46 @@ DIST_SOURCES =3D $(libsframe_la_SOURCES) \ $(testsuite_libsframe_decode_frecnt_1_SOURCES) \ $(testsuite_libsframe_decode_frecnt_2_SOURCES) \ $(testsuite_libsframe_encode_encode_1_SOURCES) +AM_V_DVIPS =3D $(am__v_DVIPS_@AM_V@) +am__v_DVIPS_ =3D $(am__v_DVIPS_@AM_DEFAULT_V@) +am__v_DVIPS_0 =3D @echo " DVIPS " $@; +am__v_DVIPS_1 =3D=20 +AM_V_MAKEINFO =3D $(am__v_MAKEINFO_@AM_V@) +am__v_MAKEINFO_ =3D $(am__v_MAKEINFO_@AM_DEFAULT_V@) +am__v_MAKEINFO_0 =3D @echo " MAKEINFO" $@; +am__v_MAKEINFO_1 =3D=20 +AM_V_INFOHTML =3D $(am__v_INFOHTML_@AM_V@) +am__v_INFOHTML_ =3D $(am__v_INFOHTML_@AM_DEFAULT_V@) +am__v_INFOHTML_0 =3D @echo " INFOHTML" $@; +am__v_INFOHTML_1 =3D=20 +AM_V_TEXI2DVI =3D $(am__v_TEXI2DVI_@AM_V@) +am__v_TEXI2DVI_ =3D $(am__v_TEXI2DVI_@AM_DEFAULT_V@) +am__v_TEXI2DVI_0 =3D @echo " TEXI2DVI" $@; +am__v_TEXI2DVI_1 =3D=20 +AM_V_TEXI2PDF =3D $(am__v_TEXI2PDF_@AM_V@) +am__v_TEXI2PDF_ =3D $(am__v_TEXI2PDF_@AM_DEFAULT_V@) +am__v_TEXI2PDF_0 =3D @echo " TEXI2PDF" $@; +am__v_TEXI2PDF_1 =3D=20 +AM_V_texinfo =3D $(am__v_texinfo_@AM_V@) +am__v_texinfo_ =3D $(am__v_texinfo_@AM_DEFAULT_V@) +am__v_texinfo_0 =3D -q +am__v_texinfo_1 =3D=20 +AM_V_texidevnull =3D $(am__v_texidevnull_@AM_V@) +am__v_texidevnull_ =3D $(am__v_texidevnull_@AM_DEFAULT_V@) +am__v_texidevnull_0 =3D > /dev/null +am__v_texidevnull_1 =3D=20 +INFO_DEPS =3D doc/sframe-spec.info +am__TEXINFO_TEX_DIR =3D $(srcdir) +DVIS =3D doc/sframe-spec.dvi +PDFS =3D doc/sframe-spec.pdf +PSS =3D doc/sframe-spec.ps +HTMLS =3D doc/sframe-spec.html +TEXINFOS =3D $(am__append_1) +TEXI2DVI =3D texi2dvi +TEXI2PDF =3D $(TEXI2DVI) --pdf --batch +MAKEINFOHTML =3D $(MAKEINFO) --html +AM_MAKEINFOHTMLFLAGS =3D $(AM_MAKEINFOFLAGS) +DVIPS =3D dvips am__can_run_installinfo =3D \ case $$AM_UPDATE_INFO_DIR in \ n|no|NO) false;; \ @@ -258,6 +320,7 @@ AM_RECURSIVE_TARGETS =3D cscope DEJATOOL =3D $(PACKAGE) RUNTESTDEFAULTFLAGS =3D --tool $$tool --srcdir $$srcdir am__DIST_COMMON =3D $(srcdir)/Makefile.in $(srcdir)/config.h.in \ + $(srcdir)/doc/local.mk \ $(srcdir)/testsuite/libsframe.decode/local.mk \ $(srcdir)/testsuite/libsframe.encode/local.mk \ $(srcdir)/testsuite/local.mk $(top_srcdir)/../ar-lib \ @@ -418,7 +481,12 @@ top_srcdir =3D @top_srcdir@ # . # ACLOCAL_AMFLAGS =3D -I .. -I ../config -I ../bfd -AUTOMAKE_OPTIONS =3D dejagnu foreign no-texinfo.tex subdir-objects +AUTOMAKE_OPTIONS =3D dejagnu foreign no-texinfo.tex info-in-builddir subdi= r-objects + +# Variables that we might accumulate conditionally or in subdirs. +info_TEXINFOS =3D $(am__append_1) +DISTCLEANFILES =3D $(am__append_2) +MAINTAINERCLEANFILES =3D $(am__append_3) INCDIR =3D $(srcdir)/../include # include libctf for swap.h AM_CPPFLAGS =3D -I$(srcdir) -I$(srcdir)/../include -I$(srcdir)/../libctf @@ -429,6 +497,7 @@ AM_CFLAGS =3D @ac_libsframe_warn_cflags@ @INSTALL_LIBBFD_FALSE@noinst_LTLIBRARIES =3D libsframe.la libsframe_la_SOURCES =3D sframe.c sframe-dump.c sframe-error.c libsframe_la_CPPFLAGS =3D $(AM_CPPFLAGS) +@BUILD_INFO_TRUE@AM_MAKEINFOFLAGS =3D --no-split =20 # Setup the testing framework EXPECT =3D expect @@ -450,10 +519,10 @@ all: config.h $(MAKE) $(AM_MAKEFLAGS) all-am =20 .SUFFIXES: -.SUFFIXES: .c .lo .o .obj +.SUFFIXES: .c .dvi .lo .o .obj .ps am--refresh: Makefile @: -$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(srcd= ir)/testsuite/local.mk $(srcdir)/testsuite/libsframe.decode/local.mk $(srcd= ir)/testsuite/libsframe.encode/local.mk $(am__configure_deps) +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(srcd= ir)/doc/local.mk $(srcdir)/testsuite/local.mk $(srcdir)/testsuite/libsframe= .decode/local.mk $(srcdir)/testsuite/libsframe.encode/local.mk $(am__config= ure_deps) @for dep in $?; do \ case '$(am__configure_deps)' in \ *$$dep*) \ @@ -475,7 +544,7 @@ Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.= status echo ' cd $(top_builddir) && $(SHELL) ./config.status $@ $(am__depfil= es_maybe)'; \ cd $(top_builddir) && $(SHELL) ./config.status $@ $(am__depfiles_mayb= e);; \ esac; -$(srcdir)/testsuite/local.mk $(srcdir)/testsuite/libsframe.decode/local.mk= $(srcdir)/testsuite/libsframe.encode/local.mk $(am__empty): +$(srcdir)/doc/local.mk $(srcdir)/testsuite/local.mk $(srcdir)/testsuite/li= bsframe.decode/local.mk $(srcdir)/testsuite/libsframe.encode/local.mk $(am_= _empty): =20 $(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEP= ENDENCIES) $(SHELL) ./config.status --recheck @@ -726,6 +795,145 @@ clean-libtool: =20 distclean-libtool: -rm -f libtool config.lt +doc/$(am__dirstamp): + @$(MKDIR_P) doc + @: > doc/$(am__dirstamp) + +@BUILD_INFO_TRUE@doc/sframe-spec.info: doc/sframe-spec.texi=20 +@BUILD_INFO_TRUE@ @test -f doc/$(am__dirstamp) || $(MAKE) $(AM_MAKEFLAGS) = doc/$(am__dirstamp) +@BUILD_INFO_TRUE@ $(AM_V_MAKEINFO)restore=3D: && backupdir=3D"$(am__leadin= g_dot)am$$$$" && \ +@BUILD_INFO_TRUE@ rm -rf $$backupdir && mkdir $$backupdir && \ +@BUILD_INFO_TRUE@ if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ +@BUILD_INFO_TRUE@ for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=3D).i[0-9= ] $(@:.info=3D).i[0-9][0-9]; do \ +@BUILD_INFO_TRUE@ if test -f $$f; then mv $$f $$backupdir; restore=3Dm= v; else :; fi; \ +@BUILD_INFO_TRUE@ done; \ +@BUILD_INFO_TRUE@ else :; fi && \ +@BUILD_INFO_TRUE@ if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I d= oc -I $(srcdir)/doc \ +@BUILD_INFO_TRUE@ -o $@ `test -f 'doc/sframe-spec.texi' || echo '$(srcdir= )/'`doc/sframe-spec.texi; \ +@BUILD_INFO_TRUE@ then \ +@BUILD_INFO_TRUE@ rc=3D0; \ +@BUILD_INFO_TRUE@ else \ +@BUILD_INFO_TRUE@ rc=3D$$?; \ +@BUILD_INFO_TRUE@ $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$|= |'`; \ +@BUILD_INFO_TRUE@ fi; \ +@BUILD_INFO_TRUE@ rm -rf $$backupdir; exit $$rc + +doc/sframe-spec.dvi: doc/sframe-spec.texi doc/$(am__dirstamp) + $(AM_V_TEXI2DVI)TEXINPUTS=3D"$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEX= INPUTS" \ + MAKEINFO=3D'$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I doc -I $(= srcdir)/doc' \ + $(TEXI2DVI) $(AM_V_texinfo) --build-dir=3D$(@:.dvi=3D.t2d) -o $@ $(AM_V_t= exidevnull) \ + `test -f 'doc/sframe-spec.texi' || echo '$(srcdir)/'`doc/sframe-spec.texi + +doc/sframe-spec.pdf: doc/sframe-spec.texi doc/$(am__dirstamp) + $(AM_V_TEXI2PDF)TEXINPUTS=3D"$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEX= INPUTS" \ + MAKEINFO=3D'$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I doc -I $(= srcdir)/doc' \ + $(TEXI2PDF) $(AM_V_texinfo) --build-dir=3D$(@:.pdf=3D.t2p) -o $@ $(AM_V_t= exidevnull) \ + `test -f 'doc/sframe-spec.texi' || echo '$(srcdir)/'`doc/sframe-spec.texi + +doc/sframe-spec.html: doc/sframe-spec.texi doc/$(am__dirstamp) + $(AM_V_MAKEINFO)rm -rf $(@:.html=3D.htp) + $(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I = doc -I $(srcdir)/doc \ + -o $(@:.html=3D.htp) `test -f 'doc/sframe-spec.texi' || echo '$(srcdir)/= '`doc/sframe-spec.texi; \ + then \ + rm -rf $@ && mv $(@:.html=3D.htp) $@; \ + else \ + rm -rf $(@:.html=3D.htp); exit 1; \ + fi +.dvi.ps: + $(AM_V_DVIPS)TEXINPUTS=3D"$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINP= UTS" \ + $(DVIPS) $(AM_V_texinfo) -o $@ $< + +uninstall-dvi-am: + @$(NORMAL_UNINSTALL) + @list=3D'$(DVIS)'; test -n "$(dvidir)" || list=3D; \ + 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=3D'$(HTMLS)'; test -n "$(htmldir)" || list=3D; \ + 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=3D'$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=3D`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir=3D'$(DESTDIR)$(infodir)' --remove '$(D= ESTDIR)$(infodir)/$$relfile'"; \ + if install-info --info-dir=3D"$(DESTDIR)$(infodir)" --remove "$(DESTD= IR)$(infodir)/$$relfile"; \ + then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi= ; \ + done; \ + else :; fi + @$(NORMAL_UNINSTALL) + @list=3D'$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=3D`echo "$$file" | sed 's|^.*/||'`; \ + relfile_i=3D`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=3D'$(PDFS)'; test -n "$(pdfdir)" || list=3D; \ + 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=3D'$(PSS)'; test -n "$(psdir)" || list=3D; \ + 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=3D`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list=3D'$(INFO_DEPS)'; \ + for base in $$list; do \ + case $$base in \ + $(srcdir)/*) base=3D`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$base; then d=3D.; else d=3D$(srcdir); fi; \ + base_i=3D`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \ + for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$bas= e_i[0-9] $$d/$$base_i[0-9][0-9]; do \ + if test -f $$file; then \ + relfile=3D`expr "$$file" : "$$d/\(.*\)"`; \ + test -f "$(distdir)/$$relfile" || \ + cp -p $$file "$(distdir)/$$relfile"; \ + else :; fi; \ + done; \ + done + +mostlyclean-aminfo: + -rm -rf doc/sframe-spec.t2d doc/sframe-spec.t2p + +clean-aminfo: + -test -z "doc/sframe-spec.dvi doc/sframe-spec.pdf doc/sframe-spec.ps \ + doc/sframe-spec.html" \ + || rm -rf doc/sframe-spec.dvi doc/sframe-spec.pdf doc/sframe-spec.ps \ + doc/sframe-spec.html + +maintainer-clean-aminfo: + @list=3D'$(INFO_DEPS)'; for i in $$list; do \ + i_i=3D`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-includeHEADERS: $(include_HEADERS) @$(NORMAL_INSTALL) @list=3D'$(include_HEADERS)'; test -n "$(includedir)" || list=3D; \ @@ -869,6 +1077,9 @@ distdir: $(DISTFILES) || exit 1; \ fi; \ done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir=3D"$(top_distdir)" distdir=3D"$(distdir)" \ + dist-info -test -n "$(am__skip_mode_fix)" \ || find "$(distdir)" -type d ! -perm -755 \ -exec chmod u+rwx,go+rx {} \; -o \ @@ -1004,9 +1215,9 @@ check-am: all-am $(MAKE) $(AM_MAKEFLAGS) $(check_PROGRAMS) $(MAKE) $(AM_MAKEFLAGS) check-DEJAGNU check: check-am -all-am: Makefile $(LTLIBRARIES) $(HEADERS) config.h +all-am: Makefile $(INFO_DEPS) $(LTLIBRARIES) $(HEADERS) config.h installdirs: - for dir in "$(DESTDIR)$(libdir)" "$(DESTDIR)$(includedir)"; do \ + for dir in "$(DESTDIR)$(libdir)" "$(DESTDIR)$(infodir)" "$(DESTDIR)$(incl= udedir)"; do \ test -z "$$dir" || $(MKDIR_P) "$$dir"; \ done install: install-am @@ -1035,18 +1246,23 @@ clean-generic: distclean-generic: -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) -test . =3D "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f= $(CONFIG_CLEAN_VPATH_FILES) + -rm -f doc/$(am__dirstamp) -rm -f testsuite/libsframe.decode/$(DEPDIR)/$(am__dirstamp) -rm -f testsuite/libsframe.decode/$(am__dirstamp) -rm -f testsuite/libsframe.encode/$(DEPDIR)/$(am__dirstamp) -rm -f testsuite/libsframe.encode/$(am__dirstamp) + -test -z "$(DISTCLEANFILES)" || rm -f $(DISTCLEANFILES) =20 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) +@BUILD_INFO_FALSE@html-local: clean: clean-am =20 -clean-am: clean-checkPROGRAMS clean-generic clean-libLTLIBRARIES \ - clean-libtool clean-noinstLTLIBRARIES mostlyclean-am +clean-am: clean-aminfo clean-checkPROGRAMS clean-generic \ + clean-libLTLIBRARIES clean-libtool clean-noinstLTLIBRARIES \ + mostlyclean-am =20 distclean: distclean-am -rm -f $(am__CONFIG_DISTCLEAN_FILES) @@ -1058,42 +1274,133 @@ distclean-am: clean-am distclean-DEJAGNU distclean= -compile \ =20 dvi: dvi-am =20 -dvi-am: +dvi-am: $(DVIS) =20 html: html-am =20 -html-am: +html-am: $(HTMLS) html-local =20 info: info-am =20 -info-am: +info-am: $(INFO_DEPS) =20 -install-data-am: install-includeHEADERS +install-data-am: install-includeHEADERS install-info-am =20 install-dvi: install-dvi-am =20 -install-dvi-am: - +install-dvi-am: $(DVIS) + @$(NORMAL_INSTALL) + @list=3D'$(DVIS)'; test -n "$(dvidir)" || list=3D; \ + 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=3D; else d=3D"$(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-libLTLIBRARIES =20 install-html: install-html-am =20 -install-html-am: - +install-html-am: $(HTMLS) + @$(NORMAL_INSTALL) + @list=3D'$(HTMLS)'; list2=3D; test -n "$(htmldir)" || list=3D; \ + 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=3D; else d=3D"$(srcdir)/"; fi= ; \ + $(am__strip_dir) \ + d2=3D$$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=3D"$$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-am =20 -install-info-am: - +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + @srcdirstrip=3D`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list=3D'$(INFO_DEPS)'; test -n "$(infodir)" || list=3D; \ + 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=3D`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$file; then d=3D.; else d=3D$(srcdir); fi; \ + file_i=3D`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=3D'$(INFO_DEPS)'; test -n "$(infodir)" || list=3D; \ + for file in $$list; do \ + relfile=3D`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir=3D'$(DESTDIR)$(infodir)' '$(DESTDIR)$(= infodir)/$$relfile'";\ + install-info --info-dir=3D"$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir= )/$$relfile" || :;\ + done; \ + else : ; fi install-man: =20 install-pdf: install-pdf-am =20 -install-pdf-am: - +install-pdf-am: $(PDFS) + @$(NORMAL_INSTALL) + @list=3D'$(PDFS)'; test -n "$(pdfdir)" || list=3D; \ + 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=3D; else d=3D"$(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-am =20 -install-ps-am: - +install-ps-am: $(PSS) + @$(NORMAL_INSTALL) + @list=3D'$(PSS)'; test -n "$(psdir)" || list=3D; \ + 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=3D; else d=3D"$(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: =20 maintainer-clean: maintainer-clean-am @@ -1101,48 +1408,63 @@ maintainer-clean: maintainer-clean-am -rm -rf $(top_srcdir)/autom4te.cache -rm -rf ./$(DEPDIR) testsuite/libsframe.decode/$(DEPDIR) testsuite/libsfr= ame.encode/$(DEPDIR) -rm -f Makefile -maintainer-clean-am: distclean-am maintainer-clean-generic +maintainer-clean-am: distclean-am maintainer-clean-aminfo \ + maintainer-clean-generic =20 mostlyclean: mostlyclean-am =20 -mostlyclean-am: mostlyclean-compile mostlyclean-generic \ - mostlyclean-libtool +mostlyclean-am: mostlyclean-aminfo mostlyclean-compile \ + mostlyclean-generic mostlyclean-libtool =20 pdf: pdf-am =20 -pdf-am: +pdf-am: $(PDFS) =20 ps: ps-am =20 -ps-am: +ps-am: $(PSS) =20 -uninstall-am: uninstall-includeHEADERS uninstall-libLTLIBRARIES +uninstall-am: uninstall-dvi-am uninstall-html-am \ + uninstall-includeHEADERS uninstall-info-am \ + uninstall-libLTLIBRARIES uninstall-pdf-am uninstall-ps-am =20 .MAKE: all check-am install-am install-strip =20 .PHONY: CTAGS GTAGS TAGS all all-am am--refresh check check-DEJAGNU \ - check-am clean clean-checkPROGRAMS clean-cscope clean-generic \ - clean-libLTLIBRARIES clean-libtool clean-noinstLTLIBRARIES \ - cscope cscopelist-am ctags ctags-am dist dist-all dist-bzip2 \ - dist-gzip dist-lzip dist-shar dist-tarZ dist-xz dist-zip \ - distcheck distclean distclean-DEJAGNU distclean-compile \ - distclean-generic distclean-hdr distclean-libtool \ - distclean-tags distcleancheck distdir distuninstallcheck dvi \ - dvi-am html html-am info info-am install install-am \ - install-data install-data-am install-dvi install-dvi-am \ - install-exec install-exec-am install-html install-html-am \ - install-includeHEADERS install-info install-info-am \ - install-libLTLIBRARIES install-man install-pdf install-pdf-am \ - install-ps install-ps-am install-strip installcheck \ - installcheck-am installdirs maintainer-clean \ - maintainer-clean-generic mostlyclean mostlyclean-compile \ - mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ - tags tags-am uninstall uninstall-am uninstall-includeHEADERS \ - uninstall-libLTLIBRARIES + check-am clean clean-aminfo clean-checkPROGRAMS clean-cscope \ + clean-generic clean-libLTLIBRARIES clean-libtool \ + clean-noinstLTLIBRARIES cscope cscopelist-am ctags ctags-am \ + dist dist-all dist-bzip2 dist-gzip dist-info dist-lzip \ + dist-shar dist-tarZ dist-xz dist-zip distcheck distclean \ + distclean-DEJAGNU distclean-compile distclean-generic \ + distclean-hdr distclean-libtool distclean-tags distcleancheck \ + distdir distuninstallcheck dvi dvi-am html html-am html-local \ + info info-am install install-am install-data install-data-am \ + install-dvi install-dvi-am install-exec install-exec-am \ + install-html install-html-am install-includeHEADERS \ + install-info install-info-am install-libLTLIBRARIES \ + install-man install-pdf install-pdf-am install-ps \ + install-ps-am install-strip installcheck installcheck-am \ + installdirs maintainer-clean maintainer-clean-aminfo \ + maintainer-clean-generic mostlyclean mostlyclean-aminfo \ + mostlyclean-compile mostlyclean-generic mostlyclean-libtool \ + pdf pdf-am ps ps-am tags tags-am uninstall uninstall-am \ + uninstall-dvi-am uninstall-html-am uninstall-includeHEADERS \ + uninstall-info-am uninstall-libLTLIBRARIES uninstall-pdf-am \ + uninstall-ps-am =20 .PRECIOUS: Makefile =20 =20 +@BUILD_INFO_TRUE@html-local: doc/sframe-spec/index.html +@BUILD_INFO_TRUE@doc/sframe-spec/index.html: doc/sframe-spec.texi doc/$(am= __dirstamp) +@BUILD_INFO_TRUE@ $(AM_V_GEN)$(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAK= EINFOFLAGS) \ +@BUILD_INFO_TRUE@ --split=3Dnode -I$(srcdir) --output doc/sframe-spec $(= srcdir)/doc/sframe-spec.texi + +# Workaround bug in automake: it can't handle conditionally building info = pages +# since GNU projects normally include info pages in the source distributio= ns. +@BUILD_INFO_FALSE@doc/sframe-spec.info: + check-DEJAGNU: site.exp srcroot=3D`cd $(srcdir) && pwd`; export srcroot; \ r=3D`pwd`; export r; \ diff --git a/libsframe/configure b/libsframe/configure index f95900c862c..7bbed5d8ccf 100755 --- a/libsframe/configure +++ b/libsframe/configure @@ -643,6 +643,8 @@ INSTALL_LIBBFD_TRUE MAINT MAINTAINER_MODE_FALSE MAINTAINER_MODE_TRUE +BUILD_INFO_FALSE +BUILD_INFO_TRUE COMPAT_DEJAGNU HAVE_COMPAT_DEJAGNU_FALSE HAVE_COMPAT_DEJAGNU_TRUE @@ -11441,7 +11443,7 @@ else lt_dlunknown=3D0; lt_dlno_uscore=3D1; lt_dlneed_uscore=3D2 lt_status=3D$lt_dlunknown cat > conftest.$ac_ext <<_LT_EOF -#line 11444 "configure" +#line 11446 "configure" #include "confdefs.h" =20 #if HAVE_DLFCN_H @@ -11547,7 +11549,7 @@ else lt_dlunknown=3D0; lt_dlno_uscore=3D1; lt_dlneed_uscore=3D2 lt_status=3D$lt_dlunknown cat > conftest.$ac_ext <<_LT_EOF -#line 11550 "configure" +#line 11552 "configure" #include "confdefs.h" =20 #if HAVE_DLFCN_H @@ -12223,6 +12225,77 @@ fi COMPAT_DEJAGNU=3D$ac_cv_dejagnu_compat =20 =20 +build_info=3D +for ac_prog in makeinfo +do + # Extract the first word of "$ac_prog", so it can be a program name with= args. +set dummy $ac_prog; ac_word=3D$2 +{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +$as_echo_n "checking for $ac_word... " >&6; } +if ${ac_cv_prog_MAKEINFO+:} false; then : + $as_echo_n "(cached) " >&6 +else + if test -n "$MAKEINFO"; then + ac_cv_prog_MAKEINFO=3D"$MAKEINFO" # Let the user override the test. +else +as_save_IFS=3D$IFS; IFS=3D$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=3D$as_save_IFS + test -z "$as_dir" && as_dir=3D. + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then + ac_cv_prog_MAKEINFO=3D"$ac_prog" + $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_= ext" >&5 + break 2 + fi +done + done +IFS=3D$as_save_IFS + +fi +fi +MAKEINFO=3D$ac_cv_prog_MAKEINFO +if test -n "$MAKEINFO"; then + { $as_echo "$as_me:${as_lineno-$LINENO}: result: $MAKEINFO" >&5 +$as_echo "$MAKEINFO" >&6; } +else + { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 +$as_echo "no" >&6; } +fi + + + test -n "$MAKEINFO" && break +done +test -n "$MAKEINFO" || MAKEINFO=3D"makeinfo" + +if test "x$MAKEINFO" =3D "x"; then + MAKEINFO=3D"@echo makeinfo missing; true" + build_info=3D +else + BUILD_INFO=3Dinfo + case "$MAKEINFO" in + */missing\ makeinfo*) + build_info=3D + { $as_echo "$as_me:${as_lineno-$LINENO}: WARNING: +*** Makeinfo is missing. Info documentation will not be built." >&5 +$as_echo "$as_me: WARNING: +*** Makeinfo is missing. Info documentation will not be built." >&2;} + ;; + *) + build_info=3Dyes + ;; + esac +fi + if test "${build_info}" =3D yes; then + BUILD_INFO_TRUE=3D + BUILD_INFO_FALSE=3D'#' +else + BUILD_INFO_TRUE=3D'#' + BUILD_INFO_FALSE=3D +fi + + =20 { $as_echo "$as_me:${as_lineno-$LINENO}: checking whether to enable mainta= iner-specific portions of Makefiles" >&5 $as_echo_n "checking whether to enable maintainer-specific portions of Mak= efiles... " >&6; } @@ -12694,6 +12767,10 @@ if test -z "${HAVE_COMPAT_DEJAGNU_TRUE}" && test -= z "${HAVE_COMPAT_DEJAGNU_FALSE as_fn_error $? "conditional \"HAVE_COMPAT_DEJAGNU\" was never defined. Usually this means the macro was only invoked conditionally." "$LINENO" 5 fi +if test -z "${BUILD_INFO_TRUE}" && test -z "${BUILD_INFO_FALSE}"; then + as_fn_error $? "conditional \"BUILD_INFO\" was never defined. +Usually this means the macro was only invoked conditionally." "$LINENO" 5 +fi if test -z "${MAINTAINER_MODE_TRUE}" && test -z "${MAINTAINER_MODE_FALSE}"= ; then as_fn_error $? "conditional \"MAINTAINER_MODE\" was never defined. Usually this means the macro was only invoked conditionally." "$LINENO" 5 diff --git a/libsframe/configure.ac b/libsframe/configure.ac index a6c1d26bbbb..4182a0dc0ab 100644 --- a/libsframe/configure.ac +++ b/libsframe/configure.ac @@ -59,6 +59,27 @@ AM_CONDITIONAL([HAVE_COMPAT_DEJAGNU], [test "x$ac_cv_dej= agnu_compat" =3D "xyes"]) COMPAT_DEJAGNU=3D$ac_cv_dejagnu_compat AC_SUBST(COMPAT_DEJAGNU) =20 +dnl Check for makeinfo for building documentation +build_info=3D +AC_CHECK_PROGS([MAKEINFO], makeinfo, makeinfo, ) +if test "x$MAKEINFO" =3D "x"; then + MAKEINFO=3D"@echo makeinfo missing; true" + build_info=3D +else + BUILD_INFO=3Dinfo + case "$MAKEINFO" in + */missing\ makeinfo*) + build_info=3D + AC_MSG_WARN([ +*** Makeinfo is missing. Info documentation will not be built.]) + ;; + *) + build_info=3Dyes + ;; + esac +fi +AM_CONDITIONAL(BUILD_INFO, test "${build_info}" =3D yes) + AM_MAINTAINER_MODE AM_INSTALL_LIBBFD =20 diff --git a/libsframe/doc/local.mk b/libsframe/doc/local.mk new file mode 100644 index 00000000000..bdd1312e040 --- /dev/null +++ b/libsframe/doc/local.mk @@ -0,0 +1,40 @@ +## Process this file with automake to produce Makefile.in. +# +# Copyright (C) 2019-2022 Free Software Foundation, Inc. +# +# This file 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 2 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; see the file COPYING. If not see +# . +# + +if BUILD_INFO + +info_TEXINFOS +=3D %D%/sframe-spec.texi + +AM_MAKEINFOFLAGS =3D --no-split + +DISTCLEANFILES +=3D texput.log +MAINTAINERCLEANFILES +=3D %D%/sframe-spec.info + +html-local: %D%/sframe-spec/index.html +%D%/sframe-spec/index.html: %D%/sframe-spec.texi %D%/$(am__dirstamp) + $(AM_V_GEN)$(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) \ + --split=3Dnode -I$(srcdir) --output %D%/sframe-spec $(srcdir)/%D%/sfram= e-spec.texi + +else + +# Workaround bug in automake: it can't handle conditionally building info = pages +# since GNU projects normally include info pages in the source distributio= ns. +%D%/sframe-spec.info: + +endif diff --git a/libsframe/doc/sframe-spec.texi b/libsframe/doc/sframe-spec.texi new file mode 100644 index 00000000000..41f4ba17d83 --- /dev/null +++ b/libsframe/doc/sframe-spec.texi @@ -0,0 +1,619 @@ +\input texinfo @c -*- Texinfo -*- +@setfilename sframe-spec.info +@settitle The SFrame Format +@ifnottex +@xrefautomaticsectiontitle on +@end ifnottex + +@copying +Copyright @copyright{} 2021-2022 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU General Public License, Version 3 or any +later version published by the Free Software Foundation. A copy of the +license is included in the section entitled ``GNU General Public +License''. + +@end copying + +@dircategory Software development +@direntry +* SFrame: (sframe-spec). The Simple Frame format. +@end direntry + +@titlepage +@title The SFrame Format +@subtitle Version 1 +@author Indu Bhagat + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage +@contents + +@ifnottex +@node Top +@top The SFrame format + +This manual describes version 1 of the SFrame file format. SFrame stands = for +Simple Frame format. SFrame format keeps track of the minimal necessary +information needed for stack unwinding: + +@itemize @minus +@item +Canonical Frame Address (CFA). +@item +Frame Pointer (FP). +@item +Return Address (RA). +@end itemize + +The reason for existence of the SFrame format is to support fast, online +backtracing using a simple unwinder. + +@menu +* Overview:: +* SFrame section:: +* Index:: +@end menu + +@end ifnottex + +@node Overview +@unnumbered Overview +@cindex Overview +@tindex PT_GNU_SFRAME + +The SFrame unwind information is provided in a loaded section, known as the +@code{.sframe} section. When available, the @code{.sframe} section appear= s in +a new segment of its own, PT_GNU_SFRAME. + +The SFrame format is currently supported only for select ABIs, namely, AMD= 64 +and AAPCS64. + +The contents of the SFrame section are stored in the target endianness, i.= e., +in the endianness of the system on which the section is targetted to be us= ed. +An SFrame section reader may use the magic number in the SFrame header to +identify the endianness of the SFrame section. + +Addresses in this specification are expressed in bytes. + +The associated API to decode, probe and encode the SFrame section, provide= d via +@code{libsframe}, is not accompanied here at this time. This will be added +later. + +This document is intended to be in sync with the C code in @file{sframe.h}. +Please report descrepancies between the two, if any. + +@node SFrame section +@chapter SFrame section +@cindex SFrame section + +The SFrame section consists of an SFrame header, starting with a preamble,= and +two other sub-sections, namely the SFrame Function Descriptor Entry (SFrame +FDE) sub-section, and the SFrame Frame Row Entry (SFrame FRE) sub-section. + +@menu +* SFrame Preamble:: +* SFrame Header:: +* SFrame Function Descriptor Entries:: +* SFrame Frame Row Entries:: +@end menu + +@node SFrame Preamble +@section SFrame Preamble +@cindex SFrame preamble + +The preamble is a 32-bit packed structure; the only part of the SFrame who= se +format cannot vary between versions. + +@example +typedef struct sframe_preamble +@{ + uint16_t sfp_magic; + uint8_t sfp_version; + uint8_t sfp_flags; +@} ATTRIBUTE_PACKED sframe_preamble; +@end example + +All values are stored in the endianness of the target system for which the +SFrame section is intended. Further details: + +@multitable {Offset} {@code{uint8_t sfp_version}} {The magic number for SF= rame section: 0xdee2. Defined} +@headitem Offset @tab Name @tab Description +@item 0x00 +@tab @code{uint16_t sfp_magic} +@tab The magic number for SFrame section: 0xdee2. Defined as a macro @cod= e{SFRAME_MAGIC}. +@tindex SFRAME_MAGIC + +@item 0x02 +@tab @code{uint8_t sfp_version} +@tab The version number of this SFrame section. @xref{SFrame version}, fo= r the +set of valid values. Current version is +@code{SFRAME_VERSION_1}. + +@item 0x03 +@tab @code{uint8_t sfp_flags} +@tab Flags (section-wide) for this SFrame section. @xref{SFrame flags}, f= or the +set of valid values. +@end multitable + +@menu +* SFrame endianness:: +* SFrame version:: +* SFrame flags:: +@end menu + +@node SFrame endianness +@subsection SFrame endianness + +@cindex endianness +SFrame sections are stored in the target endianness of the system that con= sumes +them. The SFrame library (@code{libsframe}) can, however, detect whether = to +endian-flip an SFrame section at decode time, by inspecting the +@code{sfp_magic} field in the SFrame header (If it appears as 0xe2de, +endian-flipping is needed). + +@node SFrame version +@subsection SFrame version + +The version of the SFrame format can be determined by inspecting +@code{sfp_version}. The following versions are currently valid: + +@tindex SFRAME_VERSION_1 +@cindex SFrame versions +@multitable {SFRAME_VERSION_1} {Number} {First version, under development.} +@headitem Version @tab Number @tab Description +@item @code{SFRAME_VERSION_1} +@tab 1 @tab First version, under development. +@end multitable + +This section documents @code{SFRAME_VERSION_1}. + +@node SFrame flags +@subsection SFrame flags +@cindex SFrame flags +@comment @vindex sfp_flags +@comment @vindex SFrame section-wide flags +@comment @subsection SFrame section-wide flags + +The preamble contains bitflags in its @code{sfp_flags} field that +describe various section-wide properties. + +The following flags are currently defined. + +@multitable {@code{SFRAME_F_FRAME_POINTER}} {Versions} {Value} {Function D= escriptor Entries} +@headitem Flag @tab Versions @tab Value @tab Meaning +@tindex SFRAME_F_FDE_SORTED +@item @code{SFRAME_F_FDE_SORTED} @tab All @tab 0x1 @tab Function Descriptor +Entries are sorted on PC. +@tindex SFRAME_F_FRAME_POINTER +@item @code{SFRAME_F_FRAME_POINTER} @tab All @tab 0x2 +@tab Functions preserve frame-pointer. +@end multitable + +Further flags may be added in future. + +@node SFrame Header +@section SFrame Header +@cindex SFrame header + +The SFrame header is the first part of an SFrame section. It begins with = the +SFrame preamble. All parts of it other than the preamble +(@pxref{SFrame Preamble}) can vary between SFrame file versions. It conta= ins +things that apply to the section as a whole, and offsets to the various ot= her +sub-sections defined in the format. As with the rest of the SFrame sectio= n, +all values are stored in the endianness of the target system. + +The two sub-sections tile the SFrame section: each section runs from the o= ffset +given until the start of the next section. An explicit length is given fo= r the +last sub-section, the SFrame Frame Row Entry (SFrame FRE) sub-section. + +@example +typedef struct sframe_header +@{ + sframe_preamble sfh_preamble; + uint8_t sfh_abi_arch; + int8_t sfh_cfa_fixed_fp_offset; + int8_t sfh_cfa_fixed_ra_offset; + uint8_t sfh_auxhdr_len; + uint32_t sfh_num_fdes; + uint32_t sfh_num_fres; + uint32_t sfh_fre_len; + uint32_t sfh_fdeoff; + uint32_t sfh_freoff; +@} ATTRIBUTE_PACKED sframe_header; +@end example + +The sub-section offsets, namely @code{sfh_fdeoff} and @code{sfh_freoff}, i= n the +SFrame header are relative to the @emph{end} of the SFrame header; they are +each an offset in bytes into the SFrame section where the SFrame FDE +sub-section and the SFrame FRE sub-section respectively start. + +SFrame header allows specifying explicitly the fixed offsets from CFA, if = any, +from which FP or RA may be recovered. For example, in AMD64, the stack of= fset +of the return address is @code{CFA - 8}. Since this offset is in close +vicinity with the CFA in most ABIs, @code{sfh_cfa_fixed_fp_offset} and +@code{sfh_cfa_fixed_ra_offset} are limited to signed 8-bit integers. + +SFrame format has provisioned for future ABIs/architectures that it may +support. The @code{sframe_header} structure provides an unsigned 8-bit +integral field to denote the size of an auxilliary SFrame header. The +auxilliary SFrame header follows right after the @code{sframe_header} +structure. As for the offset calculations, the @emph{end} of SFrame header +must be the end of the auxilliary SFrame header, if the latter is present. + +Tieing it all together: + +@multitable {Offset} {@code{int8_t sfh_cfa_fixed_fp_offset}} {The ABI/arch= identifier. See above} +@headitem Offset @tab Name @tab Description +@item 0x00 +@tab @code{sframe_preamble sfh_preamble} +@tab The SFrame preamble. @xref{SFrame Preamble}. + +@item 0x04 +@tab @code{uint8_t sfh_abi_arch} +@tab The ABI/arch identifier. @xref{SFrame ABI/arch identifier}. + +@item 0x05 +@tab @code{int8_t sfh_cfa_fixed_fp_offset} +@tab The CFA fixed FP offset, if any. + +@item 0x06 +@tab @code{int8_t sfh_cfa_fixed_ra_offset} +@tab The CFA fixed RA offset, if any. + +@item 0x07 +@tab @code{uint8_t sfh_auxhdr_len} +@tab Size in bytes of the auxilliary header that follows the +@code{sframe_header} structure. + +@item 0x08 +@tab @code{uint32_t sfh_num_fdes} +@tab The number of SFrame FDEs in the section. + +@item 0xc +@tab @code{uint32_t sfh_num_fres} +@tab The number of SFrame FREs in the section. + +@item 0x10 +@tab @code{uint32_t sfh_fre_len} +@tab The length in bytes of the SFrame FRE sub-section. + +@item 0x14 +@tab @code{uint32_t sfh_fdeoff} +@tab The offset in bytes of the SFrame FDE sub-section. This sub-section +contains @code{sfh_num_fdes} number of fixed-length array elements. The a= rray +element is of type SFrame function desciptor entry, each providing a +high-level function description for backtracing. +@xref{SFrame Function Descriptor Entries}. + +@item 0x18 +@tab @code{uint32_t sfh_freoff} +@tab The offset in bytes of the SFrame FRE sub-section, the core of the SF= rame +section, which describes the unwind information using variable-length array +elements. @xref{SFrame Frame Row Entries}. + +@end multitable + +@menu +* SFrame ABI/arch identifier:: +@end menu + +@node SFrame ABI/arch identifier +@subsection SFrame ABI/arch identifier +@cindex SFrame ABI/arch identifier + +SFrame header identifies the ABI/arch of the target system for which the +executable and it's unwind information is intended. There are currently t= hree +identifiable ABI/arch values in the format. + +@multitable {SFRAME_ABI_AARCH64_ENDIAN_LITTLE} {Value} {@code{AARCH64 litt= le-endian}} +@headitem ABI/arch Identifier @tab Value @tab Description + +@tindex SFRAME_ABI_AARCH64_ENDIAN_BIG +@item @code{SFRAME_ABI_AARCH64_ENDIAN_BIG} +@tab 1 @tab AARCH64 big-endian + +@tindex SFRAME_ABI_AARCH64_ENDIAN_LITTLE +@item @code{SFRAME_ABI_AARCH64_ENDIAN_LITTLE} +@tab 2 @tab AARCH64 little-endian + +@tindex SFRAME_ABI_AMD64_ENDIAN_LITTLE +@item @code{SFRAME_ABI_AMD64_ENDIAN_LITTLE} +@tab 3 @tab AMD64 little-endian + +@end multitable + +The presence of an explicit identification of ABI/arch in SFrame may allow +unwinders to make certain ABI-specific decisions. + +@node SFrame Function Descriptor Entries +@section SFrame FDE +@cindex SFrame FDE + +The SFrame Function Descriptor Entry sub-section is a sorted array of +fixed-length SFrame function descriptor entries (SFrame FDEs). Each SFram= e FDE +is a packed structure which contains information to describe a function's = unwind +information at a high-level. + +@example +typedef struct sframe_func_desc_entry +@{ + int32_t sfde_func_start_address; + uint32_t sfde_func_size; + uint32_t sfde_func_start_fre_off; + uint32_t sfde_func_num_fres; + uint8_t sfde_func_info; +@} ATTRIBUTE_PACKED sframe_func_desc_entry; +@end example + +@code{sfde_func_start_fre_off} is the offset to the first SFrame FRE for t= he +function. This offset is relative to the @emph{end of the SFrame FDE} +sub-section (unlike the offsets in the SFrame header, which are relative t= o the +@emph{end} of the SFrame header). + +@code{sfde_func_info} is the "info word", containing information on the FRE +type and the FDE type for the function @xref{The SFrame FDE info word}. + +Following table describes each component of the SFrame FDE structure: + +@multitable {Offset} {@code{uint32_t sfde_func_start_fre_off}} {The ABI/ar= ch identifier. See above} +@headitem Offset @tab Name @tab Description +@item 0x00 +@tab @code{int32_t sfde_func_start_address} +@tab Signed 32-bit integral field denoting the virtual memory address of t= he +described function. + +@item 0x04 +@tab @code{uint32_t sfde_func_size} +@tab Unsigned 32-bit integral field specifying the size of the function in +bytes. + +@item 0x08 +@tab @code{uint32_t sfde_func_start_fre_off} +@tab Unsigned 32-bit integral field specifying the offset in bytes of the +function's first SFrame FRE in the SFrame section. + +@item 0x0c +@tab @code{uint32_t sfde_func_num_fres} +@tab Unsigned 32-bit integral field specifying the total number of SFrame = FREs +used for the function. + +@item 0x10 +@tab @code{uint8_t sfde_func_info} +@tab The SFrame FDE info word. @xref{The SFrame FDE info word}. + +@end multitable + +@menu +* The SFrame FDE info word:: +* The SFrame FDE types:: +* The SFrame FRE types:: +@end menu + +@cindex The SFrame FDE info word +@node The SFrame FDE info word +@subsection The SFrame FDE info word, sfde_func_info + +The info word is a bitfield split into three parts. From MSB to LSB: + +@multitable {Bit offset} {@code{isroot}} {Length of variable-length data f= or this type (some kinds only).} +@headitem Bit offset @tab Name @tab Description +@item 7--5 +@tab @code{unused} +@tab Unused bits. + +@item 4 +@tab @code{fdetype} +@tab SFRAME_FDE_TYPE_PCMASK (1) or SFRAME_FDE_TYPE_PCINC (0). @xref{The SF= rame FDE types}. + +@item 0--3 +@tab @code{fretype} +@tab Choice of three SFrame FRE types. @xref{The SFrame FRE types}. +@end multitable + +@node The SFrame FDE types +@subsection The SFrame FDE types +@tindex SFRAME_FDE_TYPE_PCMASK +@tindex SFRAME_FDE_TYPE_PCINC + +SFrame format defines two types of FDE entries. The choice of which SFram= e FDE +type to use is made based on the instruction patterns in the relevant prog= ram +stub. + +An SFrame FDE of type @code{SFRAME_FDE_TYPE_PCINC} is an indication that t= he PCs in the +FREs should be treated as increments in bytes. This is used fo the the bu= lk of +the executable code of a program, which contains instructions with no spec= ific +pattern. + +In contrast, an SFrame FDE of type @code{SFRAME_FDE_TYPE_PCMASK} is an +indication that the PCs in the FREs should be treated as masks. This type= is +useful for the cases where a small pattern of instructions in a program st= ub is +used repeatedly for a specific functionality. Typical usecases are pltN +entries and trampolines. + +@multitable {Name of SFrame FDE type} {Value} {Unwinders perform a (PC >= =3D FRE_START_ADDR)} +@headitem Name of SFrame FDE type @tab Value @tab Description + +@item SFRAME_FDE_TYPE_PCINC +@tab 0 @tab Unwinders perform a (PC >=3D FRE_START_ADDR) to look up a matc= hing FRE. + +@item SFRAME_FDE_TYPE_PCMASK +@tab 1 @tab Unwinders perform a (PC & FRE_START_ADDR_AS_MASK >=3D FRE_STA= RT_ADDR_AS_MASK) +to look up a matching FRE. + +@end multitable + +@node The SFrame FRE types +@subsection The SFrame FRE types + +A real world application can have functions of size big and small. SFrame +format defines three types of SFrame FRE entries to represent the unwind +information for such a variety of function sizes. These representations v= ary +in the number of bits needed to encode the start address offset in the SFr= ame +FRE. + +The following constants are defined and used to identify the SFrame FRE ty= pes: + +@multitable {SFRAME_FRE_TYPE_ADDR1} {@code{Value}} {The start address offs= et of FRE is an} +@headitem Name @tab Value @tab Description + +@tindex SFRAME_FRE_TYPE_ADDR1 +@item @code{SFRAME_FRE_TYPE_ADDR1} +@tab 0 +@tab The start address offset (in bytes) of the SFrame FRE is an unsigned +8-bit value. + +@tindex SFRAME_FRE_TYPE_ADDR2 +@item @code{SFRAME_FRE_TYPE_ADDR2} +@tab 1 +@tab The start address offset (in bytes) of the SFrame FRE is an unsigned +16-bit value. + +@tindex SFRAME_FRE_TYPE_ADDR4 +@item @code{SFRAME_FRE_TYPE_ADDR4} +@tab 2 +@tab The start address offset (in bytes) of the SFrame FRE is an unsigned +32-bit value. +@end multitable + +A single function must use the same type of FRE throughout. The choice of +which SFrame FRE is used to encode the unwind information of a function, is +stored in the @xref{The SFrame FDE info word}. + +@node SFrame Frame Row Entries +@section SFrame FRE +@cindex SFrame FRE + +The SFrame Frame Row Entry sub-section contains the core of the unwind +information. + +An SFrame Frame Row Entry is a self-sufficient record containing SFrame un= wind +info for a range of contiguous addresses, starting at the specified offset= from +the start of the function. Each SFrame Frame Row Entry is followed by S*N +bytes, where: + +@itemize @minus +@item +@code{S} is the size of the stack frame offset for the FRE, and +@item +@code{N} is the number of stack frame offsets in the FRE +@end itemize + +The stack offsets, following the FRE, are interpreted in order as follows: + +@itemize @minus +@item +The first offset is always used to locate the CFA, by interpreting it as: +CFA =3D @code{BASE_REG} + offset1. +@item +If RA is being tracked, the second offset is always used to locate the RA,= by +interpreting it as: RA =3D CFA + offset2. If RA is @emph{not} being track= ed +@emph{and} FP is being tracked, the second offset will be used to locate t= he +FP, by interpreting it as: FP =3D CFA + offset2. +@item +If both RA and FP are being tracked, the third offset will be used to loca= te +the FP, by interpreting it as FP =3D CFA + offset3. +@end itemize + +The entities @code{S}, @code{N} and @code{BASE_REG} are identified using t= he +SFrame FRE info word, a.k.a. the @code{sframe_fre_info} +@xref{The SFrame FRE info word}. + +Following are the definitions of the allowed SFrame FRE: + +@example +typedef struct sframe_frame_row_entry_addr1 +@{ + uint8_t sfre_start_address; + sframe_fre_info sfre_info; +@} ATTRIBUTE_PACKED sframe_frame_row_entry_addr1; +@end example + +@example +typedef struct sframe_frame_row_entry_addr2 +@{ + uint16_t sfre_start_address; + sframe_fre_info sfre_info; +@} ATTRIBUTE_PACKED sframe_frame_row_entry_addr2; +@end example + +@example +typedef struct sframe_frame_row_entry_addr4 +@{ + uint32_t sfre_start_address; + sframe_fre_info sfre_info; +@} ATTRIBUTE_PACKED sframe_frame_row_entry_addr4; +@end example + +@code{sfre_start_address} is an unsigned 8-bit/16-bit/32-bit integral field +identifies the start address of the range of program counters, for which t= he +SFrame FRE applies. The value encoded in the @code{sfre_start_address} fi= eld +is the offset in bytes of the start address of the SFrame FRE, from the st= art +address of the function. + +Further FRE types may be added in future. + +@menu +* The SFrame FRE info word:: +@end menu + +@cindex The SFrame FRE info word +@node The SFrame FRE info word +@subsection The SFrame FRE info word, sfre_info + +The SFrame FRE info word is a bitfield split into four parts. From MSB to= LSB: + +@multitable {Bit offset} {@code{fre_cfa_base_reg_id}} {Size of stack offse= ts in bytes. Valid values} +@headitem Bit offset @tab Name @tab Description +@item 7 +@tab @code{unused} +@tab Unused bit. + +@item 5-6 +@tab @code{fre_offset_size} +@tab Size of stack offsets in bytes. Valid values are SFRAME_FRE_OFFSET_1= B, +SFRAME_FRE_OFFSET_2B, and SFRAME_FRE_OFFSET_4B. + +@item 1-4 +@tab @code{fre_offset_count} +@tab A value of upto 3 is allowed to track all three of CFA, FP and RA. + +@item 0 +@tab @code{fre_cfa_base_reg_id} +@tab Distinguish between SP or FP based CFA recovery. + +@end multitable + +@multitable {SFRAME_FRE_OFFSET_4B} {@code{Value}} {All stack offsets follo= wing the fixed-length} +@headitem Name @tab Value @tab Description + +@tindex SFRAME_FRE_OFFSET_1B +@item @code{SFRAME_FRE_OFFSET_1B} +@tab 0 +@tab All stack offsets following the fixed-length FRE structure are 1 byte +long. + +@tindex SFRAME_FRE_OFFSET_2B +@item @code{SFRAME_FRE_OFFSET_2B} +@tab 1 +@tab All stack offsets following the fixed-length FRE structure are 2 bytes +long. + +@tindex SFRAME_FRE_OFFSET_4B +@item @code{SFRAME_FRE_OFFSET_4B} +@tab 2 +@tab All stack offsets following the fixed-length FRE structure are 4 bytes +long. + +@end multitable + +@node Index +@unnumbered Index + +@syncodeindex tp cp +@printindex cp + +@bye