libguile/tags.h

   1 /* classes: h_files */
   2
   3 #ifndef SCM_TAGS_H
   4 #define SCM_TAGS_H
   5
   6 /* Copyright (C) 1995,1996,1997,1998,1999,2000,2001 Free Software Foundation, Inc.
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2, or (at your option)
  11  * any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this software; see the file COPYING.  If not, write to
  20  * the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  21  * Boston, MA 02111-1307 USA
  22  *
  23  * As a special exception, the Free Software Foundation gives permission
  24  * for additional uses of the text contained in its release of GUILE.
  25  *
  26  * The exception is that, if you link the GUILE library with other files
  27  * to produce an executable, this does not by itself cause the
  28  * resulting executable to be covered by the GNU General Public License.
  29  * Your use of that executable is in no way restricted on account of
  30  * linking the GUILE library code into it.
  31  *
  32  * This exception does not however invalidate any other reasons why
  33  * the executable file might be covered by the GNU General Public License.
  34  *
  35  * This exception applies only to the code released by the
  36  * Free Software Foundation under the name GUILE.  If you copy
  37  * code from other Free Software Foundation releases into a copy of
  38  * GUILE, as the General Public License permits, the exception does
  39  * not apply to the code that you add in this way.  To avoid misleading
  40  * anyone as to the status of such modified files, you must delete
  41  * this exception notice from them.
  42  *
  43  * If you write modifications of your own for GUILE, it is your choice
  44  * whether to permit this exception to apply to your modifications.
  45  * If you do not wish that, delete this exception notice.  */
  46
  47 \f
  48
  49 /** This file defines the format of SCM values and cons pairs.
  50  ** It is here that tag bits are assigned for various purposes.
  51  **/
  52
  53 #ifdef HAVE_STDINT_H
  54 #include <stdint.h>
  55 #endif
  56
  57 #ifdef HAVE_INTTYPES_H
  58 #include <inttypes.h>
  59 #endif
  60
  61 \f
  62
  63 /* In the beginning was the Word:
  64  */
  65 #ifdef HAVE_UINTPTR_T
  66 typedef uintptr_t scm_t_bits;
  67 typedef intptr_t scm_t_signed_bits;
  68 #else
  69 typedef unsigned long scm_t_bits;
  70 typedef signed long scm_t_signed_bits;
  71 #endif
  72
  73 /* But as external interface, we use SCM, which may, according to the desired
  74  * level of type checking, be defined in several ways:
  75  */
  76 #if (SCM_DEBUG_TYPING_STRICTNESS == 2)
  77     typedef union { struct { scm_t_bits n; } n; } SCM;
  78     static SCM scm_pack(scm_t_bits b) { SCM s; s.n.n = b; return s; }
  79 #   define SCM_UNPACK(x) ((x).n.n)
  80 #   define SCM_PACK(x) (scm_pack ((scm_t_bits) (x)))
  81 #elif (SCM_DEBUG_TYPING_STRICTNESS == 1)
  82 /* This is the default, which provides an intermediate level of compile time
  83  * type checking while still resulting in very efficient code.
  84  */
  85     typedef struct scm_unused_struct * SCM;
  86 #   define SCM_UNPACK(x) ((scm_t_bits) (x))
  87 #   define SCM_PACK(x) ((SCM) (x))
  88 #else
  89 /* This should be used as a fall back solution for machines on which casting
  90  * to a pointer may lead to loss of bit information, e. g. in the three least
  91  * significant bits.
  92  */
  93     typedef scm_t_bits SCM;
  94 #   define SCM_UNPACK(x) (x)
  95 #   define SCM_PACK(x) ((scm_t_bits) (x))
  96 #endif
  97
  98
  99 /* SCM values can not be compared by using the operator ==.  Use the following
 100  * macro instead, which is the equivalent of the scheme predicate 'eq?'.
 101  */
 102 #define SCM_EQ_P(x, y) (SCM_UNPACK (x) == SCM_UNPACK (y))
 103
 104 \f
 105
 106 /* SCM variables can contain:
 107  *
 108  * Non-objects -- meaning that the tag-related macros don't apply to them
 109  * in the usual way.
 110  *
 111  * Immediates -- meaning that the variable contains an entire Scheme object.
 112  *
 113  * Non-immediates -- meaning that the variable holds a (possibly
 114  * tagged) pointer into the cons pair heap.
 115  *
 116  * Non-objects are distinguished from other values by careful coding
 117  * only (i.e., programmers must keep track of any SCM variables they
 118  * create that don't contain ordinary scheme values).
 119  *
 120  * All immediates and pointers to cells of non-immediates have a 0 in
 121  * bit 0.  All non-immediates that are not pairs have a 1 in bit 0 of
 122  * the first word of their cell.  This is how pairs are distinguished
 123  * from other non-immediates; a pair can have a immediate in its car
 124  * (thus a 0 in bit 0), or a pointer to the cell of a non-immediate
 125  * (again, this pointer has a 0 in bit 0).
 126  *
 127  * Immediates and non-immediates are distinguished by bits 1 and 2.
 128  * Immediate values must have a 1 in at least one of those bits.
 129  * Consequently, a pointer to a cell of a non-immediate must have
 130  * zeros in bits 1 and 2.  Together with the requirement from above
 131  * that bit 0 must also be zero, this means that pointers to cells of
 132  * non-immediates must have their three low bits all zero.  This in
 133  * turn means that cells must be aligned on a 8 byte boundary, which
 134  * is just right for two 32bit numbers (surprise, surprise).  Does
 135  * this (or any other detail of tagging) seem arbitrary?  Try changing
 136  * it!  (Not always impossible but it is fair to say that many details
 137  * of tags are mutually dependent).  */
 138
 139 #define SCM_IMP(x)              (6 & SCM_UNPACK (x))
 140 #define SCM_NIMP(x)             (!SCM_IMP (x))
 141
 142 /* Here is a summary of tagging in SCM values as they might occur in
 143  * SCM variables or in the heap.
 144  *
 145  * low bits    meaning
 146  *
 147  *
 148  * 0            Most objects except...
 149  * 1            ... structs (this tag is valid only in the header
 150  *              of a struct's data, as with all odd tags).
 151  *
 152  * 00           heap addresses and many immediates (not integers)
 153  * 01           structs, some tc7_ codes
 154  * 10           immediate integers
 155  * 11           various tc7_ codes including, tc16_ codes.
 156  *
 157  *
 158  * 000          heap address
 159  * 001          structs
 160  * 010          integer
 161  * 011          closure
 162  * 100          immediates
 163  * 101          tc7_
 164  * 110          integer
 165  * 111          tc7_
 166  *
 167  *
 168  * 100 --- IMMEDIATES
 169  *
 170  * Looking at the seven final bits of an immediate:
 171  *
 172  * 0000-100     short instruction
 173  * 0001-100     short instruction
 174  * 0010-100     short instruction
 175  * 0011-100     short instruction
 176  * 0100-100     short instruction
 177  * 0101-100     short instruction
 178  * 0110-100     various immediates and long instructions
 179  * 0111-100     short instruction
 180  * 1000-100     short instruction
 181  * 1001-100     short instruction
 182  * 1010-100     short instruction
 183  * 1011-100     short instruction
 184  * 1100-100     short instruction
 185  * 1101-100     short instruction
 186  * 1110-100     immediate characters
 187  * 1111-100     ilocs
 188  *
 189  * Some of the 0110100 immediates are long instructions (they dispatch
 190  * in two steps compared to one step for a short instruction).
 191  * The two steps are, (1) dispatch on 7 bits to the long instruction
 192  * handler, (2) dispatch on 7 additional bits.
 193  *
 194  * One way to think of it is that there are 128 short instructions,
 195  * with the 13 immediates above being some of the most interesting.
 196  *
 197  * Also noteworthy are the groups of 16 7-bit instructions implied by
 198  * some of the 3-bit tags.  For example, closure references consist of
 199  * an 8-byte aligned address tagged with 011.  There are 16 identical
 200  * 7-bit instructions, all ending 011, which are invoked by evaluating
 201  * closures.
 202  *
 203  * In other words, if you hand the evaluator a closure, the evaluator
 204  * treats the closure as a graph of virtual machine instructions.  A
 205  * closure is a pair with a pointer to the body of the procedure in
 206  * the CDR and a pointer to the environment of the closure in the CAR.
 207  * The environment pointer is tagged 011 which implies that the least
 208  * significant 7 bits of the environment pointer also happen to be a
 209  * virtual machine instruction we could call "SELF" (for
 210  * self-evaluating object).
 211  *
 212  * A less trivial example are the 16 instructions ending 000.  If
 213  * those bits tag the CAR of a pair, then evidently the pair is an
 214  * ordinary cons pair and should be evaluated as a procedure
 215  * application.  The sixteen, 7-bit 000 instructions are all
 216  * "NORMAL-APPLY" (Things get trickier.  For example, if the CAR of a
 217  * procedure application is a symbol, the NORMAL-APPLY instruction
 218  * will, as a side effect, overwrite that CAR with a new instruction
 219  * that contains a cached address for the variable named by the
 220  * symbol.)
 221  *
 222  * Here is a summary of tags in the CAR of a non-immediate:
 223  *
 224  *   HEAP CELL: G=gc_mark; 1 during mark, 0 other times.
 225  *
 226  * cons    ..........SCM car..............0  ...........SCM cdr.............G
 227  * struct  ..........void * type........001  ...........void * data.........G
 228  * closure ..........SCM code...........011  ...........SCM env.............G
 229  * tc7     ......24.bits of data...Gxxxx1S1  ..........void *data............
 230  *
 231  *
 232  *
 233  * 101 & 111 --- tc7_ types
 234  *
 235  *              tc7_tags are 7 bit tags ending in 1x1.  These tags
 236  *              occur only in the CAR of heap cells, and have the
 237  *              handy property that all bits of the CAR above the
 238  *              bottom eight can be used to store some data, thus
 239  *              saving a word in the body itself.  Thus, we use them
 240  *              for strings and vectors (among other things).
 241  *
 242  *              TYP7(X) returns bits 0...6 of CELL_TYPE (X)
 243  *
 244  *              Sometimes we choose the bottom seven bits carefully,
 245  *              so that the 2-valued bit (called S bit) can be masked
 246  *              off to reveal a common type.
 247  *
 248  *              TYP7S(X) returns TYP7, but masking out the option bit S.
 249  *
 250  *              Some TC7 types are subdivided into 256 subtypes giving
 251  *              rise to the macros:
 252  *
 253  *              TYP16
 254  *              TYP16S
 255  *
 256  *              TYP16S functions similarly wrt to TYP16 as TYP7S to TYP7,
 257  *              but a different option bit is used (bit 2 for TYP7S,
 258  *              bit 8 for TYP16S).
 259  * */
 260
 261
 262
 263 \f
 264 /* {Non-immediate values.}
 265  *
 266  * If X is non-immediate, it is necessary to look at SCM_CAR (X) to
 267  * figure out Xs type.  X may be a cons pair, in which case the value
 268  * SCM_CAR (x) will be either an immediate or non-immediate value.  X
 269  * may be something other than a cons pair, in which case the value
 270  * SCM_CAR (x) will be a non-object value.
 271  *
 272  * All immediates and non-immediates have a 0 in bit 0.  We
 273  * additionally preserve the invariant that all non-object values
 274  * stored in the SCM_CAR of a non-immediate object have a 1 in bit 1:
 275  */
 276
 277 #define SCM_CONSP(x)  (!SCM_IMP (x) && ((1 & SCM_CELL_TYPE (x)) == 0))
 278 #define SCM_NCONSP(x) (!SCM_CONSP (x))
 279
 280 \f
 281
 282 /* See numbers.h for macros relating to immediate integers.
 283  */
 284
 285 #define SCM_ITAG3(x)             (7 & SCM_UNPACK (x))
 286 #define SCM_TYP3(x)              (7 & SCM_CELL_TYPE (x))
 287 #define scm_tc3_cons             0
 288 #define scm_tc3_struct           1
 289 #define scm_tc3_int_1            2
 290 #define scm_tc3_closure          3
 291 #define scm_tc3_imm24            4
 292 #define scm_tc3_tc7_1            5
 293 #define scm_tc3_int_2            6
 294 #define scm_tc3_tc7_2            7
 295
 296
 297 /*
 298  * Do not change the three bit tags.
 299  */
 300
 301
 302 #define SCM_ITAG7(x)            (127 & SCM_UNPACK (x))
 303 #define SCM_TYP7(x)             (0x7f &        SCM_CELL_TYPE (x))
 304 #define SCM_TYP7S(x)            ((0x7f & ~2) & SCM_CELL_TYPE (x))
 305
 306
 307 #define SCM_TYP16(x)            (0xffff & SCM_CELL_TYPE (x))
 308 #define SCM_TYP16S(x)           (0xfeff & SCM_CELL_TYPE (x))
 309
 310 #define SCM_TYP16_PREDICATE(tag,x) (!SCM_IMP (x) && SCM_TYP16 (x) == (tag))
 311
 312 \f
 313
 314 #define scm_tc7_symbol          5
 315 #define scm_tc7_variable        7
 316
 317 /* couple */
 318 #define scm_tc7_vector          13
 319 #define scm_tc7_wvect           15
 320
 321 #define scm_tc7_string          21
 322 /* free                         23 */
 323
 324 /* Many of the following should be turned
 325  * into structs or smobs.  We need back some
 326  * of these 7 bit tags!
 327  */
 328 #define scm_tc7_pws             31
 329
 330 #ifdef HAVE_ARRAYS
 331 #define scm_tc7_llvect          29
 332 #define scm_tc7_uvect           37
 333 /* free                         39 */
 334 #define scm_tc7_fvect           45
 335 #define scm_tc7_dvect           47
 336 #define scm_tc7_cvect           53
 337 #define scm_tc7_svect           55
 338 #define scm_tc7_bvect           71
 339 #define scm_tc7_byvect          77
 340 #define scm_tc7_ivect           79
 341 #endif
 342
 343 /* free                         61 */
 344 #define scm_tc7_cclo            63
 345 #define scm_tc7_rpsubr          69
 346 #define scm_tc7_subr_0          85
 347 #define scm_tc7_subr_1          87
 348 #define scm_tc7_cxr             93
 349 #define scm_tc7_subr_3          95
 350 #define scm_tc7_subr_2          101
 351 #define scm_tc7_asubr           103
 352 #define scm_tc7_subr_1o         109
 353 #define scm_tc7_subr_2o         111
 354 #define scm_tc7_lsubr_2         117
 355 #define scm_tc7_lsubr           119
 356
 357
 358 /* There are 256 port subtypes.
 359  */
 360 #define scm_tc7_port            125
 361
 362
 363 /* There are 256 smob subtypes.  Here are the first four.
 364  */
 365
 366 #define scm_tc7_smob            127 /* DO NOT CHANGE [**] */
 367
 368 /* [**] If you change scm_tc7_smob, you must also change
 369  * the places it is hard coded in this file and possibly others.
 370  */
 371
 372
 373 /* scm_tc_free_cell is also the 0th smob type.  We place this
 374  * in free cells to tell the conservative marker not to trace it.
 375  */
 376 #define scm_tc_free_cell        (scm_tc7_smob + 0 * 256L)
 377
 378 /* Smob type 1 to 3 (note the dependency on the predicate SCM_NUMP)
 379  */
 380 #define scm_tc16_big            (scm_tc7_smob + 1 * 256L)
 381 #define scm_tc16_real           (scm_tc7_smob + 2 * 256L)
 382 #define scm_tc16_complex        (scm_tc7_smob + 3 * 256L)
 383
 384 \f
 385 /* {Immediate Values}
 386  */
 387
 388 enum scm_tags
 389 {
 390   scm_tc8_char = 0xf4,
 391   scm_tc8_iloc = 0xfc
 392 };
 393
 394 #define SCM_ITAG8(X)            (SCM_UNPACK (X) & 0xff)
 395 #define SCM_MAKE_ITAG8(X, TAG)  SCM_PACK (((X) << 8) + TAG)
 396 #define SCM_ITAG8_DATA(X)       (SCM_UNPACK (X) >> 8)
 397
 398
 399 \f
 400 /* Immediate Symbols, Special Symbols, Flags (various constants).
 401  */
 402
 403 /* SCM_ISYMP tests for ISPCSYM and ISYM */
 404 #define SCM_ISYMP(n)            ((0x187 & SCM_UNPACK (n)) == 4)
 405
 406 /* SCM_IFLAGP tests for ISPCSYM, ISYM and IFLAG */
 407 #define SCM_IFLAGP(n)           ((0x87 & SCM_UNPACK (n)) == 4)
 408 #define SCM_ISYMNUM(n)          (SCM_UNPACK (n) >> 9)
 409 #define SCM_ISYMCHARS(n)        (scm_isymnames[SCM_ISYMNUM (n)])
 410 #define SCM_MAKSPCSYM(n)        SCM_PACK (((n) << 9) + ((n) << 3) + 4L)
 411 #define SCM_MAKISYM(n)          SCM_PACK (((n) << 9) + 0x74L)
 412 #define SCM_MAKIFLAG(n)         SCM_PACK (((n) << 9) + 0x174L)
 413
 414 extern char *scm_isymnames[];   /* defined in print.c */
 415
 416 /* This table must agree with the declarations
 417  * in repl.c: {Names of immediate symbols}.
 418  *
 419  * These are used only in eval but their values
 420  * have to be allocated here.
 421  *
 422  */
 423
 424 #define SCM_IM_AND              SCM_MAKSPCSYM (0)
 425 #define SCM_IM_BEGIN            SCM_MAKSPCSYM (1)
 426 #define SCM_IM_CASE             SCM_MAKSPCSYM (2)
 427 #define SCM_IM_COND             SCM_MAKSPCSYM (3)
 428 #define SCM_IM_DO               SCM_MAKSPCSYM (4)
 429 #define SCM_IM_IF               SCM_MAKSPCSYM (5)
 430 #define SCM_IM_LAMBDA           SCM_MAKSPCSYM (6)
 431 #define SCM_IM_LET              SCM_MAKSPCSYM (7)
 432 #define SCM_IM_LETSTAR          SCM_MAKSPCSYM (8)
 433 #define SCM_IM_LETREC           SCM_MAKSPCSYM (9)
 434 #define SCM_IM_OR               SCM_MAKSPCSYM (10)
 435 #define SCM_IM_QUOTE            SCM_MAKSPCSYM (11)
 436 #define SCM_IM_SET_X            SCM_MAKSPCSYM (12)
 437 #define SCM_IM_DEFINE           SCM_MAKSPCSYM (13)
 438 #define SCM_IM_APPLY            SCM_MAKISYM (14)
 439 #define SCM_IM_CONT             SCM_MAKISYM (15)
 440 #define SCM_BOOL_F              SCM_MAKIFLAG (16)
 441 #define SCM_BOOL_T              SCM_MAKIFLAG (17)
 442 #define SCM_UNDEFINED           SCM_MAKIFLAG (18)
 443 #define SCM_EOF_VAL             SCM_MAKIFLAG (19)
 444 #define SCM_EOL                 SCM_MAKIFLAG (20)
 445 #define SCM_UNSPECIFIED         SCM_MAKIFLAG (21)
 446 #define SCM_IM_DISPATCH         SCM_MAKISYM (22)
 447 #define SCM_IM_SLOT_REF         SCM_MAKISYM (23)
 448 #define SCM_IM_SLOT_SET_X       SCM_MAKISYM (24)
 449
 450 /* Multi-language support */
 451
 452 #define SCM_IM_NIL_COND         SCM_MAKISYM (25)
 453 #define SCM_IM_NIL_IFY          SCM_MAKISYM (26)
 454 #define SCM_IM_T_IFY            SCM_MAKISYM (27)
 455 #define SCM_IM_0_COND           SCM_MAKISYM (28)
 456 #define SCM_IM_0_IFY            SCM_MAKISYM (29)
 457 #define SCM_IM_1_IFY            SCM_MAKISYM (30)
 458 #define SCM_IM_BIND             SCM_MAKISYM (31)
 459
 460 #define SCM_IM_DELAY            SCM_MAKISYM (32)
 461 #define SCM_IM_CALL_WITH_VALUES SCM_MAKISYM (33)
 462
 463 /* When a variable is unbound this is marked by the SCM_UNDEFINED
 464  * value.  The following is an unbound value which can be handled on
 465  * the Scheme level, i.e., it can be stored in and retrieved from a
 466  * Scheme variable.  This value is only intended to mark an unbound
 467  * slot in GOOPS.  It is needed now, but we should probably rewrite
 468  * the code which handles this value in C so that SCM_UNDEFINED can be
 469  * used instead.  It is not ideal to let this kind of unique and
 470  * strange values loose on the Scheme level.
 471  */
 472 #define SCM_UNBOUND             SCM_MAKIFLAG (34)
 473
 474 #define SCM_UNBNDP(x)           (SCM_EQ_P ((x), SCM_UNDEFINED))
 475
 476 \f
 477
 478 /* Dispatching aids:
 479
 480    When switching on SCM_TYP7 of a SCM value, use these fake case
 481    labels to catch types that use fewer than 7 bits for tagging.  */
 482
 483 /* For cons pairs with immediate values in the CAR
 484  */
 485
 486 #define scm_tcs_cons_imcar 2:case 4:case 6:case 10:\
 487  case 12:case 14:case 18:case 20:\
 488  case 22:case 26:case 28:case 30:\
 489  case 34:case 36:case 38:case 42:\
 490  case 44:case 46:case 50:case 52:\
 491  case 54:case 58:case 60:case 62:\
 492  case 66:case 68:case 70:case 74:\
 493  case 76:case 78:case 82:case 84:\
 494  case 86:case 90:case 92:case 94:\
 495  case 98:case 100:case 102:case 106:\
 496  case 108:case 110:case 114:case 116:\
 497  case 118:case 122:case 124:case 126
 498
 499 /* For cons pairs with non-immediate values in the SCM_CAR
 500  */
 501 #define scm_tcs_cons_nimcar 0:case 8:case 16:case 24:\
 502  case 32:case 40:case 48:case 56:\
 503  case 64:case 72:case 80:case 88:\
 504  case 96:case 104:case 112:case 120
 505
 506 /* For structs
 507  */
 508 #define scm_tcs_struct 1:case 9:case 17:case 25:\
 509  case 33:case 41:case 49:case 57:\
 510  case 65:case 73:case 81:case 89:\
 511  case 97:case 105:case 113:case 121
 512
 513 /* For closures
 514  */
 515 #define scm_tcs_closures   3:case 11:case 19:case 27:\
 516  case 35:case 43:case 51:case 59:\
 517  case 67:case 75:case 83:case 91:\
 518  case 99:case 107:case 115:case 123
 519
 520 /* For subrs
 521  */
 522 #define scm_tcs_subrs scm_tc7_asubr:case scm_tc7_subr_0:case scm_tc7_subr_1:case scm_tc7_cxr:\
 523  case scm_tc7_subr_3:case scm_tc7_subr_2:case scm_tc7_rpsubr:case scm_tc7_subr_1o:\
 524  case scm_tc7_subr_2o:case scm_tc7_lsubr_2:case scm_tc7_lsubr
 525
 526 \f
 527
 528 #if (SCM_ENABLE_DEPRECATED == 1)
 529
 530 #define SCM_CELLP(x)    (((sizeof (scm_cell) - 1) & SCM_UNPACK (x)) == 0)
 531 #define SCM_NCELLP(x)   (!SCM_CELLP (x))
 532
 533 #endif
 534
 535 #endif  /* SCM_TAGS_H */
 536
 537 /*
 538   Local Variables:
 539   c-file-style: "gnu"
 540   End:
 541 */