Debian Codegraph @

include/fcml_lag_assembler.h

raw
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_lag_assembler.h
21 * Experimental multiline load-and-go assembler implementation.
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_LAG_ASSEMBLER_H_
27 #define FCML_LAG_ASSEMBLER_H_
28
29 #include "fcml_symbols.h"
30 #include "fcml_assembler.h"
31
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35
36 /** Result holder for load-and-go assembler. */
37 typedef struct fcml_st_lag_assembler_result {
38 /** Error and warning messages from one-line assembler. */
39 fcml_st_ceh_error_container errors;
40 /** Number of line where assembler failed. */
41 fcml_int error_line;
42 /** Chain of assembled instructions.*/
43 fcml_st_assembled_instruction *instructions;
44 } fcml_st_lag_assembler_result;
45
46 /** Load-and-go assembler runtime context. */
47 typedef struct fcml_st_lag_assembler_context {
48 /** Assembler instance that should be used to assemble instructions. */
49 fcml_st_assembler *assembler;
50 /** Assembler behavior can be configured here.*/
51 fcml_st_assembler_conf configuration;
52 /** Instruction entry point configuration. */
53 fcml_st_entry_point entry_point;
54 /** Symbols table. */
55 fcml_st_symbol_table symbol_table;
56 } fcml_st_lag_assembler_context;
57
58 /**
59 * Multipass load-and-go assembler.
60 * Assembles all instructions given in the NULL terminated source_code
61 * array of strings. Every instruction has to be represented as one string
62 * in the source array. Like every multipass assembler implementation it
63 * passes through the source code multiple times in order to generate optimal
64 * code. Assembler also supports symbols that can be provided using symbol
65 * table available in the context. Context should be initialized the same way
66 * as in case of one line assembler. The only difference here is the symbol
67 * table itself which can be initialized using fcml_fn_symbol_table_alloc()
68 * function. Symbols can be also declared directly in the source code and
69 * accessed through the same symbols table when processing is done (Only if
70 * you provide valid symbol table through the context). Reusable result holder
71 * has to be prepared using fcml_fn_lag_assembler_result_prepare() function.
72 * As long as the context and the result holder are not shared across multiple
73 * calls function is thread safe.
74 *
75 * @param context Assembler context.
76 * @param source_code NULL terminated array of the instructions.
77 * @param result Reusable result holder.
78 * @return Error code or FCML_CEH_GEC_NO_ERROR.
79 * @warning This is an experimental implementation and it still needs
80 * some testing.
81 * @see fcml_fn_lag_assembler_result_prepare
82 * @see fcml_fn_symbol_table_alloc
83 */
84 LIB_EXPORT fcml_ceh_error LIB_CALL fcml_fn_lag_assemble(
85 fcml_st_lag_assembler_context *context, const fcml_string *source_code,
86 fcml_st_lag_assembler_result *result);
87
88 /**
89 * Prepares reusable result holder for assembler.
90 * Every instance of fcml_st_lag_assembler_result structure is reusable from
91 * the assembler's point of view, so it has to be prepared in the right way in
92 * order to allow assembler to reuse it correctly. It is up to the library user
93 * to allocate space for the holder itself. This function is only responsible
94 * for cleaning the structure correctly and preparing it for first assembling
95 * process. Notice that assembler has to clean the result holder at the
96 * beginning so you can not pass an uninitialized memory block because it can
97 * even cause a crash due to illegal memory access.
98 *
99 * @param result Result holder instance to be prepared.
100 */
101 LIB_EXPORT void LIB_CALL fcml_fn_lag_assembler_result_prepare(
102 fcml_st_lag_assembler_result *result);
103
104 /**
105 * Cleans result holder.
106 * Frees all memory blocks allocated by the assembler and held inside the
107 * result holder (Instructions, errors etc.). Notice that result holder itself
108 * is not freed and can be even safety reused after call to this function. In
109 * fact this function is also called internally by assembler in order to clean
110 * result holder before
111 * reusing it.
112 * @param result Result holder to clean.
113 */
114 LIB_EXPORT void LIB_CALL fcml_fn_lag_assembler_result_free(
115 fcml_st_lag_assembler_result *result);
116
117 #ifdef __cplusplus
118 }
119 #endif
120
121 #endif /* FCML_LAG_ASSEMBLER_H_ */