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
27extern "C"
28{
29#endif
30
31typedef struct sframe_decoder_ctx sframe_decoder_ctx;
32typedef 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
47typedef 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
77enum
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
91extern const char *
92sframe_errmsg (int error);
93
94/* Create an FDE function info bye given an FRE_TYPE and an FDE_TYPE.  */
95
96extern unsigned char
97sframe_fde_create_func_info (uint32_t fre_type, uint32_t fde_type);
98
99/* Gather the FRE type given the function size.  */
100
101extern uint32_t
102sframe_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.  */
108extern sframe_decoder_ctx *
109sframe_decode (const char *cf_buf, size_t cf_size, int *errp);
110
111/* Free the decoder context.  */
112extern void
113sframe_decoder_free (sframe_decoder_ctx **dctx);
114
115/* Get the size of the SFrame header from the decoder context DCTX.  */
116extern unsigned int
117sframe_decoder_get_hdr_size (sframe_decoder_ctx *dctx);
118
119/* Get the SFrame's abi/arch info.  */
120extern uint8_t
121sframe_decoder_get_abi_arch (sframe_decoder_ctx *dctx);
122
123/* Get the format version from the SFrame decoder context DCTX.  */
124extern uint8_t
125sframe_decoder_get_version (sframe_decoder_ctx *dctx);
126
127/* Return the number of function descriptor entries in the SFrame decoder
128   DCTX.  */
129extern uint32_t
130sframe_decoder_get_num_fidx (sframe_decoder_ctx *dctx);
131
132/* Get the fixed FP offset from the decoder context DCTX.  */
133extern int8_t
134sframe_decoder_get_fixed_fp_offset (sframe_decoder_ctx *dctx);
135
136/* Get the fixed RA offset from the decoder context DCTX.  */
137extern int8_t
138sframe_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.  */
144extern void *
145sframe_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
151extern int
152sframe_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.  */
158extern int
159sframe_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.  */
167extern int
168sframe_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.  */
179extern int
180sframe_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.  */
189extern void
190dump_sframe (sframe_decoder_ctx *decoder, uint64_t addr);
191
192/* Get the base reg id from the FRE info.  Sets errp if fails.  */
193extern uint8_t
194sframe_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.  */
197extern int32_t
198sframe_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.  */
202extern int32_t
203sframe_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.  */
207extern int32_t
208sframe_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
213extern bool
214sframe_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.  */
221extern sframe_encoder_ctx *
222sframe_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.  */
226extern void
227sframe_encoder_free (sframe_encoder_ctx **encoder);
228
229/* Get the size of the SFrame header from the encoder ctx ENCODER.  */
230extern unsigned int
231sframe_encoder_get_hdr_size (sframe_encoder_ctx *encoder);
232
233/* Get the abi/arch info from the SFrame encoder context CTX.  */
234extern uint8_t
235sframe_encoder_get_abi_arch (sframe_encoder_ctx *encoder);
236
237/* Get the format version from the SFrame encoder context ENCODER.  */
238extern uint8_t
239sframe_encoder_get_version (sframe_encoder_ctx *encoder);
240
241/* Return the number of function descriptor entries in the SFrame encoder
242   ENCODER.  */
243extern uint32_t
244sframe_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.  */
248extern int
249sframe_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.  */
255extern int
256sframe_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.  */
264extern int
265sframe_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.  */
274extern char  *
275sframe_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