Debian Codegraph @

include/fcml_disassembler.h

raw
1 /*
2 * FCML - Free Code Manipulation Library.
3 * Copyright (C) 2010-2024 Slawomir Wojtasiak
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18 */
19
20 /** @file fcml_disassembler.h
21 * Structures and functions declarations related to FCML disassembler.
22 * @copyright Copyright (C) 2010-2020 Slawomir Wojtasiak. All rights reserved.
23 * This project is released under the GNU Lesser General Public License.
24 */
25
26 #ifndef FCML_DISASSEMBLER_H_
27 #define FCML_DISASSEMBLER_H_
28
29 #include "fcml_lib_export.h"
30
31 #include "fcml_instructions.h"
32 #include "fcml_types.h"
33 #include "fcml_errors.h"
34 #include "fcml_common.h"
35 #include "fcml_dialect.h"
36
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40
41 /** Maximal number of instruction prefixes. */
42 #define FCML_DASM_PREFIXES_COUNT 12
43
44 /** First group of conditional suffixes (See FCML manual). */
45 #define FCML_DASM_CONDITIONAL_GROUP_1 0x00
46 /** Second group of conditional suffixes (See FCML manual). */
47 #define FCML_DASM_CONDITIONAL_GROUP_2 0x01
48
49 /** This structure and type declaration represents an abstract disassembler. */
50 typedef struct fcml_st_disassembler fcml_st_disassembler;
51
52 /** Disassembler configuration. */
53 typedef struct fcml_st_disassembler_conf {
54 /** Set to true in order to make disassembler to increment IP address by
55 * length of the disassembled instruction. */
56 fcml_bool increment_ip;
57 /** True if optional error and warning messages should be collected
58 * during processing. */
59 fcml_bool enable_error_messages;
60 /** True if suffixes for carry flag has to be used by disassembler.*/
61 fcml_bool carry_flag_conditional_suffix;
62 /** There are two groups of suffixes for conditional instructions, you
63 * can choose which one should be used. */
64 fcml_uint8_t conditional_group;
65 /** Set to true in order to use short forms.
66 * For instance 'cmpsb' will be used instead of
67 * 'cmps byte ptr [si],byte ptr [di]'
68 */
69 fcml_bool short_forms;
70 /** True if displacement should be sign extended to effective
71 * address size; otherwise false. */
72 fcml_bool extend_disp_to_asa;
73 /** If set to true assembler will return FCML_CEH_GEC_UNKNOWN_INSTRUCTION
74 * error code if instruction is not known.
75 */
76 fcml_bool fail_if_unknown_instruction;
77 } fcml_st_disassembler_conf;
78
79 /** Disassembler context. */
80 typedef struct fcml_st_disassembler_context {
81 /** Disassembler used to decode instructions. */
82 fcml_st_disassembler *disassembler;
83 /** Disassembler configuration. */
84 fcml_st_disassembler_conf configuration;
85 /** Instruction entry point configuration. */
86 fcml_st_entry_point entry_point;
87 /** Pointer to the encoded instruction. */
88 fcml_ptr code;
89 /** Size of the code in the buffer above. */
90 fcml_usize code_length;
91 } fcml_st_disassembler_context;
92
93 /* Prefixes */
94
95 /** Available types of instruction prefixes. For more information see
96 * Intel/AMD Architecture Manual. */
97 typedef enum fcml_en_prefix_types {
98 FCML_PT_GROUP_UNKNOWN = 0,
99 FCML_PT_GROUP_1 = 1,
100 FCML_PT_GROUP_2,
101 FCML_PT_GROUP_3,
102 FCML_PT_GROUP_4,
103 FCML_PT_REX,
104 FCML_PT_VEX,
105 FCML_PT_XOP,
106 FCML_PT_EVEX
107 } fcml_en_prefix_types;
108
109 /** Describes one decoded prefix. */
110 typedef struct fcml_st_instruction_prefix {
111 /** Prefix itself as raw byte. */
112 fcml_uint8_t prefix;
113 /** Type of the prefix. */
114 fcml_en_prefix_types prefix_type;
115 /** FCML_TRUE if prefix is treated as mandatory one. */
116 fcml_bool mandatory_prefix;
117 /** Place for additional bytes of VEX/EVEX/XOP prefix.
118 * since 1.2.0
119 */
120 fcml_uint8_t avx_bytes[3];
121 } fcml_st_instruction_prefix;
122
123 /**
124 * Contains some additional information about all decoded
125 * instruction prefixes.
126 */
127 typedef struct fcml_st_prefixes_details {
128 /** Array with decoded prefixes. */
129 fcml_st_instruction_prefix prefixes[FCML_DASM_PREFIXES_COUNT];
130 /** Number of decoded prefixes. */
131 fcml_int prefixes_count;
132 /** Number of bytes used by all decoded prefixes. */
133 fcml_int prefixes_bytes_count;
134 /** FCML_TRUE if branch prefix exists. */
135 fcml_bool is_branch;
136 /** FCML_TRUE if nobranch prefix exists. */
137 fcml_bool is_nobranch;
138 /** FCML_TRUE if lock explicit prefix exists. */
139 fcml_bool is_lock;
140 /** FCML_TRUE if rep explicit prefix exists. */
141 fcml_bool is_rep;
142 /** FCML_TRUE if repne explicit prefix exists. */
143 fcml_bool is_repne;
144 /** FCML_TRUE if xrelease explicit prefix exists. */
145 fcml_bool is_xrelease;
146 /** FCML_TRUE if xacquire explicit prefix exists. */
147 fcml_bool is_xacquire;
148 /** FCML_TRUE if VEX prefix exists. */
149 fcml_bool is_vex;
150 /** FCML TRUE if EVEX prefix exists. */
151 fcml_bool is_evex;
152 /** FCML_TRUE if XOP prefix exists. */
153 fcml_bool is_xop;
154 /** True if it is an AVX instruction (VEX/XOP/EVEX). */
155 fcml_bool is_avx;
156 /** FCML_TRUE if REX prefix exists. */
157 fcml_bool is_rex;
158 /** First byte of AVX prefix. */
159 fcml_uint8_t avx_first_byte;
160 /** R field of REX,XOP or VEX prefix. */
161 fcml_uint8_t R;
162 /** EVEX R’ High-16 register specifier modifier. */
163 fcml_uint8_t R_prim;
164 /** X field of REX,XOP or VEX prefix. */
165 fcml_uint8_t X;
166 /** B field of REX,XOP or VEX prefix. */
167 fcml_uint8_t B;
168 /** b field of EVEX prefix. */
169 fcml_uint8_t b;
170 /** W field of REX,XOP or VEX/EVEX prefix. */
171 fcml_uint8_t W;
172 /** L field of XOP or VEX prefix. */
173 fcml_uint8_t L;
174 /** L’ field of EVEX prefix. */
175 fcml_uint8_t L_prim;
176 /** m-mmmm field of XOP or VEX prefix. */
177 fcml_uint8_t mmmm;
178 /** vvvv field of XOP or VEX prefix. */
179 fcml_uint8_t vvvv;
180 /** pp field of XOP or VEX/EVEX prefix. */
181 fcml_uint8_t pp;
182 /** z field of EVEX prefix */
183 fcml_uint8_t z;
184 /** V’ field of EVEX prefix. */
185 fcml_uint8_t V_prim;
186 /** Embedded opmask register specifier. */
187 fcml_uint8_t aaa;
188 } fcml_st_prefixes_details;
189
190 /** Some additional disassembler specific information about decoded operands. */
191 typedef struct fcml_st_operand_details {
192 /** Instruction operand access mode READ, WRITE or both. */
193 fcml_en_access_mode access_mode;
194 } fcml_st_operand_details;
195
196 /**
197 * Displacement in raw form.
198 */
199 typedef struct fcml_st_raw_displacement {
200 /** Displacement as encoded in disp8/disp16/disp32/disp8*N. */
201 fcml_st_integer displacement;
202 /** Scaling factor N in EVEX specific compressed disp8*N. */
203 fcml_nuint32_t N;
204 } fcml_st_raw_displacement;
205
206 /** Some basic information about decoded ModR/M and SIB bytes. */
207 typedef struct fcml_st_decoded_modrm_details {
208 /** ModR/M byte if exists.*/
209 fcml_uint8_t modrm;
210 /** SIB byte if exists.*/
211 fcml_nuint8_t sib;
212 /** True if RIP encoding is used by decoded instruction. This flag is
213 * used only in 64 bit mode. */
214 fcml_bool is_rip;
215 /** True if ModR/M exists. */
216 fcml_bool is_modrm;
217 /** Raw displacement */
218 fcml_st_raw_displacement displacement;
219 } fcml_st_decoded_modrm_details;
220
221 /** Additional instruction details provided by disassembler. */
222 typedef struct fcml_st_instruction_details {
223 /** True if this is a shortcut.
224 * A good example of such instruction is 'cmpsb' as opposed to
225 * 'cmps byte ptr [si],byte ptr [di]'. It is very important to take this
226 * information into consideration when instruction models are analyzed
227 * because there are no operands available in the GIM in
228 * case of such shortcuts.
229 */
230 fcml_bool is_shortcut;
231 /** True if a given instruction is a short form of pseudo-ops instructions.
232 * See 'vcmpunordsd' for instance. */
233 fcml_bool is_pseudo_op;
234 /** Code of the disassembled instruction. */
235 fcml_uint8_t instruction_code[FCML_INSTRUCTION_SIZE];
236 /** Instruction size in bytes. */
237 fcml_usize instruction_size;
238 /** Some additional information about decoded instruction prefixes. */
239 fcml_st_prefixes_details prefixes_details;
240 /** All disassembler specific information about operands going there. */
241 fcml_st_operand_details operand_details[FCML_OPERANDS_COUNT];
242 /** Details about decoded ModR/M and SIB bytes. */
243 fcml_st_decoded_modrm_details modrm_details;
244 /** Opcode field 's'.
245 * This is set only for informational purpose only and you should not
246 * use it for any critical functionality.
247 */
248 fcml_bool opcode_field_s_bit;
249 /** Opcode field 'w'.
250 * This is set only for informational purpose only and you should not
251 * use it for any critical functionality.
252 */
253 fcml_bool opcode_field_w_bit;
254 /** Instruction code/number. @see fcml_instructions.h header file. */
255 fcml_en_instruction instruction;
256 /** Pseudo operation code. */
257 fcml_en_pseudo_operations pseudo_op;
258 /** Code of the instruction form/addressing mode of the instruction
259 * above. */
260 fcml_uint16_t addr_mode;
261 /** Instruction group. */
262 fcml_uint64_t instruction_group;
263 /** avx-512 tuple type */
264 fcml_uint8_t tuple_type;
265 } fcml_st_instruction_details;
266
267 /** Reusable disassembler result holder. */
268 typedef struct fcml_st_disassembler_result {
269 /** All errors and warnings messages going here. */
270 fcml_st_ceh_error_container errors;
271 /** Additional disassembler specific information about decoded
272 * instruction. */
273 fcml_st_instruction_details instruction_details;
274 /** Decoded instruction in its generic form.*/
275 fcml_st_instruction instruction;
276 } fcml_st_disassembler_result;
277
278 /**
279 * Initializes disassembler instance.
280 * Initializes disassembler instance for given dialect. Disassembler
281 * initialized in such a way is dialect dependent and generates generic
282 * instruction models compliant to the syntax supported by the dialect
283 * (Intel, AT&T). Every disassembler instance has to be freed using
284 * fcml_fn_disassembler_free() function as soon as it is not needed anymore.
285 *
286 * @param dialect Dialect for newly created disassembler.
287 * @param[out] disassembler Initialized disassembler instance.
288 * @return Error code or FCML_CEH_GEC_NO_ERROR.
289 * @see fcml_fn_disassembler_free
290 */
291 LIB_EXPORT fcml_ceh_error LIB_CALL fcml_fn_disassembler_init(
292 const fcml_st_dialect *dialect, fcml_st_disassembler **disassembler);
293
294 /**
295 * Disassembles one instruction from provided code buffer.
296 * Disassembles the first instruction available in the provided code buffer
297 * using disassembler instance, configuration and entry point accessible through
298 * the disassembler context. Disassembled instruction model as well as potential
299 * errors are returned in reusable result holder given in the second parameter.
300 * Result holder has to be allocated by the user and appropriately prepared
301 * using fcml_fn_disassembler_result_prepare() function. As long as the
302 * instruction context and the result holder are not shared across multiple
303 * function calls disassembling process is thread safe.
304 *
305 * @param context Disassembler context.
306 * @param result Appropriately prepared result holder.
307 * @return Error code or FCML_CEH_GEC_NO_ERROR.
308 * @see fcml_fn_disassembler_result_free
309 */
310 LIB_EXPORT fcml_ceh_error LIB_CALL fcml_fn_disassemble(
311 fcml_st_disassembler_context *context,
312 fcml_st_disassembler_result *result);
313
314 /**
315 * Prepares reusable result holder for disassembler.
316 * Every instance of fcml_st_disassembler_result structure is reusable from
317 * the disassembler's point of view, so it has to be prepared in the right
318 * way in order to allow disassembler to reuse it correctly. It is up to the
319 * library user to allocate space for the holder itself. This function is only
320 * responsible for cleaning the structure correctly and preparing it for first
321 * disassembling process. Notice that disassembler has to clean the result
322 * holder at the beginning so you can not pass an uninitialized memory
323 * block because it can even cause a crash due to illegal memory access.
324 *
325 * @param result Result holder instance to be prepared.
326 * @see fcml_fn_disassembler_result_free
327 */
328 LIB_EXPORT void LIB_CALL fcml_fn_disassembler_result_prepare(
329 fcml_st_disassembler_result *result);
330
331 /**
332 * Cleans result holder.
333 * Frees all memory blocks allocated by the disassembler and held inside
334 * the result holder (Instructions, errors etc.). Notice that result holder
335 * itself is not freed and can be even safety reused after calling this
336 * function. In fact this function is also called internally by assembler in
337 * order to clean result holder before reusing it.
338 *
339 * @param result Result holder to clean.
340 */
341 LIB_EXPORT void LIB_CALL fcml_fn_disassembler_result_free(
342 fcml_st_disassembler_result *result);
343
344 /**
345 * Frees disassembler instance.
346 * Every disassembler instance manages some resources internally and as
347 * such it has to be deallocated as soon as it is not needed anymore.
348 * @param disassembler Disassembler to be freed.
349 */
350 LIB_EXPORT void LIB_CALL fcml_fn_disassembler_free(
351 fcml_st_disassembler *disassembler);
352
353 #ifdef __cplusplus
354 }
355 #endif
356
357 #endif /* FCML_DISASSEMBLER_H_ */