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