initial import of magical new API... FINALLY!
--HG-- extra : convert_revision : svn%3A39bc706e-5318-0410-9160-8a85361fbb7c/trunk%4072
This commit is contained in:
David Anderson
@@ -0,0 +1,133 @@
|
||||
#ifndef _INCLUDE_SOURCEPAWN_VM_API_H_
|
||||
#define _INCLUDE_SOURCEPAWN_VM_API_H_
|
||||
|
||||
#include <stdio.h>
|
||||
#include "sp_vm_types.h"
|
||||
#include "sp_vm_context.h"
|
||||
|
||||
namespace SourcePawn
|
||||
{
|
||||
class IPluginContext;
|
||||
|
||||
/**
|
||||
* Contains helper functions used by VMs and the host app
|
||||
*/
|
||||
class ISourcePawnEngine
|
||||
{
|
||||
public:
|
||||
/**
|
||||
* Loads a named file from a file pointer.
|
||||
* Using this means base memory will be allocated by the VM.
|
||||
*
|
||||
* @param fp File pointer. May be at any offset. Not closed on return.
|
||||
* @param err Optional error code pointer.
|
||||
* @return A new plugin structure.
|
||||
*/
|
||||
virtual sp_plugin_t *LoadFromFilePointer(FILE *fp, int *err) =0;
|
||||
|
||||
/**
|
||||
* Loads a file from a base memory address.
|
||||
*
|
||||
* @param base Base address of the plugin's memory region.
|
||||
* @param plugin If NULL, a new plugin pointer is returned.
|
||||
* Otherwise, the passed pointer is used.
|
||||
* @param err Optional error code pointer.
|
||||
* @return The resulting plugin pointer.
|
||||
*/
|
||||
virtual sp_plugin_t *LoadFromMemory(void *base, sp_plugin_t *plugin, int *err) =0;
|
||||
|
||||
/**
|
||||
* Frees all of the memory associated with a plugin file.
|
||||
* If allocated using SP_LoadFromMemory, the base and plugin pointer
|
||||
* itself are not freed (so this may end up doing nothing).
|
||||
*/
|
||||
virtual int FreeFromMemory(sp_plugin_t *plugin) =0;
|
||||
|
||||
/**
|
||||
* Creates a new IContext from a context handle.
|
||||
*
|
||||
* @param ctx Context to use as a basis for the IPluginContext.
|
||||
* @return New IPluginContext handle.
|
||||
*/
|
||||
virtual IPluginContext *CreateBaseContext(sp_context_t *ctx) =0;
|
||||
|
||||
/**
|
||||
* Frees a context.
|
||||
*
|
||||
* @param ctx Context pointer to free.
|
||||
*/
|
||||
virtual void FreeBaseContext(IPluginContext *ctx) =0;
|
||||
|
||||
/**
|
||||
* Allocates memory.
|
||||
*
|
||||
* @param size Size of memory to allocate.
|
||||
* @return Pointer to memory, NULL if allocation failed.
|
||||
*/
|
||||
virtual void *BaseAlloc(size_t size) =0;
|
||||
|
||||
/**
|
||||
* Frees memory allocated with BaseAlloc.
|
||||
*
|
||||
* @param mem Memory address to free.
|
||||
*/
|
||||
virtual void BaseFree(void *memory) =0;
|
||||
};
|
||||
|
||||
class ICompilation;
|
||||
|
||||
class IVirtualMachine
|
||||
{
|
||||
public:
|
||||
/**
|
||||
* Returns the string name of a VM implementation.
|
||||
*/
|
||||
virtual const char *GetVMName() =0;
|
||||
|
||||
/**
|
||||
* Begins a new compilation
|
||||
*
|
||||
* @param plugin Pointer to a plugin structure.
|
||||
* @return New compilation pointer.
|
||||
*/
|
||||
virtual ICompilation *StartCompilation(sp_plugin_t *plugin) =0;
|
||||
|
||||
/**
|
||||
* Sets a compilation option.
|
||||
*
|
||||
* @param co Pointer to a compilation.
|
||||
* @param key Option key name.
|
||||
* @param val Option value string.
|
||||
* @return True if option could be set, false otherwise.
|
||||
*/
|
||||
virtual bool SetCompilationOption(ICompilation *co, const char *key, const char *val) =0;
|
||||
|
||||
/**
|
||||
* Finalizes a compilation into a new IContext.
|
||||
* Note: This will free the ICompilation pointer.
|
||||
*
|
||||
* @param co Compilation pointer.
|
||||
* @return New plugin context.
|
||||
*/
|
||||
virtual IPluginContext *CompileToContext(ICompilation *co) =0;
|
||||
|
||||
/**
|
||||
* Frees any internal variable usage on a context.
|
||||
*
|
||||
* @param ctx Context structure pointer.
|
||||
*/
|
||||
virtual void FreeContextVars(sp_context_t *ctx) =0;
|
||||
|
||||
/**
|
||||
* Calls the "execute" function on a context.
|
||||
*
|
||||
* @param ctx Executes a function in a context.
|
||||
* @param code_idx Index into the code section.
|
||||
* @param result Pointer to store result in.
|
||||
* @return Error code (if any).
|
||||
*/
|
||||
virtual int ContextExecute(sp_context_t *ctx, uint32_t code_idx, cell_t *result) =0;
|
||||
};
|
||||
};
|
||||
|
||||
#endif //_INCLUDE_SOURCEPAWN_VM_API_H_
|
||||
@@ -0,0 +1,309 @@
|
||||
#ifndef _INCLUDE_SOURCEPAWN_VM_CONTEXT_H_
|
||||
#define _INCLUDE_SOURCEPAWN_VM_CONTEXT_H_
|
||||
|
||||
#include "sp_vm_types.h"
|
||||
|
||||
/*****************
|
||||
** Note that all functions return a non-zero error code on failure
|
||||
* unless otherwise noted.
|
||||
* All input pointers must be valid unless otherwise noted as optional.
|
||||
* All output pointers on failure are undefined.
|
||||
* All local address are guaranteed to be positive. However, they are stored
|
||||
* as signed integers, because they must logically fit inside a cell.
|
||||
*/
|
||||
|
||||
namespace SourcePawn
|
||||
{
|
||||
class IVirtualMachine;
|
||||
|
||||
class IPluginDebugInfo
|
||||
{
|
||||
public:
|
||||
/**
|
||||
* Given a code pointer, finds the file it is associated with.
|
||||
*
|
||||
* @param addr Code address offset.
|
||||
* @param filename Pointer to store filename pointer in.
|
||||
*/
|
||||
virtual int LookupFile(ucell_t addr, const char **filename) =0;
|
||||
|
||||
/**
|
||||
* Given a code pointer, finds the function it is associated with.
|
||||
*
|
||||
* @param addr Code address offset.
|
||||
* @param name Pointer to store function name pointer in.
|
||||
*/
|
||||
virtual int LookupFunction(ucell_t addr, const char **name) =0;
|
||||
|
||||
/**
|
||||
* Given a code pointer, finds the line it is associated with.
|
||||
*
|
||||
* @param addr Code address offset.
|
||||
* @param line Pointer to store line number in.
|
||||
*/
|
||||
virtual int LookupLine(ucell_t addr, uint32_t *line) =0;
|
||||
};
|
||||
|
||||
class IPluginContext
|
||||
{
|
||||
public:
|
||||
virtual ~IPluginContext() { };
|
||||
public:
|
||||
/**
|
||||
* Returns the parent IVirtualMachine.
|
||||
*
|
||||
* @return Parent virtual machine pointer.
|
||||
*/
|
||||
virtual IVirtualMachine *GetVirtualMachine() =0;
|
||||
|
||||
/**
|
||||
* Returns the child sp_context_t structure.
|
||||
*
|
||||
* @return Child sp_context_t structure.
|
||||
*/
|
||||
virtual sp_context_t *GetContext() =0;
|
||||
|
||||
/**
|
||||
* Returns true if the plugin is in debug mode.
|
||||
*
|
||||
* @return True if in debug mode, false otherwise.
|
||||
*/
|
||||
virtual bool IsDebugging() =0;
|
||||
|
||||
/**
|
||||
* Installs a debug break and returns the old one, if any.
|
||||
* This will fail if the plugin is not debugging.
|
||||
*
|
||||
* @param newpfn New function pointer.
|
||||
* @param oldpfn Pointer to retrieve old function pointer.
|
||||
*/
|
||||
virtual int SetDebugBreak(SPVM_DEBUGBREAK newpfn, SPVM_DEBUGBREAK *oldpfn) =0;
|
||||
|
||||
/**
|
||||
* Returns debug info.
|
||||
*
|
||||
* @return IPluginDebugInfo, or NULL if no debug info found.
|
||||
*/
|
||||
virtual IPluginDebugInfo *GetDebugInfo() =0;
|
||||
|
||||
/**
|
||||
* Allocs memory on the secondary stack of a plugin.
|
||||
* Note that although called a heap, it is in fact a stack.
|
||||
*
|
||||
* @param cells Number of cells to allocate.
|
||||
* @param local_adddr Will be filled with data offset to heap.
|
||||
* @param phys_addr Physical address to heap memory.
|
||||
*/
|
||||
virtual int HeapAlloc(unsigned int cells, cell_t *local_addr, cell_t **phys_addr) =0;
|
||||
|
||||
/**
|
||||
* Pops a heap address off the heap stack. Use this to free memory allocated with
|
||||
* SP_HeapAlloc().
|
||||
* Note that in SourcePawn, the heap is in fact a bottom-up stack. Deallocations
|
||||
* with this native should be performed in precisely the REVERSE order.
|
||||
*
|
||||
* @param local_addr Local address to free.
|
||||
*/
|
||||
virtual int HeapPop(cell_t local_addr) =0;
|
||||
|
||||
/**
|
||||
* Releases a heap address using a different method than SP_HeapPop().
|
||||
* This allows you to release in any order. However, if you allocate N
|
||||
* objects, release only some of them, then begin allocating again,
|
||||
* you cannot go back and starting freeing the originals.
|
||||
* In other words, for each chain of allocations, if you start deallocating,
|
||||
* then allocating more in a chain, you must only deallocate from the current
|
||||
* allocation chain. This is basically HeapPop() except on a larger scale.
|
||||
*
|
||||
* @param local_addr Local address to free.
|
||||
*/
|
||||
virtual int HeapRelease(cell_t local_addr) =0;
|
||||
|
||||
/**
|
||||
* Finds a native by name.
|
||||
*
|
||||
* @param name Name of native.
|
||||
* @param index Optionally filled with native index number.
|
||||
*/
|
||||
virtual int FindNativeByName(const char *name, uint32_t *index) =0;
|
||||
|
||||
/**
|
||||
* Gets native info by index.
|
||||
*
|
||||
* @param index Index number of native.
|
||||
* @param native Optionally filled with pointer to native structure.
|
||||
*/
|
||||
virtual int GetNativeByIndex(uint32_t index, sp_native_t **native) =0;
|
||||
|
||||
/**
|
||||
* Gets the number of natives.
|
||||
*
|
||||
* @return Filled with the number of natives.
|
||||
*/
|
||||
virtual uint32_t GetNativesNum() =0;
|
||||
|
||||
/**
|
||||
* Finds a public function by name.
|
||||
*
|
||||
* @param name Name of public
|
||||
* @param index Optionally filled with public index number.
|
||||
*/
|
||||
virtual int FindPublicByName(const char *name, uint32_t *index) =0;
|
||||
|
||||
/**
|
||||
* Gets public function info by index.
|
||||
*
|
||||
* @param index Public function index number.
|
||||
* @param pblic Optionally filled with pointer to public structure.
|
||||
*/
|
||||
virtual int GetPublicByIndex(uint32_t index, sp_public_t **publicptr) =0;
|
||||
|
||||
/**
|
||||
* Gets the number of public functions.
|
||||
*
|
||||
* @return Filled with the number of public functions.
|
||||
*/
|
||||
virtual uint32_t GetPublicsNum() =0;
|
||||
|
||||
/**
|
||||
* Gets public variable info by index.
|
||||
* @param index Public variable index number.
|
||||
* @param pubvar Optionally filled with pointer to pubvar structure.
|
||||
*/
|
||||
virtual int GetPubvarByIndex(uint32_t index, sp_pubvar_t **pubvar) =0;
|
||||
|
||||
/**
|
||||
* Finds a public variable by name.
|
||||
*
|
||||
* @param name Name of pubvar
|
||||
* @param index Optionally filled with pubvar index number.
|
||||
* @param local_addr Optionally filled with local address offset.
|
||||
* @param phys_addr Optionally filled with relocated physical address.
|
||||
*/
|
||||
virtual int FindPubvarByName(const char *name, uint32_t *index) =0;
|
||||
|
||||
/**
|
||||
* Gets the addresses of a public variable.
|
||||
*
|
||||
* @param index Index of public variable.
|
||||
* @param local_addr Address to store local address in.
|
||||
* @param phys_addr Address to store physically relocated in.
|
||||
*/
|
||||
virtual int GetPubvarAddrs(uint32_t index, cell_t *local_addr, cell_t **phys_addr) =0;
|
||||
|
||||
/**
|
||||
* Returns the number of public variables.
|
||||
*
|
||||
* @return Number of public variables.
|
||||
*/
|
||||
virtual uint32_t GetPubVarsNum() =0;
|
||||
|
||||
/**
|
||||
* Round-about method of converting a plugin reference to a physical address
|
||||
*
|
||||
* @param local_addr Local address in plugin.
|
||||
* @param phys_addr Optionally filled with relocated physical address.
|
||||
*/
|
||||
virtual int LocalToPhysAddr(cell_t local_addr, cell_t **phys_addr) =0;
|
||||
|
||||
/**
|
||||
* Converts a local address to a physical string.
|
||||
* Note that SourcePawn does not support packed strings, as such this function is
|
||||
* 'cell to char' only.
|
||||
*
|
||||
* @param local_addr Local address in plugin.
|
||||
* @param buffer Destination output buffer.
|
||||
* @param maxlength Maximum length of output buffer, including null terminator.
|
||||
* @param chars Optionally filled with the number of characters written.
|
||||
*/
|
||||
virtual int LocalToString(cell_t local_addr, char *buffer, size_t maxlength, int *chars) =0;
|
||||
|
||||
/**
|
||||
* Converts a physical string to a local address.
|
||||
* Note that SourcePawn does not support packed strings.
|
||||
*
|
||||
* @param local_addr Local address in plugin.
|
||||
* @param chars Number of chars to write, including NULL terminator.
|
||||
* @param source Source string to copy.
|
||||
*/
|
||||
virtual int StringToLocal(cell_t local_addr, size_t chars, const char *source) =0;
|
||||
|
||||
/**
|
||||
* Pushes a cell onto the stack. Increases the parameter count by one.
|
||||
*
|
||||
* @param value Cell value.
|
||||
*/
|
||||
virtual int PushCell(cell_t value) =0;
|
||||
|
||||
/**
|
||||
* Pushes an array of cells onto the stack. Increases the parameter count by one.
|
||||
* If the function returns an error it will fail entirely, releasing anything allocated in the process.
|
||||
* Note that this does not release the heap, so you should release it after
|
||||
* calling Execute().
|
||||
*
|
||||
* @param local_addr Filled with local address to release.
|
||||
* @param phys_addr Optionally filled with physical address of new array.
|
||||
* @param array Cell array to copy.
|
||||
* @param numcells Number of cells in the array to copy.
|
||||
*/
|
||||
virtual int PushCellArray(cell_t *local_addr, cell_t **phys_addr, cell_t array[], unsigned int numcells) =0;
|
||||
|
||||
/**
|
||||
* Pushes a string onto the stack (by reference) and increases the parameter count by one.
|
||||
* Note that this does not release the heap, so you should release it after
|
||||
* calling Execute().
|
||||
*
|
||||
* @param local_addr Filled with local address to release.
|
||||
* @param phys_addr Optionally filled with physical address of new array.
|
||||
* @param array Cell array to copy.
|
||||
* @param numcells Number of cells in the array to copy.
|
||||
*/
|
||||
virtual int PushString(cell_t *local_addr, cell_t **phys_addr, const char *string) =0;
|
||||
|
||||
/**
|
||||
* Individually pushes each cell of an array of cells onto the stack. Increases the
|
||||
* parameter count by the number of cells pushed.
|
||||
* If the function returns an error it will fail entirely, releasing anything allocated in the process.
|
||||
*
|
||||
* @param array Array of cells to read from.
|
||||
* @param numcells Number of cells to read.
|
||||
*/
|
||||
virtual int PushCellsFromArray(cell_t array[], unsigned int numcells) =0;
|
||||
|
||||
/**
|
||||
* Binds a list of native names and their function pointers to a context.
|
||||
* If num is 0, the list is read until an entry with a NULL name is reached.
|
||||
* All natives are assigned a status of SP_NATIVE_OKAY by default.
|
||||
* If overwrite is non-zero, already registered natives will be overwritten.
|
||||
*
|
||||
* @param natives Array of natives.
|
||||
* @param num Number of natives in array.
|
||||
*/
|
||||
virtual int BindNatives(sp_nativeinfo_t *natives, unsigned int num, int overwrite) =0;
|
||||
|
||||
/**
|
||||
* Binds a single native. Overwrites any existing bind.
|
||||
* If the context does not contain the native that will be binded the function will return
|
||||
* with a SP_ERR_NOT_FOUND error.
|
||||
*
|
||||
* @param native Pointer to native.
|
||||
* @param status Status value to set (should be SP_NATIVE_OKAY).
|
||||
*/
|
||||
virtual int BindNative(sp_nativeinfo_t *native, uint32_t status) =0;
|
||||
|
||||
/**
|
||||
* Binds a single native to any non-registered or pending native.
|
||||
* Status is automatically set to pending.
|
||||
*
|
||||
* @param native Native to bind.
|
||||
*/
|
||||
virtual int BindNativeToAny(SPVM_NATIVE_FUNC native) =0;
|
||||
|
||||
/**
|
||||
* Executes a public function.
|
||||
*/
|
||||
virtual int Execute(uint32_t public_func, cell_t *result) =0;
|
||||
};
|
||||
};
|
||||
|
||||
#endif //_INCLUDE_SOURCEPAWN_VM_CONTEXT_H_
|
||||
@@ -19,6 +19,7 @@ typedef int32_t cell_t;
|
||||
#define SP_ERR_INDEX 7 /* Invalid index parameter */
|
||||
#define SP_ERR_NATIVE_PENDING 8 /* A script tried to exec an unbound native */
|
||||
#define SP_ERR_STACKERR 9 /* Stack/Heap collision */
|
||||
#define SP_ERR_NOTDEBUGGING 10 /* Debug mode was not on or debug section not found */
|
||||
|
||||
/**********************************************
|
||||
*** The following structures are reference structures.
|
||||
@@ -125,6 +126,15 @@ typedef struct sp_native_s
|
||||
uint32_t status; /* status flags */
|
||||
} sp_native_t;
|
||||
|
||||
/**
|
||||
* Used for setting natives from modules/host apps.
|
||||
*/
|
||||
typedef struct sp_nativeinfo_s
|
||||
{
|
||||
const char *name;
|
||||
SPVM_NATIVE_FUNC func;
|
||||
} sp_nativeinfo_t;
|
||||
|
||||
/**
|
||||
* Debug file table
|
||||
*/
|
||||
@@ -159,49 +169,39 @@ typedef struct sp_debug_symbol_s
|
||||
sp_fdbg_symbol_t *sym; /* pointer to original symbol */
|
||||
} sp_debug_symbol_t;
|
||||
|
||||
/**
|
||||
* Executes a Context.
|
||||
* @sp_context_s - Execution Context
|
||||
* @uint32_t - Offset from code pointer
|
||||
* @res - return value of function
|
||||
* @return - error code (0=none)
|
||||
*/
|
||||
typedef int (*SPVM_EXEC)(struct sp_context_s *,
|
||||
uint32_t,
|
||||
cell_t *res);
|
||||
|
||||
/**
|
||||
* Breaks into a debugger
|
||||
*/
|
||||
typedef int (*SPVM_DEBUGBREAK)(struct sp_context_s *);
|
||||
|
||||
#define SP_CONTEXT_DEBUG (1<<0) /* in debug mode */
|
||||
#define SP_CONTEXT_INHERIT_MEMORY (1<<1) /* inherits memory pointers */
|
||||
#define SP_CONTEXT_INHERIT_CODE (1<<2) /* inherits code pointers */
|
||||
#define SPFLAG_PLUGIN_DEBUG (1<<0) /* plugin is in debug mode */
|
||||
|
||||
/**
|
||||
* This is the heart of the VM. It contains all of the runtime
|
||||
* information about a plugin context.
|
||||
* It is split into three sections.
|
||||
* Note that user[0..3] can be used for any user based pointers.
|
||||
* vm[0..3] should not be touched, as it is reserved for the VM.
|
||||
*/
|
||||
typedef struct sp_context_s
|
||||
{
|
||||
/* general/parent information */
|
||||
void *base; /* base of generated code and memory */
|
||||
sp_plugin_t *plugin; /* pointer back to parent information */
|
||||
struct sp_context_s *parent; /* pointer to parent context */
|
||||
uint32_t flags; /* context flags */
|
||||
void *context; /* pointer to IPluginContext */
|
||||
void *vmbase; /* pointer to IVirtualMachine */
|
||||
void *user[4]; /* user specific pointers */
|
||||
void *vm[4]; /* VM specific pointers */
|
||||
uint32_t flags; /* compilation flags */
|
||||
SPVM_DEBUGBREAK dbreak; /* debug break function */
|
||||
void *user; /* user specific pointer */
|
||||
/* execution specific data */
|
||||
SPVM_EXEC exec; /* execution base */
|
||||
cell_t pri; /* PRI register */
|
||||
cell_t alt; /* ALT register */
|
||||
/* context runtime information */
|
||||
ucell_t memory; /* total memory size; */
|
||||
uint8_t *data; /* data chunk */
|
||||
cell_t heapbase; /* heap base */
|
||||
/* execution specific data */
|
||||
cell_t pri; /* PRI register */
|
||||
cell_t alt; /* ALT register */
|
||||
cell_t hp; /* heap pointer */
|
||||
cell_t sp; /* stack pointer */
|
||||
ucell_t memory; /* total memory size; */
|
||||
int32_t err; /* error code */
|
||||
uint32_t pushcount; /* push count */
|
||||
/* context rebased database */
|
||||
|
||||
Reference in New Issue
Block a user