include/sframe-api.h

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