dvander@67: #ifndef _INCLUDE_SOURCEPAWN_VM_API_H_
dvander@67: #define _INCLUDE_SOURCEPAWN_VM_API_H_
dvander@67: 
dvander@67: #include <stdio.h>
dvander@67: #include "sp_vm_types.h"
dvander@67: 
dvander@175: #define SOURCEPAWN_VM_API_VERSION		1
dvander@175: 
dvander@262: #if defined SOURCEMOD_BUILD
dvander@262: namespace SourceMod
dvander@262: {
dvander@262: 	struct IdentityToken_t;
dvander@262: };
dvander@262: #endif
dvander@262: 
dvander@67: namespace SourcePawn
dvander@67: {
dvander@157: 	class IVirtualMachine;
dvander@157: 
dvander@164: 	/**
dvander@164: 	 * @brief Interface to managing a debug context at runtime.
dvander@164: 	 */
dvander@157: 	class IPluginDebugInfo
dvander@157: 	{
dvander@157: 	public:
dvander@157: 		/**
dvander@263: 		 * @brief Given a code pointer, finds the file it is associated with.
dvander@157: 		 * 
dvander@157: 		 * @param addr		Code address offset.
dvander@157: 		 * @param filename	Pointer to store filename pointer in.
dvander@157: 		 */
dvander@157: 		virtual int LookupFile(ucell_t addr, const char **filename) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Given a code pointer, finds the function it is associated with.
dvander@157: 		 *
dvander@157: 		 * @param addr		Code address offset.
dvander@157: 		 * @param name		Pointer to store function name pointer in.
dvander@157: 		 */
dvander@157: 		virtual int LookupFunction(ucell_t addr, const char **name) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Given a code pointer, finds the line it is associated with.
dvander@157: 		 *
dvander@157: 		 * @param addr		Code address offset.
dvander@157: 		 * @param line		Pointer to store line number in.
dvander@157: 		 */
dvander@157: 		virtual int LookupLine(ucell_t addr, uint32_t *line) =0;
dvander@157: 	};
dvander@157: 
dvander@164: 	/**
dvander@164: 	 * @brief Interface to managing a context at runtime.
dvander@164: 	 */
dvander@157: 	class IPluginContext
dvander@157: 	{
dvander@157: 	public:
dvander@157: 		virtual ~IPluginContext() { };
dvander@157: 	public:
dvander@157: 		/** 
dvander@263: 		 * @brief Returns the parent IVirtualMachine.
dvander@157: 		 *
dvander@157: 		 * @return				Parent virtual machine pointer.
dvander@157: 		 */
dvander@157: 		virtual IVirtualMachine *GetVirtualMachine() =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Returns the child sp_context_t structure.
dvander@157: 		 *
dvander@157: 		 * @return				Child sp_context_t structure.
dvander@157: 		 */
dvander@157: 		virtual sp_context_t *GetContext() =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Returns true if the plugin is in debug mode.
dvander@157: 		 *
dvander@157: 		 * @return				True if in debug mode, false otherwise.
dvander@157: 		 */
dvander@157: 		virtual bool IsDebugging() =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Installs a debug break and returns the old one, if any.
dvander@157: 		 * This will fail if the plugin is not debugging.
dvander@157: 		 *
dvander@157: 		 * @param newpfn		New function pointer.
dvander@157: 		 * @param oldpfn		Pointer to retrieve old function pointer.
dvander@157: 		 */
dvander@157: 		virtual int SetDebugBreak(SPVM_DEBUGBREAK newpfn, SPVM_DEBUGBREAK *oldpfn) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Returns debug info.
dvander@157: 		 *
dvander@157: 		 * @return				IPluginDebugInfo, or NULL if no debug info found.
dvander@157: 		 */
dvander@157: 		virtual IPluginDebugInfo *GetDebugInfo() =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Allocs memory on the secondary stack of a plugin.
dvander@157: 		 * Note that although called a heap, it is in fact a stack.
dvander@157: 		 * 
dvander@157: 		 * @param cells			Number of cells to allocate.
dvander@263: 		 * @param local_addr	Will be filled with data offset to heap.
dvander@157: 		 * @param phys_addr		Physical address to heap memory.
dvander@157: 		 */
dvander@157: 		virtual int HeapAlloc(unsigned int cells, cell_t *local_addr, cell_t **phys_addr) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Pops a heap address off the heap stack.  Use this to free memory allocated with
dvander@157: 		 *  SP_HeapAlloc().  
dvander@157: 		 * Note that in SourcePawn, the heap is in fact a bottom-up stack.  Deallocations
dvander@157: 		 *  with this native should be performed in precisely the REVERSE order.
dvander@157: 		 *
dvander@157: 		 * @param local_addr	Local address to free.
dvander@157:  		 */
dvander@157: 		virtual int HeapPop(cell_t local_addr) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Releases a heap address using a different method than SP_HeapPop().
dvander@157: 		 * This allows you to release in any order.  However, if you allocate N 
dvander@157: 		 *  objects, release only some of them, then begin allocating again, 
dvander@157: 		 *  you cannot go back and starting freeing the originals.  
dvander@157: 		 * In other words, for each chain of allocations, if you start deallocating,
dvander@157: 		 *  then allocating more in a chain, you must only deallocate from the current 
dvander@157: 		 *  allocation chain.  This is basically HeapPop() except on a larger scale.
dvander@157: 		 *
dvander@157: 		 * @param local_addr	Local address to free.
dvander@157:  		 */
dvander@157: 		virtual int HeapRelease(cell_t local_addr) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Finds a native by name.
dvander@157: 		 *
dvander@157: 		 * @param name			Name of native.
dvander@157: 		 * @param index			Optionally filled with native index number.
dvander@157: 		 */
dvander@157: 		virtual int FindNativeByName(const char *name, uint32_t *index) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Gets native info by index.
dvander@157: 		 *
dvander@157: 		 * @param index			Index number of native.
dvander@157: 		 * @param native		Optionally filled with pointer to native structure.
dvander@157: 		 */
dvander@157: 		virtual int GetNativeByIndex(uint32_t index, sp_native_t **native) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Gets the number of natives.
dvander@157: 		 * 
dvander@157: 		 * @return				Filled with the number of natives.
dvander@157: 		 */
dvander@157: 		virtual uint32_t GetNativesNum() =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Finds a public function by name.
dvander@157: 		 *
dvander@157: 		 * @param name			Name of public
dvander@157: 		 * @param index			Optionally filled with public index number.
dvander@157: 		 */
dvander@157: 		virtual int FindPublicByName(const char *name, uint32_t *index) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Gets public function info by index.
dvander@157: 		 * 
dvander@157: 		 * @param index			Public function index number.
dvander@263: 		 * @param publicptr		Optionally filled with pointer to public structure.
dvander@157: 		 */
dvander@157: 		virtual int GetPublicByIndex(uint32_t index, sp_public_t **publicptr) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Gets the number of public functions.
dvander@157: 		 *
dvander@157: 		 * @return				Filled with the number of public functions.
dvander@157: 		 */
dvander@157: 		virtual uint32_t GetPublicsNum() =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Gets public variable info by index.
dvander@263: 		 * 
dvander@157: 		 * @param index			Public variable index number.
dvander@157: 		 * @param pubvar		Optionally filled with pointer to pubvar structure.
dvander@157: 		 */
dvander@157: 		virtual int GetPubvarByIndex(uint32_t index, sp_pubvar_t **pubvar) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Finds a public variable by name.
dvander@157: 		 *
dvander@157: 		 * @param name			Name of pubvar
dvander@157: 		 * @param index			Optionally filled with pubvar index number.
dvander@157: 		 */
dvander@157: 		virtual int FindPubvarByName(const char *name, uint32_t *index) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Gets the addresses of a public variable.
dvander@263: 		 * 
dvander@263: 		 * @param index			Index of public variable.
dvander@263: 		 * @param local_addr		Address to store local address in.
dvander@263: 		 * @param phys_addr		Address to store physically relocated in.
dvander@263: 		 */
dvander@157: 		virtual int GetPubvarAddrs(uint32_t index, cell_t *local_addr, cell_t **phys_addr) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Returns the number of public variables.
dvander@157: 		 *
dvander@157: 		 * @return				Number of public variables.
dvander@157: 		 */
dvander@157: 		virtual uint32_t GetPubVarsNum() =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Round-about method of converting a plugin reference to a physical address
dvander@157: 		 *
dvander@157: 		 * @param local_addr	Local address in plugin.
dvander@157: 		 * @param phys_addr		Optionally filled with relocated physical address.
dvander@157: 		 */
dvander@157: 		virtual int LocalToPhysAddr(cell_t local_addr, cell_t **phys_addr) =0;
dvander@157: 
faluco@179: 		/**
dvander@263: 		 * @brief Converts a local address to a physical string.
dvander@157: 		 *
dvander@157: 		 * @param local_addr	Local address in plugin.
dvander@157: 		 * @param addr			Destination output pointer.
dvander@157: 		 */
dvander@157: 		virtual int LocalToString(cell_t local_addr, char **addr) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Converts a physical string to a local address.
dvander@157: 		 *
dvander@157: 		 * @param local_addr	Local address in plugin.
dvander@183: 		 * @param bytes			Number of chars to write, including NULL terminator.
dvander@157: 		 * @param source		Source string to copy.
dvander@157: 		 */
dvander@183: 		virtual int StringToLocal(cell_t local_addr, size_t bytes, const char *source) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Converts a physical UTF-8 string to a local address.
dvander@263: 		 * This function is the same as the ANSI version, except it will copy the maximum number of characters possible 
dvander@263: 		 *  without accidentally chopping a multi-byte character.
dvander@263: 		 *
dvander@263: 		 * @param local_addr		Local address in plugin.
dvander@263: 		 * @param maxbytes		Number of bytes to write, including NULL terminator.
dvander@263: 		 * @param source			Source string to copy.
dvander@263: 		 * @param wrtnbytes		Optionally set to the number of actual bytes written.
dvander@263: 		 */
dvander@183: 		virtual int StringToLocalUTF8(cell_t local_addr, 
dvander@183: 									  size_t maxbytes, 
dvander@183: 									  const char *source, 
dvander@183: 									  size_t *wrtnbytes) =0;
faluco@179: 
faluco@179: 		/**
dvander@263: 		 * @brief Pushes a cell onto the stack.  Increases the parameter count by one.
dvander@157: 		 *
dvander@157: 		 * @param value			Cell value.
dvander@157: 		 */
dvander@157: 		virtual int PushCell(cell_t value) =0;
dvander@157: 
dvander@157: 		/** 
dvander@263: 		 * @brief Pushes an array of cells onto the stack.  Increases the parameter count by one.
dvander@157: 		 * If the function returns an error it will fail entirely, releasing anything allocated in the process.
dvander@157: 		 * Note that this does not release the heap, so you should release it after
dvander@157: 		 *  calling Execute().
dvander@157: 		 *
dvander@157: 		 * @param local_addr	Filled with local address to release.
dvander@157: 		 * @param phys_addr		Optionally filled with physical address of new array.
dvander@157: 		 * @param array			Cell array to copy.
dvander@157: 		 * @param numcells		Number of cells in the array to copy.
dvander@157: 		 */
dvander@157: 		virtual int PushCellArray(cell_t *local_addr, cell_t **phys_addr, cell_t array[], unsigned int numcells) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Pushes a string onto the stack (by reference) and increases the parameter count by one.
dvander@157: 		 * Note that this does not release the heap, so you should release it after
dvander@157: 		 *  calling Execute().
dvander@157: 		 *
dvander@157: 		 * @param local_addr	Filled with local address to release.
dvander@157: 		 * @param phys_addr		Optionally filled with physical address of new array.
dvander@157: 		 * @param string		Source string to push.
dvander@157: 		 */
faluco@179: 		virtual int PushString(cell_t *local_addr, char **phys_addr, const char *string) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Individually pushes each cell of an array of cells onto the stack.  Increases the 
dvander@157: 		 *  parameter count by the number of cells pushed.
dvander@157: 		 * If the function returns an error it will fail entirely, releasing anything allocated in the process.
dvander@157: 		 *
dvander@157: 		 * @param array			Array of cells to read from.
dvander@157: 		 * @param numcells		Number of cells to read.
dvander@157: 		 */
dvander@157: 		virtual int PushCellsFromArray(cell_t array[], unsigned int numcells) =0;
dvander@157: 
dvander@157: 		/** 
dvander@263: 		 * @brief Binds a list of native names and their function pointers to a context.
dvander@157: 		 * If num is 0, the list is read until an entry with a NULL name is reached.
dvander@157: 		 * If overwrite is non-zero, already registered natives will be overwritten.
dvander@157: 		 * 
dvander@157: 		 * @param natives		Array of natives.
dvander@157: 		 * @param num			Number of natives in array.
dvander@157: 		 * @param overwrite		Toggles overwrite.
dvander@157: 		 */
dvander@157: 		virtual int BindNatives(sp_nativeinfo_t *natives, unsigned int num, int overwrite) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Binds a single native.  Overwrites any existing bind.
dvander@157: 		 * If the context does not contain the native that will be binded the function will return
dvander@164: 		 *  with a SP_ERROR_NOT_FOUND error.
dvander@157: 		 *
dvander@157: 		 * @param native		Pointer to native.
dvander@157: 		 */
dvander@164: 		virtual int BindNative(sp_nativeinfo_t *native) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Binds a single native to any non-registered native.
dvander@157: 		 *
dvander@157: 		 * @param native		Native to bind.
dvander@157: 		 */
dvander@157: 		virtual int BindNativeToAny(SPVM_NATIVE_FUNC native) =0;
dvander@157: 
dvander@157: 		/**
dvander@263: 		 * @brief Executes a function ID located in this context.
dvander@164: 		 *
dvander@164: 		 * @param funcid		Function id to execute.
dvander@164: 		 * @param result		Pointer to store the return value (required).
dvander@164: 		 * @return				Error code (if any) from the VM.
dvander@157: 		 */
dvander@164: 		virtual int Execute(uint32_t funcid, cell_t *result) =0;
dvander@239: 
dvander@239: 
dvander@239: 		/**
dvander@239: 		 * @brief Throws a error and halts any current execution.
dvander@239: 		 *
dvander@239: 		 * @param error		The error number to set.
dvander@239: 		 * @param msg		Custom error message format.  NULL to use default.
dvander@239: 		 * @param ...		Message format arguments, if any.
dvander@239: 		 */
dvander@239: 		virtual void ThrowNativeErrorEx(int error, const char *msg, ...) =0;
dvander@239: 
dvander@239: 		/**
dvander@239: 		 * @brief Throws a generic native error and halts any current execution.
dvander@239: 		 *
dvander@239: 		 * @param msg		Custom error message format.  NULL to set no message.
dvander@239: 		 * @param ...		Message format arguments, if any.
dvander@239: 		 * @return			0 for convenience.
dvander@239: 		 */
dvander@239: 		virtual cell_t ThrowNativeError(const char *msg, ...) =0;
dvander@262: 
dvander@262: #if defined SOURCEMOD_BUILD
dvander@262: 		/**
dvander@262: 		 * @brief Returns the identity token for this context.
dvander@262: 		 * Note: This is a helper function for native calls and the Handle System.
dvander@262: 		 *
dvander@262: 		 * @return			Identity token.
dvander@262: 		 */
dvander@262: 		virtual SourceMod::IdentityToken_t *GetIdentity() =0;
dvander@262: #endif
dvander@157: 	};
dvander@67: 
dvander@239: 
dvander@239: 	/**
dvander@239: 	 * @brief Information about a position in a call stack.
dvander@239: 	 */
dvander@239: 	struct CallStackInfo
dvander@237: 	{
dvander@239: 		const char *filename;		/* NULL if not found */
dvander@239: 		unsigned int line;			/* 0 if not found */
dvander@239: 		const char *function;		/* NULL if not found */
dvander@237: 	};
dvander@237: 
dvander@239: 	/**
dvander@239: 	 * @brief Retrieves error information from a debug hook.
dvander@239: 	 */
dvander@239: 	class IContextTrace
dvander@237: 	{
dvander@245: 	public:
dvander@237: 		/**
dvander@237: 		 * @brief Returns the integer error code.
dvander@237: 		 *
dvander@237: 		 * @return			Integer error code.
dvander@237: 		 */
dvander@237: 		virtual int GetErrorCode() =0;
dvander@237: 
dvander@237: 		/**
dvander@237: 		 * @brief Returns a string describing the error.
dvander@237: 		 *
dvander@237: 		 * @return			Error string.
dvander@237: 		 */
dvander@237: 		virtual const char *GetErrorString() =0;
dvander@237: 
dvander@237: 		/**
dvander@237: 		 * @brief Returns whether debug info is available.
dvander@237: 		 *
dvander@237: 		 * @return			True if debug info is available, false otherwise.
dvander@237: 		 */
dvander@237: 		virtual bool DebugInfoAvailable() =0;
dvander@237: 
dvander@237: 		/**
dvander@237: 		 * @brief Returns a custom error message.
dvander@237: 		 *
dvander@237: 		 * @return			A pointer to a custom error message, or NULL otherwise.
dvander@237: 		 */
dvander@237: 		virtual const char *GetCustomErrorString() =0;
dvander@237: 
dvander@237: 		/**
dvander@239: 		 * @brief Returns trace info for a specific point in the backtrace, if any.
dvander@239: 		 * The next subsequent call to GetTraceInfo() will return the next item in the call stack.
dvander@239: 		 * Calls are retrieved in descending order (i.e. the first item is at the top of the stack/call sequence).
dvander@237: 		 *
dvander@239: 		 * @param trace		An ErrorTraceInfo buffer to store information (NULL to ignore).
dvander@239: 		 * @return			True if successful, false if there are no more traces.
dvander@237: 		 */
dvander@239: 		virtual bool GetTraceInfo(CallStackInfo *trace) =0;
dvander@237: 
dvander@237: 		/**
dvander@239: 		 * @brief Resets the trace to its original position (the call on the top of the stack).
dvander@237: 		 */
dvander@239: 		virtual void ResetTrace() =0;
dvander@245: 
dvander@245: 		/**
dvander@245: 		 * @brief Retrieves the name of the last native called.
dvander@245: 		 * Returns NULL if there was no native that caused the error.
dvander@245: 		 *
faluco@256: 		 * @param index		Optional pointer to store index.
dvander@245: 		 * @return			Native name, or NULL if none.
dvander@245: 		 */
dvander@245: 		virtual const char *GetLastNative(uint32_t *index) =0;
dvander@237: 	};
dvander@237: 
dvander@239: 
dvander@239: 	/**
dvander@239: 	 * @brief Provides callbacks for debug information.
dvander@239: 	 */
dvander@237: 	class IDebugListener
dvander@237: 	{
dvander@237: 	public:
dvander@239: 		virtual void OnContextExecuteError(IPluginContext *ctx, IContextTrace *error) =0;
dvander@237: 	};
dvander@237: 
dvander@239: 
dvander@67: 	/**
dvander@164: 	 * @brief Contains helper functions used by VMs and the host app
dvander@67: 	 */
dvander@67: 	class ISourcePawnEngine
dvander@67: 	{
dvander@67: 	public:
dvander@67: 		/**
dvander@237: 		 * @brief Loads a named file from a file pointer.  
dvander@237: 		 * Note: Using this means the memory will be allocated by the VM.
dvander@237: 		 * 
dvander@237: 		 * @param fp			File pointer.  May be at any offset.  Not closed on return.
dvander@237: 		 * @param err		Optional error code pointer.
dvander@237: 		 * @return			A new plugin structure.
dvander@237: 		 */	
dvander@67: 		virtual sp_plugin_t *LoadFromFilePointer(FILE *fp, int *err) =0;
dvander@67: 	
dvander@67: 		/**
dvander@237: 		 * @brief Loads a file from a base memory address.
dvander@67: 		 *	
dvander@67: 		 * @param base		Base address of the plugin's memory region.
dvander@67: 		 * @param plugin	If NULL, a new plugin pointer is returned.
dvander@67: 		 *                  Otherwise, the passed pointer is used.
dvander@67: 		 * @param err		Optional error code pointer.
dvander@67: 		 * @return			The resulting plugin pointer.
dvander@67: 		 */
dvander@67: 		virtual sp_plugin_t *LoadFromMemory(void *base, sp_plugin_t *plugin, int *err) =0;
dvander@67: 
dvander@67: 		/**
dvander@67: 		 * Frees all of the memory associated with a plugin file.
dvander@67: 		 * If allocated using SP_LoadFromMemory, the base and plugin pointer 
dvander@67: 		 *  itself are not freed (so this may end up doing nothing).
dvander@67: 		 */
dvander@67: 		virtual int FreeFromMemory(sp_plugin_t *plugin) =0;
dvander@67: 
dvander@67: 		/**
dvander@237: 		 * @brief Allocates large blocks of temporary memory.
dvander@67: 		 * 
dvander@67: 		 * @param size		Size of memory to allocate.
dvander@67: 		 * @return			Pointer to memory, NULL if allocation failed.
dvander@67: 		 */
dvander@67: 		virtual void *BaseAlloc(size_t size) =0;
dvander@67: 
dvander@67: 		/**
dvander@237: 		 * @brief Frees memory allocated with BaseAlloc.
dvander@67: 		 *
faluco@149: 		 * @param memory	Memory address to free.
dvander@67: 		 */
dvander@67: 		virtual void BaseFree(void *memory) =0;
dvander@93: 
dvander@93: 		/**
dvander@237: 		 * @brief Allocates executable memory.
dvander@93: 		 *
dvander@93: 		 * @param size		Size of memory to allocate.
dvander@93: 		 * @return			Pointer to memory, NULL if allocation failed.
dvander@93: 		 */
dvander@93: 		virtual void *ExecAlloc(size_t size) =0;
dvander@93: 
dvander@93: 		/**
dvander@237: 		 * @brief Frees executable memory.
dvander@93: 		 *
faluco@149: 		 * @param address	Address to free.
dvander@93: 		 */
dvander@93: 		virtual void ExecFree(void *address) =0;
dvander@237: 
dvander@237: 		/**
dvander@245: 		 * @brief Sets the debug listener.  This should only be called once.
dvander@245: 		 * If called successively (using manual chaining), only the last function should
dvander@245: 		 * attempt to call back into the same plugin.  Otherwise, globally cached states
dvander@245: 		 * can be accidentally overwritten.
dvander@237: 		 *
dvander@237: 		 * @param listener	Pointer to an IDebugListener.
dvander@237: 		 * @return			Old IDebugListener, or NULL if none.
dvander@237: 		 */
dvander@263: 		virtual IDebugListener *SetDebugListener(IDebugListener *listener) =0;
dvander@237: 		
dvander@237: 		/**
dvander@237: 		 * @brief Returns the number of plugins on the call stack.
dvander@237: 		 *
dvander@237: 		 * @return			Number of contexts in the call stack.
dvander@237: 		 */
dvander@237: 		virtual unsigned int GetContextCallCount() =0;
dvander@239: 	};
dvander@237: 
dvander@67: 
dvander@237: 	/**
dvander@237: 	 * @brief Dummy class for encapsulating private compilation data.
dvander@237: 	 */
dvander@69: 	class ICompilation
dvander@69: 	{
dvander@69: 	public:
dvander@69: 		virtual ~ICompilation() { };
dvander@69: 	};
dvander@67: 
dvander@239: 
dvander@164: 	/** 
dvander@164: 	 * @brief Outlines the interface a Virtual Machine (JIT) must expose
dvander@164: 	 */
dvander@67: 	class IVirtualMachine
dvander@67: 	{
dvander@67: 	public:
dvander@67: 		/**
dvander@175: 		 * @brief Returns the current API version.
dvander@175: 		 */
dvander@175: 		virtual unsigned int GetAPIVersion() =0;
dvander@175: 
dvander@175: 		/**
dvander@175: 		 * @brief Returns the string name of a VM implementation.
dvander@67: 		 */
dvander@67: 		virtual const char *GetVMName() =0;
dvander@67: 
dvander@67: 		/**
dvander@175: 		 * @brief Begins a new compilation
dvander@67: 		 * 
dvander@67: 		 * @param plugin	Pointer to a plugin structure.
dvander@67: 		 * @return			New compilation pointer.
dvander@67: 		 */
dvander@67: 		virtual ICompilation *StartCompilation(sp_plugin_t *plugin) =0;
dvander@67: 
dvander@67: 		/**
dvander@175: 		 * @brief Sets a compilation option.
dvander@67: 		 *
dvander@67: 		 * @param co		Pointer to a compilation.
dvander@67: 		 * @param key		Option key name.
dvander@67: 		 * @param val		Option value string.
dvander@67: 		 * @return			True if option could be set, false otherwise.
dvander@67: 		 */
dvander@67: 		virtual bool SetCompilationOption(ICompilation *co, const char *key, const char *val) =0;
dvander@67: 
dvander@67: 		/**
dvander@175: 		 * @brief Finalizes a compilation into a new sp_context_t.
dvander@67: 		 * Note: This will free the ICompilation pointer.
dvander@67: 		 *
dvander@67: 		 * @param co		Compilation pointer.
dvander@69: 		 * @param err		Filled with error code on exit.
dvander@67: 		 * @return			New plugin context.
dvander@67: 		 */
dvander@93: 		virtual sp_context_t *CompileToContext(ICompilation *co, int *err) =0;
dvander@69: 
dvander@69: 		/**
dvander@175: 		 * @brief Aborts a compilation and frees the ICompilation pointer.
dvander@69: 		 *
dvander@69: 		 * @param co		Compilation pointer.
dvander@69: 		 */
dvander@69: 		virtual void AbortCompilation(ICompilation *co) =0;
dvander@67: 
dvander@67: 		/**
dvander@175: 		 * @brief Frees any internal variable usage on a context.
dvander@67: 		 *
dvander@67: 		 * @param ctx		Context structure pointer.
dvander@67: 		 */
dvander@93: 		virtual void FreeContext(sp_context_t *ctx) =0;
dvander@67: 
dvander@67: 		/**
dvander@175: 		 * @brief Calls the "execute" function on a context.
dvander@67: 		 *
dvander@67: 		 * @param ctx		Executes a function in a context.
dvander@175: 		 * @param code_addr	Index into the code section.
dvander@175: 		 * @param result	Pointer to store result into.
dvander@67: 		 * @return			Error code (if any).
dvander@67: 		 */
dvander@175: 		virtual int ContextExecute(sp_context_t *ctx, uint32_t code_addr, cell_t *result) =0;
dvander@175: 
dvander@175: 		/**
dvander@175: 		 * @brief Given a context and a code address, returns the index of the function.
dvander@175: 		 * 
dvander@175: 		 * @param ctx		Context to search.
dvander@175: 		 * @param code_addr	Index into the code section.
dvander@175: 		 * @param result	Pointer to store result into.
dvander@175: 		 * @return			True if code index is valid, false otherwise.
dvander@175: 		 */
dvander@175: 		virtual bool FunctionLookup(const sp_context_t *ctx, uint32_t code_addr, unsigned int *result) =0;
dvander@175: 
dvander@175: 		/**
dvander@175: 		 * @brief Returns the number of functions defined in the context.
dvander@175: 		 *
dvander@175: 		 * @param ctx		Context to search.
dvander@175: 		 * @return			Number of functions.
dvander@175: 		 */
dvander@175: 		virtual unsigned int FunctionCount(const sp_context_t *ctx) =0;
dvander@253: 
dvander@253: 		/**
dvander@253: 		 * @brief Returns a version string.
dvander@253: 		 *
dvander@253: 		 * @return			Versioning string.
dvander@253: 		 */
dvander@253: 		virtual const char *GetVersionString() =0;
dvander@253: 
dvander@253: 		/**
dvander@253: 		 * @brief Returns a string describing optimizations.
dvander@253: 		 *
dvander@253: 		 * @return			String describing CPU specific optimizations.
dvander@253: 		 */
dvander@253: 		virtual const char *GetCPUOptimizations() =0;
dvander@67: 	};
dvander@67: };
dvander@67: 
dvander@67: #endif //_INCLUDE_SOURCEPAWN_VM_API_H_