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