fcml  1.1.3
Classes | Typedefs | Functions
fcml_assembler.h File Reference

Structures and functions declarations related to one-line FCML assembler. More...

#include "fcml_lib_export.h"
#include "fcml_types.h"
#include "fcml_errors.h"
#include "fcml_common.h"
#include "fcml_dialect.h"
#include "fcml_optimizers.h"
#include "fcml_choosers.h"

Go to the source code of this file.

Classes

struct  fcml_st_assembler_conf
 Assembler runtime configuration. More...
 
struct  fcml_st_assembled_instruction
 Encoded instruction. More...
 
struct  fcml_st_assembler_result
 Assembler result. More...
 
struct  fcml_st_assembler_context
 Assembler runtime context. More...
 

Typedefs

typedef struct fcml_st_assembler fcml_st_assembler
 Abstract assembler representation. More...
 
typedef struct fcml_st_assembler_conf fcml_st_assembler_conf
 Assembler runtime configuration.
 
typedef struct fcml_st_assembled_instruction fcml_st_assembled_instruction
 Encoded instruction. More...
 
typedef struct fcml_st_assembler_result fcml_st_assembler_result
 Assembler result. More...
 
typedef struct fcml_st_assembler_context fcml_st_assembler_context
 Assembler runtime context. More...
 

Functions

LIB_EXPORT fcml_ceh_error LIB_CALL fcml_fn_assembler_init (const fcml_st_dialect *dialect, fcml_st_assembler **assembler)
 Initializes assembler for given dialect. More...
 
LIB_EXPORT fcml_ceh_error LIB_CALL fcml_fn_assemble (fcml_st_assembler_context *context, const fcml_st_instruction *instruction, fcml_st_assembler_result *result)
 Assembles one instruction encoded in the generic instruction model. More...
 
LIB_EXPORT void LIB_CALL fcml_fn_assembler_result_prepare (fcml_st_assembler_result *result)
 Prepares reusable result holder for assembler. More...
 
LIB_EXPORT void LIB_CALL fcml_fn_assembler_result_free (fcml_st_assembler_result *result)
 Cleans result holder. More...
 
LIB_EXPORT void LIB_CALL fcml_fn_assembler_instruction_free (fcml_st_assembled_instruction *instruction)
 Frees assembled instruction. More...
 
LIB_EXPORT void LIB_CALL fcml_fn_assembler_instruction_detach (fcml_st_assembled_instruction **chain, fcml_st_assembled_instruction *instruction)
 Detaches given instruction from the instructions chain. More...
 
LIB_EXPORT void LIB_CALL fcml_fn_assembler_free (fcml_st_assembler *assembler)
 Frees assembler instance. More...
 

Detailed Description

Structures and functions declarations related to one-line FCML assembler.

Typedef Documentation

Encoded instruction.

Every instruction might be encoded to more than one binary form. This chain holds all forms assembler was able to assemble instruction to.

Abstract assembler representation.

Assembler runtime context.

Assembler result.

Function Documentation

LIB_EXPORT fcml_ceh_error LIB_CALL fcml_fn_assemble ( fcml_st_assembler_context context,
const fcml_st_instruction instruction,
fcml_st_assembler_result result 
)

Assembles one instruction encoded in the generic instruction model.

Instruction is proceeded using configuration and assembler provided in given fcml_st_assembler_context instance. Assembled code as well as potential errors or warnings are accessible via provided reusable result holder instance. Result holder has to be allocated by the user and appropriately prepared using fcml_fn_assembler_result_prepare() function. As long as the instruction context and the result holder are not shared across multiple function calls assembling process is thread safe.

Parameters
contextAssembler context (Assembler, Entry Point, Configuration).
instructionInstruction encoded as generic instruction model (Dialect dependent).
resultResult holder (Remember to prepare it appropriately).
Returns
Error code or FCML_CEH_GEC_NO_ERROR.
See also
fcml_fn_assembler_result_prepare fcml_fn_assembler_init
LIB_EXPORT void LIB_CALL fcml_fn_assembler_free ( fcml_st_assembler assembler)

Frees assembler instance.

Every assembler instance manages some resources internally and as such it has to be deallocated as soon as it is not needed anymore.

Parameters
assemblerAssembler to be freed.
LIB_EXPORT fcml_ceh_error LIB_CALL fcml_fn_assembler_init ( const fcml_st_dialect dialect,
fcml_st_assembler **  assembler 
)

Initializes assembler for given dialect.

Initializes assembler instance for given dialect (Intel, AT&T). Assembler initialized in such a way is dialect dependent and supports GIM with the syntax supported by it. Every assembler instance has to be freed using fcml_fn_assembler_free() function as soon as it is not needed anymore.

Parameters
dialectDialect instance.
[out]assemblerInitialized assembler instance.
Returns
Error code or FCML_CEH_GEC_NO_ERROR.
See also
fcml_fn_assembler_free
LIB_EXPORT void LIB_CALL fcml_fn_assembler_instruction_detach ( fcml_st_assembled_instruction **  chain,
fcml_st_assembled_instruction instruction 
)

Detaches given instruction from the instructions chain.

Removes given assembled instruction from the provided chain in order to prevent premature freeing of memory while assembler cleans result holder reusing it. Detached instructions are not automatically deallocated by fcml_fn_assemble() or fcml_fn_assembler_result_free() functions, so it is up to you to free it using fcml_fn_assembler_instruction_free() function when it is not needed anymore. Function may be useful when you need to store assembled instructions across multiple calls to the assembler if you reuse the same result holder. If there is only one instruction in the chain its pointer will be set to NULL after detaching it.

Parameters
chainPointer to the instructions chain pointer.
instructionInstruction to be detached from the chain.
LIB_EXPORT void LIB_CALL fcml_fn_assembler_instruction_free ( fcml_st_assembled_instruction instruction)

Frees assembled instruction.

Take into account that it does not free whole chain recursively but only the one instruction you have provided.

Parameters
instructionInstruction to be freed.
LIB_EXPORT void LIB_CALL fcml_fn_assembler_result_free ( fcml_st_assembler_result result)

Cleans result holder.

Frees all memory blocks allocated by the assembler and held inside the result holder (Instructions, errors etc.). Notice that result holder itself is not freed and can be even safety reused after call to this function. In fact this function is also called internally by the assembler in order to clean result holder before reusing it.

Parameters
resultResult holder to clean.
LIB_EXPORT void LIB_CALL fcml_fn_assembler_result_prepare ( fcml_st_assembler_result result)

Prepares reusable result holder for assembler.

Every instance of fcml_st_assembler_result structure is reusable from the assembler's point of view, so it has to be prepared in the right way in order to allow assembler to reuse it correctly. It is up to the library user to allocate space for the holder itself. This function is only responsible for cleaning the structure correctly and preparing it for the first assembling process. Notice that assembler has to clean the result holder at the beginning so you can not pass an uninitialized memory block because it can even cause a crash due to illegal memory access.

Parameters
resultResult holder instance to be prepared.