[PATCH,V6 01/10] ctf-frame.h: Add CTF Frame format definition

Indu Bhagat indu.bhagat@oracle.com
Tue Aug 2 08:04:43 GMT 2022


[Changes from V5]
 - Fix minor typos.
[End of changes from V5]

[Changes from V4]
 - Fix minor typos.
[End of changes from V4]

[Changes from V3]
  - CTF Format differentiates between the two possible FDE types using a
    bit in the fde_func_info byte - CTF_FRAME_DESCRIPTOR_ENTRY_TYPE_ADDRINC
    or CTF_FRAME_DESCRIPTOR_ENTRY_TYPE_ADDRMASK.
    The new CTF FDE type (CTF_FRAME_DESCRIPTOR_ENTRY_TYPE_ADDRMASK) is ideal
    for representing unwind information for regular, repetitive instruction
    patterns like plt entries.
[End of changes from V3]

[Changes from V2]
  - Consistent use of terminology.
[End of changes from V2]

[Changes from V1]
  - Make use of uint8_t, uint16_t consistently.  Removed the usage of
    unsigned char, unsigned short.
[End of changes from V1]

The header ctf-frame.h defines the CTF Frame format.

The CTF Frame format is a simple, compact format for representing
unwind information.  This information can be used for generating
backtraces.  The current version supports AMD64 and AARCH64.

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

include/ChangeLog:
	* ctf-frame.h: New file.
---
 include/ctf-frame.h | 281 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 281 insertions(+)
 create mode 100644 include/ctf-frame.h

diff --git a/include/ctf-frame.h b/include/ctf-frame.h
new file mode 100644
index 00000000000..fc46b8a06d1
--- /dev/null
+++ b/include/ctf-frame.h
@@ -0,0 +1,281 @@
+/* CTF Frame format description.
+   Copyright (C) 2022 Free Software Foundation, Inc.
+
+   This file is part of libctfframe.
+
+   libctfframe 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	_CTF_FRAME_H
+#define	_CTF_FRAME_H
+
+#include <sys/types.h>
+#include <limits.h>
+#include <stdint.h>
+
+
+#ifdef	__cplusplus
+extern "C"
+{
+#endif
+
+/* CTF Frame format.
+
+   CTF Frame format can be used to compactly represent the information needed
+   for virtual stack unwinding.  CTF Frame format keeps track of the minimal
+   necessary information needed for stack unwinding:
+     - Canonical Frame Address (CFA)
+     - Frame Pointer (FP)
+     - Return Address (RA)
+
+   The CTF Frame 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 CTF Frame 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.
+
+   */
+
+
+/* CTF Frame format versions.  */
+#define CTF_FRAME_VERSION_1	1
+/* CTF Frame magic number.  */
+#define CTF_FRAME_MAGIC		0xdee2
+/* Current version of CTF Frame format.  */
+#define CTF_FRAME_VERSION	CTF_FRAME_VERSION_1
+
+/* Various flags for CTF Frame.  */
+
+/* Function Descriptor Entries are sorted on PC.  */
+#define CTF_FRAME_F_FDE_SORTED	0x1
+/* Frame-pointer based unwinding.  */
+#define CTF_FRAME_F_FRAME_POINTER 0x2
+
+#define CTF_FRAME_CFA_FIXED_FP_INVALID 0
+#define CTF_FRAME_CFA_FIXED_RA_INVALID 0
+
+/* Supported ABIs/Arch.  */
+#define CTF_FRAME_ABI_AARCH64_ENDIAN_BIG      1 /* AARCH64 big endian.  */
+#define CTF_FRAME_ABI_AARCH64_ENDIAN_LITTLE   2 /* AARCH64 little endian.  */
+#define CTF_FRAME_ABI_AMD64_ENDIAN_LITTLE     3 /* AMD64 little endian.  */
+
+/* CTF Frame FRE types.  */
+#define CTF_FRAME_ROW_ENTRY_TYPE_ADDR1  1
+#define CTF_FRAME_ROW_ENTRY_TYPE_ADDR2  2
+#define CTF_FRAME_ROW_ENTRY_TYPE_ADDR4	3
+
+/* CTF Frame Function Descriptor Entry types.
+
+   The CTF Frame 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.
+
+   A CTF FDE of type CTF_FRAME_FUNC_DESC_ENTRY_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.
+
+   A CTF FDE of type CTF_FRAME_FUNC_DESC_ENTRY_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 CTF_FRAME_FUNC_DESC_ENTRY_TYPE_PCINC   0
+/* Unwinders perform a (PC & FRE_START_ADDR_AS_MASK >= FRE_START_ADDR_AS_MASK)
+   to look up a matching FRE.  */
+#define CTF_FRAME_FUNC_DESC_ENTRY_TYPE_PCMASK  1
+
+typedef struct ctf_frame_preamble
+{
+  uint16_t ctfp_magic;	/* Magic number (CTF_FRAME_MAGIC).  */
+  uint8_t ctfp_version;	/* Data format version number (CTF_FRAME_VERSION).  */
+  uint8_t ctfp_flags;	/* Flags.  */
+} __attribute__ ((packed)) ctf_frame_preamble;
+
+typedef struct ctf_frame_header
+{
+  ctf_frame_preamble cth_frame_preamble;
+  /* Information about the arch (endianness) and ABI.  */
+  uint8_t cth_frame_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
+     CTF_FRAME_CFA_FIXED_FP_INVALID, and the individual FREs may provide
+     the applicable stack frame offset, if any.  */
+  int8_t cth_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 CTF_FRAME_CFA_FIXED_RA_INVALID, and individual
+     FREs provide the applicable stack frame offset, if any.  */
+  int8_t cth_cfa_fixed_ra_offset;
+  /* Number of CTF FDEs in this CTF Frame section.  May be useful for
+     debugging.  */
+  uint32_t cth_num_fdes;
+  /* Number of CTF Frame row entries.  */
+  uint32_t cth_num_fres;
+  /* Number of bytes in the CTF Frame Row Entry section. */
+  uint32_t cth_fre_len;
+  /* Offset of CTF function descriptor entry section.  */
+  uint32_t cth_fdeoff;
+  /* Offset of CTF Frame Row Entry section.  */
+  uint32_t cth_freoff;
+} __attribute__ ((packed)) ctf_frame_header;
+
+typedef struct ctf_frame_func_desc_entry
+{
+  /* Function start address.  Encoded as a signed offset, relative to the
+     beginning of the current FDE.  */
+  int32_t ctf_func_start_address;
+  /* Size of the function in bytes.  */
+  uint32_t ctf_func_size;
+  /* Offset of the first CTF Frame Row Entry of the function, relative to the
+     beginning of the CTF Frame Row Entry sub-section.  */
+  uint32_t ctf_func_start_fre_off;
+  /* Number of frame row entries for the function.  */
+  uint32_t ctf_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 ctf_func_info;
+} __attribute__ ((packed)) ctf_frame_func_desc_entry;
+
+/* Macros to compose and decompose function info in FDE.  */
+
+#define CTF_FRAME_V1_FUNC_INFO(fde_type, fre_enc_type) \
+  (((fde_type) & 0x1) << 4 | (fre_enc_type))
+
+#define CTF_FRAME_V1_FUNC_FRE_TYPE(data)	  ((data) & 0xf)
+#define CTF_FRAME_V1_FUNC_FDE_TYPE(data)	  ((data >> 4) & 0x1)
+
+/* Size of stack frame offsets in a CTF Frame Row Entry.  A single CTF Frame
+   row entry has all offsets of the same size.  Offset size may vary across
+   frame row entries.  */
+#define CTF_FRAME_FRE_OFFSET_1B	  0
+#define CTF_FRAME_FRE_OFFSET_2B	  1
+#define CTF_FRAME_FRE_OFFSET_4B	  2
+
+/* A CTF Frame Row Entry can be SP or FP based.  */
+#define CTF_FRAME_BASE_REG_FP	0
+#define CTF_FRAME_BASE_REG_SP	1
+
+/* The index at which a specific offset is presented in the variable length
+   bytes of an FRE.  */
+#define CTF_FRAME_FRE_CFA_OFFSET_IDX  0
+#define CTF_FRAME_FRE_FP_OFFSET_IDX   1
+#define CTF_FRAME_FRE_RA_OFFSET_IDX   2
+
+typedef struct ctf_frame_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 CTF_FRAME_FRE_OFFSET_1B, CTF_FRAME_FRE_OFFSET_2B,
+     CTF_FRAME_FRE_OFFSET_4B
+     - 1 bit: Unused.
+     -----------------------------------------------------------------------
+     |  Unused  |  Size of offsets   |   Number of offsets    |   base_reg |
+     -----------------------------------------------------------------------
+     8          7                    5                        1            0
+
+     */
+  uint8_t fre_info;
+} ctf_frame_fre_info;
+
+/* Macros to compose and decompose FRE info.  */
+
+#define CTF_FRAME_V1_FRE_INFO(base_reg_id, offset_num, offset_size) \
+  ((offset_size << 5) | (offset_num << 1) | (base_reg_id))
+
+#define CTF_FRAME_V1_FRE_CFA_BASE_REG_ID(data)	  ((data) & 0x1)
+#define CTF_FRAME_V1_FRE_OFFSET_COUNT(data)	  (((data) >> 1) & 0xf)
+#define CTF_FRAME_V1_FRE_OFFSET_SIZE(data)	  (((data) >> 5) & 0x3)
+
+/* CTF Frame Row Entry definitions.
+
+   Used for both AMD64 and AARCH64.
+
+   A CTF Frame Row Entry is a self-sufficient record containing CTF Frame
+   unwind info for a range of addresses, starting at the specified offset in
+   the function.  Each CTF 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)
+   offset2 (interpreted as FP = CFA + offset2)
+   offset3 (interpreted as RA = CFA + offset3)
+*/
+
+typedef struct ctf_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 ctf_fre_start_address;
+  ctf_frame_fre_info ctf_fre_info;
+} __attribute__ ((packed)) ctf_frame_row_entry_addr1;
+
+typedef struct ctf_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 ctf_fre_start_address;
+  ctf_frame_fre_info ctf_fre_info;
+} __attribute__ ((packed)) ctf_frame_row_entry_addr2;
+
+typedef struct ctf_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 ctf_fre_start_address;
+  ctf_frame_fre_info ctf_fre_info;
+} __attribute__ ((packed)) ctf_frame_row_entry_addr4;
+
+#ifdef	__cplusplus
+}
+#endif
+
+#endif				/* _CTF_FRAME_H */
-- 
2.37.1



More information about the Binutils mailing list