flight/libraries/PyMite/vm/pm.h

   1 /*
   2 # This file is Copyright 2006, 2007, 2009, 2010 Dean Hall.
   3 #
   4 # This file is part of the PyMite VM.
   5 # The PyMite VM is free software: you can redistribute it and/or modify
   6 # it under the terms of the GNU GENERAL PUBLIC LICENSE Version 2.
   7 #
   8 # The PyMite VM is distributed in the hope that it will be useful,
   9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  11 # A copy of the GNU GENERAL PUBLIC LICENSE Version 2
  12 # is seen in the file COPYING in this directory.
  13 */
  14
  15
  16 #ifndef __PM_H__
  17 #define __PM_H__
  18
  19
  20 /**
  21  * \file
  22  * \brief PyMite Header
  23  *
  24  * Include things that are needed by nearly everything.
  25  */
  26
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 #include <stdint.h>
  33 #include <stdio.h>
  34
  35
  36 /**
  37  * Value indicating the release of PyMite
  38  *
  39  * This value should be incremented for every public release.
  40  * It helps locate a defect when used in conjunction with a fileID
  41  * and line number.
  42  */
  43 #define PM_RELEASE 8
  44
  45
  46 /** null for C code */
  47 #define C_NULL 0
  48
  49 /** false for C code */
  50 #define C_FALSE 0
  51
  52 /** true for C code */
  53 #define C_TRUE 1
  54
  55 /** Comparison result is that items are the same */
  56 #define C_SAME (int8_t)0
  57
  58 /** Comparison result is that items differ */
  59 #define C_DIFFER (int8_t)-1
  60
  61 /** PORT inline for C code */
  62 #define INLINE __inline__
  63
  64
  65 /**
  66  * Returns an exception error code and stores debug data
  67  *
  68  * This macro must be used as an rval statement.  That is, it must
  69  * be used after an assignment such as "retval = " or a return statement
  70  */
  71 #if __DEBUG__
  72 #define PM_RAISE(retexn, exn) \
  73         do \
  74         { \
  75             retexn = (exn); \
  76             gVmGlobal.errFileId = __FILE_ID__; \
  77             gVmGlobal.errLineNum = (uint16_t)__LINE__; \
  78         } while (0)
  79 #else
  80 #define PM_RAISE(retexn, exn) \
  81         retexn = (exn)
  82 #endif
  83
  84 /** if retval is not OK, break from the block */
  85 #define PM_BREAK_IF_ERROR(retval) if ((retval) != PM_RET_OK) break
  86
  87 /** return an error code if it is not PM_RET_OK */
  88 #define PM_RETURN_IF_ERROR(retval)  if ((retval) != PM_RET_OK) return (retval)
  89
  90 /** print an error message if argument is not PM_RET_OK */
  91 #define PM_REPORT_IF_ERROR(retval)   if ((retval) != PM_RET_OK) \
  92                                         plat_reportError(retval)
  93
  94 /** Jumps to a label if argument is not PM_RET_OK */
  95 #define PM_GOTO_IF_ERROR(retval, target) if ((retval) != PM_RET_OK) \
  96                                             goto target
  97
  98 //Dirty hack to resolve conflicts with winnt.h on Windows
  99 #if defined(C_ASSERT)
 100 #undef C_ASSERT
 101 #endif
 102
 103 #if __DEBUG__
 104 /** If the boolean expression fails, return the ASSERT error code */
 105 #define C_ASSERT(boolexpr) \
 106     do \
 107     { \
 108         if (!((boolexpr))) \
 109         { \
 110             gVmGlobal.errFileId = __FILE_ID__; \
 111             gVmGlobal.errLineNum = (uint16_t)__LINE__; \
 112             return PM_RET_ASSERT_FAIL; \
 113         } \
 114     } \
 115     while (0)
 116
 117 #else
 118 /** Assert statements are removed from production code */
 119 #define C_ASSERT(boolexpr)
 120 #endif
 121
 122 /** Use as the first argument to C_DEBUG_PRINT for low volume messages */
 123 #define VERBOSITY_LOW 1
 124
 125 /** Use as the first argument to C_DEBUG_PRINT for medium volume messages */
 126 #define VERBOSITY_MEDIUM 2
 127
 128 /** Use as the first argument to C_DEBUG_PRINT for high volume messages */
 129 #define VERBOSITY_HIGH 3
 130
 131 #if __DEBUG__
 132
 133 /** To be used to set DEBUG_PRINT_VERBOSITY to a value so no prints occur */
 134 #define VERBOSITY_OFF 0
 135
 136 /** Sets the level of verbosity to allow in debug prints */
 137 #define DEBUG_PRINT_VERBOSITY VERBOSITY_OFF
 138
 139 /** Prints a debug message when the verbosity is within the set value */
 140 #define C_DEBUG_PRINT(v, f, ...) \
 141     do \
 142     { \
 143         if (DEBUG_PRINT_VERBOSITY >= (v)) \
 144         { \
 145             printf("PM_DEBUG: " f, ## __VA_ARGS__); \
 146         } \
 147     } \
 148     while (0)
 149
 150 #else
 151 #define C_DEBUG_PRINT(...)
 152 #endif
 153
 154
 155 /**
 156  * Return values for system functions
 157  * to report status, errors, exceptions, etc.
 158  * Normally, functions which use these values
 159  * should propagate the same return value
 160  * up the call tree to the interpreter.
 161  */
 162 typedef enum PmReturn_e
 163 {
 164     /* general status return values */
 165     PM_RET_OK = 0,              /**< Everything is ok */
 166     PM_RET_NO = 0xFF,           /**< General "no result" */
 167     PM_RET_ERR = 0xFE,          /**< General failure */
 168     PM_RET_STUB = 0xFD,         /**< Return val for stub fxn */
 169     PM_RET_ASSERT_FAIL = 0xFC,  /**< Assertion failure */
 170     PM_RET_FRAME_SWITCH = 0xFB, /**< Frame pointer was modified */
 171
 172     /* return vals that indicate an exception occured */
 173     PM_RET_EX = 0xE0,           /**< General exception */
 174     PM_RET_EX_EXIT = 0xE1,      /**< System exit */
 175     PM_RET_EX_IO = 0xE2,        /**< Input/output error */
 176     PM_RET_EX_ZDIV = 0xE3,      /**< Zero division error */
 177     PM_RET_EX_ASSRT = 0xE4,     /**< Assertion error */
 178     PM_RET_EX_ATTR = 0xE5,      /**< Attribute error */
 179     PM_RET_EX_IMPRT = 0xE6,     /**< Import error */
 180     PM_RET_EX_INDX = 0xE7,      /**< Index error */
 181     PM_RET_EX_KEY = 0xE8,       /**< Key error */
 182     PM_RET_EX_MEM = 0xE9,       /**< Memory error */
 183     PM_RET_EX_NAME = 0xEA,      /**< Name error */
 184     PM_RET_EX_SYNTAX = 0xEB,    /**< Syntax error */
 185     PM_RET_EX_SYS = 0xEC,       /**< System error */
 186     PM_RET_EX_TYPE = 0xED,      /**< Type error */
 187     PM_RET_EX_VAL = 0xEE,       /**< Value error */
 188     PM_RET_EX_STOP = 0xEF,      /**< Stop iteration */
 189     PM_RET_EX_WARN = 0xF0,      /**< Warning */
 190 } PmReturn_t;
 191
 192
 193 extern volatile uint32_t pm_timerMsTicks;
 194
 195
 196 /* WARNING: The order of the following includes is critical */
 197 #include "plat.h"
 198 #include "pmfeatures.h"
 199 #include "pmEmptyPlatformDefs.h"
 200 #include "sli.h"
 201 #include "mem.h"
 202 #include "obj.h"
 203 #include "seq.h"
 204 #include "tuple.h"
 205 #include "strobj.h"
 206 #include "heap.h"
 207 #include "int.h"
 208 #include "seglist.h"
 209 #include "lst.h"
 210 #include "dict.h"
 211 #include "codeobj.h"
 212 #include "func.h"
 213 #include "module.h"
 214 #include "frame.h"
 215 #include "interp.h"
 216 #include "img.h"
 217 #include "global.h"
 218 #include "class.h"
 219 #include "thread.h"
 220 #include "float.h"
 221 #include "plat_interface.h"
 222 #include "bytearray.h"
 223
 224
 225 /** Pointer to a native function used for lookup tables in interp.c */
 226 typedef PmReturn_t (* pPmNativeFxn_t)(pPmFrame_t *);
 227 extern pPmNativeFxn_t const std_nat_fxn_table[];
 228 extern pPmNativeFxn_t const usr_nat_fxn_table[];
 229
 230
 231 /**
 232  * Initializes the PyMite virtual machine and indexes the user's application
 233  * image.  The VM heap and globals are reset.  The argument, pusrimg, may be
 234  * null for interactive sessions.
 235  *
 236  * @param memspace      Memory space in which the user image is located
 237  * @param pusrimg       Address of the user image in the memory space
 238  * @return Return status
 239  */
 240 PmReturn_t pm_init(PmMemSpace_t memspace, uint8_t const * const pusrimg);
 241
 242 /**
 243  * Executes the named module
 244  *
 245  * @param modstr        Name of module to run
 246  * @return Return status
 247  */
 248 PmReturn_t pm_run(uint8_t const *modstr);
 249
 250 /**
 251  * Needs to be called periodically by the host program.
 252  * For the desktop target, it is periodically called using a signal.
 253  * For embedded targets, it needs to be called periodically. It should
 254  * be called from a timer interrupt.
 255  *
 256  * @param usecsSinceLastCall Microseconds (not less than those) that passed
 257  *                           since last call. This must be <64535.
 258  * @return Return status
 259  */
 260 PmReturn_t pm_vmPeriodic(uint16_t usecsSinceLastCall);
 261
 262 #ifdef __cplusplus
 263 }
 264 #endif
 265
 266 #endif /* __PM_H__ */