[thirdparty/binutils-gdb.git] / include / sframe-api.h

/* Public API to SFrame.

   Copyright (C) 2022-2025 Free Software Foundation, Inc.

   This file is part of libsframe.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */

#ifndef	_SFRAME_API_H
#define	_SFRAME_API_H

#include <sframe.h>
#include <stdbool.h>

#ifdef	__cplusplus
extern "C"
{
#endif

typedef struct sframe_decoder_ctx sframe_decoder_ctx;
typedef struct sframe_encoder_ctx sframe_encoder_ctx;

#define MAX_NUM_STACK_OFFSETS	3

#define MAX_OFFSET_BYTES  \
  ((SFRAME_FRE_OFFSET_4B * 2 * MAX_NUM_STACK_OFFSETS))

/* User interfacing SFrame Row Entry.
   An abstraction provided by libsframe so the consumer is decoupled from
   the binary format representation of the same.

   The members are best ordered such that they are aligned at their natural
   boundaries.  This helps avoid usage of undesirable misaligned memory
   accesses.  See PR libsframe/29856.  */

typedef struct sframe_frame_row_entry
{
  uint32_t fre_start_addr;
  unsigned char fre_offsets[MAX_OFFSET_BYTES];
  unsigned char fre_info;
} sframe_frame_row_entry;

#define SFRAME_ERR ((int) -1)

/* This macro holds information about all the available SFrame
   errors.  It is used to form both an enum holding all the error
   constants, and also the error strings themselves.  To use, define
   _SFRAME_FIRST and _SFRAME_ITEM to expand as you like, then
   mention the macro name.  See the enum after this for an example.  */
#define _SFRAME_ERRORS \
  _SFRAME_FIRST (SFRAME_ERR_VERSION_INVAL, "SFrame version not supported.") \
  _SFRAME_ITEM (SFRAME_ERR_NOMEM, "Out of Memory.") \
  _SFRAME_ITEM (SFRAME_ERR_INVAL, "Corrupt SFrame.") \
  _SFRAME_ITEM (SFRAME_ERR_BUF_INVAL, "Buffer does not contain SFrame data.") \
  _SFRAME_ITEM (SFRAME_ERR_DCTX_INVAL, "Corrupt SFrame decoder.") \
  _SFRAME_ITEM (SFRAME_ERR_ECTX_INVAL, "Corrupt SFrame encoder.") \
  _SFRAME_ITEM (SFRAME_ERR_FDE_INVAL, "Corrput FDE.") \
  _SFRAME_ITEM (SFRAME_ERR_FRE_INVAL, "Corrupt FRE.") \
  _SFRAME_ITEM (SFRAME_ERR_FDE_NOTFOUND,"FDE not found.") \
  _SFRAME_ITEM (SFRAME_ERR_FDE_NOTSORTED, "FDEs not sorted.") \
  _SFRAME_ITEM (SFRAME_ERR_FRE_NOTFOUND,"FRE not found.") \
  _SFRAME_ITEM (SFRAME_ERR_FREOFFSET_NOPRESENT,"FRE offset not present.")

#define	SFRAME_ERR_BASE	2000	/* Base value for libsframe errnos.  */

enum
  {
#define _SFRAME_FIRST(NAME, STR) NAME = SFRAME_ERR_BASE
#define _SFRAME_ITEM(NAME, STR) , NAME
_SFRAME_ERRORS
#undef _SFRAME_ITEM
#undef _SFRAME_FIRST
  };

/* Count of SFrame errors.  */
#define SFRAME_ERR_NERR (SFRAME_ERR_FREOFFSET_NOPRESENT - SFRAME_ERR_BASE + 1)

/* Get the error message string.  */

extern const char *
sframe_errmsg (int error);

/* Create an FDE function info bye given an FRE_TYPE and an FDE_TYPE.  */

extern unsigned char
sframe_fde_create_func_info (uint32_t fre_type, uint32_t fde_type);

/* Gather the FRE type given the function size.  */

extern uint32_t
sframe_calc_fre_type (size_t func_size);

/* The SFrame Decoder.  */

/* Decode the specified SFrame buffer CF_BUF of size CF_SIZE and return the
   new SFrame decoder context.  Sets ERRP for the caller if any error.  */
extern sframe_decoder_ctx *
sframe_decode (const char *cf_buf, size_t cf_size, int *errp);

/* Free the decoder context.  */
extern void
sframe_decoder_free (sframe_decoder_ctx **dctx);

/* Get the size of the SFrame header from the decoder context DCTX.  */
extern unsigned int
sframe_decoder_get_hdr_size (sframe_decoder_ctx *dctx);

/* Get the SFrame's abi/arch info.  */
extern uint8_t
sframe_decoder_get_abi_arch (sframe_decoder_ctx *dctx);

/* Get the format version from the SFrame decoder context DCTX.  */
extern uint8_t
sframe_decoder_get_version (sframe_decoder_ctx *dctx);

/* Return the number of function descriptor entries in the SFrame decoder
   DCTX.  */
extern uint32_t
sframe_decoder_get_num_fidx (sframe_decoder_ctx *dctx);

/* Get the fixed FP offset from the decoder context DCTX.  */
extern int8_t
sframe_decoder_get_fixed_fp_offset (sframe_decoder_ctx *dctx);

/* Get the fixed RA offset from the decoder context DCTX.  */
extern int8_t
sframe_decoder_get_fixed_ra_offset (sframe_decoder_ctx *dctx);

/* Find the function descriptor entry which contains the specified address.

   Note: This function is deprecated and will be removed from future release
   X+2 of the library.  */
extern void *
sframe_get_funcdesc_with_addr (sframe_decoder_ctx *dctx, int32_t addr,
			       int *errp);

/* Find the SFrame Frame Row Entry which contains the PC.  Returns
   SFRAME_ERR if failure.  */

extern int
sframe_find_fre (sframe_decoder_ctx *ctx, int32_t pc,
		 sframe_frame_row_entry *frep);

/* Get the FRE_IDX'th FRE of the function at FUNC_IDX'th function
   index entry in the SFrame decoder CTX.  Returns error code as
   applicable.  */
extern int
sframe_decoder_get_fre (sframe_decoder_ctx *ctx,
			unsigned int func_idx,
			unsigned int fre_idx,
			sframe_frame_row_entry *fre);

/* Get the data (NUM_FRES, FUNC_START_ADDRESS) from the function
   descriptor entry at index I'th in the decoder CTX.  If failed,
   return error code.  */
extern int
sframe_decoder_get_funcdesc (sframe_decoder_ctx *ctx,
			     unsigned int i,
			     uint32_t *num_fres,
			     uint32_t *func_size,
			     int32_t *func_start_address,
			     unsigned char *func_info);

/* Get the data (NUM_FRES, FUNC_SIZE, FUNC_START_ADDRESS, FUNC_INFO,
   REP_BLOCK_SIZE) from the function descriptor entry at index I'th
   in the decoder CTX.  If failed, return error code.
   This API is only available from SFRAME_VERSION_2.  */
extern int
sframe_decoder_get_funcdesc_v2 (sframe_decoder_ctx *ctx,
				unsigned int i,
				uint32_t *num_fres,
				uint32_t *func_size,
				int32_t *func_start_address,
				unsigned char *func_info,
				uint8_t *rep_block_size);

/* SFrame textual dump.  */
extern void
dump_sframe (sframe_decoder_ctx *decoder, uint64_t addr);

/* Get the base reg id from the FRE info.  Sets errp if fails.  */
extern uint8_t
sframe_fre_get_base_reg_id (sframe_frame_row_entry *fre, int *errp);

/* Get the CFA offset from the FRE.  If the offset is invalid, sets errp.  */
extern int32_t
sframe_fre_get_cfa_offset (sframe_decoder_ctx *dtcx,
			   sframe_frame_row_entry *fre, int *errp);

/* Get the FP offset from the FRE.  If the offset is invalid, sets errp.  */
extern int32_t
sframe_fre_get_fp_offset (sframe_decoder_ctx *dctx,
			  sframe_frame_row_entry *fre, int *errp);

/* Get the RA offset from the FRE.  If the offset is invalid, sets errp.  */
extern int32_t
sframe_fre_get_ra_offset (sframe_decoder_ctx *dctx,
			  sframe_frame_row_entry *fre, int *errp);

/* Get whether the RA is mangled.  */

extern bool
sframe_fre_get_ra_mangled_p (sframe_decoder_ctx *dctx,
			     sframe_frame_row_entry *fre, int *errp);

/* The SFrame Encoder.  */

/* Create an encoder context with the given SFrame format version VER, FLAGS
   and ABI information.  Sets errp if failure.  */
extern sframe_encoder_ctx *
sframe_encode (uint8_t ver, uint8_t flags, uint8_t abi_arch,
	       int8_t fixed_fp_offset, int8_t fixed_ra_offset, int *errp);

/* Free the encoder context.  */
extern void
sframe_encoder_free (sframe_encoder_ctx **encoder);

/* Get the size of the SFrame header from the encoder ctx ENCODER.  */
extern unsigned int
sframe_encoder_get_hdr_size (sframe_encoder_ctx *encoder);

/* Get the abi/arch info from the SFrame encoder context CTX.  */
extern uint8_t
sframe_encoder_get_abi_arch (sframe_encoder_ctx *encoder);

/* Get the format version from the SFrame encoder context ENCODER.  */
extern uint8_t
sframe_encoder_get_version (sframe_encoder_ctx *encoder);

/* Return the number of function descriptor entries in the SFrame encoder
   ENCODER.  */
extern uint32_t
sframe_encoder_get_num_fidx (sframe_encoder_ctx *encoder);

/* Add an FRE to function at FUNC_IDX'th function descriptor index entry in
   the encoder context.  */
extern int
sframe_encoder_add_fre (sframe_encoder_ctx *encoder,
			unsigned int func_idx,
			sframe_frame_row_entry *frep);

/* Add a new function descriptor entry with START_ADDR, FUNC_SIZE and NUM_FRES
   to the encoder.  */
extern int
sframe_encoder_add_funcdesc (sframe_encoder_ctx *encoder,
			     int32_t start_addr,
			     uint32_t func_size,
			     unsigned char func_info,
			     uint32_t num_fres);

/* Add a new function descriptor entry with START_ADDR, FUNC_SIZE, FUNC_INFO
   and REP_BLOCK_SIZE to the encoder.  */
extern int
sframe_encoder_add_funcdesc_v2 (sframe_encoder_ctx *encoder,
				int32_t start_addr,
				uint32_t func_size,
				unsigned char func_info,
				uint8_t rep_block_size,
				uint32_t num_fres);

/* Serialize the contents of the encoder and return the buffer.  ENCODED_SIZE
   is updated to the size of the buffer.  Sets ERRP if failure.  */
extern char  *
sframe_encoder_write (sframe_encoder_ctx *encoder,
		      size_t *encoded_size, int *errp);

#ifdef	__cplusplus
}
#endif

#endif				/* _SFRAME_API_H */
Commit	Line	Data
	1	/* Public API to SFrame.
	2
	3	Copyright (C) 2022-2025 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 */