obj.h

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