obj.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 __OBJ_H__
00017 #define __OBJ_H__
00018 
00019 
00020 /**
00021  * \file
00022  * \brief Object Type
00023  *
00024  * Object type header.
00025  */
00026 
00027 
00028 /** Object descriptor field constants */
00029 #define OD_MARK_SHIFT 14
00030 #define OD_FREE_SHIFT 15
00031 #define OD_MARK_BIT (uint16_t)(1 << OD_MARK_SHIFT)
00032 #define OD_FREE_BIT (uint16_t)(1 << OD_FREE_SHIFT)
00033 #define OD_SIZE_MASK (uint16_t)(0x01FF)
00034 #define OD_TYPE_MASK (uint16_t)(0x3E00)
00035 #define OD_TYPE_SHIFT 9
00036 
00037 /** Heap descriptor size mask */
00038 #define HD_SIZE_MASK (uint16_t)(0x3FFF)
00039 
00040 
00041 /**
00042  * Gets the free bit of the given object to the given value.
00043  * If the object is marked free, it is not being used by the VM.
00044  */
00045 #define OBJ_GET_FREE(pobj) \
00046     ((((pPmObj_t)pobj)->od >> OD_FREE_SHIFT) & (uint8_t)1)
00047 
00048 /**
00049  * Sets the free bit of the given object to the given value.
00050  * Setting the free bit means that the object will use the heap descriptor
00051  * structure instead of the object descriptor structure.
00052  */
00053 #define OBJ_SET_FREE(pobj, free) \
00054     do \
00055     { \
00056         ((pPmObj_t)pobj)->od = ((uint8_t)free) \
00057                                ? ((pPmObj_t)pobj)->od | OD_FREE_BIT \
00058                                : ((pPmObj_t)pobj)->od & ~OD_FREE_BIT;\
00059     } \
00060     while (0)
00061 
00062 /*
00063  * #99: od_size bits are shifted because size is a scaled value
00064  * True size is always a multiple of 4, so the lower two bits are ignored
00065  * and two more significant bits are gained.
00066  */
00067 /**
00068  * Gets the size of the chunk in bytes.
00069  * Tests whether the object is free as that determines whether the chunk is
00070  * using an object descriptor or a heap descriptor.  Heap descriptors have
00071  * a larger size field and use a different bit mask than object descriptors.
00072  */
00073 #define OBJ_GET_SIZE(pobj) \
00074     ((((pPmObj_t)pobj)->od & OD_FREE_BIT) \
00075      ? ((((pPmObj_t)pobj)->od & HD_SIZE_MASK) << 2) \
00076      : ((((pPmObj_t)pobj)->od & OD_SIZE_MASK) << 2))
00077 
00078 /**
00079  * Sets the size of the chunk in bytes.
00080  * Tests whether the object is free as that determines whether the chunk is
00081  * using an object descriptor or a heap descriptor.  Heap descriptors have
00082  * a larger size field and use a different bit mask than object descriptors.
00083  */
00084 #define OBJ_SET_SIZE(pobj, size) \
00085     do \
00086     { \
00087         if (((pPmObj_t)pobj)->od & OD_FREE_BIT) \
00088         { \
00089             ((pPmObj_t)pobj)->od &= ~HD_SIZE_MASK; \
00090             ((pPmObj_t)pobj)->od |= (((size) >> 2) & HD_SIZE_MASK); \
00091         } \
00092         else \
00093         { \
00094             ((pPmObj_t)pobj)->od &= ~OD_SIZE_MASK; \
00095             ((pPmObj_t)pobj)->od |= (((size) >> 2) & OD_SIZE_MASK); \
00096         } \
00097     } \
00098     while (0)
00099 
00100 /**
00101  * Gets the type of the object
00102  * This MUST NOT be called on objects that are free.
00103  */
00104 #define OBJ_GET_TYPE(pobj) \
00105     (((((pPmObj_t)pobj)->od) & OD_TYPE_MASK) >> OD_TYPE_SHIFT)
00106 
00107 /**
00108  * Sets the type of the object
00109  * This MUST NOT be called on objects that are free.
00110  */
00111 #define OBJ_SET_TYPE(pobj, type) \
00112     do \
00113     { \
00114         ((pPmObj_t)pobj)->od &= ~OD_TYPE_MASK; \
00115         ((pPmObj_t)pobj)->od |= (((type) << OD_TYPE_SHIFT) & OD_TYPE_MASK); \
00116     } \
00117     while (0)
00118 
00119 
00120 /**
00121  * Object type enum
00122  *
00123  * These values go in the od_type fields of the obj descriptor.
00124  * Be sure these values correspond to those in the image creator
00125  * tool.
00126  * The hashable types are grouped together for convenience.
00127  *
00128  * WARNING: od_type must be at most 5 bits! (must be < 0x20)
00129  */
00130 typedef enum PmType_e
00131 {
00132     OBJ_TYPE_HASHABLE_MIN = 0x00,
00133 
00134     /** None */
00135     OBJ_TYPE_NON = 0x00,
00136 
00137     /** Signed integer */
00138     OBJ_TYPE_INT = 0x01,
00139 
00140     /** Floating point 32b */
00141     OBJ_TYPE_FLT = 0x02,
00142 
00143     /** String */
00144     OBJ_TYPE_STR = 0x03,
00145 
00146     /** Tuple (immutable sequence) */
00147     OBJ_TYPE_TUP = 0x04,
00148 
00149     /** Code obj */
00150     OBJ_TYPE_COB = 0x05,
00151 
00152     /** Module obj */
00153     OBJ_TYPE_MOD = 0x06,
00154 
00155     /** Class obj */
00156     OBJ_TYPE_CLO = 0x07,
00157 
00158     /** Function obj (callable) */
00159     OBJ_TYPE_FXN = 0x08,
00160 
00161     /** Class instance */
00162     OBJ_TYPE_CLI = 0x09,
00163 
00164     /** Code image in static memory */
00165     OBJ_TYPE_CIM = 0x0A,
00166 
00167     /** Native function image */
00168     OBJ_TYPE_NIM = 0x0B,
00169 
00170     /** Native function object */
00171     OBJ_TYPE_NOB = 0x0C,
00172 
00173     /** Thread */
00174     OBJ_TYPE_THR = 0x0D,
00175 
00176     /** Boolean object */
00177     OBJ_TYPE_BOOL = 0x0F,
00178 
00179     /** Code image object */
00180     OBJ_TYPE_CIO = 0x10,
00181 
00182     /** Method object */
00183     OBJ_TYPE_MTH = 0x11,
00184 
00185     /* All types after this are not hashable */
00186     OBJ_TYPE_HASHABLE_MAX = 0x11,
00187 
00188     /** List (mutable sequence) */
00189     OBJ_TYPE_LST = 0x12,
00190 
00191     /** Dictionary (hash table) */
00192     OBJ_TYPE_DIC = 0x13,
00193 
00194 #ifdef HAVE_BYTEARRAY
00195     /** Bytearray (mutable) */
00196     OBJ_TYPE_BYA = 0x14,
00197 #endif /* HAVE_BYTEARRAY */
00198 
00199     /* All types after this are not accessible to the user */
00200     OBJ_TYPE_ACCESSIBLE_MAX = 0x18,
00201 
00202 #ifdef HAVE_BYTEARRAY
00203     /** Bytes (mutable container for Bytearray type) */
00204     OBJ_TYPE_BYS = 0x18,
00205 #endif /* HAVE_BYTEARRAY */
00206 
00207     /** Frame type */
00208     OBJ_TYPE_FRM = 0x19,
00209 
00210     /** Block type (for,while,try,etc) */
00211     OBJ_TYPE_BLK = 0x1A,
00212 
00213     /** Segment (within a seglist) */
00214     OBJ_TYPE_SEG = 0x1B,
00215 
00216     /** Seglist */
00217     OBJ_TYPE_SGL = 0x1C,
00218 
00219     /** Sequence iterator */
00220     OBJ_TYPE_SQI = 0x1D,
00221 
00222     /** Native frame (there is only one) */
00223     OBJ_TYPE_NFM = 0x1E,
00224 } PmType_t, *pPmType_t;
00225 
00226 
00227 /**
00228  * Object Descriptor
00229  *
00230  * All active PyMite "objects" must have this at the top of their struct.
00231  * (CodeObj, Frame, Dict, List, Tuple, etc.).
00232  *
00233  * The following is a diagram of the object descriptor:
00234  *
00235  *              MSb           LSb
00236  *               7 6 5 4 3 2 1 0
00237  *     pchunk-> +-+-+-+-+-+-+-+-+     S := Size of the chunk (2 LSbs dropped)
00238  *              |     S[9:2]    |     F := Free bit
00239  *              +-+-+---------+-+     M := GC Mark bit
00240  *              |F|M|    T    |S|     T := Object type (PyMite specific)
00241  *              +-+-+---------+-+
00242  *              | object data   |
00243  *              ...           ...
00244  *              | end data      |     Theoretical min size == 2
00245  *              +---------------+     Effective min size == 8
00246  *                                    (due to pmHeapDesc_t)
00247  *
00248  * Macros are used to get and set field values.
00249  * Using macros eliminates declaring bit fields which fails on some compilers.
00250  */
00251 typedef uint16_t PmObjDesc_t,
00252  *pPmObjDesc_t;
00253 
00254 /**
00255  * Object
00256  *
00257  * The abstract empty object type for PyMite.
00258  */
00259 typedef struct PmObj_s
00260 {
00261     /** Object descriptor */
00262     PmObjDesc_t od;
00263 } PmObj_t,
00264  *pPmObj_t;
00265 
00266 /** Boolean object */
00267 typedef struct PmBoolean_s
00268 {
00269     /** Object descriptor */
00270     PmObjDesc_t od;
00271 
00272     /** Boolean value */
00273     int32_t val;
00274 }
00275 PmBoolean_t, *pPmBoolean_t;
00276 
00277 
00278 /**
00279  * Loads an object from an image in memory.
00280  * Return pointer to object.
00281  * Leave add pointing one byte past end of obj.
00282  *
00283  * The following lists the simple object types
00284  * and their image structures:
00285  * -None:
00286  *      -type:      int8_t - OBJ_TYPE_NON
00287  *
00288  * -Int:
00289  *      -type:      int8_t - OBJ_TYPE_INT
00290  *      -value:     int32_t - signed integer value
00291  *
00292  * -Float:
00293  *      -type:      int8_t - OBJ_TYPE_FLOAT
00294  *      -value:     float32_t - 32-bit floating point value
00295  *
00296  * -Slice (is this allowed in img?):
00297  *      -type:      int8_t - OBJ_TYPE_SLICE
00298  *      -index1:    int16_t - first index.
00299  *      -index2:    int16_t - second index.
00300  *
00301  * @param   memspace memory space/type
00302  * @param   paddr ptr to ptr to obj
00303  *          return by reference: paddr pts to
00304  *          first byte after obj
00305  * @param   r_pobj Return arg, the loaded object.
00306  * @return  Return status
00307  */
00308 PmReturn_t obj_loadFromImg(PmMemSpace_t memspace,
00309                            uint8_t const **paddr, pPmObj_t *r_pobj);
00310 
00311 /**
00312  * Loads a code object from a code image object
00313  *
00314  * @param pimg Ptr to a code image object
00315  * @param r_pobj Return arg, the loaded object
00316  * @return  Returns status
00317  */
00318 PmReturn_t obj_loadFromImgObj(pPmObj_t pimg, pPmObj_t *r_pobj);
00319 
00320 /**
00321  * Finds the boolean value of the given object.
00322  *
00323  * @param   pobj Ptr to object to test.
00324  * @return  Nonzero value if object is False.
00325  */
00326 int8_t obj_isFalse(pPmObj_t pobj);
00327 
00328 /**
00329  * Returns the boolean true if the item is in the object
00330  *
00331  * @param   pobj Ptr to container object
00332  * @param   pitem Ptr to item
00333  */
00334 PmReturn_t obj_isIn(pPmObj_t pobj, pPmObj_t pitem);
00335 
00336 /**
00337  * Compares two objects for equality.
00338  *
00339  * @param   pobj1 Ptr to first object.
00340  * @param   pobj2 Ptr to second object.
00341  * @return  C_SAME if the items are equivalent, C_DIFFER otherwise.
00342  */
00343 int8_t obj_compare(pPmObj_t pobj1, pPmObj_t pobj2);
00344 
00345 /**
00346  * Print an object, thereby using objects helpers.
00347  *
00348  * @param   pobj Ptr to object for printing.
00349  * @param   marshallString Only has influence on the way strings are printed.
00350  *                         If 0, just output the string bytewise. Otherwise,
00351  *                         surround with single quotes and escape unprintable
00352  *                         characters.
00353  * @return  Return status
00354  */
00355 PmReturn_t obj_print(pPmObj_t pobj, uint8_t marshallString);
00356 
00357 #ifdef HAVE_BACKTICK
00358 /**
00359  * Returns by reference a string object that is the human-readable
00360  * representation of the object. Used by the backtick operation (UNARY_CONVERT).
00361  *
00362  * @param pobj Ptr to object to represent
00363  * @param r_pstr Return arg, the string object
00364  * @return Return status
00365  */
00366 PmReturn_t obj_repr(pPmObj_t pobj, pPmObj_t *r_pstr);
00367 #endif /* HAVE_BACKTICK */
00368 
00369 #endif /* __OBJ_H__ */