| 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_ */ |