source/include/sframe-api.h

0001 /* Public API to SFrame.
0002
0003    Copyright (C) 2022-2024 Free Software Foundation, Inc.
0004
0005    This file is part of libsframe.
0006
0007    This program is free software; you can redistribute it and/or modify
0008    it under the terms of the GNU General Public License as published by
0009    the Free Software Foundation; either version 3 of the License, or
0010    (at your option) any later version.
0011
0012    This program is distributed in the hope that it will be useful,
0013    but WITHOUT ANY WARRANTY; without even the implied warranty of
0014    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
0015    GNU General Public License for more details.
0016
0017    You should have received a copy of the GNU General Public License
0018    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
0019
0020 #ifndef _SFRAME_API_H
0021 #define _SFRAME_API_H
0022
0023 #include <sframe.h>
0024 #include <stdbool.h>
0025
0026 #ifdef  __cplusplus
0027 extern "C"
0028 {
0029 #endif
0030
0031 typedef struct sframe_decoder_ctx sframe_decoder_ctx;
0032 typedef struct sframe_encoder_ctx sframe_encoder_ctx;
0033
0034 #define MAX_NUM_STACK_OFFSETS   3
0035
0036 #define MAX_OFFSET_BYTES  \
0037   ((SFRAME_FRE_OFFSET_4B * 2 * MAX_NUM_STACK_OFFSETS))
0038
0039 /* User interfacing SFrame Row Entry.
0040    An abstraction provided by libsframe so the consumer is decoupled from
0041    the binary format representation of the same.
0042
0043    The members are best ordered such that they are aligned at their natural
0044    boundaries.  This helps avoid usage of undesirable misaligned memory
0045    accesses.  See PR libsframe/29856.  */
0046
0047 typedef struct sframe_frame_row_entry
0048 {
0049   uint32_t fre_start_addr;
0050   unsigned char fre_offsets[MAX_OFFSET_BYTES];
0051   unsigned char fre_info;
0052 } sframe_frame_row_entry;
0053
0054 #define SFRAME_ERR ((int) -1)
0055
0056 /* This macro holds information about all the available SFrame
0057    errors.  It is used to form both an enum holding all the error
0058    constants, and also the error strings themselves.  To use, define
0059    _SFRAME_FIRST and _SFRAME_ITEM to expand as you like, then
0060    mention the macro name.  See the enum after this for an example.  */
0061 #define _SFRAME_ERRORS \
0062   _SFRAME_FIRST (SFRAME_ERR_VERSION_INVAL, "SFrame version not supported.") \
0063   _SFRAME_ITEM (SFRAME_ERR_NOMEM, "Out of Memory.") \
0064   _SFRAME_ITEM (SFRAME_ERR_INVAL, "Corrupt SFrame.") \
0065   _SFRAME_ITEM (SFRAME_ERR_BUF_INVAL, "Buffer does not contain SFrame data.") \
0066   _SFRAME_ITEM (SFRAME_ERR_DCTX_INVAL, "Corrupt SFrame decoder.") \
0067   _SFRAME_ITEM (SFRAME_ERR_ECTX_INVAL, "Corrupt SFrame encoder.") \
0068   _SFRAME_ITEM (SFRAME_ERR_FDE_INVAL, "Corrput FDE.") \
0069   _SFRAME_ITEM (SFRAME_ERR_FRE_INVAL, "Corrupt FRE.") \
0070   _SFRAME_ITEM (SFRAME_ERR_FDE_NOTFOUND,"FDE not found.") \
0071   _SFRAME_ITEM (SFRAME_ERR_FDE_NOTSORTED, "FDEs not sorted.") \
0072   _SFRAME_ITEM (SFRAME_ERR_FRE_NOTFOUND,"FRE not found.") \
0073   _SFRAME_ITEM (SFRAME_ERR_FREOFFSET_NOPRESENT,"FRE offset not present.")
0074
0075 #define SFRAME_ERR_BASE 2000    /* Base value for libsframe errnos.  */
0076
0077 enum
0078   {
0079 #define _SFRAME_FIRST(NAME, STR) NAME = SFRAME_ERR_BASE
0080 #define _SFRAME_ITEM(NAME, STR) , NAME
0081 _SFRAME_ERRORS
0082 #undef _SFRAME_ITEM
0083 #undef _SFRAME_FIRST
0084   };
0085
0086 /* Count of SFrame errors.  */
0087 #define SFRAME_ERR_NERR (SFRAME_ERR_FREOFFSET_NOPRESENT - SFRAME_ERR_BASE + 1)
0088
0089 /* Get the error message string.  */
0090
0091 extern const char *
0092 sframe_errmsg (int error);
0093
0094 /* Create an FDE function info bye given an FRE_TYPE and an FDE_TYPE.  */
0095
0096 extern unsigned char
0097 sframe_fde_create_func_info (uint32_t fre_type, uint32_t fde_type);
0098
0099 /* Gather the FRE type given the function size.  */
0100
0101 extern uint32_t
0102 sframe_calc_fre_type (size_t func_size);
0103
0104 /* The SFrame Decoder.  */
0105
0106 /* Decode the specified SFrame buffer CF_BUF of size CF_SIZE and return the
0107    new SFrame decoder context.  Sets ERRP for the caller if any error.  */
0108 extern sframe_decoder_ctx *
0109 sframe_decode (const char *cf_buf, size_t cf_size, int *errp);
0110
0111 /* Free the decoder context.  */
0112 extern void
0113 sframe_decoder_free (sframe_decoder_ctx **dctx);
0114
0115 /* Get the size of the SFrame header from the decoder context DCTX.  */
0116 extern unsigned int
0117 sframe_decoder_get_hdr_size (sframe_decoder_ctx *dctx);
0118
0119 /* Get the SFrame's abi/arch info.  */
0120 extern uint8_t
0121 sframe_decoder_get_abi_arch (sframe_decoder_ctx *dctx);
0122
0123 /* Get the format version from the SFrame decoder context DCTX.  */
0124 extern uint8_t
0125 sframe_decoder_get_version (sframe_decoder_ctx *dctx);
0126
0127 /* Return the number of function descriptor entries in the SFrame decoder
0128    DCTX.  */
0129 extern uint32_t
0130 sframe_decoder_get_num_fidx (sframe_decoder_ctx *dctx);
0131
0132 /* Get the fixed FP offset from the decoder context DCTX.  */
0133 extern int8_t
0134 sframe_decoder_get_fixed_fp_offset (sframe_decoder_ctx *dctx);
0135
0136 /* Get the fixed RA offset from the decoder context DCTX.  */
0137 extern int8_t
0138 sframe_decoder_get_fixed_ra_offset (sframe_decoder_ctx *dctx);
0139
0140 /* Find the function descriptor entry which contains the specified address.
0141
0142    Note: This function is deprecated and will be removed from future release
0143    X+2 of the library.  */
0144 extern void *
0145 sframe_get_funcdesc_with_addr (sframe_decoder_ctx *dctx, int32_t addr,
0146                    int *errp);
0147
0148 /* Find the SFrame Frame Row Entry which contains the PC.  Returns
0149    SFRAME_ERR if failure.  */
0150
0151 extern int
0152 sframe_find_fre (sframe_decoder_ctx *ctx, int32_t pc,
0153          sframe_frame_row_entry *frep);
0154
0155 /* Get the FRE_IDX'th FRE of the function at FUNC_IDX'th function
0156    index entry in the SFrame decoder CTX.  Returns error code as
0157    applicable.  */
0158 extern int
0159 sframe_decoder_get_fre (sframe_decoder_ctx *ctx,
0160             unsigned int func_idx,
0161             unsigned int fre_idx,
0162             sframe_frame_row_entry *fre);
0163
0164 /* Get the data (NUM_FRES, FUNC_START_ADDRESS) from the function
0165    descriptor entry at index I'th in the decoder CTX.  If failed,
0166    return error code.  */
0167 extern int
0168 sframe_decoder_get_funcdesc (sframe_decoder_ctx *ctx,
0169                  unsigned int i,
0170                  uint32_t *num_fres,
0171                  uint32_t *func_size,
0172                  int32_t *func_start_address,
0173                  unsigned char *func_info);
0174
0175 /* Get the data (NUM_FRES, FUNC_SIZE, FUNC_START_ADDRESS, FUNC_INFO,
0176    REP_BLOCK_SIZE) from the function descriptor entry at index I'th
0177    in the decoder CTX.  If failed, return error code.
0178    This API is only available from SFRAME_VERSION_2.  */
0179 extern int
0180 sframe_decoder_get_funcdesc_v2 (sframe_decoder_ctx *ctx,
0181                 unsigned int i,
0182                 uint32_t *num_fres,
0183                 uint32_t *func_size,
0184                 int32_t *func_start_address,
0185                 unsigned char *func_info,
0186                 uint8_t *rep_block_size);
0187
0188 /* SFrame textual dump.  */
0189 extern void
0190 dump_sframe (sframe_decoder_ctx *decoder, uint64_t addr);
0191
0192 /* Get the base reg id from the FRE info.  Sets errp if fails.  */
0193 extern uint8_t
0194 sframe_fre_get_base_reg_id (sframe_frame_row_entry *fre, int *errp);
0195
0196 /* Get the CFA offset from the FRE.  If the offset is invalid, sets errp.  */
0197 extern int32_t
0198 sframe_fre_get_cfa_offset (sframe_decoder_ctx *dtcx,
0199                sframe_frame_row_entry *fre, int *errp);
0200
0201 /* Get the FP offset from the FRE.  If the offset is invalid, sets errp.  */
0202 extern int32_t
0203 sframe_fre_get_fp_offset (sframe_decoder_ctx *dctx,
0204               sframe_frame_row_entry *fre, int *errp);
0205
0206 /* Get the RA offset from the FRE.  If the offset is invalid, sets errp.  */
0207 extern int32_t
0208 sframe_fre_get_ra_offset (sframe_decoder_ctx *dctx,
0209               sframe_frame_row_entry *fre, int *errp);
0210
0211 /* Get whether the RA is mangled.  */
0212
0213 extern bool
0214 sframe_fre_get_ra_mangled_p (sframe_decoder_ctx *dctx,
0215                  sframe_frame_row_entry *fre, int *errp);
0216
0217 /* The SFrame Encoder.  */
0218
0219 /* Create an encoder context with the given SFrame format version VER, FLAGS
0220    and ABI information.  Sets errp if failure.  */
0221 extern sframe_encoder_ctx *
0222 sframe_encode (uint8_t ver, uint8_t flags, uint8_t abi_arch,
0223            int8_t fixed_fp_offset, int8_t fixed_ra_offset, int *errp);
0224
0225 /* Free the encoder context.  */
0226 extern void
0227 sframe_encoder_free (sframe_encoder_ctx **encoder);
0228
0229 /* Get the size of the SFrame header from the encoder ctx ENCODER.  */
0230 extern unsigned int
0231 sframe_encoder_get_hdr_size (sframe_encoder_ctx *encoder);
0232
0233 /* Get the abi/arch info from the SFrame encoder context CTX.  */
0234 extern uint8_t
0235 sframe_encoder_get_abi_arch (sframe_encoder_ctx *encoder);
0236
0237 /* Get the format version from the SFrame encoder context ENCODER.  */
0238 extern uint8_t
0239 sframe_encoder_get_version (sframe_encoder_ctx *encoder);
0240
0241 /* Return the number of function descriptor entries in the SFrame encoder
0242    ENCODER.  */
0243 extern uint32_t
0244 sframe_encoder_get_num_fidx (sframe_encoder_ctx *encoder);
0245
0246 /* Add an FRE to function at FUNC_IDX'th function descriptor index entry in
0247    the encoder context.  */
0248 extern int
0249 sframe_encoder_add_fre (sframe_encoder_ctx *encoder,
0250             unsigned int func_idx,
0251             sframe_frame_row_entry *frep);
0252
0253 /* Add a new function descriptor entry with START_ADDR, FUNC_SIZE and NUM_FRES
0254    to the encoder.  */
0255 extern int
0256 sframe_encoder_add_funcdesc (sframe_encoder_ctx *encoder,
0257                  int32_t start_addr,
0258                  uint32_t func_size,
0259                  unsigned char func_info,
0260                  uint32_t num_fres);
0261
0262 /* Add a new function descriptor entry with START_ADDR, FUNC_SIZE, FUNC_INFO
0263    and REP_BLOCK_SIZE to the encoder.  */
0264 extern int
0265 sframe_encoder_add_funcdesc_v2 (sframe_encoder_ctx *encoder,
0266                 int32_t start_addr,
0267                 uint32_t func_size,
0268                 unsigned char func_info,
0269                 uint8_t rep_block_size,
0270                 uint32_t num_fres);
0271
0272 /* Serialize the contents of the encoder and return the buffer.  ENCODED_SIZE
0273    is updated to the size of the buffer.  Sets ERRP if failure.  */
0274 extern char  *
0275 sframe_encoder_write (sframe_encoder_ctx *encoder,
0276               size_t *encoded_size, int *errp);
0277
0278 #ifdef  __cplusplus
0279 }
0280 #endif
0281
0282 #endif              /* _SFRAME_API_H */