codeobj.h

00001 /*
00002 # This file is Copyright 2003, 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 __CODEOBJ_H__
00017 #define __CODEOBJ_H__
00018 
00019 
00020 /**
00021  * \file
00022  * \brief CodeObj Type
00023  *
00024  * CodeObj type header.
00025  */
00026 
00027 
00028 /** Code image field offset consts */
00029 #define CI_TYPE_FIELD       0
00030 #define CI_SIZE_FIELD       1
00031 #define CI_ARGCOUNT_FIELD   3
00032 #define CI_FLAGS_FIELD      4
00033 #define CI_STACKSIZE_FIELD  5
00034 #define CI_NLOCALS_FIELD    6
00035 #ifdef HAVE_CLOSURES
00036 #define CI_FREEVARS_FIELD   7
00037 #define CI_NAMES_FIELD      8
00038 #else
00039 #define CI_NAMES_FIELD      7
00040 #endif /* HAVE_CLOSURES */
00041 
00042 /** Native code image size */
00043 #define NATIVE_IMAGE_SIZE   4
00044 
00045 /* Masks for co_flags (from Python's code.h) */
00046 #define CO_OPTIMIZED 0x01
00047 #define CO_NEWLOCALS 0x02
00048 #define CO_VARARGS 0x04
00049 #define CO_VARKEYWORDS 0x08
00050 #define CO_NESTED 0x10
00051 #define CO_GENERATOR 0x20
00052 #define CO_NOFREE 0x40
00053 
00054 /**
00055  * Code Object
00056  *
00057  * An extended object that holds only the most frequently used parts
00058  * of the static code image.  Other parts can be obtained by
00059  * inspecting the code image itself.
00060  */
00061 typedef struct PmCo_s
00062 {
00063     /** object descriptor */
00064     PmObjDesc_t od;
00065     /** memory space selector */
00066     PmMemSpace_t co_memspace:8;
00067     /** address in progmem of the code image, or of code img obj in heap */
00068     uint8_t const *co_codeimgaddr;
00069     /** address in RAM of names tuple */
00070     pPmTuple_t co_names;
00071     /** address in RAM of constants tuple */
00072     pPmTuple_t co_consts;
00073 #ifdef HAVE_CLOSURES
00074     /** Number of freevars */
00075     uint8_t co_nfreevars;
00076     /** address in RAM of cellvars tuple */
00077     pPmTuple_t co_cellvars;
00078     /** Number of local variables */
00079     uint16_t co_nlocals;
00080 #endif /* HAVE_CLOSURES */
00081     /** address in memspace of bytecode (or native function) */
00082     uint8_t const *co_codeaddr;
00083     /** number of positional arguments the function expects */
00084     uint8_t co_argcount;
00085     /** compiler flags */
00086     uint8_t co_flags;
00087 } PmCo_t,
00088  *pPmCo_t;
00089 
00090 /**
00091  * Native Code Object
00092  *
00093  * An extended object that holds only the most frequently used parts
00094  * of the static native image.  Other parts can be obtained by
00095  * inspecting the native image itself.
00096  */
00097 typedef struct PmNo_s
00098 {
00099     /** object descriptor */
00100     PmObjDesc_t od;
00101     /** expected num args to the func */
00102     int8_t no_argcount;
00103     /** index into native function table */
00104     int16_t no_funcindx;
00105 } PmNo_t,
00106  *pPmNo_t;
00107 
00108 
00109 /**
00110  * Creates a CodeObj by loading info from a code image in memory.
00111  *
00112  * An image is a static representation of a Python object.
00113  * The process of converting an object to and from an image
00114  * is also called marshalling.
00115  * In PyMite, code images are the equivalent of .pyc files.
00116  * Code images can only contain a select subset of object types
00117  * (None, Int, Float, String, Slice?, Tuple, and CodeImg).
00118  * All other types (Lists, Dicts, CodeObjs, Modules, Classes,
00119  * Functions, ClassInstances) are built at runtime.
00120  *
00121  * All multibyte values are in Little Endian order
00122  * (least significant byte comes first in the byte stream).
00123  *
00124  * memspace and *paddr determine the start of the code image.
00125  * Load the code object with values from the code image,
00126  * including the names and consts tuples.
00127  * Leave contents of paddr pointing one byte past end of
00128  * code img.
00129  *
00130  * The code image has the following structure:
00131  *      -type:      8b - OBJ_TYPE_CIM
00132  *      -size:      16b - number of bytes
00133  *                  the code image occupies.
00134  *      -argcount:  8b - number of arguments to this code obj.
00135  *      -stacksz:   8b - the maximum arg-stack size needed.
00136  *      -nlocals:   8b - number of local vars in the code obj.
00137  *      -names:     Tuple - tuple of string objs.
00138  *      -consts:    Tuple - tuple of objs.
00139  *      -code:      8b[] - bytecode array.
00140  *
00141  * @param   memspace memory space containing image
00142  * @param   paddr ptr to ptr to code img in memspace
00143  *          return by reference: paddr points one byte
00144  *          past end of code img
00145  * @param   r_pco Return arg.  New code object with fields
00146  *          filled in.
00147  * @return  Return status
00148  */
00149 PmReturn_t
00150 co_loadFromImg(PmMemSpace_t memspace, uint8_t const **paddr, pPmObj_t *r_pco);
00151 
00152 /**
00153  * Creates a Native code object by loading a native image.
00154  *
00155  * An image is a static representation of a Python object.
00156  * A native image is much smaller than a regular image
00157  * because only two items of data are needed after the type:
00158  * the number of args the func expects and the index into
00159  * the native function table.
00160  * A reference to the image is not needed since it is
00161  * just as efficient to store the info in RAM as it is to
00162  * store a pointer and memspace value.
00163  *
00164  * memspace and *paddr determine the start of the native image.
00165  * Loads the argcount and the func index from the native object.
00166  * Leaves contents of paddr pointing one byte past end of
00167  * code img.
00168  *
00169  * The native image has the following structure:
00170  *      -type:      8b - OBJ_TYPE_CIM
00171  *      -argcount:  8b - number of arguments to this code obj.
00172  *      -code:      16b - index into native function table.
00173  *
00174  * @param   memspace memory space containing image
00175  * @param   paddr ptr to ptr to code img in memspace (return)
00176  * @param   r_pno Return by reference, new code object 
00177  * @return  Return status
00178  */
00179 PmReturn_t no_loadFromImg(PmMemSpace_t memspace,
00180                           uint8_t const **paddr, pPmObj_t *r_pno);
00181 
00182 #endif /* __CODEOBJ_H__ */