libsframe: add the SFrame library

libsframe is a library that allows you to:
- decode a .sframe section
- probe and inspect a .sframe section
- encode (and eventually write) a .sframe section.

This library is currently being used by the linker, readelf, objdump.
This library will also be used by the SFrame unwinder which is still
to be upstream'd.

The file include/sframe-api.h defines the user-facing APIs for decoding,
encoding and probing .sframe sections. A set of error codes together
with their error message strings are also defined.

Endian flipping is performed automatically at read and write time, if
cross-endianness is detected.

ChangeLog:

	* Makefile.def: Add libsframe as new module with its
	dependencies.
	* Makefile.in: Regenerated.
	* binutils/Makefile.am: Add libsframe.
	* binutils/Makefile.in: Regenerated.
	* configure: Regenerated
	* configure.ac: Add libsframe to host_libs.
	* libsframe/Makefile.am: New file.
	* libsframe/Makefile.in: New file.
	* libsframe/aclocal.m4: New file.
	* libsframe/config.h.in: New file.
	* libsframe/configure: New file.
	* libsframe/configure.ac: New file.
	* libsframe/sframe-error.c: New file.
	* libsframe/sframe-impl.h: New file.
	* libsframe/sframe.c: New file.

include/ChangeLog:

	* sframe-api.h: New file.

testsuite/ChangeLog:

	* libsframe/testsuite/Makefile.am: New file.
	* libsframe/testsuite/Makefile.in: Regenerated.
	* libsframe/testsuite/libsframe.decode/Makefile.am: New
	  file.
	* libsframe/testsuite/libsframe.decode/Makefile.in:
	  Regenerated.
	* libsframe/testsuite/libsframe.decode/decode.exp: New file.
	* libsframe/testsuite/libsframe.encode/Makefile.am:
	  Likewise.
	* libsframe/testsuite/libsframe.encode/Makefile.in:
	  Regenerated.
	* libsframe/testsuite/libsframe.encode/encode.exp: New file.
	* libsframe/testsuite/libsframe.encode/encode-1.c: Likewise.
	* libsframe/testsuite/libsframe.decode/be-flipping.c: Likewise.
	* libsframe/testsuite/libsframe.decode/frecnt-1.c: Likewise.
	* libsframe/testsuite/libsframe.decode/frecnt-2.c: Likewise.
	* libsframe/testsuite/libsframe.decode/DATA-BE: New file.
	* libsframe/testsuite/libsframe.decode/DATA1: Likewise.
	* libsframe/testsuite/libsframe.decode/DATA2: Likewise.

1 files changed, 231 insertions, 0 deletions

diff --git a/include/sframe-api.h b/include/sframe-api.h
new file mode 100644
index 00000000000..f0924dc91e3
--- /dev/null
+++ b/include/sframe-api.h
@@ -0,0 +1,231 @@
+/* Public API to SFrame.
+
+   Copyright (C) 2022 Free Software Foundation, Inc.
+
+   This file is part of libsframe.
+
+   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/>.  */
+
+#ifndef	_SFRAME_API_H
+#define	_SFRAME_API_H
+
+#include <sframe.h>
+
+#ifdef	__cplusplus
+extern "C"
+{
+#endif
+
+typedef struct sframe_decoder_ctx sframe_decoder_ctx;
+typedef struct sframe_encoder_ctx sframe_encoder_ctx;
+
+#define MAX_OFFSET_BYTES (SFRAME_FRE_OFFSET_4B * 2 * 3)
+
+/* User interfacing SFrame Row Entry.
+   An abstraction provided by libsframe so the consumer is decoupled from
+   the binary format representation of the same.  */
+
+typedef struct sframe_frame_row_entry
+{
+  uint32_t fre_start_addr;
+  unsigned char fre_info;
+  unsigned char fre_offsets[MAX_OFFSET_BYTES];
+} sframe_frame_row_entry;
+
+#define SFRAME_ERR ((int) -1)
+
+/* This macro holds information about all the available SFrame
+   errors.  It is used to form both an enum holding all the error
+   constants, and also the error strings themselves.  To use, define
+   _SFRAME_FIRST and _SFRAME_ITEM to expand as you like, then
+   mention the macro name.  See the enum after this for an example.  */
+#define _SFRAME_ERRORS \
+  _SFRAME_FIRST (SFRAME_ERR_VERSION_INVAL, "SFrame version not supported.") \
+  _SFRAME_ITEM (SFRAME_ERR_NOMEM, "Out of Memory.") \
+  _SFRAME_ITEM (SFRAME_ERR_INVAL, "Corrupt SFrame.") \
+  _SFRAME_ITEM (SFRAME_ERR_BUF_INVAL, "Buffer does not contain SFrame data.") \
+  _SFRAME_ITEM (SFRAME_ERR_DCTX_INVAL, "Corrupt SFrame decoder.") \
+  _SFRAME_ITEM (SFRAME_ERR_ECTX_INVAL, "Corrupt SFrame encoder.") \
+  _SFRAME_ITEM (SFRAME_ERR_FDE_INVAL, "Corrput FDE.") \
+  _SFRAME_ITEM (SFRAME_ERR_FRE_INVAL, "Corrupt FRE.") \
+  _SFRAME_ITEM (SFRAME_ERR_FDE_NOTFOUND,"FDE not found.") \
+  _SFRAME_ITEM (SFRAME_ERR_FDE_NOTSORTED, "FDEs not sorted.") \
+  _SFRAME_ITEM (SFRAME_ERR_FRE_NOTFOUND,"FRE not found.") \
+  _SFRAME_ITEM (SFRAME_ERR_FREOFFSET_NOPRESENT,"FRE offset not present.")
+
+#define	SFRAME_ERR_BASE	2000	/* Base value for libsframe errnos.  */
+
+enum
+  {
+#define _SFRAME_FIRST(NAME, STR) NAME = SFRAME_ERR_BASE
+#define _SFRAME_ITEM(NAME, STR) , NAME
+_SFRAME_ERRORS
+#undef _SFRAME_ITEM
+#undef _SFRAME_FIRST
+  };
+
+/* Count of SFrame errors.  */
+#define SFRAME_ERR_NERR (SFRAME_ERR_FREOFFSET_NOPRESENT - SFRAME_ERR_BASE + 1)
+
+/* Get the error message string.  */
+
+extern const char *
+sframe_errmsg (int error);
+
+/* Get FDE function info given a FRE_TYPE.  */
+
+extern unsigned char
+sframe_fde_func_info (unsigned int fre_type, unsigned int fde_type);
+
+/* Gather the FRE type given the function size.  */
+
+extern unsigned int
+sframe_calc_fre_type (unsigned int func_size);
+
+/* The SFrame Decoder.  */
+
+/* Decode the specified SFrame buffer CF_BUF of size CF_SIZE and return the
+   new SFrame decoder context.  Sets ERRP for the caller if any error.  */
+extern sframe_decoder_ctx *
+sframe_decode (const char *cf_buf, size_t cf_size, int *errp);
+
+/* Free the decoder context.  */
+extern void
+sframe_decoder_free (sframe_decoder_ctx **dctx);
+
+/* Get the size of the SFrame header from the decoder context DCTX.  */
+extern unsigned int
+sframe_decoder_get_hdr_size (sframe_decoder_ctx *dctx);
+
+/* Get the SFrame's abi/arch info.  */
+extern unsigned char
+sframe_decoder_get_abi_arch (sframe_decoder_ctx *dctx);
+
+/* Return the number of function descriptor entries in the SFrame decoder
+   DCTX.  */
+unsigned int
+sframe_decoder_get_num_fidx (sframe_decoder_ctx *dctx);
+
+/* Get the fixed FP offset from the decoder context DCTX.  */
+extern int8_t
+sframe_decoder_get_fixed_fp_offset (sframe_decoder_ctx *dctx);
+
+/* Get the fixed RA offset from the decoder context DCTX.  */
+extern int8_t
+sframe_decoder_get_fixed_ra_offset (sframe_decoder_ctx *dctx);
+
+/* Find the function descriptor entry which contains the specified address.  */
+extern sframe_func_desc_entry *
+sframe_get_funcdesc_with_addr (sframe_decoder_ctx *dctx,
+			       int32_t addr, int *errp);
+
+/* Find the SFrame Frame Row Entry which contains the PC.  Returns
+   SFRAME_ERR if failure.  */
+
+extern int
+sframe_find_fre (sframe_decoder_ctx *ctx, int32_t pc,
+		 sframe_frame_row_entry *frep);
+
+/* Get the FRE_IDX'th FRE of the function at FUNC_IDX'th function
+   index entry in the SFrame decoder CTX.  Returns error code as
+   applicable.  */
+extern int
+sframe_decoder_get_fre (sframe_decoder_ctx *ctx,
+			unsigned int func_idx,
+			unsigned int fre_idx,
+			sframe_frame_row_entry *fre);
+
+/* Get the data (NUM_FRES, FUNC_START_ADDRESS) from the function
+   descriptor entry at index I'th in the decoder CTX.  If failed,
+   return error code.  */
+extern int
+sframe_decoder_get_funcdesc (sframe_decoder_ctx *ctx,
+			     unsigned int i,
+			     uint32_t *num_fres,
+			     uint32_t *func_size,
+			     int32_t *func_start_address,
+			     unsigned char *func_info);
+
+
+/* Get the base reg id from the FRE info.  Sets errp if fails.  */
+extern unsigned int
+sframe_fre_get_base_reg_id (sframe_frame_row_entry *fre, int *errp);
+
+/* Get the CFA offset from the FRE.  If the offset is invalid, sets errp.  */
+extern int32_t
+sframe_fre_get_cfa_offset (sframe_decoder_ctx *dtcx,
+			   sframe_frame_row_entry *fre, int *errp);
+
+/* Get the FP offset from the FRE.  If the offset is invalid, sets errp.  */
+extern int32_t
+sframe_fre_get_fp_offset (sframe_decoder_ctx *dctx,
+			  sframe_frame_row_entry *fre, int *errp);
+
+/* Get the RA offset from the FRE.  If the offset is invalid, sets errp.  */
+extern int32_t
+sframe_fre_get_ra_offset (sframe_decoder_ctx *dctx,
+			  sframe_frame_row_entry *fre, int *errp);
+
+/* The SFrame Encoder.  */
+
+/* Create an encoder context with the given SFrame format version VER, FLAGS
+   and ABI information.  Sets errp if failure.  */
+extern sframe_encoder_ctx *
+sframe_encode (unsigned char ver, unsigned char flags, int abi,
+	       int8_t fixed_fp_offset, int8_t fixed_ra_offset, int *errp);
+
+/* Free the encoder context.  */
+extern void
+sframe_free_encoder (sframe_encoder_ctx *encoder);
+
+/* Get the size of the SFrame header from the encoder ctx ENCODER.  */
+extern unsigned int
+sframe_encoder_get_hdr_size (sframe_encoder_ctx *encoder);
+
+/* Get the abi/arch info from the SFrame encoder context CTX.  */
+extern unsigned char
+sframe_encoder_get_abi_arch (sframe_encoder_ctx *encoder);
+
+/* Return the number of function descriptor entries in the SFrame encoder
+   ENCODER.  */
+extern unsigned int
+sframe_encoder_get_num_fidx (sframe_encoder_ctx *encoder);
+
+/* Add an FRE to function at FUNC_IDX'th function descriptor index entry in
+   the encoder context.  */
+extern int
+sframe_encoder_add_fre (sframe_encoder_ctx *encoder,
+			unsigned int func_idx,
+			sframe_frame_row_entry *frep);
+
+/* Add a new function descriptor entry with START_ADDR, FUNC_SIZE and NUM_FRES
+   to the encoder.  */
+extern int
+sframe_encoder_add_funcdesc (sframe_encoder_ctx *encoder,
+			     int32_t start_addr,
+			     uint32_t func_size,
+			     unsigned char func_info,
+			     uint32_t num_fres);
+
+/* Serialize the contents of the encoder and return the buffer.  ENCODED_SIZE
+   is updated to the size of the buffer.  Sets ERRP if failure.  */
+extern char  *
+sframe_encoder_write (sframe_encoder_ctx *encoder,
+		      size_t *encoded_size, int *errp);
+
+#ifdef	__cplusplus
+}
+#endif
+
+#endif				/* _SFRAME_API_H */