1.1 --- a/public/sourcepawn/sp_vm_types.h Thu Jan 25 22:39:12 2007 +0000
1.2 +++ b/public/sourcepawn/sp_vm_types.h Fri Jan 26 01:55:06 2007 +0000
1.3 @@ -1,45 +1,64 @@
1.4 +/**
1.5 + * ================================================================
1.6 + * SourcePawn (C)2004-2007 AlliedModders LLC. All rights reserved.
1.7 + * ================================================================
1.8 + *
1.9 + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used
1.10 + * or modified under the Terms and Conditions of its License Agreement, which is found
1.11 + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins
1.12 + * may change at any time. To view the latest information, see:
1.13 + * http://www.sourcemod.net/license.php
1.14 + *
1.15 + * Version: $Id$
1.16 + */
1.17 +
1.18 #ifndef _INCLUDE_SOURCEPAWN_VM_TYPES_H
1.19 #define _INCLUDE_SOURCEPAWN_VM_TYPES_H
1.20
1.21 +/**
1.22 + * @file sp_vm_types.h
1.23 + * @brief Contains all run-time SourcePawn structures.
1.24 + */
1.25 +
1.26 #include "sp_file_headers.h"
1.27
1.28 -typedef uint32_t ucell_t;
1.29 -typedef int32_t cell_t;
1.30 -typedef uint32_t funcid_t;
1.31 +typedef uint32_t ucell_t; /**< Unsigned 32bit integer */
1.32 +typedef int32_t cell_t; /**< Basic 32bit signed integer type for plugins */
1.33 +typedef uint32_t funcid_t; /**< Function index code */
1.34
1.35 #include "sp_typeutil.h"
1.36
1.37 -#define SP_MAX_EXEC_PARAMS 32 /* Maximum number of parameters in a function */
1.38 +#define SP_MAX_EXEC_PARAMS 32 /**< Maximum number of parameters in a function */
1.39
1.40 /**
1.41 - * Error codes
1.42 - * NOTE: Be sure to update the error string table when changing these
1.43 + * @brief Error codes for SourcePawn routines.
1.44 */
1.45 -#define SP_ERROR_NONE 0
1.46 -#define SP_ERROR_FILE_FORMAT 1 /* File format unrecognized */
1.47 -#define SP_ERROR_DECOMPRESSOR 2 /* A decompressor was not found */
1.48 -#define SP_ERROR_HEAPLOW 3 /* Not enough space left on the heap */
1.49 -#define SP_ERROR_PARAM 4 /* Invalid parameter or parameter type */
1.50 -#define SP_ERROR_INVALID_ADDRESS 5 /* A memory address was not valid */
1.51 -#define SP_ERROR_NOT_FOUND 6 /* The object in question was not found */
1.52 -#define SP_ERROR_INDEX 7 /* Invalid index parameter */
1.53 -#define SP_ERROR_STACKLOW 8 /* Nnot enough space left on the stack */
1.54 -#define SP_ERROR_NOTDEBUGGING 9 /* Debug mode was not on or debug section not found */
1.55 -#define SP_ERROR_INVALID_INSTRUCTION 10 /* Invalid instruction was encountered */
1.56 -#define SP_ERROR_MEMACCESS 11 /* Invalid memory access */
1.57 -#define SP_ERROR_STACKMIN 12 /* Stack went beyond its minimum value */
1.58 -#define SP_ERROR_HEAPMIN 13 /* Heap went beyond its minimum value */
1.59 -#define SP_ERROR_DIVIDE_BY_ZERO 14 /* Division by zero */
1.60 -#define SP_ERROR_ARRAY_BOUNDS 15 /* Array index is out of bounds */
1.61 -#define SP_ERROR_INSTRUCTION_PARAM 16 /* Instruction had an invalid parameter */
1.62 -#define SP_ERROR_STACKLEAK 17 /* A native leaked an item on the stack */
1.63 -#define SP_ERROR_HEAPLEAK 18 /* A native leaked an item on the heap */
1.64 -#define SP_ERROR_ARRAY_TOO_BIG 19 /* A dynamic array is too big */
1.65 -#define SP_ERROR_TRACKER_BOUNDS 20 /* Tracker stack is out of bounds */
1.66 -#define SP_ERROR_INVALID_NATIVE 21 /* Native was pending or invalid */
1.67 -#define SP_ERROR_PARAMS_MAX 22 /* Maximum number of parameters reached */
1.68 -#define SP_ERROR_NATIVE 23 /* Error originates from a native */
1.69 -#define SP_ERROR_NOT_RUNNABLE 24 /* Function or plugin is not runnable */
1.70 +#define SP_ERROR_NONE 0 /**< No error occurred */
1.71 +#define SP_ERROR_FILE_FORMAT 1 /**< File format unrecognized */
1.72 +#define SP_ERROR_DECOMPRESSOR 2 /**< A decompressor was not found */
1.73 +#define SP_ERROR_HEAPLOW 3 /**< Not enough space left on the heap */
1.74 +#define SP_ERROR_PARAM 4 /**< Invalid parameter or parameter type */
1.75 +#define SP_ERROR_INVALID_ADDRESS 5 /**< A memory address was not valid */
1.76 +#define SP_ERROR_NOT_FOUND 6 /**< The object in question was not found */
1.77 +#define SP_ERROR_INDEX 7 /**< Invalid index parameter */
1.78 +#define SP_ERROR_STACKLOW 8 /**< Nnot enough space left on the stack */
1.79 +#define SP_ERROR_NOTDEBUGGING 9 /**< Debug mode was not on or debug section not found */
1.80 +#define SP_ERROR_INVALID_INSTRUCTION 10 /**< Invalid instruction was encountered */
1.81 +#define SP_ERROR_MEMACCESS 11 /**< Invalid memory access */
1.82 +#define SP_ERROR_STACKMIN 12 /**< Stack went beyond its minimum value */
1.83 +#define SP_ERROR_HEAPMIN 13 /**< Heap went beyond its minimum value */
1.84 +#define SP_ERROR_DIVIDE_BY_ZERO 14 /**< Division by zero */
1.85 +#define SP_ERROR_ARRAY_BOUNDS 15 /**< Array index is out of bounds */
1.86 +#define SP_ERROR_INSTRUCTION_PARAM 16 /**< Instruction had an invalid parameter */
1.87 +#define SP_ERROR_STACKLEAK 17 /**< A native leaked an item on the stack */
1.88 +#define SP_ERROR_HEAPLEAK 18 /**< A native leaked an item on the heap */
1.89 +#define SP_ERROR_ARRAY_TOO_BIG 19 /**< A dynamic array is too big */
1.90 +#define SP_ERROR_TRACKER_BOUNDS 20 /**< Tracker stack is out of bounds */
1.91 +#define SP_ERROR_INVALID_NATIVE 21 /**< Native was pending or invalid */
1.92 +#define SP_ERROR_PARAMS_MAX 22 /**< Maximum number of parameters reached */
1.93 +#define SP_ERROR_NATIVE 23 /**< Error originates from a native */
1.94 +#define SP_ERROR_NOT_RUNNABLE 24 /**< Function or plugin is not runnable */
1.95 +//Hey you! Update the string table if you add to the end of me! */
1.96
1.97 /**********************************************
1.98 *** The following structures are reference structures.
1.99 @@ -49,60 +68,56 @@
1.100 **********************************************/
1.101
1.102 /**
1.103 - * Information about the core plugin tables.
1.104 - * These may or may not be present!
1.105 + * @brief Information about the core plugin tables. These may or may not be present!
1.106 */
1.107 typedef struct sp_plugin_infotab_s
1.108 {
1.109 - const char *stringbase; /* base of string table */
1.110 - uint32_t publics_num; /* number of publics */
1.111 - sp_file_publics_t *publics; /* public table */
1.112 - uint32_t natives_num; /* number of natives */
1.113 - sp_file_natives_t *natives; /* native table */
1.114 - uint32_t pubvars_num; /* number of pubvars */
1.115 - sp_file_pubvars_t *pubvars; /* pubvars table */
1.116 - uint32_t libraries_num; /* number of libraries */
1.117 - sp_file_libraries_t *lib; /* library table */
1.118 + const char *stringbase; /**< base of string table */
1.119 + uint32_t publics_num; /**< number of publics */
1.120 + sp_file_publics_t *publics; /**< public table */
1.121 + uint32_t natives_num; /**< number of natives */
1.122 + sp_file_natives_t *natives; /**< native table */
1.123 + uint32_t pubvars_num; /**< number of pubvars */
1.124 + sp_file_pubvars_t *pubvars; /**< pubvars table */
1.125 + uint32_t libraries_num; /**< number of libraries */
1.126 + sp_file_libraries_t *lib; /**< library table */
1.127 } sp_plugin_infotab_t;
1.128
1.129 /**
1.130 - * Information about the plugin's debug tables.
1.131 - * These are all present if one is present.
1.132 + * @brief Information about the plugin's debug tables. These are all present if one is present.
1.133 */
1.134 typedef struct sp_plugin_debug_s
1.135 {
1.136 - const char *stringbase; /* base of string table */
1.137 - uint32_t files_num; /* number of files */
1.138 - sp_fdbg_file_t *files; /* files table */
1.139 - uint32_t lines_num; /* number of lines */
1.140 - sp_fdbg_line_t *lines; /* lines table */
1.141 - uint32_t syms_num; /* number of symbols */
1.142 - sp_fdbg_symbol_t *symbols; /* symbol table */
1.143 + const char *stringbase; /**< base of string table */
1.144 + uint32_t files_num; /**< number of files */
1.145 + sp_fdbg_file_t *files; /**< files table */
1.146 + uint32_t lines_num; /**< number of lines */
1.147 + sp_fdbg_line_t *lines; /**< lines table */
1.148 + uint32_t syms_num; /**< number of symbols */
1.149 + sp_fdbg_symbol_t *symbols; /**< symbol table */
1.150 } sp_plugin_debug_t;
1.151
1.152 -#define SP_FA_SELF_EXTERNAL (1<<0)
1.153 -#define SP_FA_BASE_EXTERNAL (1<<1)
1.154 +#define SP_FA_SELF_EXTERNAL (1<<0) /**< Allocation of structure is external */
1.155 +#define SP_FA_BASE_EXTERNAL (1<<1) /**< Allocation of base is external */
1.156
1.157 /**
1.158 - * The rebased, in-memory format of a plugin.
1.159 - * This differs from the on-disk structure to ensure
1.160 - * that the format is properly read.
1.161 + * @brief The rebased memory format of a plugin. This differs from the on-disk structure
1.162 + * to ensure that the format is properly read.
1.163 */
1.164 typedef struct sp_plugin_s
1.165 {
1.166 - uint8_t *base; /* base of memory */
1.167 - uint8_t *pcode; /* p-code */
1.168 - uint32_t pcode_size; /* size of p-code */
1.169 - uint8_t *data; /* data size */
1.170 - uint32_t data_size; /* size of data */
1.171 - uint32_t memory; /* required memory */
1.172 - uint16_t flags; /* code flags */
1.173 - uint32_t allocflags; /* allocation flags */
1.174 - sp_plugin_infotab_t info; /* base info table */
1.175 - sp_plugin_debug_t debug; /* debug info table */
1.176 + uint8_t *base; /**< Base of memory for this plugin. */
1.177 + uint8_t *pcode; /**< P-Code of plugin */
1.178 + uint32_t pcode_size; /**< Size of p-code */
1.179 + uint8_t *data; /**< Data/memory layout */
1.180 + uint32_t data_size; /**< Size of data */
1.181 + uint32_t memory; /**< Required memory space */
1.182 + uint16_t flags; /**< Code flags */
1.183 + uint32_t allocflags; /**< Allocation flags */
1.184 + sp_plugin_infotab_t info; /**< Base info table */
1.185 + sp_plugin_debug_t debug; /**< Debug info table */
1.186 } sp_plugin_t;
1.187
1.188 -/** Forward declarations */
1.189
1.190 namespace SourcePawn
1.191 {
1.192 @@ -112,6 +127,10 @@
1.193
1.194 struct sp_context_s;
1.195
1.196 +/**
1.197 + * @brief Native callback prototype, passed a context and a parameter stack (0=count, 1+=args).
1.198 + * A cell must be returned.
1.199 + */
1.200 typedef cell_t (*SPVM_NATIVE_FUNC)(SourcePawn::IPluginContext *, const cell_t *);
1.201
1.202 /**********************************************
1.203 @@ -120,84 +139,82 @@
1.204 **********************************************/
1.205
1.206 /**
1.207 - * Offsets and names to a public function.
1.208 - * By default, these point back to the string table
1.209 - * in the sp_plugin_infotab_t structure.
1.210 + * @brief Offsets and names to a public function.
1.211 */
1.212 typedef struct sp_public_s
1.213 {
1.214 - funcid_t funcid; /* encoded function id */
1.215 - uint32_t code_offs; /* code offset */
1.216 - const char *name; /* name */
1.217 + funcid_t funcid; /**< Encoded function id */
1.218 + uint32_t code_offs; /**< Relocated code offset */
1.219 + const char *name; /**< Name of function */
1.220 } sp_public_t;
1.221
1.222 /**
1.223 - * Offsets and names to public variables.
1.224 - * The offset is relocated and the name by default
1.225 - * points back to the sp_plugin_infotab_t structure.
1.226 + * @brief Offsets and names to public variables.
1.227 + *
1.228 + * The offset is relocated and the name by default points back to the sp_plugin_infotab_t structure.
1.229 */
1.230 typedef struct sp_pubvar_s
1.231 {
1.232 - cell_t *offs; /* pointer to data */
1.233 - const char *name; /* name */
1.234 + cell_t *offs; /**< Pointer to data */
1.235 + const char *name; /**< Name */
1.236 } sp_pubvar_t;
1.237
1.238 -#define SP_NATIVE_UNBOUND (0) /* Native is undefined */
1.239 -#define SP_NATIVE_BOUND (1) /* Native is bound */
1.240 +#define SP_NATIVE_UNBOUND (0) /**< Native is undefined */
1.241 +#define SP_NATIVE_BOUND (1) /**< Native is bound */
1.242
1.243 /**
1.244 - * Native lookup table, by default names
1.245 - * point back to the sp_plugin_infotab_t structure.
1.246 - * A native is NULL if unit
1.247 + * @brief Native lookup table, by default names point back to the sp_plugin_infotab_t structure.
1.248 */
1.249 typedef struct sp_native_s
1.250 {
1.251 - SPVM_NATIVE_FUNC pfn; /* function pointer */
1.252 - const char * name; /* name of function */
1.253 - uint32_t status; /* status flags */
1.254 + SPVM_NATIVE_FUNC pfn; /**< Function pointer */
1.255 + const char * name; /**< Name of function */
1.256 + uint32_t status; /**< Status flags */
1.257 } sp_native_t;
1.258
1.259 /**
1.260 - * Used for setting natives from modules/host apps.
1.261 + * @brief Used for setting natives from modules/host apps.
1.262 */
1.263 typedef struct sp_nativeinfo_s
1.264 {
1.265 - const char *name;
1.266 - SPVM_NATIVE_FUNC func;
1.267 + const char *name; /**< Name of the native */
1.268 + SPVM_NATIVE_FUNC func; /**< Address of native implementation */
1.269 } sp_nativeinfo_t;
1.270
1.271 /**
1.272 - * Debug file table
1.273 + * @brief Run-time debug file table
1.274 */
1.275 typedef struct sp_debug_file_s
1.276 {
1.277 - uint32_t addr; /* address into code */
1.278 - const char * name; /* name of file */
1.279 + uint32_t addr; /**< Address into code */
1.280 + const char * name; /**< Name of file */
1.281 } sp_debug_file_t;
1.282
1.283 /**
1.284 - * Note that line is missing. It is not necessary since
1.285 - * this can be retrieved from the base plugin info.
1.286 + * @brief Contains run-time debug line table.
1.287 */
1.288 typedef struct sp_debug_line_s
1.289 {
1.290 - uint32_t addr; /* address into code */
1.291 - uint32_t line; /* line no. */
1.292 + uint32_t addr; /**< Address into code */
1.293 + uint32_t line; /**< Line number */
1.294 } sp_debug_line_t;
1.295
1.296 +/**
1.297 + * @brief These structures are equivalent.
1.298 + */
1.299 typedef sp_fdbg_arraydim_t sp_debug_arraydim_t;
1.300
1.301 /**
1.302 - * The majority of this struct is already located in the parent
1.303 - * block. Thus, only the relocated portions are required.
1.304 + * @brief The majority of this struct is already located in the parent
1.305 + * block. Thus, only the relocated portions are required.
1.306 */
1.307 typedef struct sp_debug_symbol_s
1.308 {
1.309 - uint32_t codestart; /* relocated code address */
1.310 - uint32_t codeend; /* relocated code end address */
1.311 - const char * name; /* relocated name */
1.312 - sp_debug_arraydim_t *dims; /* relocated dimension struct, if any */
1.313 - sp_fdbg_symbol_t *sym; /* pointer to original symbol */
1.314 + uint32_t codestart; /**< Relocated code address */
1.315 + uint32_t codeend; /**< relocated code end address */
1.316 + const char * name; /**< Relocated name */
1.317 + sp_debug_arraydim_t *dims; /**< Relocated dimension struct, if any */
1.318 + sp_fdbg_symbol_t *sym; /**< Pointer to original symbol */
1.319 } sp_debug_symbol_t;
1.320
1.321 /**
1.322 @@ -209,44 +226,39 @@
1.323 */
1.324 typedef int (*SPVM_DEBUGBREAK)(struct sp_context_s *, uint32_t, uint32_t);
1.325
1.326 -#define SPFLAG_PLUGIN_DEBUG (1<<0) /* plugin is in debug mode */
1.327 +#define SPFLAG_PLUGIN_DEBUG (1<<0) /**< plugin is in debug mode */
1.328
1.329 /**
1.330 - * This is the heart of the VM. It contains all of the runtime
1.331 - * information about a plugin context.
1.332 - * Note that user[0..3] can be used for any user based pointers.
1.333 - * vm[0..3] should not be touched, as it is reserved for the VM.
1.334 + * @brief This is the heart of the VM. It contains all of the runtime
1.335 + * information about a plugin context. Note that user[0..3] can be used for any user based pointers.
1.336 + * However, vm[0..3] should not be touched, as it is reserved for the VM.
1.337 */
1.338 typedef struct sp_context_s
1.339 {
1.340 - /* general/parent information */
1.341 - void *codebase; /* base of generated code and memory */
1.342 - sp_plugin_t *plugin; /* pointer back to parent information */
1.343 - SourcePawn::IPluginContext *context; /* pointer to IPluginContext */
1.344 - SourcePawn::IVirtualMachine *vmbase; /* pointer to IVirtualMachine */
1.345 - void *user[4]; /* user specific pointers */
1.346 - void *vm[4]; /* VM specific pointers */
1.347 - uint32_t flags; /* compilation flags */
1.348 - SPVM_DEBUGBREAK dbreak; /* debug break function */
1.349 - /* context runtime information */
1.350 - uint8_t *memory; /* data chunk */
1.351 - ucell_t mem_size; /* total memory size; */
1.352 - cell_t data_size; /* data chunk size, always starts at 0 */
1.353 - cell_t heap_base; /* where the heap starts */
1.354 - /* execution specific data */
1.355 - cell_t hp; /* heap pointer */
1.356 - cell_t sp; /* stack pointer */
1.357 - cell_t frm; /* frame pointer */
1.358 - uint32_t pushcount; /* push count */
1.359 - int32_t n_err; /* error code set by a native */
1.360 - uint32_t n_idx; /* current native index being executed */
1.361 - /* context rebased database */
1.362 - sp_public_t *publics; /* public functions table */
1.363 - sp_pubvar_t *pubvars; /* public variables table */
1.364 - sp_native_t *natives; /* natives table */
1.365 - sp_debug_file_t *files; /* files */
1.366 - sp_debug_line_t *lines; /* lines */
1.367 - sp_debug_symbol_t *symbols; /* symbols */
1.368 + void *codebase; /**< Base of generated code and memory */
1.369 + sp_plugin_t *plugin; /**< Pointer back to parent information */
1.370 + SourcePawn::IPluginContext *context; /**< Pointer to IPluginContext */
1.371 + SourcePawn::IVirtualMachine *vmbase; /**< Pointer to IVirtualMachine */
1.372 + void *user[4]; /**< User specific pointers */
1.373 + void *vm[4]; /**< VM specific pointers */
1.374 + uint32_t flags; /**< Compilation flags */
1.375 + SPVM_DEBUGBREAK dbreak; /**< Debug break function */
1.376 + uint8_t *memory; /**< Data chunk */
1.377 + ucell_t mem_size; /**< Total memory size; */
1.378 + cell_t data_size; /**< Data chunk size, always starts at 0 */
1.379 + cell_t heap_base; /**< Where the heap starts */
1.380 + cell_t hp; /**< Heap pointer */
1.381 + cell_t sp; /**< Stack pointer */
1.382 + cell_t frm; /**< Frame pointer */
1.383 + uint32_t pushcount; /**< Push count */
1.384 + int32_t n_err; /**< Error code set by a native */
1.385 + uint32_t n_idx; /**< Current native index being executed */
1.386 + sp_public_t *publics; /**< Public functions table */
1.387 + sp_pubvar_t *pubvars; /**< Public variables table */
1.388 + sp_native_t *natives; /**< Natives table */
1.389 + sp_debug_file_t *files; /**< Files */
1.390 + sp_debug_line_t *lines; /**< Lines */
1.391 + sp_debug_symbol_t *symbols; /**< Symbols */
1.392 } sp_context_t;
1.393
1.394 #endif //_INCLUDE_SOURCEPAWN_VM_TYPES_H
