1 /* Public API to SFrame. 2 3 Copyright (C) 2022-2024 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 (uint32_t fre_type, uint32_t fde_type); 98 99 /* Gather the FRE type given the function size. */ 100 101 extern uint32_t 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 uint8_t 121 sframe_decoder_get_abi_arch (sframe_decoder_ctx *dctx); 122 123 /* Get the format version from the SFrame decoder context DCTX. */ 124 extern uint8_t 125 sframe_decoder_get_version (sframe_decoder_ctx *dctx); 126 127 /* Return the number of function descriptor entries in the SFrame decoder 128 DCTX. */ 129 extern uint32_t 130 sframe_decoder_get_num_fidx (sframe_decoder_ctx *dctx); 131 132 /* Get the fixed FP offset from the decoder context DCTX. */ 133 extern int8_t 134 sframe_decoder_get_fixed_fp_offset (sframe_decoder_ctx *dctx); 135 136 /* Get the fixed RA offset from the decoder context DCTX. */ 137 extern int8_t 138 sframe_decoder_get_fixed_ra_offset (sframe_decoder_ctx *dctx); 139 140 /* Find the function descriptor entry which contains the specified address. 141 142 Note: This function is deprecated and will be removed from future release 143 X+2 of the library. */ 144 extern void * 145 sframe_get_funcdesc_with_addr (sframe_decoder_ctx *dctx, int32_t addr, 146 int *errp); 147 148 /* Find the SFrame Frame Row Entry which contains the PC. Returns 149 SFRAME_ERR if failure. */ 150 151 extern int 152 sframe_find_fre (sframe_decoder_ctx *ctx, int32_t pc, 153 sframe_frame_row_entry *frep); 154 155 /* Get the FRE_IDX'th FRE of the function at FUNC_IDX'th function 156 index entry in the SFrame decoder CTX. Returns error code as 157 applicable. */ 158 extern int 159 sframe_decoder_get_fre (sframe_decoder_ctx *ctx, 160 unsigned int func_idx, 161 unsigned int fre_idx, 162 sframe_frame_row_entry *fre); 163 164 /* Get the data (NUM_FRES, FUNC_START_ADDRESS) from the function 165 descriptor entry at index I'th in the decoder CTX. If failed, 166 return error code. */ 167 extern int 168 sframe_decoder_get_funcdesc (sframe_decoder_ctx *ctx, 169 unsigned int i, 170 uint32_t *num_fres, 171 uint32_t *func_size, 172 int32_t *func_start_address, 173 unsigned char *func_info); 174 175 /* Get the data (NUM_FRES, FUNC_SIZE, FUNC_START_ADDRESS, FUNC_INFO, 176 REP_BLOCK_SIZE) from the function descriptor entry at index I'th 177 in the decoder CTX. If failed, return error code. 178 This API is only available from SFRAME_VERSION_2. */ 179 extern int 180 sframe_decoder_get_funcdesc_v2 (sframe_decoder_ctx *ctx, 181 unsigned int i, 182 uint32_t *num_fres, 183 uint32_t *func_size, 184 int32_t *func_start_address, 185 unsigned char *func_info, 186 uint8_t *rep_block_size); 187 188 /* SFrame textual dump. */ 189 extern void 190 dump_sframe (sframe_decoder_ctx *decoder, uint64_t addr); 191 192 /* Get the base reg id from the FRE info. Sets errp if fails. */ 193 extern uint8_t 194 sframe_fre_get_base_reg_id (sframe_frame_row_entry *fre, int *errp); 195 196 /* Get the CFA offset from the FRE. If the offset is invalid, sets errp. */ 197 extern int32_t 198 sframe_fre_get_cfa_offset (sframe_decoder_ctx *dtcx, 199 sframe_frame_row_entry *fre, int *errp); 200 201 /* Get the FP offset from the FRE. If the offset is invalid, sets errp. */ 202 extern int32_t 203 sframe_fre_get_fp_offset (sframe_decoder_ctx *dctx, 204 sframe_frame_row_entry *fre, int *errp); 205 206 /* Get the RA offset from the FRE. If the offset is invalid, sets errp. */ 207 extern int32_t 208 sframe_fre_get_ra_offset (sframe_decoder_ctx *dctx, 209 sframe_frame_row_entry *fre, int *errp); 210 211 /* Get whether the RA is mangled. */ 212 213 extern bool 214 sframe_fre_get_ra_mangled_p (sframe_decoder_ctx *dctx, 215 sframe_frame_row_entry *fre, int *errp); 216 217 /* The SFrame Encoder. */ 218 219 /* Create an encoder context with the given SFrame format version VER, FLAGS 220 and ABI information. Sets errp if failure. */ 221 extern sframe_encoder_ctx * 222 sframe_encode (uint8_t ver, uint8_t flags, uint8_t abi_arch, 223 int8_t fixed_fp_offset, int8_t fixed_ra_offset, int *errp); 224 225 /* Free the encoder context. */ 226 extern void 227 sframe_encoder_free (sframe_encoder_ctx **encoder); 228 229 /* Get the size of the SFrame header from the encoder ctx ENCODER. */ 230 extern unsigned int 231 sframe_encoder_get_hdr_size (sframe_encoder_ctx *encoder); 232 233 /* Get the abi/arch info from the SFrame encoder context CTX. */ 234 extern uint8_t 235 sframe_encoder_get_abi_arch (sframe_encoder_ctx *encoder); 236 237 /* Get the format version from the SFrame encoder context ENCODER. */ 238 extern uint8_t 239 sframe_encoder_get_version (sframe_encoder_ctx *encoder); 240 241 /* Return the number of function descriptor entries in the SFrame encoder 242 ENCODER. */ 243 extern uint32_t 244 sframe_encoder_get_num_fidx (sframe_encoder_ctx *encoder); 245 246 /* Add an FRE to function at FUNC_IDX'th function descriptor index entry in 247 the encoder context. */ 248 extern int 249 sframe_encoder_add_fre (sframe_encoder_ctx *encoder, 250 unsigned int func_idx, 251 sframe_frame_row_entry *frep); 252 253 /* Add a new function descriptor entry with START_ADDR, FUNC_SIZE and NUM_FRES 254 to the encoder. */ 255 extern int 256 sframe_encoder_add_funcdesc (sframe_encoder_ctx *encoder, 257 int32_t start_addr, 258 uint32_t func_size, 259 unsigned char func_info, 260 uint32_t num_fres); 261 262 /* Add a new function descriptor entry with START_ADDR, FUNC_SIZE, FUNC_INFO 263 and REP_BLOCK_SIZE to the encoder. */ 264 extern int 265 sframe_encoder_add_funcdesc_v2 (sframe_encoder_ctx *encoder, 266 int32_t start_addr, 267 uint32_t func_size, 268 unsigned char func_info, 269 uint8_t rep_block_size, 270 uint32_t num_fres); 271 272 /* Serialize the contents of the encoder and return the buffer. ENCODED_SIZE 273 is updated to the size of the buffer. Sets ERRP if failure. */ 274 extern char * 275 sframe_encoder_write (sframe_encoder_ctx *encoder, 276 size_t *encoded_size, int *errp); 277 278 #ifdef __cplusplus 279 } 280 #endif 281 282 #endif /* _SFRAME_API_H */ 283
Indexes created Tue Feb 24 08:35:24 UTC 2026