pm.h

00001 /*
00002 # This file is Copyright 2006, 2007, 2009 Dean Hall.
00003 #
00004 # This file is part of the PyMite VM.
00005 # The PyMite VM is free software: you can redistribute it and/or modify
00006 # it under the terms of the GNU GENERAL PUBLIC LICENSE Version 2.
00007 #
00008 # The PyMite VM is distributed in the hope that it will be useful,
00009 # but WITHOUT ANY WARRANTY; without even the implied warranty of
00010 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
00011 # A copy of the GNU GENERAL PUBLIC LICENSE Version 2
00012 # is seen in the file COPYING in this directory.
00013 */
00014 
00015 
00016 #ifndef __PM_H__
00017 #define __PM_H__
00018 
00019 
00020 /**
00021  * \file
00022  * \brief PyMite Header
00023  *
00024  * Include things that are needed by nearly everything.
00025  */
00026 
00027 
00028 #ifdef __cplusplus
00029 extern "C" {
00030 #endif
00031 
00032 #include <stdint.h>
00033 #include <stdio.h>
00034 
00035 
00036 /**
00037  * Value indicating the release of PyMite
00038  *
00039  * This value should be incremented for every public release.
00040  * It helps locate a defect when used in conjunction with a fileID
00041  * and line number.
00042  */
00043 #define PM_RELEASE 8
00044 
00045 
00046 /** null for C code */
00047 #define C_NULL 0
00048 
00049 /** false for C code */
00050 #define C_FALSE 0
00051 
00052 /** true for C code */
00053 #define C_TRUE 1
00054 
00055 /** Comparison result is that items are the same */
00056 #define C_SAME (int8_t)0
00057 
00058 /** Comparison result is that items differ */
00059 #define C_DIFFER (int8_t)-1
00060 
00061 /** PORT inline for C code */
00062 #define INLINE __inline__
00063 
00064 
00065 /**
00066  * Returns an exception error code and stores debug data
00067  *
00068  * This macro must be used as an rval statement.  That is, it must
00069  * be used after an assignment such as "retval = " or a return statement
00070  */
00071 #if __DEBUG__
00072 #define PM_RAISE(retexn, exn) \
00073         do \
00074         { \
00075             retexn = (exn); \
00076             gVmGlobal.errFileId = __FILE_ID__; \
00077             gVmGlobal.errLineNum = (uint16_t)__LINE__; \
00078         } while (0)
00079 #else
00080 #define PM_RAISE(retexn, exn) \
00081         retexn = (exn)
00082 #endif
00083 
00084 /** if retval is not OK, break from the block */
00085 #define PM_BREAK_IF_ERROR(retval) if ((retval) != PM_RET_OK) break
00086 
00087 /** return an error code if it is not PM_RET_OK */
00088 #define PM_RETURN_IF_ERROR(retval)  if ((retval) != PM_RET_OK) return (retval)
00089 
00090 /** print an error message if argument is not PM_RET_OK */
00091 #define PM_REPORT_IF_ERROR(retval)   if ((retval) != PM_RET_OK) \
00092                                         plat_reportError(retval)
00093 
00094 #if __DEBUG__
00095 /** If the boolean expression fails, return the ASSERT error code */
00096 #define C_ASSERT(boolexpr) \
00097     do \
00098     { \
00099         if (!((boolexpr))) \
00100         { \
00101             gVmGlobal.errFileId = __FILE_ID__; \
00102             gVmGlobal.errLineNum = (uint16_t)__LINE__; \
00103             return PM_RET_ASSERT_FAIL; \
00104         } \
00105     } \
00106     while (0)
00107 
00108 #else
00109 /** Assert statements are removed from production code */
00110 #define C_ASSERT(boolexpr)
00111 #endif
00112 
00113 /** Use as the first argument to C_DEBUG_PRINT for low volume messages */
00114 #define VERBOSITY_LOW 1
00115 
00116 /** Use as the first argument to C_DEBUG_PRINT for medium volume messages */
00117 #define VERBOSITY_MEDIUM 2
00118 
00119 /** Use as the first argument to C_DEBUG_PRINT for high volume messages */
00120 #define VERBOSITY_HIGH 3
00121 
00122 #if __DEBUG__
00123 
00124 /** To be used to set DEBUG_PRINT_VERBOSITY to a value so no prints occur */
00125 #define VERBOSITY_OFF 0
00126 
00127 /** Sets the level of verbosity to allow in debug prints */
00128 #define DEBUG_PRINT_VERBOSITY VERBOSITY_OFF
00129 
00130 /** Prints a debug message when the verbosity is within the set value */
00131 #define C_DEBUG_PRINT(v, f, ...) \
00132     do \
00133     { \
00134         if (DEBUG_PRINT_VERBOSITY >= (v)) \
00135         { \
00136             printf("PM_DEBUG: " f, ## __VA_ARGS__); \
00137         } \
00138     } \
00139     while (0)
00140 
00141 #else
00142 #define C_DEBUG_PRINT(...)
00143 #endif
00144 
00145 
00146 /**
00147  * Return values for system functions
00148  * to report status, errors, exceptions, etc.
00149  * Normally, functions which use these values
00150  * should propagate the same return value
00151  * up the call tree to the interpreter.
00152  */
00153 typedef enum PmReturn_e
00154 {
00155     /* general status return values */
00156     PM_RET_OK = 0,              /**< Everything is ok */
00157     PM_RET_NO = 0xFF,           /**< General "no result" */
00158     PM_RET_ERR = 0xFE,          /**< General failure */
00159     PM_RET_STUB = 0xFD,         /**< Return val for stub fxn */
00160     PM_RET_ASSERT_FAIL = 0xFC,  /**< Assertion failure */
00161     PM_RET_FRAME_SWITCH = 0xFB, /**< Frame pointer was modified */
00162 
00163     /* return vals that indicate an exception occured */
00164     PM_RET_EX = 0xE0,           /**< General exception */
00165     PM_RET_EX_EXIT = 0xE1,      /**< System exit */
00166     PM_RET_EX_IO = 0xE2,        /**< Input/output error */
00167     PM_RET_EX_ZDIV = 0xE3,      /**< Zero division error */
00168     PM_RET_EX_ASSRT = 0xE4,     /**< Assertion error */
00169     PM_RET_EX_ATTR = 0xE5,      /**< Attribute error */
00170     PM_RET_EX_IMPRT = 0xE6,     /**< Import error */
00171     PM_RET_EX_INDX = 0xE7,      /**< Index error */
00172     PM_RET_EX_KEY = 0xE8,       /**< Key error */
00173     PM_RET_EX_MEM = 0xE9,       /**< Memory error */
00174     PM_RET_EX_NAME = 0xEA,      /**< Name error */
00175     PM_RET_EX_SYNTAX = 0xEB,    /**< Syntax error */
00176     PM_RET_EX_SYS = 0xEC,       /**< System error */
00177     PM_RET_EX_TYPE = 0xED,      /**< Type error */
00178     PM_RET_EX_VAL = 0xEE,       /**< Value error */
00179     PM_RET_EX_STOP = 0xEF,      /**< Stop iteration */
00180     PM_RET_EX_WARN = 0xF0,      /**< Warning */
00181 } PmReturn_t;
00182 
00183 
00184 extern volatile uint32_t pm_timerMsTicks;
00185 
00186 
00187 /* WARNING: The order of the following includes is critical */
00188 #include "pmfeatures.h"
00189 #include "sli.h"
00190 #include "mem.h"
00191 #include "obj.h"
00192 #include "seq.h"
00193 #include "tuple.h"
00194 #include "strobj.h"
00195 #include "heap.h"
00196 #include "int.h"
00197 #include "seglist.h"
00198 #include "list.h"
00199 #include "dict.h"
00200 #include "codeobj.h"
00201 #include "func.h"
00202 #include "module.h"
00203 #include "frame.h"
00204 #include "interp.h"
00205 #include "img.h"
00206 #include "global.h"
00207 #include "class.h"
00208 #include "thread.h"
00209 #include "float.h"
00210 #include "plat.h"
00211 #include "bytearray.h"
00212 
00213 /**
00214  * Initializes the PyMite virtual machine and indexes the user's application
00215  * image.  The VM heap and globals are reset.  The argument, pusrimg, may be
00216  * null for interactive sessions.
00217  *
00218  * @param memspace      Memory space in which the user image is located
00219  * @param pusrimg       Address of the user image in the memory space
00220  * @return Return status
00221  */
00222 PmReturn_t pm_init(PmMemSpace_t memspace, uint8_t *pusrimg);
00223 
00224 /**
00225  * Executes the named module
00226  *
00227  * @param modstr        Name of module to run
00228  * @return Return status
00229  */
00230 PmReturn_t pm_run(uint8_t const *modstr);
00231 
00232 /**
00233  * Needs to be called periodically by the host program.
00234  * For the desktop target, it is periodically called using a signal.
00235  * For embedded targets, it needs to be called periodically. It should
00236  * be called from a timer interrupt.
00237  *
00238  * @param usecsSinceLastCall Microseconds (not less than those) that passed
00239  *                           since last call. This must be <64535.
00240  * @return Return status
00241  */
00242 PmReturn_t pm_vmPeriodic(uint16_t usecsSinceLastCall);
00243 
00244 #endif /* __PM_H__ */
00245 
00246 
00247 #ifdef __cplusplus
00248 }
00249 #endif