Skip to content

Tagha API Reference

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

Contents

Typedefs

typedef struct Tagha			Tagha;
typedef struct NativeInfo		NativeInfo;
typedef union CValue			CValue;
typedef struct TaghaHeader		TaghaHeader;

//	API for scripts to call C/C++ host functions.
typedef		void (*fnNative_t)(struct Tagha *, union CValue [], union CValue *, const uint32_t);

Structs

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

struct Tagha {
	union CValue m_Regs[regsize];
	uint8_t
		*m_pMemory,			// script memory, entirely aligned by 8 bytes.
		*m_pStackSegment,	// stack segment ptr where the stack's lowest address lies.
		*m_pDataSegment,	// data segment is the address AFTER the stack segment ptr. Aligned by 8 bytes.
		*m_pTextSegment		// text segment is the address after the last global variable AKA the last opcode.
	;
	// stores a C/C++ function ptr using the script-side name as the key.
	char **m_pstrNativeCalls;		// natives string table.
	struct hashmap *m_pmapNatives;	// native C/C++ interface hashmap.
	
	union CValue *m_pArgv;	// forcing char** to 8 bytes
	struct hashmap
		*m_pmapFuncs,		// stores the functions compiled to script.
		*m_pmapGlobals		// stores global vars like string literals or variables.
	;
	uint32_t
		m_uiMemsize,		// total size of m_pMemory
		m_uiInstrSize,		// size of the text segment
		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.
	;
	int32_t m_iArgc;
	bool
		m_bSafeMode : 1,	// does the script want bounds checking?
		m_bDebugMode : 1,	// print debug info.
		m_bZeroFlag : 1		// conditional zero flag.
	;
};

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;
	char *Str, **StrPtr;
	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,
	IPRelative	= 8,	// unused, will be replaced in the future with useful addr mode.
	Byte		= 16,
	TwoBytes	= 32,
	FourBytes	= 64,
	EightBytes	= 128,
};

// Register ID list
// 13 general purpose use registers + 3 reserved use.
enum RegID {
	// 'ras' is gen. purpose + accumulator
	// all native and tagha func return data that fits within 64-bits goes here.
	// natives can only return a single 8-byte piece of data.
	// if you need to return larger than 8 bytes...
	// use ras, rbs, and rcs. otherwise, return as pointer in ras.
	ras=0,rbs,rcs,
	
	// 12 more gen. purpose regs for whatever use.
	// when passing arguments, use registers rds to rms
	// since params are passed right to left.
	// put the rightmost arg in rms.
	// thus if you passed 10 args, the 1st arg would be in rds and 10th arg in rms.
	rds,
	res,rfs,rgs,
	rhs,ris,rjs,
	rks,rls,rms,
	
	// 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 RegID list
};

API Functions/Methods

void Tagha_Init(struct Tagha *pSys);
  • intializes and allocates m_pmapNatives hashmap and m_pArgv. Prints a console message if m_pmapNatives or m_pArgv could not be allocated.
struct Tagha *Tagha_New(void);
  • allocates, inits, and returns a pointer to a new Tagha system instance. Automatically calls Tagha_Init if the instance isn't NULL.
void Tagha_LoadScriptByName(struct Tagha *pSys, char *filename);
  • opens up script file and allocates the script to Tagha's system. Once verified and header is valid, the script's data is setup to the system. if any of the loading process fails except for natives table, the system is promptly freed and an error is printed to console.
void Tagha_LoadScriptFromMemory(struct Tagha *pSys, void *pMemory, const uint64_t memsize);
  • Same as Tagha_LoadScriptByName but uses a memory buffer as the script data rather than reading from a file buffer.
void Tagha_Free(struct Tagha *pSys);
  • frees the entire Tagha system and sets pointers to NULL.
void Tagha_RunScript(struct Tagha *pSys);
  • executes the instructions loaded on the system until the script halts, returns on empty stack, or an error occurs.
bool Tagha_RegisterNatives(struct Tagha *pSys, struct NativeInfo arrNatives[]);
  • registers an array of natives to Tagha's native map. returns 1 on success, 0 on failure. 0 can occur if pSys, arrNatives, or m_pmapNatives are NULL.
void Tagha_CallFunc(struct Tagha *pSys, 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.
void Tagha_BuildFromFile(struct Tagha *pSys, const char *strFilename);
  • sets up the tagha system from a script by filename.
void Tagha_BuildFromPtr(struct Tagha *pSys, void *pProgram, const uint64_t Programsize);
  • sets up the tagha system from a script by memory buffer.
void Tagha_PrintPtrs(const struct Tagha *pSys);
  • prints the values of the script's instruction, stack, and base pointer.
void Tagha_PrintData(const struct Tagha *pSys);
  • prints every byte of a script's .data section for debugging purposes.
void Tagha_PrintStack(const struct Tagha *pSys);
  • prints a script's .stack section for debugging purposes. All data is printed in increments of 8 bytes.
void Tagha_PrintInstrs(const struct Tagha *pSys);
  • prints every byte of the script's instruction stream.
void Tagha_PrintRegData(const struct Tagha *pSys);
  • prints all the data in the script's registers.
void Tagha_Reset(struct Tagha *pSys);
  • zeroes out the script's .data and .stack segment of 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.
uint32_t Tagha_GetMemSize(const struct Tagha *pSys);
  • returns the total memory size the script has allocated.
uint32_t Tagha_GetInstrSize(const struct Tagha *pSys);
  • returns the size of the script's instruction stream.
uint32_t Tagha_GetMaxInstrs(const struct Tagha *pSys);
  • returns the max instructions remaining for the script.
uint32_t Tagha_GetNativeCount(const struct Tagha *pSys);
  • returns the amount of natives used by the script.
uint32_t Tagha_GetFuncCount(const struct Tagha *pSys);
  • returns the amount of functions compiled in the script.
uint32_t Tagha_GetGlobalsCount(const struct Tagha *pSys);
  • returns the amount of global variables in the script.
bool Tagha_IsSafemodeActive(const struct Tagha *pSys);
  • returns true or false if safe mode is enabled for the script.
bool Tagha_IsDebugActive(const struct Tagha *pSys);
  • returns true or false if debug mode is enabled for the script.
void *Tagha_GetGlobalByName(struct Tagha *pSys, const char *strGlobalName);
  • matches strGlobalName in m_pmapGlobals hashmap to retrieve the address of the global variable and returns it as a void * pointer. Returns NULL if the name entry doesn't exist.
void Tagha_PushValues(struct Tagha *pSys, const uint32_t uiArgs, union CValue values[]);
  • pushes an array of union CValue to the script's registers (and stack if more than 10 arguments).
union CValue Tagha_PopValue(struct Tagha *pSys);
  • pops a value of union CValue from the script's ras general purpose/accumulator register.
void Tagha_SetCmdArgs(struct Tagha *pSys, char *argv[]);
  • copies the argv string vector to the system's argument vector, resizing if argv is larger/smaller than the previous argv. argv vector must have an ending NULL value, similar to registering natives.

Clone this wiki locally