include/sframe-api.h

   1 /* Public API to SFrame.
   2
   3    Copyright (C) 2022-2023 Free Software Foundation, Inc.
   4
   5    This file is part of libsframe.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  19
  20 #ifndef _SFRAME_API_H
  21 #define _SFRAME_API_H
  22
  23 #include <sframe.h>
  24 #include <stdbool.h>
  25
  26 #ifdef  __cplusplus
  27 extern "C"
  28 {
  29 #endif
  30
  31 typedef struct sframe_decoder_ctx sframe_decoder_ctx;
  32 typedef struct sframe_encoder_ctx sframe_encoder_ctx;
  33
  34 #define MAX_NUM_STACK_OFFSETS   3
  35
  36 #define MAX_OFFSET_BYTES  \
  37   ((SFRAME_FRE_OFFSET_4B * 2 * MAX_NUM_STACK_OFFSETS))
  38
  39 /* User interfacing SFrame Row Entry.
  40    An abstraction provided by libsframe so the consumer is decoupled from
  41    the binary format representation of the same.
  42
  43    The members are best ordered such that they are aligned at their natural
  44    boundaries.  This helps avoid usage of undesirable misaligned memory
  45    accesses.  See PR libsframe/29856.  */
  46
  47 typedef struct sframe_frame_row_entry
  48 {
  49   uint32_t fre_start_addr;
  50   unsigned char fre_offsets[MAX_OFFSET_BYTES];
  51   unsigned char fre_info;
  52 } sframe_frame_row_entry;
  53
  54 #define SFRAME_ERR ((int) -1)
  55
  56 /* This macro holds information about all the available SFrame
  57    errors.  It is used to form both an enum holding all the error
  58    constants, and also the error strings themselves.  To use, define
  59    _SFRAME_FIRST and _SFRAME_ITEM to expand as you like, then
  60    mention the macro name.  See the enum after this for an example.  */
  61 #define _SFRAME_ERRORS \
  62   _SFRAME_FIRST (SFRAME_ERR_VERSION_INVAL, "SFrame version not supported.") \
  63   _SFRAME_ITEM (SFRAME_ERR_NOMEM, "Out of Memory.") \
  64   _SFRAME_ITEM (SFRAME_ERR_INVAL, "Corrupt SFrame.") \
  65   _SFRAME_ITEM (SFRAME_ERR_BUF_INVAL, "Buffer does not contain SFrame data.") \
  66   _SFRAME_ITEM (SFRAME_ERR_DCTX_INVAL, "Corrupt SFrame decoder.") \
  67   _SFRAME_ITEM (SFRAME_ERR_ECTX_INVAL, "Corrupt SFrame encoder.") \
  68   _SFRAME_ITEM (SFRAME_ERR_FDE_INVAL, "Corrput FDE.") \
  69   _SFRAME_ITEM (SFRAME_ERR_FRE_INVAL, "Corrupt FRE.") \
  70   _SFRAME_ITEM (SFRAME_ERR_FDE_NOTFOUND,"FDE not found.") \
  71   _SFRAME_ITEM (SFRAME_ERR_FDE_NOTSORTED, "FDEs not sorted.") \
  72   _SFRAME_ITEM (SFRAME_ERR_FRE_NOTFOUND,"FRE not found.") \
  73   _SFRAME_ITEM (SFRAME_ERR_FREOFFSET_NOPRESENT,"FRE offset not present.")
  74
  75 #define SFRAME_ERR_BASE 2000    /* Base value for libsframe errnos.  */
  76
  77 enum
  78   {
  79 #define _SFRAME_FIRST(NAME, STR) NAME = SFRAME_ERR_BASE
  80 #define _SFRAME_ITEM(NAME, STR) , NAME
  81 _SFRAME_ERRORS
  82 #undef _SFRAME_ITEM
  83 #undef _SFRAME_FIRST
  84   };
  85
  86 /* Count of SFrame errors.  */
  87 #define SFRAME_ERR_NERR (SFRAME_ERR_FREOFFSET_NOPRESENT - SFRAME_ERR_BASE + 1)
  88
  89 /* Get the error message string.  */
  90
  91 extern const char *
  92 sframe_errmsg (int error);
  93
  94 /* Create an FDE function info bye given an FRE_TYPE and an FDE_TYPE.  */
  95
  96 extern unsigned char
  97 sframe_fde_create_func_info (unsigned int fre_type, unsigned int fde_type);
  98
  99 /* Gather the FRE type given the function size.  */
 100
 101 extern unsigned int
 102 sframe_calc_fre_type (size_t func_size);
 103
 104 /* The SFrame Decoder.  */
 105
 106 /* Decode the specified SFrame buffer CF_BUF of size CF_SIZE and return the
 107    new SFrame decoder context.  Sets ERRP for the caller if any error.  */
 108 extern sframe_decoder_ctx *
 109 sframe_decode (const char *cf_buf, size_t cf_size, int *errp);
 110
 111 /* Free the decoder context.  */
 112 extern void
 113 sframe_decoder_free (sframe_decoder_ctx **dctx);
 114
 115 /* Get the size of the SFrame header from the decoder context DCTX.  */
 116 extern unsigned int
 117 sframe_decoder_get_hdr_size (sframe_decoder_ctx *dctx);
 118
 119 /* Get the SFrame's abi/arch info.  */
 120 extern unsigned char
 121 sframe_decoder_get_abi_arch (sframe_decoder_ctx *dctx);
 122
 123 /* Return the number of function descriptor entries in the SFrame decoder
 124    DCTX.  */
 125 unsigned int
 126 sframe_decoder_get_num_fidx (sframe_decoder_ctx *dctx);
 127
 128 /* Get the fixed FP offset from the decoder context DCTX.  */
 129 extern int8_t
 130 sframe_decoder_get_fixed_fp_offset (sframe_decoder_ctx *dctx);
 131
 132 /* Get the fixed RA offset from the decoder context DCTX.  */
 133 extern int8_t
 134 sframe_decoder_get_fixed_ra_offset (sframe_decoder_ctx *dctx);
 135
 136 /* Find the function descriptor entry which contains the specified address.  */
 137 extern sframe_func_desc_entry *
 138 sframe_get_funcdesc_with_addr (sframe_decoder_ctx *dctx,
 139                                int32_t addr, int *errp);
 140
 141 /* Find the SFrame Frame Row Entry which contains the PC.  Returns
 142    SFRAME_ERR if failure.  */
 143
 144 extern int
 145 sframe_find_fre (sframe_decoder_ctx *ctx, int32_t pc,
 146                  sframe_frame_row_entry *frep);
 147
 148 /* Get the FRE_IDX'th FRE of the function at FUNC_IDX'th function
 149    index entry in the SFrame decoder CTX.  Returns error code as
 150    applicable.  */
 151 extern int
 152 sframe_decoder_get_fre (sframe_decoder_ctx *ctx,
 153                         unsigned int func_idx,
 154                         unsigned int fre_idx,
 155                         sframe_frame_row_entry *fre);
 156
 157 /* Get the data (NUM_FRES, FUNC_START_ADDRESS) from the function
 158    descriptor entry at index I'th in the decoder CTX.  If failed,
 159    return error code.  */
 160 extern int
 161 sframe_decoder_get_funcdesc (sframe_decoder_ctx *ctx,
 162                              unsigned int i,
 163                              uint32_t *num_fres,
 164                              uint32_t *func_size,
 165                              int32_t *func_start_address,
 166                              unsigned char *func_info);
 167
 168 /* SFrame textual dump.  */
 169 extern void
 170 dump_sframe (sframe_decoder_ctx *decoder, uint64_t addr);
 171
 172 /* Get the base reg id from the FRE info.  Sets errp if fails.  */
 173 extern unsigned int
 174 sframe_fre_get_base_reg_id (sframe_frame_row_entry *fre, int *errp);
 175
 176 /* Get the CFA offset from the FRE.  If the offset is invalid, sets errp.  */
 177 extern int32_t
 178 sframe_fre_get_cfa_offset (sframe_decoder_ctx *dtcx,
 179                            sframe_frame_row_entry *fre, int *errp);
 180
 181 /* Get the FP offset from the FRE.  If the offset is invalid, sets errp.  */
 182 extern int32_t
 183 sframe_fre_get_fp_offset (sframe_decoder_ctx *dctx,
 184                           sframe_frame_row_entry *fre, int *errp);
 185
 186 /* Get the RA offset from the FRE.  If the offset is invalid, sets errp.  */
 187 extern int32_t
 188 sframe_fre_get_ra_offset (sframe_decoder_ctx *dctx,
 189                           sframe_frame_row_entry *fre, int *errp);
 190
 191 /* Get whether the RA is mangled.  */
 192
 193 extern bool
 194 sframe_fre_get_ra_mangled_p (sframe_decoder_ctx *dctx,
 195                              sframe_frame_row_entry *fre, int *errp);
 196
 197 /* The SFrame Encoder.  */
 198
 199 /* Create an encoder context with the given SFrame format version VER, FLAGS
 200    and ABI information.  Sets errp if failure.  */
 201 extern sframe_encoder_ctx *
 202 sframe_encode (unsigned char ver, unsigned char flags, int abi,
 203                int8_t fixed_fp_offset, int8_t fixed_ra_offset, int *errp);
 204
 205 /* Free the encoder context.  */
 206 extern void
 207 sframe_encoder_free (sframe_encoder_ctx **encoder);
 208
 209 /* Get the size of the SFrame header from the encoder ctx ENCODER.  */
 210 extern unsigned int
 211 sframe_encoder_get_hdr_size (sframe_encoder_ctx *encoder);
 212
 213 /* Get the abi/arch info from the SFrame encoder context CTX.  */
 214 extern unsigned char
 215 sframe_encoder_get_abi_arch (sframe_encoder_ctx *encoder);
 216
 217 /* Return the number of function descriptor entries in the SFrame encoder
 218    ENCODER.  */
 219 extern unsigned int
 220 sframe_encoder_get_num_fidx (sframe_encoder_ctx *encoder);
 221
 222 /* Add an FRE to function at FUNC_IDX'th function descriptor index entry in
 223    the encoder context.  */
 224 extern int
 225 sframe_encoder_add_fre (sframe_encoder_ctx *encoder,
 226                         unsigned int func_idx,
 227                         sframe_frame_row_entry *frep);
 228
 229 /* Add a new function descriptor entry with START_ADDR, FUNC_SIZE and NUM_FRES
 230    to the encoder.  */
 231 extern int
 232 sframe_encoder_add_funcdesc (sframe_encoder_ctx *encoder,
 233                              int32_t start_addr,
 234                              uint32_t func_size,
 235                              unsigned char func_info,
 236                              uint32_t num_fres);
 237
 238 /* Serialize the contents of the encoder and return the buffer.  ENCODED_SIZE
 239    is updated to the size of the buffer.  Sets ERRP if failure.  */
 240 extern char  *
 241 sframe_encoder_write (sframe_encoder_ctx *encoder,
 242                       size_t *encoded_size, int *errp);
 243
 244 #ifdef  __cplusplus
 245 }
 246 #endif
 247
 248 #endif                          /* _SFRAME_API_H */