include/sframe.h

   1 /* SFrame format description.
   2    Copyright (C) 2022-2023 Free Software Foundation, Inc.
   3
   4    This file is part of libsframe.
   5
   6    libsframe is free software; you can redistribute it and/or modify it
   7    under the terms of the GNU General Public License as published by the Free
   8    Software Foundation; either version 3, or (at your option) any later
   9    version.
  10
  11    This program is distributed in the hope that it will be useful, but
  12    WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  14    See the GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; see the file COPYING.  If not see
  18    <http://www.gnu.org/licenses/>.  */
  19
  20 #ifndef _SFRAME_H
  21 #define _SFRAME_H
  22
  23 #include <sys/types.h>
  24 #include <limits.h>
  25 #include <stdint.h>
  26
  27 #include "ansidecl.h"
  28
  29 #ifdef  __cplusplus
  30 extern "C"
  31 {
  32 #endif
  33
  34 /* SFrame format.
  35
  36    SFrame format is a simple format to represent the information needed
  37    for vanilla virtual stack unwinding.  SFrame format keeps track of the
  38    minimal necessary information needed for stack unwinding:
  39      - Canonical Frame Address (CFA)
  40      - Frame Pointer (FP)
  41      - Return Address (RA)
  42
  43    The SFrame section itself has the following structure:
  44
  45        +--------+------------+---------+
  46        |  file  |  function  | frame   |
  47        | header | descriptor |  row    |
  48        |        |   entries  | entries |
  49        +--------+------------+---------+
  50
  51    The file header stores a magic number and version information, flags, and
  52    the byte offset of each of the sections relative to the end of the header
  53    itself.  The file header also specifies the total number of Function
  54    Descriptor Entries, Frame Row Entries and length of the FRE sub-section.
  55
  56    Following the header is a list of Function Descriptor Entries (FDEs).
  57    This list may be sorted if the flags in the file header indicate it to be
  58    so.  The sort order, if applicable, is the order of functions in the
  59    .text.* sections in the resulting binary artifact.  Each Function
  60    Descriptor Entry specifies the start PC of a function, the size in bytes
  61    of the function and an offset to its first Frame Row Entry (FRE).  Each FDE
  62    additionally also specifies the type of FRE it uses to encode the unwind
  63    information.
  64
  65    Next, the Frame Row Entry section is a list of variable size records,
  66    each of which represent SFrame unwind information for a set of PCs.  A
  67    singular Frame Row Entry is a self-sufficient record with information on
  68    how to virtually unwind the stack for the applicable set of PCs.
  69
  70    */
  71
  72
  73 /* SFrame format versions.  */
  74 #define SFRAME_VERSION_1        1
  75 /* SFrame magic number.  */
  76 #define SFRAME_MAGIC            0xdee2
  77 /* Current version of SFrame format.  */
  78 #define SFRAME_VERSION  SFRAME_VERSION_1
  79
  80 /* Various flags for SFrame.  */
  81
  82 /* Function Descriptor Entries are sorted on PC.  */
  83 #define SFRAME_F_FDE_SORTED     0x1
  84 /* Frame-pointer based unwinding.  */
  85 #define SFRAME_F_FRAME_POINTER 0x2
  86
  87 #define SFRAME_CFA_FIXED_FP_INVALID 0
  88 #define SFRAME_CFA_FIXED_RA_INVALID 0
  89
  90 /* Supported ABIs/Arch.  */
  91 #define SFRAME_ABI_AARCH64_ENDIAN_BIG      1 /* AARCH64 big endian.  */
  92 #define SFRAME_ABI_AARCH64_ENDIAN_LITTLE   2 /* AARCH64 little endian.  */
  93 #define SFRAME_ABI_AMD64_ENDIAN_LITTLE     3 /* AMD64 little endian.  */
  94
  95 /* SFrame FRE types.  */
  96 #define SFRAME_FRE_TYPE_ADDR1   0
  97 #define SFRAME_FRE_TYPE_ADDR2   1
  98 #define SFRAME_FRE_TYPE_ADDR4   2
  99
 100 /* SFrame Function Descriptor Entry types.
 101
 102    The SFrame format has two possible representations for functions.  The
 103    choice of which type to use is made according to the instruction patterns
 104    in the relevant program stub.
 105
 106    An SFrame FDE of type SFRAME_FDE_TYPE_PCINC is an indication
 107    that the PCs in the FREs should be treated as increments in bytes.  This is
 108    used for a bulk of the executable code of a program, which contains
 109    instructions with no specific pattern.
 110
 111    An SFrame FDE of type SFRAME_FDE_TYPE_PCMASK is an indication
 112    that the PCs in the FREs should be treated as masks.  This type is useful
 113    for the cases when a small pattern of instructions in a program stub is
 114    repeatedly to cover a specific functionality.  Typical usescases are pltN
 115    entries, trampolines etc.  */
 116
 117 /* Unwinders perform a (PC >= FRE_START_ADDR) to look up a matching FRE.  */
 118 #define SFRAME_FDE_TYPE_PCINC   0
 119 /* Unwinders perform a (PC & FRE_START_ADDR_AS_MASK >= FRE_START_ADDR_AS_MASK)
 120    to look up a matching FRE.  */
 121 #define SFRAME_FDE_TYPE_PCMASK  1
 122
 123 typedef struct sframe_preamble
 124 {
 125   uint16_t sfp_magic;   /* Magic number (SFRAME_MAGIC).  */
 126   uint8_t sfp_version;  /* Data format version number (SFRAME_VERSION).  */
 127   uint8_t sfp_flags;    /* Flags.  */
 128 } ATTRIBUTE_PACKED sframe_preamble;
 129
 130 typedef struct sframe_header
 131 {
 132   sframe_preamble sfh_preamble;
 133   /* Information about the arch (endianness) and ABI.  */
 134   uint8_t sfh_abi_arch;
 135   /* Offset for the Frame Pointer (FP) from CFA may be fixed for some
 136      ABIs (e.g, in AMD64 when -fno-omit-frame-pointer is used).  When fixed,
 137      this field specifies the fixed stack frame offset and the individual
 138      FREs do not need to track it.  When not fixed, it is set to
 139      SFRAME_CFA_FIXED_FP_INVALID, and the individual FREs may provide
 140      the applicable stack frame offset, if any.  */
 141   int8_t sfh_cfa_fixed_fp_offset;
 142   /* Offset for the Return Address from CFA is fixed for some ABIs
 143      (e.g., AMD64 has it as CFA-8).  When fixed, the header specifies the
 144      fixed stack frame offset and the individual FREs do not track it.  When
 145      not fixed, it is set to SFRAME_CFA_FIXED_RA_INVALID, and individual
 146      FREs provide the applicable stack frame offset, if any.  */
 147   int8_t sfh_cfa_fixed_ra_offset;
 148   /* Number of bytes making up the auxilliary header, if any.
 149      Some ABI/arch, in the future, may use this space for extending the
 150      information in SFrame header.  Auxilliary header is contained in
 151      bytes sequentially following the sframe_header.  */
 152   uint8_t sfh_auxhdr_len;
 153   /* Number of SFrame FDEs in this SFrame section.  */
 154   uint32_t sfh_num_fdes;
 155   /* Number of SFrame Frame Row Entries.  */
 156   uint32_t sfh_num_fres;
 157   /* Number of bytes in the SFrame Frame Row Entry section. */
 158   uint32_t sfh_fre_len;
 159   /* Offset of SFrame Function Descriptor Entry section.  */
 160   uint32_t sfh_fdeoff;
 161   /* Offset of SFrame Frame Row Entry section.  */
 162   uint32_t sfh_freoff;
 163 } ATTRIBUTE_PACKED sframe_header;
 164
 165 #define SFRAME_V1_HDR_SIZE(sframe_hdr)  \
 166   ((sizeof (sframe_header) + (sframe_hdr).sfh_auxhdr_len))
 167
 168 /* Two possible keys for executable (instruction) pointers signing.  */
 169 #define SFRAME_AARCH64_PAUTH_KEY_A    0 /* Key A.  */
 170 #define SFRAME_AARCH64_PAUTH_KEY_B    1 /* Key B.  */
 171
 172 typedef struct sframe_func_desc_entry
 173 {
 174   /* Function start address.  Encoded as a signed offset, relative to the
 175      beginning of the current FDE.  */
 176   int32_t sfde_func_start_address;
 177   /* Size of the function in bytes.  */
 178   uint32_t sfde_func_size;
 179   /* Offset of the first SFrame Frame Row Entry of the function, relative to the
 180      beginning of the SFrame Frame Row Entry sub-section.  */
 181   uint32_t sfde_func_start_fre_off;
 182   /* Number of frame row entries for the function.  */
 183   uint32_t sfde_func_num_fres;
 184   /* Additional information for deciphering the unwind information for the
 185      function.
 186      - 4-bits: Identify the FRE type used for the function.
 187      - 1-bit: Identify the FDE type of the function - mask or inc.
 188      - 1-bit: PAC authorization A/B key (aarch64).
 189      - 2-bits: Unused.
 190      ------------------------------------------------------------------------
 191      |     Unused    |  PAC auth A/B key (aarch64) |  FDE type |   FRE type   |
 192      |               |        Unused (amd64)       |           |              |
 193      ------------------------------------------------------------------------
 194      8               6                             5           4              0     */
 195   uint8_t sfde_func_info;
 196 } ATTRIBUTE_PACKED sframe_func_desc_entry;
 197
 198 /* Macros to compose and decompose function info in FDE.  */
 199
 200 /* Note: Set PAC auth key to SFRAME_AARCH64_PAUTH_KEY_A by default.  */
 201 #define SFRAME_V1_FUNC_INFO(fde_type, fre_enc_type) \
 202   (((SFRAME_AARCH64_PAUTH_KEY_A & 0x1) << 5) | \
 203    (((fde_type) & 0x1) << 4) | ((fre_enc_type) & 0xf))
 204
 205 #define SFRAME_V1_FUNC_FRE_TYPE(data)     ((data) & 0xf)
 206 #define SFRAME_V1_FUNC_FDE_TYPE(data)     (((data) >> 4) & 0x1)
 207 #define SFRAME_V1_FUNC_PAUTH_KEY(data)    (((data) >> 5) & 0x1)
 208
 209 /* Set the pauth key as indicated.  */
 210 #define SFRAME_V1_FUNC_INFO_UPDATE_PAUTH_KEY(pauth_key, fde_info) \
 211   ((((pauth_key) & 0x1) << 5) | ((fde_info) & 0xdf))
 212
 213 /* Size of stack frame offsets in an SFrame Frame Row Entry.  A single
 214    SFrame FRE has all offsets of the same size.  Offset size may vary
 215    across frame row entries.  */
 216 #define SFRAME_FRE_OFFSET_1B      0
 217 #define SFRAME_FRE_OFFSET_2B      1
 218 #define SFRAME_FRE_OFFSET_4B      2
 219
 220 /* An SFrame Frame Row Entry can be SP or FP based.  */
 221 #define SFRAME_BASE_REG_FP      0
 222 #define SFRAME_BASE_REG_SP      1
 223
 224 /* The index at which a specific offset is presented in the variable length
 225    bytes of an FRE.  */
 226 #define SFRAME_FRE_CFA_OFFSET_IDX   0
 227 /* The RA stack offset, if present, will always be at index 1 in the variable
 228    length bytes of the FRE.  */
 229 #define SFRAME_FRE_RA_OFFSET_IDX    1
 230 /* The FP stack offset may appear at offset 1 or 2, depending on the ABI as RA
 231    may or may not be tracked.  */
 232 #define SFRAME_FRE_FP_OFFSET_IDX    2
 233
 234 typedef struct sframe_fre_info
 235 {
 236   /* Information about
 237      - 1 bit: base reg for CFA
 238      - 4 bits: Number of offsets (N).  A value of upto 3 is allowed to track
 239      all three of CFA, FP and RA (fixed implicit order).
 240      - 2 bits: information about size of the offsets (S) in bytes.
 241      Valid values are SFRAME_FRE_OFFSET_1B, SFRAME_FRE_OFFSET_2B,
 242      SFRAME_FRE_OFFSET_4B
 243      - 1 bit: Mangled RA state bit (aarch64 only).
 244      ----------------------------------------------------------------------------------
 245      | Mangled-RA (aarch64) |  Size of offsets   |   Number of offsets    |   base_reg |
 246      |  Unused (amd64)      |                    |                        |            |
 247      ----------------------------------------------------------------------------------
 248      8                     7                    5                        1            0
 249
 250      */
 251   uint8_t fre_info;
 252 } sframe_fre_info;
 253
 254 /* Macros to compose and decompose FRE info.  */
 255
 256 /* Note: Set mangled_ra_p to zero by default.  */
 257 #define SFRAME_V1_FRE_INFO(base_reg_id, offset_num, offset_size) \
 258   (((0 & 0x1) << 7) | (((offset_size) & 0x3) << 5) | \
 259    (((offset_num) & 0xf) << 1) | ((base_reg_id) & 0x1))
 260
 261 /* Set the mangled_ra_p bit as indicated.  */
 262 #define SFRAME_V1_FRE_INFO_UPDATE_MANGLED_RA_P(mangled_ra_p, fre_info) \
 263   ((((mangled_ra_p) & 0x1) << 7) | ((fre_info) & 0x7f))
 264
 265 #define SFRAME_V1_FRE_CFA_BASE_REG_ID(data)       ((data) & 0x1)
 266 #define SFRAME_V1_FRE_OFFSET_COUNT(data)          (((data) >> 1) & 0xf)
 267 #define SFRAME_V1_FRE_OFFSET_SIZE(data)           (((data) >> 5) & 0x3)
 268 #define SFRAME_V1_FRE_MANGLED_RA_P(data)          (((data) >> 7) & 0x1)
 269
 270 /* SFrame Frame Row Entry definitions.
 271
 272    Used for both AMD64 and AARCH64.
 273
 274    An SFrame Frame Row Entry is a self-sufficient record containing SFrame
 275    unwind info for a range of addresses, starting at the specified offset in
 276    the function.  Each SFrame Frame Row Entry is followed by S*N bytes, where:
 277      S is the size of the stack frame offset for the FRE, and
 278      N is the number of stack frame offsets in the FRE
 279
 280    The offsets are interpreted in order as follows:
 281
 282     offset1 (interpreted as CFA = BASE_REG + offset1)
 283
 284     if RA is being tracked
 285       offset2 (interpreted as RA = CFA + offset2)
 286       if FP is being tracked
 287         offset3 (intrepreted as FP = CFA + offset2)
 288       fi
 289     else
 290       if FP is being tracked
 291         offset2 (intrepreted as FP = CFA + offset2)
 292       fi
 293     fi
 294 */
 295
 296 /* Used when SFRAME_FRE_TYPE_ADDR1 is specified as FRE type.  */
 297 typedef struct sframe_frame_row_entry_addr1
 298 {
 299   /* Start address of the frame row entry.  Encoded as an 1-byte unsigned
 300      offset, relative to the start address of the function.  */
 301   uint8_t sfre_start_address;
 302   sframe_fre_info sfre_info;
 303 } ATTRIBUTE_PACKED sframe_frame_row_entry_addr1;
 304
 305 /* Upper limit of start address in sframe_frame_row_entry_addr1
 306    is 0x100 (not inclusive).  */
 307 #define SFRAME_FRE_TYPE_ADDR1_LIMIT  ((SFRAME_FRE_TYPE_ADDR1 + 1) * 8)
 308
 309 /* Used when SFRAME_FRE_TYPE_ADDR2 is specified as FRE type.  */
 310 typedef struct sframe_frame_row_entry_addr2
 311 {
 312   /* Start address of the frame row entry.  Encoded as an 2-byte unsigned
 313      offset, relative to the start address of the function.  */
 314   uint16_t sfre_start_address;
 315   sframe_fre_info sfre_info;
 316 } ATTRIBUTE_PACKED sframe_frame_row_entry_addr2;
 317
 318 /* Upper limit of start address in sframe_frame_row_entry_addr2
 319    is 0x10000 (not inclusive).  */
 320 #define SFRAME_FRE_TYPE_ADDR2_LIMIT  ((SFRAME_FRE_TYPE_ADDR2 * 2) * 8)
 321
 322 /* Used when SFRAME_FRE_TYPE_ADDR4 is specified as FRE type.  */
 323 typedef struct sframe_frame_row_entry_addr4
 324 {
 325   /* Start address of the frame row entry.  Encoded as a 4-byte unsigned
 326      offset, relative to the start address of the function.  */
 327   uint32_t sfre_start_address;
 328   sframe_fre_info sfre_info;
 329 } ATTRIBUTE_PACKED sframe_frame_row_entry_addr4;
 330
 331 /* Upper limit of start address in sframe_frame_row_entry_addr2
 332    is 0x100000000 (not inclusive).  */
 333 #define SFRAME_FRE_TYPE_ADDR4_LIMIT  ((SFRAME_FRE_TYPE_ADDR4 * 2) * 8)
 334
 335 #ifdef  __cplusplus
 336 }
 337 #endif
 338
 339 #endif                          /* _SFRAME_H */