Skip to content

Tagha API Reference

Jump to bottom
assyrianic edited this page Nov 29, 2017 · 64 revisions

Contents

Typedefs

typedef struct TaghaScript		Script_t, Applet_t, Plugin_t;
typedef struct TaghaVM			TaghaVM_t, TVM_t;
typedef struct DataTable		DataTable_t, GlobalTable_t;
typedef struct FuncTable		FuncTable_t, ProcTable_t;
typedef struct NativeInfo		NativeInfo_t, NativeData_t;
typedef union CValue			Param_t, Arg_t, Val_t;

typedef	void (*fnNative_t)(struct TaghaScript *, union CValue [], union CValue *, const uint32_t, struct TaghaVM *);

Structs

struct FuncTable {
	uint32_t	uiParams;
	uint32_t	uiEntry;
};

struct DataTable {
	uint32_t	uiBytes;
	uint32_t	uiOffset;
};

struct NativeInfo {
	const char	*strName;	// use as string literals
	fnNative_t	pFunc;
};

struct TaghaScript {
	char m_strName[64];	// script's name
	uint8_t
		*m_pMemory,	// stack and data stream. Used for stack and data segment
		*m_pText	// instruction stream.
	;
	union CValue m_Regs[regsize];
	char	**m_pstrNatives;	// natives table as stored strings.
	struct hashmap
		*m_pmapFuncs,	// stores the functions compiled to script.
		*m_pmapGlobals	// stores global vars like string literals or variables.
	;
	uint32_t
		m_uiMemsize,	// size of m_pMemory
		m_uiInstrSize,	// size of m_pText
		m_uiMaxInstrs,	// max amount of instrs a script can execute.
		m_uiNatives,	// amount of natives the script uses.
		m_uiFuncs,	// how many functions the script has.
		m_uiGlobals	// how many globals variables the script has.
	;
	bool	m_bSafeMode : 1;	// does the script want bounds checking?
	bool	m_bDebugMode : 1;	// print debug info.
	uint8_t	m_ucZeroFlag : 1; // conditional zero flag.
};

struct TaghaVM {
	struct TaghaScript	*m_pScript;
	struct hashmap		*m_pmapNatives;
};

Unions

union CValue {
	bool Bool, *BoolPtr;
	int8_t Char, *CharPtr;
	int16_t Short, *ShortPtr;
	int32_t Int32, *Int32Ptr;
	int64_t Int64, *Int64Ptr;
	
	uint8_t UChar, *UCharPtr;
	uint16_t UShort, *UShortPtr;
	uint32_t UInt32, *UInt32Ptr;
	uint64_t UInt64, *UInt64Ptr;
	
	float Float, *FloatPtr;
	double Double, *DoublePtr;
	
	void *Ptr, **PtrPtr;
	const char *String, **StringPtr;
	union CValue *SelfPtr;
};

Enums

/* addressing modes
 *	immediate - simple constant value.
 *	register - register holds the exact data.
 *	register indirect - register holds memory address and dereferenced. Can be used as displacement as well.
 *	direct - a simple memory address. Useful for static data like global vars.
*/
enum AddrMode {
	Immediate	= 1,
	Register	= 2,
	RegIndirect	= 4,
	Direct		= 8,
	Byte		= 16,
	TwoBytes	= 32,
	FourBytes	= 64,
	EightBytes	= 128,
};

// Register ID list
enum RegID {
	ras=0,		// general purpose, accumulator - all return results go here.
	rbs,rcs,	// general purpose
	rds,res,	// general purpose
	rfs,rgs,rhs,// general purpose, floating point regs, rfs is used as float accumulator
	ris,rjs,rks,// general purpose
	
	// do not modify after this. Add more registers, if u need, above.
	rsp,rbp,	// stack ptrs, do not touch
	rip,		// instr ptr, do not touch as well.
	regsize		// for lazily updating id list
};

Functions

TaghaVM oriented Functions

void Tagha_init(struct TaghaVM *vm);
  • intializes and allocates pmapNatives hashmap and m_pScript. Prints a console message if pmapNatives or m_pScript could not be allocated.
void Tagha_load_script_by_name(struct TaghaVM *vm, char *filename);
  • opens a file, allocates a script, and allocates memory for it, once verified and header is valid, the script is then copied to m_pScript. if any of the loading process fails except for natives table, the script is promptly freed.
void Tagha_free(struct TaghaVM *vm);
  • frees m_pScript and its data and sets to NULL, then frees m_pmapNatives.
void Tagha_exec(struct TaghaVM *vm, uint8_t *oldbp);
  • executes the instructions of a loaded script until the script halts or an error occurs. oldbp param is for halting execution after reaching a specific stack frame.
bool Tagha_register_natives(struct TaghaVM *vm, struct NativeInfo arrNatives[]);
  • registers an array of natives to Tagha's native map. returns 1 on success, 0 on failure. 0 can occur if vm, arrNatives, or m_pmapNatives are NULL.
void Tagha_load_libc_natives(struct TaghaVM *vm);
  • registers Tagha's implementation of libc for the scripts to use. Certain functions or whatever can be stripped in order to reduce Tagha's size for embedded systems if necessary.
void Tagha_load_self_natives(struct TaghaVM *vm);
  • registers Tagha's API as natives for scripts to self-modify themselves. Use with caution...
void Tagha_call_script_func(struct TaghaVM *vm, const char *strFunc);
  • matches strFunc in a script's m_pmapFuncs hashmap to retrieve a function address and invokes the function at said address. This function assumes you've already pushed the necessary data prior to invocation.
Script_t *Tagha_get_script(const struct TaghaVM *vm);
  • returns the script pointer used by the VM.
void Tagha_set_script(struct TaghaVM *vm, struct TaghaScript *script);
  • sets the VMs script pointer to script.

Tagha Script Oriented Functions

Script_t *TaghaScript_from_file(const char *filename);
  • allocates and returns a usable script by filename.
void TaghaScript_debug_print_ptrs(const struct TaghaScript *script);
  • prints the scripts the values of the instruction, stack, and base pointers.
void TaghaScript_debug_print_memory(const struct TaghaScript *script);
  • prints every byte of a script's memory for debugging.
void TaghaScript_debug_print_instrs(const struct TaghaScript *script);
  • prints every byte of the script's instruction stream.
void TaghaScript_reset(struct TaghaScript *script);
  • zeroes out the script's memory, then resets the scripts stack and base pointer back to the top address in the script's memory, and zeroes out the general purpose registers.
void TaghaScript_free(struct TaghaScript *script);
  • frees all the allocated data of a single script.
uint32_t TaghaScript_stacksize(const struct TaghaScript *script);
  • returns the stack/memory size the script has allocated.
uint32_t TaghaScript_instrsize(const struct TaghaScript *script);
  • returns the size of the instruction stream of the script.
uint32_t TaghaScript_maxinstrs(const struct TaghaScript *script);
  • returns the max instructions remaining for the script.
uint32_t TaghaScript_nativecount(const struct TaghaScript *script);
  • returns the amount of natives used by the script.
uint32_t TaghaScript_funcs(const struct TaghaScript *script);
  • returns the amount of functions compiled in the script.
uint32_t TaghaScript_globals(const struct TaghaScript *script);
  • returns the amount of global variables in the script.
bool TaghaScript_safemode_active(const struct TaghaScript *script);
  • returns true or false if safe mode is enabled for the script.
bool TaghaScript_debug_active(const struct TaghaScript *script);
  • returns true or false if debug mode is enabled for the script.
void *TaghaScript_get_global_by_name(struct TaghaScript *script, const char *strGlobalName);
  • matches strGlobalName in the pmapGlobals hashmap to retrieve the address of the global variable and returns it as a void * pointer.
bool TaghaScript_bind_global_ptr(struct TaghaScript *script, const char *strGlobalName, void *pVar);
  • binds a pointer value to a global variable in a given script. The global variable in the script must be a pointer itself.
void TaghaScript_push_value(struct TaghaScript *script, const union Param value);
  • pushes a value of union CValue to script's stack.
union Param TaghaScript_pop_value(struct TaghaScript *script);
  • pops a value of union Param from script's ras accumulator register.

Clone this wiki locally