1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/public/sourcepawn/sp_vm_api.h Fri Jan 19 05:33:04 2007 +0000
1.3 @@ -0,0 +1,631 @@
1.4 +#ifndef _INCLUDE_SOURCEPAWN_VM_API_H_
1.5 +#define _INCLUDE_SOURCEPAWN_VM_API_H_
1.6 +
1.7 +#include <stdio.h>
1.8 +#include "sp_vm_types.h"
1.9 +
1.10 +#define SOURCEPAWN_VM_API_VERSION 1
1.11 +
1.12 +#if defined SOURCEMOD_BUILD
1.13 +namespace SourceMod
1.14 +{
1.15 + struct IdentityToken_t;
1.16 +};
1.17 +#endif
1.18 +
1.19 +namespace SourcePawn
1.20 +{
1.21 + class IVirtualMachine;
1.22 +
1.23 + /**
1.24 + * @brief Interface to managing a debug context at runtime.
1.25 + */
1.26 + class IPluginDebugInfo
1.27 + {
1.28 + public:
1.29 + /**
1.30 + * @brief Given a code pointer, finds the file it is associated with.
1.31 + *
1.32 + * @param addr Code address offset.
1.33 + * @param filename Pointer to store filename pointer in.
1.34 + */
1.35 + virtual int LookupFile(ucell_t addr, const char **filename) =0;
1.36 +
1.37 + /**
1.38 + * @brief Given a code pointer, finds the function it is associated with.
1.39 + *
1.40 + * @param addr Code address offset.
1.41 + * @param name Pointer to store function name pointer in.
1.42 + */
1.43 + virtual int LookupFunction(ucell_t addr, const char **name) =0;
1.44 +
1.45 + /**
1.46 + * @brief Given a code pointer, finds the line it is associated with.
1.47 + *
1.48 + * @param addr Code address offset.
1.49 + * @param line Pointer to store line number in.
1.50 + */
1.51 + virtual int LookupLine(ucell_t addr, uint32_t *line) =0;
1.52 + };
1.53 +
1.54 + /**
1.55 + * @brief Interface to managing a context at runtime.
1.56 + */
1.57 + class IPluginContext
1.58 + {
1.59 + public:
1.60 + virtual ~IPluginContext() { };
1.61 + public:
1.62 + /**
1.63 + * @brief Returns the parent IVirtualMachine.
1.64 + *
1.65 + * @return Parent virtual machine pointer.
1.66 + */
1.67 + virtual IVirtualMachine *GetVirtualMachine() =0;
1.68 +
1.69 + /**
1.70 + * @brief Returns the child sp_context_t structure.
1.71 + *
1.72 + * @return Child sp_context_t structure.
1.73 + */
1.74 + virtual sp_context_t *GetContext() =0;
1.75 +
1.76 + /**
1.77 + * @brief Returns true if the plugin is in debug mode.
1.78 + *
1.79 + * @return True if in debug mode, false otherwise.
1.80 + */
1.81 + virtual bool IsDebugging() =0;
1.82 +
1.83 + /**
1.84 + * @brief Installs a debug break and returns the old one, if any.
1.85 + * This will fail if the plugin is not debugging.
1.86 + *
1.87 + * @param newpfn New function pointer.
1.88 + * @param oldpfn Pointer to retrieve old function pointer.
1.89 + */
1.90 + virtual int SetDebugBreak(SPVM_DEBUGBREAK newpfn, SPVM_DEBUGBREAK *oldpfn) =0;
1.91 +
1.92 + /**
1.93 + * @brief Returns debug info.
1.94 + *
1.95 + * @return IPluginDebugInfo, or NULL if no debug info found.
1.96 + */
1.97 + virtual IPluginDebugInfo *GetDebugInfo() =0;
1.98 +
1.99 + /**
1.100 + * @brief Allocs memory on the secondary stack of a plugin.
1.101 + * Note that although called a heap, it is in fact a stack.
1.102 + *
1.103 + * @param cells Number of cells to allocate.
1.104 + * @param local_addr Will be filled with data offset to heap.
1.105 + * @param phys_addr Physical address to heap memory.
1.106 + */
1.107 + virtual int HeapAlloc(unsigned int cells, cell_t *local_addr, cell_t **phys_addr) =0;
1.108 +
1.109 + /**
1.110 + * @brief Pops a heap address off the heap stack. Use this to free memory allocated with
1.111 + * SP_HeapAlloc().
1.112 + * Note that in SourcePawn, the heap is in fact a bottom-up stack. Deallocations
1.113 + * with this native should be performed in precisely the REVERSE order.
1.114 + *
1.115 + * @param local_addr Local address to free.
1.116 + */
1.117 + virtual int HeapPop(cell_t local_addr) =0;
1.118 +
1.119 + /**
1.120 + * @brief Releases a heap address using a different method than SP_HeapPop().
1.121 + * This allows you to release in any order. However, if you allocate N
1.122 + * objects, release only some of them, then begin allocating again,
1.123 + * you cannot go back and starting freeing the originals.
1.124 + * In other words, for each chain of allocations, if you start deallocating,
1.125 + * then allocating more in a chain, you must only deallocate from the current
1.126 + * allocation chain. This is basically HeapPop() except on a larger scale.
1.127 + *
1.128 + * @param local_addr Local address to free.
1.129 + */
1.130 + virtual int HeapRelease(cell_t local_addr) =0;
1.131 +
1.132 + /**
1.133 + * @brief Finds a native by name.
1.134 + *
1.135 + * @param name Name of native.
1.136 + * @param index Optionally filled with native index number.
1.137 + */
1.138 + virtual int FindNativeByName(const char *name, uint32_t *index) =0;
1.139 +
1.140 + /**
1.141 + * @brief Gets native info by index.
1.142 + *
1.143 + * @param index Index number of native.
1.144 + * @param native Optionally filled with pointer to native structure.
1.145 + */
1.146 + virtual int GetNativeByIndex(uint32_t index, sp_native_t **native) =0;
1.147 +
1.148 + /**
1.149 + * @brief Gets the number of natives.
1.150 + *
1.151 + * @return Filled with the number of natives.
1.152 + */
1.153 + virtual uint32_t GetNativesNum() =0;
1.154 +
1.155 + /**
1.156 + * @brief Finds a public function by name.
1.157 + *
1.158 + * @param name Name of public
1.159 + * @param index Optionally filled with public index number.
1.160 + */
1.161 + virtual int FindPublicByName(const char *name, uint32_t *index) =0;
1.162 +
1.163 + /**
1.164 + * @brief Gets public function info by index.
1.165 + *
1.166 + * @param index Public function index number.
1.167 + * @param publicptr Optionally filled with pointer to public structure.
1.168 + */
1.169 + virtual int GetPublicByIndex(uint32_t index, sp_public_t **publicptr) =0;
1.170 +
1.171 + /**
1.172 + * @brief Gets the number of public functions.
1.173 + *
1.174 + * @return Filled with the number of public functions.
1.175 + */
1.176 + virtual uint32_t GetPublicsNum() =0;
1.177 +
1.178 + /**
1.179 + * @brief Gets public variable info by index.
1.180 + *
1.181 + * @param index Public variable index number.
1.182 + * @param pubvar Optionally filled with pointer to pubvar structure.
1.183 + */
1.184 + virtual int GetPubvarByIndex(uint32_t index, sp_pubvar_t **pubvar) =0;
1.185 +
1.186 + /**
1.187 + * @brief Finds a public variable by name.
1.188 + *
1.189 + * @param name Name of pubvar
1.190 + * @param index Optionally filled with pubvar index number.
1.191 + */
1.192 + virtual int FindPubvarByName(const char *name, uint32_t *index) =0;
1.193 +
1.194 + /**
1.195 + * @brief Gets the addresses of a public variable.
1.196 + *
1.197 + * @param index Index of public variable.
1.198 + * @param local_addr Address to store local address in.
1.199 + * @param phys_addr Address to store physically relocated in.
1.200 + */
1.201 + virtual int GetPubvarAddrs(uint32_t index, cell_t *local_addr, cell_t **phys_addr) =0;
1.202 +
1.203 + /**
1.204 + * @brief Returns the number of public variables.
1.205 + *
1.206 + * @return Number of public variables.
1.207 + */
1.208 + virtual uint32_t GetPubVarsNum() =0;
1.209 +
1.210 + /**
1.211 + * @brief Round-about method of converting a plugin reference to a physical address
1.212 + *
1.213 + * @param local_addr Local address in plugin.
1.214 + * @param phys_addr Optionally filled with relocated physical address.
1.215 + */
1.216 + virtual int LocalToPhysAddr(cell_t local_addr, cell_t **phys_addr) =0;
1.217 +
1.218 + /**
1.219 + * @brief Converts a local address to a physical string.
1.220 + *
1.221 + * @param local_addr Local address in plugin.
1.222 + * @param addr Destination output pointer.
1.223 + */
1.224 + virtual int LocalToString(cell_t local_addr, char **addr) =0;
1.225 +
1.226 + /**
1.227 + * @brief Converts a physical string to a local address.
1.228 + *
1.229 + * @param local_addr Local address in plugin.
1.230 + * @param bytes Number of chars to write, including NULL terminator.
1.231 + * @param source Source string to copy.
1.232 + */
1.233 + virtual int StringToLocal(cell_t local_addr, size_t bytes, const char *source) =0;
1.234 +
1.235 + /**
1.236 + * @brief Converts a physical UTF-8 string to a local address.
1.237 + * This function is the same as the ANSI version, except it will copy the maximum number of characters possible
1.238 + * without accidentally chopping a multi-byte character.
1.239 + *
1.240 + * @param local_addr Local address in plugin.
1.241 + * @param maxbytes Number of bytes to write, including NULL terminator.
1.242 + * @param source Source string to copy.
1.243 + * @param wrtnbytes Optionally set to the number of actual bytes written.
1.244 + */
1.245 + virtual int StringToLocalUTF8(cell_t local_addr,
1.246 + size_t maxbytes,
1.247 + const char *source,
1.248 + size_t *wrtnbytes) =0;
1.249 +
1.250 + /**
1.251 + * @brief Pushes a cell onto the stack. Increases the parameter count by one.
1.252 + *
1.253 + * @param value Cell value.
1.254 + */
1.255 + virtual int PushCell(cell_t value) =0;
1.256 +
1.257 + /**
1.258 + * @brief Pushes an array of cells onto the stack. Increases the parameter count by one.
1.259 + * If the function returns an error it will fail entirely, releasing anything allocated in the process.
1.260 + * Note that this does not release the heap, so you should release it after
1.261 + * calling Execute().
1.262 + *
1.263 + * @param local_addr Filled with local address to release.
1.264 + * @param phys_addr Optionally filled with physical address of new array.
1.265 + * @param array Cell array to copy.
1.266 + * @param numcells Number of cells in the array to copy.
1.267 + */
1.268 + virtual int PushCellArray(cell_t *local_addr, cell_t **phys_addr, cell_t array[], unsigned int numcells) =0;
1.269 +
1.270 + /**
1.271 + * @brief Pushes a string onto the stack (by reference) and increases the parameter count by one.
1.272 + * Note that this does not release the heap, so you should release it after
1.273 + * calling Execute().
1.274 + *
1.275 + * @param local_addr Filled with local address to release.
1.276 + * @param phys_addr Optionally filled with physical address of new array.
1.277 + * @param string Source string to push.
1.278 + */
1.279 + virtual int PushString(cell_t *local_addr, char **phys_addr, const char *string) =0;
1.280 +
1.281 + /**
1.282 + * @brief Individually pushes each cell of an array of cells onto the stack. Increases the
1.283 + * parameter count by the number of cells pushed.
1.284 + * If the function returns an error it will fail entirely, releasing anything allocated in the process.
1.285 + *
1.286 + * @param array Array of cells to read from.
1.287 + * @param numcells Number of cells to read.
1.288 + */
1.289 + virtual int PushCellsFromArray(cell_t array[], unsigned int numcells) =0;
1.290 +
1.291 + /**
1.292 + * @brief Binds a list of native names and their function pointers to a context.
1.293 + * If num is 0, the list is read until an entry with a NULL name is reached.
1.294 + * If overwrite is non-zero, already registered natives will be overwritten.
1.295 + *
1.296 + * @param natives Array of natives.
1.297 + * @param num Number of natives in array.
1.298 + * @param overwrite Toggles overwrite.
1.299 + */
1.300 + virtual int BindNatives(const sp_nativeinfo_t *natives, unsigned int num, int overwrite) =0;
1.301 +
1.302 + /**
1.303 + * @brief Binds a single native. Overwrites any existing bind.
1.304 + * If the context does not contain the native that will be binded the function will return
1.305 + * with a SP_ERROR_NOT_FOUND error.
1.306 + *
1.307 + * @param native Pointer to native.
1.308 + */
1.309 + virtual int BindNative(const sp_nativeinfo_t *native) =0;
1.310 +
1.311 + /**
1.312 + * @brief Binds a single native to any non-registered native.
1.313 + *
1.314 + * @param native Native to bind.
1.315 + */
1.316 + virtual int BindNativeToAny(SPVM_NATIVE_FUNC native) =0;
1.317 +
1.318 + /**
1.319 + * @brief Executes a function ID located in this context.
1.320 + *
1.321 + * @param funcid Function id to execute.
1.322 + * @param result Pointer to store the return value (required).
1.323 + * @return Error code (if any) from the VM.
1.324 + */
1.325 + virtual int Execute(uint32_t funcid, cell_t *result) =0;
1.326 +
1.327 +
1.328 + /**
1.329 + * @brief Throws a error and halts any current execution.
1.330 + *
1.331 + * @param error The error number to set.
1.332 + * @param msg Custom error message format. NULL to use default.
1.333 + * @param ... Message format arguments, if any.
1.334 + */
1.335 + virtual void ThrowNativeErrorEx(int error, const char *msg, ...) =0;
1.336 +
1.337 + /**
1.338 + * @brief Throws a generic native error and halts any current execution.
1.339 + *
1.340 + * @param msg Custom error message format. NULL to set no message.
1.341 + * @param ... Message format arguments, if any.
1.342 + * @return 0 for convenience.
1.343 + */
1.344 + virtual cell_t ThrowNativeError(const char *msg, ...) =0;
1.345 +
1.346 +#if defined SOURCEMOD_BUILD
1.347 + /**
1.348 + * @brief Returns the identity token for this context.
1.349 + * Note: This is a helper function for native calls and the Handle System.
1.350 + *
1.351 + * @return Identity token.
1.352 + */
1.353 + virtual SourceMod::IdentityToken_t *GetIdentity() =0;
1.354 +#endif
1.355 + };
1.356 +
1.357 +
1.358 + /**
1.359 + * @brief Information about a position in a call stack.
1.360 + */
1.361 + struct CallStackInfo
1.362 + {
1.363 + const char *filename; /* NULL if not found */
1.364 + unsigned int line; /* 0 if not found */
1.365 + const char *function; /* NULL if not found */
1.366 + };
1.367 +
1.368 + /**
1.369 + * @brief Retrieves error information from a debug hook.
1.370 + */
1.371 + class IContextTrace
1.372 + {
1.373 + public:
1.374 + /**
1.375 + * @brief Returns the integer error code.
1.376 + *
1.377 + * @return Integer error code.
1.378 + */
1.379 + virtual int GetErrorCode() =0;
1.380 +
1.381 + /**
1.382 + * @brief Returns a string describing the error.
1.383 + *
1.384 + * @return Error string.
1.385 + */
1.386 + virtual const char *GetErrorString() =0;
1.387 +
1.388 + /**
1.389 + * @brief Returns whether debug info is available.
1.390 + *
1.391 + * @return True if debug info is available, false otherwise.
1.392 + */
1.393 + virtual bool DebugInfoAvailable() =0;
1.394 +
1.395 + /**
1.396 + * @brief Returns a custom error message.
1.397 + *
1.398 + * @return A pointer to a custom error message, or NULL otherwise.
1.399 + */
1.400 + virtual const char *GetCustomErrorString() =0;
1.401 +
1.402 + /**
1.403 + * @brief Returns trace info for a specific point in the backtrace, if any.
1.404 + * The next subsequent call to GetTraceInfo() will return the next item in the call stack.
1.405 + * Calls are retrieved in descending order (i.e. the first item is at the top of the stack/call sequence).
1.406 + *
1.407 + * @param trace An ErrorTraceInfo buffer to store information (NULL to ignore).
1.408 + * @return True if successful, false if there are no more traces.
1.409 + */
1.410 + virtual bool GetTraceInfo(CallStackInfo *trace) =0;
1.411 +
1.412 + /**
1.413 + * @brief Resets the trace to its original position (the call on the top of the stack).
1.414 + */
1.415 + virtual void ResetTrace() =0;
1.416 +
1.417 + /**
1.418 + * @brief Retrieves the name of the last native called.
1.419 + * Returns NULL if there was no native that caused the error.
1.420 + *
1.421 + * @param index Optional pointer to store index.
1.422 + * @return Native name, or NULL if none.
1.423 + */
1.424 + virtual const char *GetLastNative(uint32_t *index) =0;
1.425 + };
1.426 +
1.427 +
1.428 + /**
1.429 + * @brief Provides callbacks for debug information.
1.430 + */
1.431 + class IDebugListener
1.432 + {
1.433 + public:
1.434 + virtual void OnContextExecuteError(IPluginContext *ctx, IContextTrace *error) =0;
1.435 + };
1.436 +
1.437 +
1.438 + /**
1.439 + * @brief Contains helper functions used by VMs and the host app
1.440 + */
1.441 + class ISourcePawnEngine
1.442 + {
1.443 + public:
1.444 + /**
1.445 + * @brief Loads a named file from a file pointer.
1.446 + * Note: Using this means the memory will be allocated by the VM.
1.447 + *
1.448 + * @param fp File pointer. May be at any offset. Not closed on return.
1.449 + * @param err Optional error code pointer.
1.450 + * @return A new plugin structure.
1.451 + */
1.452 + virtual sp_plugin_t *LoadFromFilePointer(FILE *fp, int *err) =0;
1.453 +
1.454 + /**
1.455 + * @brief Loads a file from a base memory address.
1.456 + *
1.457 + * @param base Base address of the plugin's memory region.
1.458 + * @param plugin If NULL, a new plugin pointer is returned.
1.459 + * Otherwise, the passed pointer is used.
1.460 + * @param err Optional error code pointer.
1.461 + * @return The resulting plugin pointer.
1.462 + */
1.463 + virtual sp_plugin_t *LoadFromMemory(void *base, sp_plugin_t *plugin, int *err) =0;
1.464 +
1.465 + /**
1.466 + * Frees all of the memory associated with a plugin file.
1.467 + * If allocated using SP_LoadFromMemory, the base and plugin pointer
1.468 + * itself are not freed (so this may end up doing nothing).
1.469 + */
1.470 + virtual int FreeFromMemory(sp_plugin_t *plugin) =0;
1.471 +
1.472 + /**
1.473 + * @brief Allocates large blocks of temporary memory.
1.474 + *
1.475 + * @param size Size of memory to allocate.
1.476 + * @return Pointer to memory, NULL if allocation failed.
1.477 + */
1.478 + virtual void *BaseAlloc(size_t size) =0;
1.479 +
1.480 + /**
1.481 + * @brief Frees memory allocated with BaseAlloc.
1.482 + *
1.483 + * @param memory Memory address to free.
1.484 + */
1.485 + virtual void BaseFree(void *memory) =0;
1.486 +
1.487 + /**
1.488 + * @brief Allocates executable memory.
1.489 + *
1.490 + * @param size Size of memory to allocate.
1.491 + * @return Pointer to memory, NULL if allocation failed.
1.492 + */
1.493 + virtual void *ExecAlloc(size_t size) =0;
1.494 +
1.495 + /**
1.496 + * @brief Frees executable memory.
1.497 + *
1.498 + * @param address Address to free.
1.499 + */
1.500 + virtual void ExecFree(void *address) =0;
1.501 +
1.502 + /**
1.503 + * @brief Sets the debug listener. This should only be called once.
1.504 + * If called successively (using manual chaining), only the last function should
1.505 + * attempt to call back into the same plugin. Otherwise, globally cached states
1.506 + * can be accidentally overwritten.
1.507 + *
1.508 + * @param listener Pointer to an IDebugListener.
1.509 + * @return Old IDebugListener, or NULL if none.
1.510 + */
1.511 + virtual IDebugListener *SetDebugListener(IDebugListener *listener) =0;
1.512 +
1.513 + /**
1.514 + * @brief Returns the number of plugins on the call stack.
1.515 + *
1.516 + * @return Number of contexts in the call stack.
1.517 + */
1.518 + virtual unsigned int GetContextCallCount() =0;
1.519 + };
1.520 +
1.521 +
1.522 + /**
1.523 + * @brief Dummy class for encapsulating private compilation data.
1.524 + */
1.525 + class ICompilation
1.526 + {
1.527 + public:
1.528 + virtual ~ICompilation() { };
1.529 + };
1.530 +
1.531 +
1.532 + /**
1.533 + * @brief Outlines the interface a Virtual Machine (JIT) must expose
1.534 + */
1.535 + class IVirtualMachine
1.536 + {
1.537 + public:
1.538 + /**
1.539 + * @brief Returns the current API version.
1.540 + */
1.541 + virtual unsigned int GetAPIVersion() =0;
1.542 +
1.543 + /**
1.544 + * @brief Returns the string name of a VM implementation.
1.545 + */
1.546 + virtual const char *GetVMName() =0;
1.547 +
1.548 + /**
1.549 + * @brief Begins a new compilation
1.550 + *
1.551 + * @param plugin Pointer to a plugin structure.
1.552 + * @return New compilation pointer.
1.553 + */
1.554 + virtual ICompilation *StartCompilation(sp_plugin_t *plugin) =0;
1.555 +
1.556 + /**
1.557 + * @brief Sets a compilation option.
1.558 + *
1.559 + * @param co Pointer to a compilation.
1.560 + * @param key Option key name.
1.561 + * @param val Option value string.
1.562 + * @return True if option could be set, false otherwise.
1.563 + */
1.564 + virtual bool SetCompilationOption(ICompilation *co, const char *key, const char *val) =0;
1.565 +
1.566 + /**
1.567 + * @brief Finalizes a compilation into a new sp_context_t.
1.568 + * Note: This will free the ICompilation pointer.
1.569 + *
1.570 + * @param co Compilation pointer.
1.571 + * @param err Filled with error code on exit.
1.572 + * @return New plugin context.
1.573 + */
1.574 + virtual sp_context_t *CompileToContext(ICompilation *co, int *err) =0;
1.575 +
1.576 + /**
1.577 + * @brief Aborts a compilation and frees the ICompilation pointer.
1.578 + *
1.579 + * @param co Compilation pointer.
1.580 + */
1.581 + virtual void AbortCompilation(ICompilation *co) =0;
1.582 +
1.583 + /**
1.584 + * @brief Frees any internal variable usage on a context.
1.585 + *
1.586 + * @param ctx Context structure pointer.
1.587 + */
1.588 + virtual void FreeContext(sp_context_t *ctx) =0;
1.589 +
1.590 + /**
1.591 + * @brief Calls the "execute" function on a context.
1.592 + *
1.593 + * @param ctx Executes a function in a context.
1.594 + * @param code_addr Index into the code section.
1.595 + * @param result Pointer to store result into.
1.596 + * @return Error code (if any).
1.597 + */
1.598 + virtual int ContextExecute(sp_context_t *ctx, uint32_t code_addr, cell_t *result) =0;
1.599 +
1.600 + /**
1.601 + * @brief Given a context and a code address, returns the index of the function.
1.602 + *
1.603 + * @param ctx Context to search.
1.604 + * @param code_addr Index into the code section.
1.605 + * @param result Pointer to store result into.
1.606 + * @return True if code index is valid, false otherwise.
1.607 + */
1.608 + virtual bool FunctionLookup(const sp_context_t *ctx, uint32_t code_addr, unsigned int *result) =0;
1.609 +
1.610 + /**
1.611 + * @brief Returns the number of functions defined in the context.
1.612 + *
1.613 + * @param ctx Context to search.
1.614 + * @return Number of functions.
1.615 + */
1.616 + virtual unsigned int FunctionCount(const sp_context_t *ctx) =0;
1.617 +
1.618 + /**
1.619 + * @brief Returns a version string.
1.620 + *
1.621 + * @return Versioning string.
1.622 + */
1.623 + virtual const char *GetVersionString() =0;
1.624 +
1.625 + /**
1.626 + * @brief Returns a string describing optimizations.
1.627 + *
1.628 + * @return String describing CPU specific optimizations.
1.629 + */
1.630 + virtual const char *GetCPUOptimizations() =0;
1.631 + };
1.632 +};
1.633 +
1.634 +#endif //_INCLUDE_SOURCEPAWN_VM_API_H_
