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