| 1 |
/* |
| 2 |
* FCML - Free Code Manipulation Library. |
| 3 |
* Copyright (C) 2010-2020 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_parser.h |
| 21 |
* Structures and functions declarations related to FCML parsers |
| 22 |
* |
| 23 |
* @copyright Copyright (C) 2010-2020 Slawomir Wojtasiak. All rights reserved. |
| 24 |
* This project is released under the GNU Lesser General Public License. |
| 25 |
*/ |
| 26 |
|
| 27 |
#ifndef FCML_PARSER_H_ |
| 28 |
#define FCML_PARSER_H_ |
| 29 |
|
| 30 |
#include "fcml_lib_export.h" |
| 31 |
|
| 32 |
#include "fcml_types.h" |
| 33 |
#include "fcml_errors.h" |
| 34 |
#include "fcml_common.h" |
| 35 |
#include "fcml_dialect.h" |
| 36 |
#include "fcml_symbols.h" |
| 37 |
|
| 38 |
#ifdef __cplusplus |
| 39 |
extern "C" { |
| 40 |
#endif |
| 41 |
|
| 42 |
/** Maximal number of character for parsed instruction. */ |
| 43 |
#define FCML_PARSER_MAX_INSTRUCTION_LEN 1024 |
| 44 |
|
| 45 |
/** Parser configuration. */ |
| 46 |
typedef struct fcml_st_parser_config { |
| 47 |
/** Set to true in order to ignore all undefined symbols. |
| 48 |
* In such a case every unknown symbol is treated as 0. |
| 49 |
*/ |
| 50 |
fcml_bool ignore_undefined_symbols; |
| 51 |
/** Disables symbols support. |
| 52 |
* If set to true every defined label will cause an error. |
| 53 |
*/ |
| 54 |
fcml_bool disable_symbols_declaration; |
| 55 |
/** Set to true in order to allow overriding existing labels. |
| 56 |
* If set to false parser returns "Symbol already exists" error when |
| 57 |
* symbol already exists. |
| 58 |
*/ |
| 59 |
fcml_bool override_labels; |
| 60 |
/** By default parser ignores all symbol declarations |
| 61 |
* if there is no symbol table provided in the parser |
| 62 |
* context. By setting this value to true you can force |
| 63 |
* the parser to allocate new symbol table when needed. |
| 64 |
* Remember that you are then responsible for freeing it, |
| 65 |
* so this functionality can be a bit dangerous because |
| 66 |
* you have to check the existence of the symbol table |
| 67 |
* every time it should be deallocated. |
| 68 |
*/ |
| 69 |
fcml_bool alloc_symbol_table_if_needed; |
| 70 |
// TODO: Support has to be implemented yet. |
| 71 |
/** Enables textual error messages. */ |
| 72 |
fcml_bool enable_error_messages; |
| 73 |
} fcml_st_parser_config; |
| 74 |
|
| 75 |
/** Parser runtime context. */ |
| 76 |
typedef struct fcml_st_parser_context { |
| 77 |
/** Dialect to be used by parser. Defines supported instructions syntax. */ |
| 78 |
fcml_st_dialect *dialect; |
| 79 |
/** Parser configuration. */ |
| 80 |
fcml_st_parser_config configuration; |
| 81 |
/** Instruction pointer. RIP/EIP register value used as a value for |
| 82 |
* newly declared symbols. |
| 83 |
* This value is never changed by the parser. |
| 84 |
*/ |
| 85 |
fcml_ip ip; |
| 86 |
/** Symbol table. It holds symbols added by the user as |
| 87 |
* well as symbols allocated by the parsers (labels). It is |
| 88 |
* very important to free this container on your own |
| 89 |
* because even if it is not allocated by the user it can be |
| 90 |
* set by the parser when the first symbol definition is found. |
| 91 |
* So the most safe way to manage it is to always use |
| 92 |
* "fcml_fn_symbol_table_free" function as soon as context |
| 93 |
* if going to be freed. |
| 94 |
*/ |
| 95 |
fcml_st_symbol_table symbol_table; |
| 96 |
} fcml_st_parser_context; |
| 97 |
|
| 98 |
/** Reusable result holder */ |
| 99 |
typedef struct fcml_st_parser_result { |
| 100 |
/** Parsing errors and warnings going here. */ |
| 101 |
fcml_st_ceh_error_container errors; |
| 102 |
/** Defined symbol if there is any. |
| 103 |
* Remember that this symbol is also stored in the context's symbol table. |
| 104 |
* It is the symbol table that is the owner and that is responsible |
| 105 |
* for freeing it. |
| 106 |
*/ |
| 107 |
fcml_st_symbol *symbol; |
| 108 |
/** Parsed instruction as generic instruction model. */ |
| 109 |
fcml_st_instruction *instruction; |
| 110 |
} fcml_st_parser_result; |
| 111 |
|
| 112 |
/** |
| 113 |
* Parses given instruction into the generic instruction model. |
| 114 |
* Parses the textual representation of the instruction using dialect and |
| 115 |
* configuration provided by the parser context. Parsed instruction is returned in the |
| 116 |
* reusable result holder. Result holder has to be allocated by the |
| 117 |
* user and appropriately prepared using fcml_fn_parser_result_prepare() |
| 118 |
* function. As long as the instruction context and the result holder |
| 119 |
* are not shared across multiple function calls parsing process is |
| 120 |
* thread safe. |
| 121 |
* |
| 122 |
* Remember that textual representation of the instruction has to be written |
| 123 |
* using syntax supported by the dialect parser is going to use. |
| 124 |
* |
| 125 |
* @param context Parser runtime context. |
| 126 |
* @param instruction textual representation of the instruction to be parsed. |
| 127 |
* @param result Reusable result holder. |
| 128 |
* @return Error code or FCML_CEH_GEC_NO_ERROR. |
| 129 |
*/ |
| 130 |
LIB_EXPORT fcml_ceh_error LIB_CALL fcml_fn_parse( |
| 131 |
fcml_st_parser_context *context, const fcml_string instruction, |
| 132 |
fcml_st_parser_result *result); |
| 133 |
|
| 134 |
/** |
| 135 |
* Prepares reusable result holder for parser. |
| 136 |
* Every instance of fcml_st_parser_result structure is reusable from the |
| 137 |
* parser's point of view, so it has to be prepared in the right way in order |
| 138 |
* to allow parser to reuse it correctly. It is up to the library user to |
| 139 |
* allocate space for the holder itself. This function is only responsible |
| 140 |
* for cleaning the structure correctly and preparing it for the first parsing |
| 141 |
* process. Notice that parser has to clean the result holder at the beginning |
| 142 |
* so you can not pass an uninitialized memory block because it can even cause |
| 143 |
* a crash due to illegal memory access. |
| 144 |
* |
| 145 |
* @param result Result holder instance to be prepared. |
| 146 |
*/ |
| 147 |
LIB_EXPORT void LIB_CALL fcml_fn_parser_result_prepare( |
| 148 |
fcml_st_parser_result *result); |
| 149 |
|
| 150 |
/** |
| 151 |
* Cleans result holder. |
| 152 |
* Frees all memory blocks allocated by the parser and held inside the result |
| 153 |
* holder (Instructions, errors etc.). Notice that result holder itself is |
| 154 |
* not freed and can be even safety reused after call to this function. In fact |
| 155 |
* this function is also called internally by the parser in order to clean |
| 156 |
* result holder before reusing it. |
| 157 |
* @param result Result holder to clean. |
| 158 |
*/ |
| 159 |
LIB_EXPORT void LIB_CALL fcml_fn_parser_result_free( |
| 160 |
fcml_st_parser_result *result); |
| 161 |
|
| 162 |
#ifdef __cplusplus |
| 163 |
} |
| 164 |
#endif |
| 165 |
|
| 166 |
#endif /* FCML_PARSER_H_ */ |