sframe.h: Add SFrame format definition

The header sframe.h defines the SFrame format.

The SFrame format is the Simple Frame format.  It can be used to
represent the minimal necessary unwind information required for
backtracing.  The current version supports AMD64 and AARCH64.

More details of the SFrame format are included in the documentation
of the header file in this patch.

include/ChangeLog:
	* sframe.h: New file.

1 files changed, 303 insertions, 0 deletions

diff --git a/include/sframe.h b/include/sframe.h
new file mode 100644
index 0000000..7e31284
--- /dev/null
+++ b/include/sframe.h
@@ -0,0 +1,303 @@
+/* SFrame format description.
+   Copyright (C) 2022 Free Software Foundation, Inc.
+
+   This file is part of libsframe.
+
+   libsframe 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, 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
+   <http://www.gnu.org/licenses/>.  */
+
+#ifndef	_SFRAME_H
+#define	_SFRAME_H
+
+#include <sys/types.h>
+#include <limits.h>
+#include <stdint.h>
+
+#include "ansidecl.h"
+
+#ifdef	__cplusplus
+extern "C"
+{
+#endif
+
+/* SFrame format.
+
+   SFrame format is a simple format to represent the information needed
+   for vanilla virtual stack unwinding.  SFrame format keeps track of the
+   minimal necessary information needed for stack unwinding:
+     - Canonical Frame Address (CFA)
+     - Frame Pointer (FP)
+     - Return Address (RA)
+
+   The SFrame section itself has the following structure:
+
+       +--------+------------+---------+
+       |  file  |  function  | frame   |
+       | header | descriptor |  row    |
+       |        |   entries  | entries |
+       +--------+------------+---------+
+
+   The file header stores a magic number and version information, flags, and
+   the byte offset of each of the sections relative to the end of the header
+   itself.  The file header also specifies the total number of Function
+   Descriptor Entries, Frame Row Entries and length of the FRE sub-section.
+
+   Following the header is a list of Function Descriptor Entries (FDEs).
+   This list may be sorted if the flags in the file header indicate it to be
+   so.  The sort order, if applicable, is the order of functions in the
+   .text.* sections in the resulting binary artifact.  Each Function
+   Descriptor Entry specifies the start PC of a function, the size in bytes
+   of the function and an offset to its first Frame Row Entry (FRE).  Each FDE
+   additionally also specifies the type of FRE it uses to encode the unwind
+   information.
+
+   Next, the Frame Row Entry section is a list of variable size records,
+   each of which represent SFrame unwind information for a set of PCs.  A
+   singular Frame Row Entry is a self-sufficient record with information on
+   how to virtually unwind the stack for the applicable set of PCs.
+
+   */
+
+
+/* SFrame format versions.  */
+#define SFRAME_VERSION_1	1
+/* SFrame magic number.  */
+#define SFRAME_MAGIC		0xdee2
+/* Current version of SFrame format.  */
+#define SFRAME_VERSION	SFRAME_VERSION_1
+
+/* Various flags for SFrame.  */
+
+/* Function Descriptor Entries are sorted on PC.  */
+#define SFRAME_F_FDE_SORTED	0x1
+/* Frame-pointer based unwinding.  */
+#define SFRAME_F_FRAME_POINTER 0x2
+
+#define SFRAME_CFA_FIXED_FP_INVALID 0
+#define SFRAME_CFA_FIXED_RA_INVALID 0
+
+/* Supported ABIs/Arch.  */
+#define SFRAME_ABI_AARCH64_ENDIAN_BIG      1 /* AARCH64 big endian.  */
+#define SFRAME_ABI_AARCH64_ENDIAN_LITTLE   2 /* AARCH64 little endian.  */
+#define SFRAME_ABI_AMD64_ENDIAN_LITTLE     3 /* AMD64 little endian.  */
+
+/* SFrame FRE types.  */
+#define SFRAME_FRE_TYPE_ADDR1	0
+#define SFRAME_FRE_TYPE_ADDR2	1
+#define SFRAME_FRE_TYPE_ADDR4	2
+
+/* SFrame Function Descriptor Entry types.
+
+   The SFrame format has two possible representations for functions.  The
+   choice of which type to use is made according to the instruction patterns
+   in the relevant program stub.
+
+   An SFrame FDE of type SFRAME_FDE_TYPE_PCINC is an indication
+   that the PCs in the FREs should be treated as increments in bytes.  This is
+   used for a bulk of the executable code of a program, which contains
+   instructions with no specific pattern.
+
+   An SFrame FDE of type 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 when a small pattern of instructions in a program stub is
+   repeatedly to cover a specific functionality.  Typical usescases are pltN
+   entries, trampolines etc.  */
+
+/* Unwinders perform a (PC >= FRE_START_ADDR) to look up a matching FRE.  */
+#define SFRAME_FDE_TYPE_PCINC   0
+/* Unwinders perform a (PC & FRE_START_ADDR_AS_MASK >= FRE_START_ADDR_AS_MASK)
+   to look up a matching FRE.  */
+#define SFRAME_FDE_TYPE_PCMASK  1
+
+typedef struct sframe_preamble
+{
+  uint16_t sfp_magic;	/* Magic number (SFRAME_MAGIC).  */
+  uint8_t sfp_version;	/* Data format version number (SFRAME_VERSION).  */
+  uint8_t sfp_flags;	/* Flags.  */
+} ATTRIBUTE_PACKED sframe_preamble;
+
+typedef struct sframe_header
+{
+  sframe_preamble sfh_preamble;
+  /* Information about the arch (endianness) and ABI.  */
+  uint8_t sfh_abi_arch;
+  /* Offset for the Frame Pointer (FP) from CFA may be fixed for some
+     ABIs (e.g, in AMD64 when -fno-omit-frame-pointer is used).  When fixed,
+     this field specifies the fixed stack frame offset and the individual
+     FREs do not need to track it.  When not fixed, it is set to
+     SFRAME_CFA_FIXED_FP_INVALID, and the individual FREs may provide
+     the applicable stack frame offset, if any.  */
+  int8_t sfh_cfa_fixed_fp_offset;
+  /* Offset for the Return Address from CFA is fixed for some ABIs
+     (e.g., AMD64 has it as CFA-8).  When fixed, the header specifies the
+     fixed stack frame offset and the individual FREs do not track it.  When
+     not fixed, it is set to SFRAME_CFA_FIXED_RA_INVALID, and individual
+     FREs provide the applicable stack frame offset, if any.  */
+  int8_t sfh_cfa_fixed_ra_offset;
+  /* Number of bytes making up the auxilliary header, if any.
+     Some ABI/arch, in the future, may use this space for extending the
+     information in SFrame header.  Auxilliary header is contained in
+     bytes sequentially following the sframe_header.  */
+  uint8_t sfh_auxhdr_len;
+  /* Number of SFrame FDEs in this SFrame section.  */
+  uint32_t sfh_num_fdes;
+  /* Number of SFrame Frame Row Entries.  */
+  uint32_t sfh_num_fres;
+  /* Number of bytes in the SFrame Frame Row Entry section. */
+  uint32_t sfh_fre_len;
+  /* Offset of SFrame Function Descriptor Entry section.  */
+  uint32_t sfh_fdeoff;
+  /* Offset of SFrame Frame Row Entry section.  */
+  uint32_t sfh_freoff;
+} ATTRIBUTE_PACKED sframe_header;
+
+#define SFRAME_V1_HDR_SIZE(sframe_hdr)	\
+  ((sizeof (sframe_header) + (sframe_hdr).sfh_auxhdr_len))
+
+typedef struct sframe_func_desc_entry
+{
+  /* Function start address.  Encoded as a signed offset, relative to the
+     beginning of the current FDE.  */
+  int32_t sfde_func_start_address;
+  /* Size of the function in bytes.  */
+  uint32_t sfde_func_size;
+  /* Offset of the first SFrame Frame Row Entry of the function, relative to the
+     beginning of the SFrame Frame Row Entry sub-section.  */
+  uint32_t sfde_func_start_fre_off;
+  /* Number of frame row entries for the function.  */
+  uint32_t sfde_func_num_fres;
+  /* Additional information for deciphering the unwind information for the
+     function.
+     - 4-bits: Identify the FRE type used for the function.
+     - 1-bit: Identify the FDE type of the function - mask or inc.
+     - 3-bits: Unused.
+     --------------------------------------------
+     |     Unused    |  FDE type |   FRE type   |
+     --------------------------------------------
+     8               5           4              0     */
+  uint8_t sfde_func_info;
+} ATTRIBUTE_PACKED sframe_func_desc_entry;
+
+/* Macros to compose and decompose function info in FDE.  */
+
+#define SFRAME_V1_FUNC_INFO(fde_type, fre_enc_type) \
+  (((fde_type) & 0x1) << 4 | (fre_enc_type))
+
+#define SFRAME_V1_FUNC_FRE_TYPE(data)	  ((data) & 0xf)
+#define SFRAME_V1_FUNC_FDE_TYPE(data)	  ((data >> 4) & 0x1)
+
+/* Size of stack frame offsets in an SFrame Frame Row Entry.  A single
+   SFrame FRE has all offsets of the same size.  Offset size may vary
+   across frame row entries.  */
+#define SFRAME_FRE_OFFSET_1B	  0
+#define SFRAME_FRE_OFFSET_2B	  1
+#define SFRAME_FRE_OFFSET_4B	  2
+
+/* An SFrame Frame Row Entry can be SP or FP based.  */
+#define SFRAME_BASE_REG_FP	0
+#define SFRAME_BASE_REG_SP	1
+
+/* The index at which a specific offset is presented in the variable length
+   bytes of an FRE.  */
+#define SFRAME_FRE_CFA_OFFSET_IDX   0
+/* The RA stack offset, if present, will always be at index 1 in the variable
+   length bytes of the FRE.  */
+#define SFRAME_FRE_RA_OFFSET_IDX    1
+/* The FP stack offset may appear at offset 1 or 2, depending on the ABI as RA
+   may or may not be tracked.  */
+#define SFRAME_FRE_FP_OFFSET_IDX    2
+
+typedef struct sframe_fre_info
+{
+  /* Information about
+     - 1 bit: base reg for CFA
+     - 4 bits: Number of offsets (N).  A value of upto 3 is allowed to track
+     all three of CFA, FP and RA (fixed implicit order).
+     - 2 bits: information about size of the offsets (S) in bytes.
+     Valid values are SFRAME_FRE_OFFSET_1B, SFRAME_FRE_OFFSET_2B,
+     SFRAME_FRE_OFFSET_4B
+     - 1 bit: Unused.
+     -----------------------------------------------------------------------
+     |  Unused  |  Size of offsets   |   Number of offsets    |   base_reg |
+     -----------------------------------------------------------------------
+     8          7                    5                        1            0
+
+     */
+  uint8_t fre_info;
+} sframe_fre_info;
+
+/* Macros to compose and decompose FRE info.  */
+
+#define SFRAME_V1_FRE_INFO(base_reg_id, offset_num, offset_size) \
+  ((offset_size << 5) | (offset_num << 1) | (base_reg_id))
+
+#define SFRAME_V1_FRE_CFA_BASE_REG_ID(data)	  ((data) & 0x1)
+#define SFRAME_V1_FRE_OFFSET_COUNT(data)	  (((data) >> 1) & 0xf)
+#define SFRAME_V1_FRE_OFFSET_SIZE(data)	  (((data) >> 5) & 0x3)
+
+/* SFrame Frame Row Entry definitions.
+
+   Used for both AMD64 and AARCH64.
+
+   An SFrame Frame Row Entry is a self-sufficient record containing SFrame
+   unwind info for a range of addresses, starting at the specified offset in
+   the function.  Each SFrame Frame Row Entry is followed by S*N bytes, where:
+     S is the size of the stack frame offset for the FRE, and
+     N is the number of stack frame offsets in the FRE
+
+   The offsets are interpreted in order as follows:
+
+    offset1 (interpreted as CFA = BASE_REG + offset1)
+
+    if RA is being tracked
+      offset2 (interpreted as RA = CFA + offset2)
+      if FP is being tracked
+	offset3 (intrepreted as FP = CFA + offset2)
+      fi
+    else
+      if FP is being tracked
+	offset2 (intrepreted as FP = CFA + offset2)
+      fi
+    fi
+*/
+
+typedef struct sframe_frame_row_entry_addr1
+{
+  /* Start address of the frame row entry.  Encoded as an 1-byte unsigned
+     offset, relative to the start address of the function.  */
+  uint8_t sfre_start_address;
+  sframe_fre_info sfre_info;
+} ATTRIBUTE_PACKED sframe_frame_row_entry_addr1;
+
+typedef struct sframe_frame_row_entry_addr2
+{
+  /* Start address of the frame row entry.  Encoded as an 2-byte unsigned
+     offset, relative to the start address of the function.  */
+  uint16_t sfre_start_address;
+  sframe_fre_info sfre_info;
+} ATTRIBUTE_PACKED sframe_frame_row_entry_addr2;
+
+typedef struct sframe_frame_row_entry_addr4
+{
+  /* Start address of the frame row entry.  Encoded as a 4-byte unsigned
+     offset, relative to the start address of the function.  */
+  uint32_t sfre_start_address;
+  sframe_fre_info sfre_info;
+} ATTRIBUTE_PACKED sframe_frame_row_entry_addr4;
+
+#ifdef	__cplusplus
+}
+#endif
+
+#endif				/* _SFRAME_H */