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