]>
Commit | Line | Data |
---|---|---|
19e559f1 WP |
1 | /* Public API to SFrame. |
2 | ||
d87bef3a | 3 | Copyright (C) 2022-2023 Free Software Foundation, Inc. |
19e559f1 WP |
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> | |
9c4b163c | 24 | #include <stdbool.h> |
19e559f1 WP |
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 | ||
d987df5c IB |
34 | #define MAX_NUM_STACK_OFFSETS 3 |
35 | ||
36 | #define MAX_OFFSET_BYTES \ | |
37 | ((SFRAME_FRE_OFFSET_4B * 2 * MAX_NUM_STACK_OFFSETS)) | |
19e559f1 WP |
38 | |
39 | /* User interfacing SFrame Row Entry. | |
40 | An abstraction provided by libsframe so the consumer is decoupled from | |
8c078abd IB |
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. */ | |
19e559f1 WP |
46 | |
47 | typedef struct sframe_frame_row_entry | |
48 | { | |
49 | uint32_t fre_start_addr; | |
19e559f1 | 50 | unsigned char fre_offsets[MAX_OFFSET_BYTES]; |
8c078abd | 51 | unsigned char fre_info; |
19e559f1 WP |
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 | ||
b659fb35 | 94 | /* Create an FDE function info bye given an FRE_TYPE and an FDE_TYPE. */ |
19e559f1 WP |
95 | |
96 | extern unsigned char | |
100d405d | 97 | sframe_fde_create_func_info (uint32_t fre_type, uint32_t fde_type); |
19e559f1 WP |
98 | |
99 | /* Gather the FRE type given the function size. */ | |
100 | ||
49e4485c | 101 | extern uint32_t |
725a19bf | 102 | sframe_calc_fre_type (size_t func_size); |
19e559f1 WP |
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. */ | |
de4879fe | 120 | extern uint8_t |
19e559f1 WP |
121 | sframe_decoder_get_abi_arch (sframe_decoder_ctx *dctx); |
122 | ||
9f71b60b IB |
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 | ||
19e559f1 WP |
127 | /* Return the number of function descriptor entries in the SFrame decoder |
128 | DCTX. */ | |
df6f1afb | 129 | extern uint32_t |
19e559f1 WP |
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 | ||
852bb8c1 IB |
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); | |
19e559f1 WP |
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 | ||
ce9a8725 IB |
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 | ||
42b6953b IB |
188 | /* SFrame textual dump. */ |
189 | extern void | |
190 | dump_sframe (sframe_decoder_ctx *decoder, uint64_t addr); | |
19e559f1 WP |
191 | |
192 | /* Get the base reg id from the FRE info. Sets errp if fails. */ | |
a9f1da26 | 193 | extern uint8_t |
19e559f1 WP |
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 | ||
9c4b163c IB |
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 | ||
19e559f1 WP |
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 * | |
3412dcec | 222 | sframe_encode (uint8_t ver, uint8_t flags, uint8_t abi_arch, |
19e559f1 WP |
223 | int8_t fixed_fp_offset, int8_t fixed_ra_offset, int *errp); |
224 | ||
225 | /* Free the encoder context. */ | |
226 | extern void | |
cf0e0a0b | 227 | sframe_encoder_free (sframe_encoder_ctx **encoder); |
19e559f1 WP |
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. */ | |
de4879fe | 234 | extern uint8_t |
19e559f1 | 235 | sframe_encoder_get_abi_arch (sframe_encoder_ctx *encoder); |
9f71b60b IB |
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); | |
19e559f1 WP |
240 | |
241 | /* Return the number of function descriptor entries in the SFrame encoder | |
242 | ENCODER. */ | |
df6f1afb | 243 | extern uint32_t |
19e559f1 WP |
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 | ||
ce9a8725 IB |
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 | ||
19e559f1 WP |
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 */ |