flight/libraries/PyMite/vm/codeobj.h

   1 /*
   2 # This file is Copyright 2003, 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 __CODEOBJ_H__
  17 #define __CODEOBJ_H__
  18
  19
  20 /**
  21  * \file
  22  * \brief CodeObj Type
  23  *
  24  * CodeObj type header.
  25  */
  26
  27
  28 /** Code image field offset consts */
  29 #define CI_TYPE_FIELD       0
  30 #define CI_SIZE_FIELD       1
  31 #define CI_ARGCOUNT_FIELD   3
  32 #define CI_FLAGS_FIELD      4
  33 #define CI_STACKSIZE_FIELD  5
  34 #define CI_NLOCALS_FIELD    6
  35
  36 #ifdef HAVE_CLOSURES
  37 # define CI_FREEVARS_FIELD  7
  38 # ifdef HAVE_DEBUG_INFO
  39 #  define CI_FIRST_LINE_NO  8
  40 #  define CI_NAMES_FIELD    10
  41 # else
  42 #  define CI_NAMES_FIELD    8
  43 # endif /* HAVE_DEBUG_INFO */
  44 #else
  45 # ifdef HAVE_DEBUG_INFO
  46 #  define CI_FIRST_LINE_NO  7
  47 #  define CI_NAMES_FIELD    9
  48 # else
  49 #  define CI_NAMES_FIELD    7
  50 # endif /* HAVE_DEBUG_INFO */
  51 #endif /* HAVE_CLOSURES */
  52
  53
  54 /** Native code image size */
  55 #define NATIVE_IMAGE_SIZE   4
  56
  57 /* Masks for co_flags (from Python's code.h) */
  58 #define CO_OPTIMIZED 0x01
  59 #define CO_NEWLOCALS 0x02
  60 #define CO_VARARGS 0x04
  61 #define CO_VARKEYWORDS 0x08
  62 #define CO_NESTED 0x10
  63 #define CO_GENERATOR 0x20
  64 #define CO_NOFREE 0x40
  65
  66 /**
  67  * Code Object
  68  *
  69  * An extended object that holds only the most frequently used parts
  70  * of the static code image.  Other parts can be obtained by
  71  * inspecting the code image itself.
  72  */
  73 typedef struct PmCo_s
  74 {
  75     /** Object descriptor */
  76     PmObjDesc_t od;
  77     /** Address in progmem of the code image, or of code img obj in heap */
  78     uint8_t const *co_codeimgaddr;
  79     /** Address in RAM of names tuple */
  80     pPmTuple_t co_names;
  81     /** Address in RAM of constants tuple */
  82     pPmTuple_t co_consts;
  83     /** Address in memspace of bytecode (or native function) */
  84     uint8_t const *co_codeaddr;
  85
  86 #ifdef HAVE_DEBUG_INFO
  87     /** Address in memspace of the line number table */
  88     uint8_t const *co_lnotab;
  89     /** Address in memspace of the filename */
  90     uint8_t const *co_filename;
  91     /** Line number of first source line of lnotab */
  92     uint16_t co_firstlineno;
  93 #endif /* HAVE_DEBUG_INFO */
  94
  95 #ifdef HAVE_CLOSURES
  96     /** Address in RAM of cellvars tuple */
  97     pPmTuple_t co_cellvars;
  98     /** Number of freevars */
  99     uint8_t co_nfreevars;
 100 #endif /* HAVE_CLOSURES */
 101
 102     /** Memory space selector */
 103     PmMemSpace_t co_memspace:8;
 104     /** Number of positional arguments the function expects */
 105     uint8_t co_argcount;
 106     /** Compiler flags */
 107     uint8_t co_flags;
 108     /** Stack size */
 109     uint8_t co_stacksize;
 110     /** Number of local variables */
 111     uint8_t co_nlocals;
 112 } PmCo_t,
 113  *pPmCo_t;
 114
 115 /**
 116  * Native Code Object
 117  *
 118  * An extended object that holds only the most frequently used parts
 119  * of the static native image.  Other parts can be obtained by
 120  * inspecting the native image itself.
 121  */
 122 typedef struct PmNo_s
 123 {
 124     /** object descriptor */
 125     PmObjDesc_t od;
 126     /** expected num args to the func */
 127     int8_t no_argcount;
 128     /** index into native function table */
 129     int16_t no_funcindx;
 130 } PmNo_t,
 131  *pPmNo_t;
 132
 133
 134 /**
 135  * Creates a CodeObj by loading info from a code image in memory.
 136  *
 137  * An image is a static representation of a Python object.
 138  * The process of converting an object to and from an image
 139  * is also called marshalling.
 140  * In PyMite, code images are the equivalent of .pyc files.
 141  * Code images can only contain a select subset of object types
 142  * (None, Int, Float, String, Slice?, Tuple, and CodeImg).
 143  * All other types (Lists, Dicts, CodeObjs, Modules, Classes,
 144  * Functions, ClassInstances) are built at runtime.
 145  *
 146  * All multibyte values are in Little Endian order
 147  * (least significant byte comes first in the byte stream).
 148  *
 149  * memspace and *paddr determine the start of the code image.
 150  * Load the code object with values from the code image,
 151  * including the names and consts tuples.
 152  * Leave contents of paddr pointing one byte past end of
 153  * code img.
 154  *
 155  * The code image has the following structure:
 156  *      -type:      8b - OBJ_TYPE_CIM
 157  *      -size:      16b - number of bytes
 158  *                  the code image occupies.
 159  *      -argcount:  8b - number of arguments to this code obj.
 160  *      -stacksz:   8b - the maximum arg-stack size needed.
 161  *      -nlocals:   8b - number of local vars in the code obj.
 162  *      -names:     Tuple - tuple of string objs.
 163  *      -consts:    Tuple - tuple of objs.
 164  *      -code:      8b[] - bytecode array.
 165  *
 166  * @param   memspace memory space containing image
 167  * @param   paddr ptr to ptr to code img in memspace
 168  *          return by reference: paddr points one byte
 169  *          past end of code img
 170  * @param   r_pco Return arg.  New code object with fields
 171  *          filled in.
 172  * @return  Return status
 173  */
 174 PmReturn_t
 175 co_loadFromImg(PmMemSpace_t memspace, uint8_t const **paddr, pPmObj_t *r_pco);
 176
 177 /**
 178  * Recursively sets image address of the CO and all its nested COs
 179  * in its constant pool.  This is done so that an image that was
 180  * received during an interactive session will persist as long as any
 181  * of its COs/funcs/objects is still alive.
 182  *
 183  * @param   pco Pointer to root code object whose images are set
 184  * @param   pimg Pointer to very top of code image (PmodeImgObj)
 185  */
 186 void co_rSetCodeImgAddr(pPmCo_t pco, uint8_t const *pimg);
 187
 188 /**
 189  * Creates a Native code object by loading a native image.
 190  *
 191  * An image is a static representation of a Python object.
 192  * A native image is much smaller than a regular image
 193  * because only two items of data are needed after the type:
 194  * the number of args the func expects and the index into
 195  * the native function table.
 196  * A reference to the image is not needed since it is
 197  * just as efficient to store the info in RAM as it is to
 198  * store a pointer and memspace value.
 199  *
 200  * memspace and *paddr determine the start of the native image.
 201  * Loads the argcount and the func index from the native object.
 202  * Leaves contents of paddr pointing one byte past end of
 203  * code img.
 204  *
 205  * The native image has the following structure:
 206  *      -type:      8b - OBJ_TYPE_CIM
 207  *      -argcount:  8b - number of arguments to this code obj.
 208  *      -code:      16b - index into native function table.
 209  *
 210  * @param   memspace memory space containing image
 211  * @param   paddr ptr to ptr to code img in memspace (return)
 212  * @param   r_pno Return by reference, new code object
 213  * @return  Return status
 214  */
 215 PmReturn_t no_loadFromImg(PmMemSpace_t memspace,
 216                           uint8_t const **paddr, pPmObj_t *r_pno);
 217
 218 #endif /* __CODEOBJ_H__ */