flight/libraries/PyMite/vm/obj.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 __OBJ_H__
  17 #define __OBJ_H__
  18
  19
  20 /**
  21  * \file
  22  * \brief Object Type
  23  *
  24  * Object type header.
  25  */
  26
  27
  28 /** Object descriptor field constants */
  29 #define OD_MARK_SHIFT 14
  30 #define OD_FREE_SHIFT 15
  31 #define OD_MARK_BIT (uint16_t)(1 << OD_MARK_SHIFT)
  32 #define OD_FREE_BIT (uint16_t)(1 << OD_FREE_SHIFT)
  33 #define OD_SIZE_MASK (uint16_t)(0x01FF)
  34 #define OD_TYPE_MASK (uint16_t)(0x3E00)
  35 #define OD_TYPE_SHIFT 9
  36
  37 /** Heap descriptor size mask */
  38 #define HD_SIZE_MASK (uint16_t)(0x3FFF)
  39
  40
  41 /**
  42  * Gets the free bit of the given object to the given value.
  43  * If the object is marked free, it is not being used by the VM.
  44  */
  45 #define OBJ_GET_FREE(pobj) \
  46     ((((pPmObj_t)pobj)->od >> OD_FREE_SHIFT) & (uint8_t)1)
  47
  48 /**
  49  * Sets the free bit of the given object to the given value.
  50  * Setting the free bit means that the object will use the heap descriptor
  51  * structure instead of the object descriptor structure.
  52  */
  53 #define OBJ_SET_FREE(pobj, free) \
  54     do \
  55     { \
  56         ((pPmObj_t)pobj)->od = ((uint8_t)free) \
  57                                ? ((pPmObj_t)pobj)->od | OD_FREE_BIT \
  58                                : ((pPmObj_t)pobj)->od & ~OD_FREE_BIT;\
  59     } \
  60     while (0)
  61
  62 /*
  63  * #99: od_size bits are shifted because size is a scaled value
  64  * True size is always a multiple of 4, so the lower two bits are ignored
  65  * and two more significant bits are gained.
  66  */
  67 /**
  68  * Gets the size of the chunk in bytes.
  69  * Tests whether the object is free as that determines whether the chunk is
  70  * using an object descriptor or a heap descriptor.  Heap descriptors have
  71  * a larger size field and use a different bit mask than object descriptors.
  72  */
  73 #define OBJ_GET_SIZE(pobj) \
  74     ((((pPmObj_t)pobj)->od & OD_FREE_BIT) \
  75      ? ((((pPmObj_t)pobj)->od & HD_SIZE_MASK) << 2) \
  76      : ((((pPmObj_t)pobj)->od & OD_SIZE_MASK) << 2))
  77
  78 /**
  79  * Sets the size of the chunk in bytes.
  80  * Tests whether the object is free as that determines whether the chunk is
  81  * using an object descriptor or a heap descriptor.  Heap descriptors have
  82  * a larger size field and use a different bit mask than object descriptors.
  83  */
  84 #define OBJ_SET_SIZE(pobj, size) \
  85     do \
  86     { \
  87         if (((pPmObj_t)pobj)->od & OD_FREE_BIT) \
  88         { \
  89             ((pPmObj_t)pobj)->od &= ~HD_SIZE_MASK; \
  90             ((pPmObj_t)pobj)->od |= (((size) >> 2) & HD_SIZE_MASK); \
  91         } \
  92         else \
  93         { \
  94             ((pPmObj_t)pobj)->od &= ~OD_SIZE_MASK; \
  95             ((pPmObj_t)pobj)->od |= (((size) >> 2) & OD_SIZE_MASK); \
  96         } \
  97     } \
  98     while (0)
  99
 100 /**
 101  * Gets the type of the object
 102  * This MUST NOT be called on objects that are free.
 103  */
 104 #define OBJ_GET_TYPE(pobj) \
 105     (((((pPmObj_t)pobj)->od) & OD_TYPE_MASK) >> OD_TYPE_SHIFT)
 106
 107 /**
 108  * Sets the type of the object
 109  * This MUST NOT be called on objects that are free.
 110  */
 111 #define OBJ_SET_TYPE(pobj, type) \
 112     do \
 113     { \
 114         ((pPmObj_t)pobj)->od &= ~OD_TYPE_MASK; \
 115         ((pPmObj_t)pobj)->od |= (((type) << OD_TYPE_SHIFT) & OD_TYPE_MASK); \
 116     } \
 117     while (0)
 118
 119
 120 /**
 121  * Object type enum
 122  *
 123  * These values go in the od_type fields of the obj descriptor.
 124  * Be sure these values correspond to those in the image creator
 125  * tool.
 126  * The hashable types are grouped together for convenience.
 127  *
 128  * WARNING: od_type must be at most 5 bits! (must be < 0x20)
 129  */
 130 typedef enum PmType_e
 131 {
 132     OBJ_TYPE_HASHABLE_MIN = 0x00,
 133
 134     /** None */
 135     OBJ_TYPE_NON = 0x00,
 136
 137     /** Signed integer */
 138     OBJ_TYPE_INT = 0x01,
 139
 140     /** Floating point 32b */
 141     OBJ_TYPE_FLT = 0x02,
 142
 143     /** String */
 144     OBJ_TYPE_STR = 0x03,
 145
 146     /** Tuple (immutable sequence) */
 147     OBJ_TYPE_TUP = 0x04,
 148
 149     /** Code obj */
 150     OBJ_TYPE_COB = 0x05,
 151
 152     /** Module obj */
 153     OBJ_TYPE_MOD = 0x06,
 154
 155     /** Class obj */
 156     OBJ_TYPE_CLO = 0x07,
 157
 158     /** Function obj (callable) */
 159     OBJ_TYPE_FXN = 0x08,
 160
 161     /** Class instance */
 162     OBJ_TYPE_CLI = 0x09,
 163
 164     /** Code image in static memory */
 165     OBJ_TYPE_CIM = 0x0A,
 166
 167     /** Native function image */
 168     OBJ_TYPE_NIM = 0x0B,
 169
 170     /** Native function object */
 171     OBJ_TYPE_NOB = 0x0C,
 172
 173     /** Thread */
 174     OBJ_TYPE_THR = 0x0D,
 175
 176     /** Boolean object */
 177     OBJ_TYPE_BOOL = 0x0F,
 178
 179     /** Code image object */
 180     OBJ_TYPE_CIO = 0x10,
 181
 182     /** Method object */
 183     OBJ_TYPE_MTH = 0x11,
 184
 185     /* All types after this are not hashable */
 186     OBJ_TYPE_HASHABLE_MAX = 0x11,
 187
 188     /** List (mutable sequence) */
 189     OBJ_TYPE_LST = 0x12,
 190
 191     /** Dictionary (hash table) */
 192     OBJ_TYPE_DIC = 0x13,
 193
 194 #ifdef HAVE_BYTEARRAY
 195     /** Bytearray (mutable) */
 196     OBJ_TYPE_BYA = 0x14,
 197 #endif /* HAVE_BYTEARRAY */
 198
 199     /* All types after this are not accessible to the user */
 200     OBJ_TYPE_ACCESSIBLE_MAX = 0x18,
 201
 202 #ifdef HAVE_BYTEARRAY
 203     /** Bytes (mutable container for Bytearray type) */
 204     OBJ_TYPE_BYS = 0x18,
 205 #endif /* HAVE_BYTEARRAY */
 206
 207     /** Frame type */
 208     OBJ_TYPE_FRM = 0x19,
 209
 210     /** Block type (for,while,try,etc) */
 211     OBJ_TYPE_BLK = 0x1A,
 212
 213     /** Segment (within a seglist) */
 214     OBJ_TYPE_SEG = 0x1B,
 215
 216     /** Seglist */
 217     OBJ_TYPE_SGL = 0x1C,
 218
 219     /** Sequence iterator */
 220     OBJ_TYPE_SQI = 0x1D,
 221
 222     /** Native frame (there is only one) */
 223     OBJ_TYPE_NFM = 0x1E,
 224 } PmType_t, *pPmType_t;
 225
 226
 227 /**
 228  * Object Descriptor
 229  *
 230  * All active PyMite "objects" must have this at the top of their struct.
 231  * (CodeObj, Frame, Dict, List, Tuple, etc.).
 232  *
 233  * The following is a diagram of the object descriptor:
 234  * \verbatim
 235  *              MSb           LSb
 236  *               7 6 5 4 3 2 1 0
 237  *     pchunk-> +-+-+-+-+-+-+-+-+     S := Size of the chunk (2 LSbs dropped)
 238  *              |     S[9:2]    |     F := Free bit
 239  *              +-+-+---------+-+     M := GC Mark bit
 240  *              |F|M|    T    |S|     T := Object type (PyMite specific)
 241  *              +-+-+---------+-+
 242  *              | object data   |
 243  *              ...           ...
 244  *              | end data      |     Theoretical min size == 2
 245  *              +---------------+     Effective min size == 8
 246  *                                    (due to pmHeapDesc_t)
 247  * \endverbatim
 248  * Macros are used to get and set field values.
 249  * Using macros eliminates declaring bit fields which fails on some compilers.
 250  */
 251 typedef uint16_t PmObjDesc_t,
 252  *pPmObjDesc_t;
 253
 254 /**
 255  * Object
 256  *
 257  * The abstract empty object type for PyMite.
 258  */
 259 typedef struct PmObj_s
 260 {
 261     /** Object descriptor */
 262     PmObjDesc_t od;
 263 } PmObj_t,
 264  *pPmObj_t;
 265
 266 /** Boolean object */
 267 typedef struct PmBoolean_s
 268 {
 269     /** Object descriptor */
 270     PmObjDesc_t od;
 271
 272     /** Boolean value */
 273     int32_t val;
 274 }
 275 PmBoolean_t, *pPmBoolean_t;
 276
 277
 278 /**
 279  * Loads an object from an image in memory.
 280  * Return pointer to object.
 281  * Leave add pointing one byte past end of obj.
 282  *
 283  * The following lists the simple object types
 284  * and their image structures:
 285  * -None:
 286  *      -type:      int8_t - OBJ_TYPE_NON
 287  *
 288  * -Int:
 289  *      -type:      int8_t - OBJ_TYPE_INT
 290  *      -value:     int32_t - signed integer value
 291  *
 292  * -Float:
 293  *      -type:      int8_t - OBJ_TYPE_FLOAT
 294  *      -value:     float32_t - 32-bit floating point value
 295  *
 296  * -Slice (is this allowed in img?):
 297  *      -type:      int8_t - OBJ_TYPE_SLICE
 298  *      -index1:    int16_t - first index.
 299  *      -index2:    int16_t - second index.
 300  *
 301  * @param   memspace memory space/type
 302  * @param   paddr ptr to ptr to obj
 303  *          return by reference: paddr pts to
 304  *          first byte after obj
 305  * @param   r_pobj Return arg, the loaded object.
 306  * @return  Return status
 307  */
 308 PmReturn_t obj_loadFromImg(PmMemSpace_t memspace,
 309                            uint8_t const **paddr, pPmObj_t *r_pobj);
 310
 311 /**
 312  * Loads a code object from a code image object
 313  *
 314  * @param pimg Ptr to a code image object
 315  * @param r_pobj Return arg, the loaded object
 316  * @return  Returns status
 317  */
 318 PmReturn_t obj_loadFromImgObj(pPmObj_t pimg, pPmObj_t *r_pobj);
 319
 320 /**
 321  * Finds the boolean value of the given object.
 322  *
 323  * @param   pobj Ptr to object to test.
 324  * @return  Nonzero value if object is False.
 325  */
 326 int8_t obj_isFalse(pPmObj_t pobj);
 327
 328 /**
 329  * Returns the boolean true if the item is in the object
 330  *
 331  * @param   pobj Ptr to container object
 332  * @param   pitem Ptr to item
 333  */
 334 PmReturn_t obj_isIn(pPmObj_t pobj, pPmObj_t pitem);
 335
 336 /**
 337  * Compares two objects for equality.
 338  *
 339  * @param   pobj1 Ptr to first object.
 340  * @param   pobj2 Ptr to second object.
 341  * @return  C_SAME if the items are equivalent, C_DIFFER otherwise.
 342  */
 343 int8_t obj_compare(pPmObj_t pobj1, pPmObj_t pobj2);
 344
 345 /**
 346  * Print an object, thereby using objects helpers.
 347  *
 348  * @param   pobj Ptr to object for printing.
 349  * @param   is_expr_repr Influences the way None and strings are printed.
 350  *                       If 0, None is printed, strings are printed.
 351  *                       If 1, None is not printed and strings are printed
 352  *                       surrounded with single quotes and unprintable
 353  *                       characters are escaped.
 354  * @param   is_nested    Influences the way None and strings are printed.
 355  *                       If 1, None will be printed and strings will be
 356  *                       surrounded with single quotes and escaped.
 357  *                       This argument overrides the is_expr_repr argument.
 358  * @return  Return status
 359  */
 360 PmReturn_t obj_print(pPmObj_t pobj, uint8_t is_expr_repr, uint8_t is_nested);
 361
 362 #ifdef HAVE_BACKTICK
 363 /**
 364  * Returns by reference a string object that is the human-readable
 365  * representation of the object. Used by the backtick operation (UNARY_CONVERT).
 366  *
 367  * @param pobj Ptr to object to represent
 368  * @param r_pstr Return arg, the string object
 369  * @return Return status
 370  */
 371 PmReturn_t obj_repr(pPmObj_t pobj, pPmObj_t *r_pstr);
 372 #endif /* HAVE_BACKTICK */
 373
 374 #endif /* __OBJ_H__ */