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