![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tr83-10a.roff CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / contrib / icon / docs|
Return to tr83-10a.roff CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / icon / docs |
1.1 root 1: .de Ls
2: .RS
3: .nr L 0 1
4: ..
5: .de Le
6: .RE
7: .LP
8: ..
9: .de Np
10: .IP (\\n+L) .25i
11: ..
12: .ds ar \v'2p'\s18\(->\s0\v'-2p'
13: .ds sd \s8\v'.2m'\h'-0.4n'
14: .ds su \v'-.2m'\s0
15: .ds ex \fIarg\fP
16: .ds e1 \fIarg\*(sd1\*(su\fP
17: .ds e2 \fIarg\*(sd2\*(su\fP
18: .ds e3 \fIarg\*(sd3\*(su\fP
19: .ds e4 \fIarg\*(sd4\*(su\fP
20: .ds e5 \fIarg\*(sd5\*(su\fP
21: .ds ei \fIarg\*(sdi\*(su\fP
22: .ds en \fIarg\*(sdn\*(su\fP
23: .ds e0 \fIarg\*(sd0\*(su\fP
24: .ds xx \fIexpr\fP
25: .ds x1 \fIexpr\*(sd1\*(su\fP
26: .ds x2 \fIexpr\*(sd2\*(su\fP
27: .ds x3 \fIexpr\*(sd3\*(su\fP
28: .ds x4 \fIexpr\*(sd4\*(su\fP
29: .ds x5 \fIexpr\*(sd5\*(su\fP
30: .ds xi \fIexpr\*(sdi\*(su\fP
31: .ds xn \fIexpr\*(sdn\*(su\fP
32: .ds x0 \fIexpr\*(sd0\*(su\fP
33: .ds v0 \fIvar\fP
34: .ds v1 \fIvar\*(sd1\*(su\fP
35: .ds v2 \fIvar\*(sd2\*(su\fP
36: .ds v3 \fIvar\*(sd3\*(su\fP
37: .ds vi \fIvar\*(sdi\*(su\fP
38: .ds vn \fIvar\*(sdn\*(su\fP
39: .ds ax \fIarg\fP
40: .ds a1 \fIarg\*(sd1\*(su\fP
41: .ds a2 \fIarg\*(sd2\*(su\fP
42: .ds a3 \fIarg\*(sd3\*(su\fP
43: .ds a4 \fIarg\*(sd4\*(su\fP
44: .ds a5 \fIarg\*(sd5\*(su\fP
45: .ds ai \fIarg\*(sdi\*(su\fP
46: .ds an \fIarg\*(sdn\*(su\fP
47: .ds a0 \fIarg\*(sd0\*(su\fP
48: .de St
49: .ta 1.0iR +.5i 4i
50: ..
51: .de S1
52: .ta 0.75i
53: ..
54: .de Pt
55: .ta 0.8i +0.8i +0.8i +0.8i +0.8i +0.8i +0.8i +0.8i
56: ..
57: .TR 83-10d
58: .DA "June 1983; Revised July 1983,\^ January 1984,\^ June 1984,\^ and August 1984"
59: .Gr
60: .TL
61: Porting the UNIX Implementation of Icon
62: .AU
63: William H. Mitchell
64: .AB
65: This document explains how to port the UNIX implementation of the
66: Icon programming language. The Icon system is composed of a translator,\^
67: a linker,\^ and an interpreter. Procedures for porting each system
68: component are described in detail. This document is meant to be a
69: companion to the Icon ``tour'' (TR 84-11) and the source code for
70: the system.
71: .AE
72: .SH
73: Introduction
74: .PP
75: This document describes how to port the Version 5 Icon interpreter
76: to a \*U environment.
77: .Un
78: There is both an interpreter and a compiler available for Icon; this
79: document only addresses porting the interpreter.
80: The Icon system has three major components:
81: a translator,\^ a linker,\^ and an interpreter. The translator and
82: the linker are entirely written in C and porting them is merely a
83: matter of setting constant values that are appropriate for the target
84: machine. Portions of the interpreter are written in assembly language and
85: thus must be written anew for each machine. The interpreter also
86: contains a very small amount of C code that must be written on a
87: per-machine basis.
88: .PP
89: The sections of this document that describe the porting of the
90: translator and the linker are straightforward,\^ being merely a
91: description of a process. While porting the translator and the
92: linker is a task of following instructions,\^ porting the interpreter
93: is a task of design and programming. The approach taken is to describe
94: what function each routine must perform and how it is implemented in
95: the VAX\u\(dg\d version of Icon. The porter's job is to determine how to
96: .FS
97: \u\(dg\dVAX is a trademark of Digital Equipment Corporation.
98: .FE
99: implement the various routines on the target machine.
100: .PP
101: In light of
102: the increasing popularity of the C language and the availability of C
103: compilers for non-UNIX environments,\^ it is quite possible that one may
104: desire to port Icon to a non-UNIX environment.
105: Because the matter of porting a UNIX program to
106: a non-UNIX environment is a problem in itself,\^ it is not addressed in
107: this document. Rather,\^ this document assumes that the target
108: environment is UNIX. This is not to say that porting Icon to a non-UNIX
109: environment is not feasible. Icon is not strongly bound to UNIX,\^ the
110: primary association being that Icon is written in C. It is
111: anticipated that most C systems that are available for a non-UNIX
112: environment will provide most of the UNIX-independent C standard
113: functions as part of a library. If such a library is available,\^
114: it should be possible to port Icon without great difficulty.
115: .PP
116: This document is a companion document of the Icon
117: ``tour''\^[1] and should be studied with the source code for
118: Version 5.8 of Icon at hand.
119: In particular,\^ the porter should be familiar with the information
120: contained in the tour.
121: .PP
122: The sections of this document that describe the VAX assembly language
123: code attempt to explain the operation of instructions when the
124: operation is not obvious. However,\^ this document does
125: assume that the porter has
126: a rudimentary familiarity with the basic concepts of the VAX-11
127: architecture\^[2].
128: .SH
129: C Compiler Requirements
130: .PP
131: Because there is no
132: standard for the C programming language,\^ it is difficult to say how
133: ``standard'' the usage of C in the system is. The system was
134: developed using the V7 C compiler,\^ often referred to as the Ritchie
135: compiler\^[3]. The system was later ported to the VAX using the \fIPortable
136: C Compiler\fP\^[4] and no serious problems were encountered.
137: .PP
138: In addition to supporting ``full'' C,\^ a few specific requirements and
139: non-requirements are made on the C compiler:
140: .Ls
141: .Np
142: The compiler must support both assignment and call-by-value for
143: structures.
144: .Np
145: The compiler need not support bit field operations.
146: .Np
147: Arguments to C functions must be stored in consecutive,\^
148: ascending memory locations.
149: .Np
150: There may be problems if \*Msizeof(int)\fP and \*Msizeof(char *)\fP
151: are not the same,\^ but no definite problems are known.
152: .Np
153: It is believed that there are great,\^ perhaps insurmountable
154: problems,\^ if \*Msizeof(char *)\fP is not equal to \*Msizeof(int *)\fP.
155: .Le
156: .SH
157: System Testing
158: .PP
159: The test programs and testing procedures to be used for porting Icon
160: are described in \^[5].
161: At various points in this document,\^ the porter is directed
162: to test the system component just completed. At such times,\^ the
163: porter should refer to \^[5] to determine what should be done.
164: .NH 1
165: Porting the Icon Translator
166: .NH 2
167: Overview
168: .PP
169: The Icon translator,\^ known as \*Mitran\fR,\^ is the first
170: logical component of the Icon system. The translator takes Icon
171: source files as input and produces two \fIucode\fR output files
172: for each input file.
173: The translator may be run by saying:
174: .Ds
175: itran hello.icn
176: .De
177: This produces two ascii files,\^
178: \*Mhello.u1\fR and \*Mhello.u2\fR. \*Mhello.u1\fR
179: contains interpretable instructions and data in a printable
180: format. \*Mhello.u2\fR contains information about global symbols and
181: scope.
182: .PP
183: The translator is written entirely in C and is the most machine
184: independent major system component. No serious
185: problems should be encountered in porting it. If difficulties are
186: encountered,\^ it probably indicates that there are major problems
187: with the C compiler being used.
188: .NH 2
189: Porting Procedure
190: .PP
191: The Icon system contains a number of instances of values that must be
192: specified on a per-machine basis. The system also contains assembly
193: code and,\^ of course,\^ such code is different on each machine. Rather
194: than maintaining a source copy of Icon for each machine that Icon runs
195: on,\^ C preprocessor control statements are used to select portions of
196: code specific to a certain machine. The source as distributed can
197: be compiled on either a VAX and PDP-11* system by defining \*MVAX\fP or
198: .FS
199: *PDP is a trademark of Digital Equipment Corporation.
200: .FE
201: \*MPDP11\fP respectively in \*Mh/config.h\fP. The porting source has
202: neither \*MVAX\fP or \*MPDP11\fP defined; rather,\^ \*MPORT\fP
203: is defined. Where machine specific code is to appear,\^ along with
204: sections bracketed by \*M#define\fPs for \*MVAX\fP and \*MPDP11\fP,\^
205: there is a skeletal section bracketed by a \*M#define\fP for
206: \*MPORT\fP. The \*MPORT\fP section is to be filled out for the
207: target machine. This convention is followed throughout and porting
208: Icon is nothing more than filling in all the \*MPORT\fP sections.
209: .PP
210: The source for the translator is contained in the directory \*Mtran\fP.
211: Translator machine dependencies are confined to the file \*Mtran/sym.h\fR.
212: A pair of constants define the sizes of two data structures used during the
213: translation process.
214: Edit the file \*Msym.h\fR and search for the string \*MPORT\fR.
215: The code looks something like
216: .Ds
217: .ta 2.0iR 2.5i
218: #ifdef PORT
219: #define TSIZE x /* default size of parse tree space */
220: #define SSIZE x /* default size of string space */
221: #endif PORT
222: #ifdef VAX
223: #define TSIZE 15000 /* size of parse tree space */
224: #define SSIZE 15000 /* default size of string space */
225: #endif VAX
226: #ifdef PDP11
227: #define TSIZE 5000 /* default size of parse tree space */
228: #define SSIZE 5000 /* default size of string space */
229: #endif PDP11
230: .De
231: The values of \*MTSIZE\fP and \*Mssize\fP are not critical
232: and current values have been chosen rather arbitrarily.
233: If you are on a large
234: machine,\^ use the values of \*MTSIZE\fR and \*MSSIZE\fR specified for
235: the VAX; otherwise,\^ use the values specified for the PDP-11.
236: .PP
237: The translator may now be compiled by issuing the \fImake\fR command
238: without any arguments.
239: .PP
240: It should be noted that although Icon programs are used to create
241: some of the translator source files (namely \*Mkeyword.h\fP,\^ \*Mkeyword.c\fP
242: \*Moptab.c\fP,\^ and \*Mtoktab.c\fP). These files are machine independent
243: and do not need to be remade. If for some reason \*Mmake\fP tries to
244: create any of these files,\^ just \*Mtouch\fP the file in question to
245: update the last-modified date. Similarly,\^ \*Mparse.c\fP is generated by
246: \fIyacc\fP and does not need to be regenerated unless the grammar is
247: modified.
248: .PP
249: When the translator has been successfully compiled using \fImake\fP,\^
250: refer to [5] for testing.
251: .PP
252: Porting the translator may seem like a trivial task,\^
253: but its successful completion is a definite milestone because
254: it is good sign that the C compiler in use is suitable.
255: .nr $1 1
256: .nr $2 0
257: .NH 1
258: Porting the Icon Linker
259: .NH 2
260: Overview
261: .PP
262: The Icon linker,\^ known as \*Milink\fP,\^ is the second logical component
263: of the Icon system. The linker takes \*Mu1\fP and \*Mu2\fP files
264: produced by the translator and binds them together to form an
265: \fIinterpretable\fP file. The interpretable file serves as input
266: for the Icon interpreter.
267: The linker is written entirely in C and is a fairly small and
268: simple program. However,\^ the interpretable files produced by
269: the linker are not machine independent and because of this,\^
270: porting the linker is more troublesome than porting the
271: translator.
272: .PP
273: Interpretable files contain two distinct types of data: opcodes and
274: associated operands that the interpreter ``understands''; and data that
275: is directly mapped into run-time data structures. By ``mapping'' it
276: is meant that the data is loaded into memory and then C structure
277: references are used to access elements of the object at a certain
278: location in memory.
279: The formats of
280: the opcodes and operands must conform to what the interpreter is
281: expecting. The data that is directly mapped must conform to the
282: format of the C data structures used by the run-time system.
283: .PP
284: On the VAX,\^ for example,\^ interpreter opcodes are one byte long
285: and operands are four bytes long. On the PDP-11,\^ opcodes are
286: also one byte long,\^ but operands are only two bytes long.
287: Opcode and operand size are fairly arbitrary,\^ but it is important
288: that the linker and the interpreter be coordinated.
289: .PP
290: The mapped data structures are slightly more complicated because
291: the linker must conform to the format produced by the C compiler.
292: This is not difficult,\^ since the data structures involved have
293: a regular form. All are composed of some number of \fIwords\fP
294: where each word is the same size in every structure.*
295: .FS
296: *Literature about the VAX conventionally uses the term \fIword\fP to refer
297: to 16-bit quantities and the term \fIlongword\fP to refer to 32-bit
298: quantities. In this document,\^ \fIword\fP in a generic context
299: refers to the basic unit of the run-time data structures; \fIword\fP
300: in a VAX-specific context refers to a 32-bit quantity.
301: .FE
302: .PP
303: The opcodes,\^ operands,\^ and mapped data are accumulated in memory during the
304: linking process. This conglomerate is referred to as the \fIcode\fP
305: section. Several routines are used to add data to the code
306: section. These routines are parameterized so that porting the linker
307: to a new machine is merely a matter of setting the parameters
308: correctly. Four primitive data units
309: compose the code section. These are \fIopcodes\fP,\^ \fIoperands\fP,\^
310: \fIwords\fP,\^ and \fIblocks\fP.
311: .IP opcodes
312: .br
313: are instructions for the
314: interpreter. An opcode may direct the interpreter to push a value
315: on the stack,\^ branch to a location,\^ perform an arithmetic operation,\^
316: etc.
317: .IP operands
318: .br
319: are associated with some opcodes. For
320: example,\^ the \*Mgoto\fP instruction has a location to branch to as
321: its single operand.
322: .IP words
323: .br
324: compose mapped data structures. A word is the basic
325: unit of the run-time data structures and should consist
326: of \*Msizeof(int *)\fP bytes.
327: .IP blocks
328: .br
329: are merely some number of bytes. For example,\^ a \*Mcset\fP constant
330: is loaded into the code section as a block of 32 8-bit bytes (256 bits).
331: .PP
332: Routines in \*Mlink/lcode.c\fP are used to add a unit
333: of data of one of the preceding types to the code section. These
334: routines are \*Moutop\fP,\^ \*Moutopnd\fP,\^ \*Moutword\fP,\^ and
335: \*Moutblock\fP. Each routine adds the appropriate data into
336: the code section at the current location (maintained as a pointer),\^
337: and then the location pointer is advanced to the next free location.
338: .NH 2
339: Porting Procedure
340: .PP
341: Edit \*Milink.h\fP and search for the string \*MPORT\fP. Define
342: the following constants as described.
343: .IP \*MINTSIZE\fP
344: .br
345: The number of bits in an \*Mint\fP.
346: .IP \*MLOGINTSIZE\fP
347: .br
348: The base 2 log of \*MINTSIZE\fP.
349: That is,\^ \*MLOGINTSIZE\fP answers
350: the question ``\fIWhat power of 2 is \*MINTSIZE\fR\^?''.
351: .IP \*MLONGS\fP
352: .br
353: Icon has an integer data type. On the VAX and the PDP-11 the range
354: of integer values is \-2\u\s-231\s0\d to 2\u\s-231\s0\d-1. On the VAX,\^
355: C \*Mint\fPs and \*Mlong\fPs are both 32 bits wide. On the PDP-11,\^
356: C \*Mint\fPs are 16 bits wide while \*Mlong\fPs are 32 bits wide.
357: The PDP-11 Icon system makes an internal distinction between integers
358: that ``fit'' in 16 bits and integers that require 32 bits.
359: The former are stored in two-word descriptors (the actual value being
360: in the second of the two 16-bit words),\^ while the latter have a
361: value descriptor that points to a block in the heap that holds the
362: two-word,\^ 32-bit value. On the other hand,\^ the VAX uses two 32-bit words
363: for descriptors and thus the second word of a descriptor can hold
364: the largest possible integer value used by Icon.
365: Rather than having an internal distinction between integer
366: types on the VAX,\^ integers are always represented by two-word
367: integer descriptors. There are places in the code where special
368: provisions must be made if C \*Mint\fPs are not the same size
369: as C \*Mlong\fPs.
370: .sp
371: If \*Msizeof(int) != sizeof(long)\fP for the C compiler in use,\^
372: define \*MLONGS\fP. (\*MLONGS\fP need not be given a value,\^
373: \*M#define LONGS\fP is sufficient.)
374: If \*MLONGS\fP must be defined,\^ the minimum
375: and maximum values that can be represented by an \*Mint\fP must also
376: be defined. Define \*MMINSHORT\fP to be the smallest value that an
377: \*Mint\fP can hold and define \*MMAXSHORT\fP to be the largest value that
378: an \*Mint\fP can hold.
379: .IP \*MMAXCODE\fP
380: .br
381: This is the maximum size in bytes of the code that can be generated for each
382: procedure. This value is not critical; 10,\^000 is used for the VAX,\^
383: while 2000 is used for the PDP-11.
384: .IP \*Mstrchr\fP\ and\ \*Mstrrchr\fP
385: .br
386: If you are on a USG UNIX system,\^ \*M#define\fP \*Mindex\fP to be
387: \*Mstrchr\fP and \*Mrindex\fP to be \*Mstrrchr\fP.
388: .PP
389: Edit \*Mdatatype.h\fP and
390: search for the \*MPORT\fP section. This section contains
391: \*M#define\fPs that are used to set and test flags contained in the
392: first word of descriptors. The basic idea in forming these
393: constants is to set some bits at the high end of the word,\^ and set some
394: other bits at the low end. The number of unused bits in the middle
395: depends on the size of a word.
396: .PP
397: \*MF_NQUAL\fP,\^ \*MF_VAR\fP,\^ \*MF_TVAR\fP,\^ \*MF_PTR\fP,\^ \*MF_NUM\fP,\^
398: \*MF_INT\fP,\^ and \*MF_AGGR\fP should be set to mask values with one
399: bit set to 1 in each. For \*MF_NQUAL\fP,\^ the leftmost bit should set,\^
400: for \*MF_VAR\fP,\^ the next to leftmost bit should be set,\^ and so
401: forth. The values for the VAX and PDP-11 should be suitable for
402: machines with 32-bit and 16-bit words,\^ respectively.
403: .PP
404: The constants
405: \*MOPSIZE\fP,\^ \*MOPNDSIZE\fP,\^ and \*MWORDSIZE\fP control the
406: sizes of opcodes,\^ operands,\^ and words in the code section.
407: Before setting these constants to values appropriate for the
408: target machine,\^ a ``standard'' linker should be built and tested using
409: the supplied values (under \*MPORT\fP) for these constants.
410: This allows the linker to be checked against output files that
411: are known to be correct. The purpose of this is to attempt to
412: discover C compiler problems. Compile the linker using \*Mmake\fP and
413: refer to
414: [5] for the testing procedure.
415: .PP
416: Once the ``standard'' linker has been checked out,\^ the following
417: ``sizing'' parameters in \*Milink.h\fP should be set to values
418: appropriate for the target machine.
419: .IP \*MOPSIZE\fP
420: .br
421: This is the size in bytes of interpreter opcodes. The interpreter treats
422: opcodes as unsigned quantities. One byte (8 bits) is currently
423: large enough to accommodate all opcodes and a value of 1 is recommended
424: for \*MOPSIZE\fP. The \*Moutop\fP routine in \*Mlcode.c\fP assumes that
425: opcodes are one byte. If a larger size is desired,\^ \*Moutop\fP
426: will have to be recoded. It might be wise to use a value other than
427: 1 for \*MOPSIZE\fP on machines that are not byte-addressable and have
428: ample memory.
429: .IP \*MOPNDSIZE\fP
430: .br
431: This is the size in bytes of operands for interpreter instructions.
432: For some instructions,\^ the operand value represents an offset
433: from the interpreter program counter and thus,\^ the maximum possible
434: offset is limited by the magnitude of values that can be represented
435: in \*MOPNDSIZE\fP bytes. Because larger operands occupy more code
436: space and smaller operands limit addressing ``distance'',\^ a trade-off
437: is involved. On the VAX,\^ operands are four bytes because memory
438: space is not very critical. On the PDP-11,\^ operands are two bytes
439: because of the limited memory. While it is easy to change the
440: value of \*MOPNDSIZE\fP in the linker,\^ the operand size is pervasive
441: in the interpreter. If the target machine has a large,\^ perhaps
442: virtual address space,\^ use a value such as 4 for \*MOPNDSIZE\fP. A
443: value such as 2 may be appropriate for a smaller machine. A value
444: of 1 is not advisable under any circumstances. The suggested value
445: for \*MOPNDSIZE\fP is \*Msizeof(int)\fP.
446: .IP \*MWORDSIZE\fP
447: .br
448: This should be set to \*Msizeof(int *)\fP on the target machine. The
449: various run-time data structures are all composed of a number
450: of words each of which contain \*MWORDSIZE\fP bytes. For example,\^
451: the data blocks for user-defined procedures are built in the code
452: section by a sequence of calls to \*Moutword\fP.
453: .PP
454: The \*Mbackpatch\fP routine in \*Mlcode.c\fP needs some
455: machine-specific modifications. This routine backpatches forward
456: references to ucode labels. In the \fIwhile\fP loop,\^ the operand (which is
457: \*MOPNDSIZE\fP bytes long) that is pointed at by \*Mq\fP is loaded
458: into the variable \*Mp\fP. Then,\^ the operand is replaced by the
459: value of \*Mr\fP. On the VAX,\^ this can be expressed as:
460: .Ds
461: p = *q;
462: *q = r;
463: .De
464: where \*Mq\fP is an \*Mint *\fP. This is possible because the VAX allows
465: word references on an arbitrary boundary. On the PDP-11,\^ such
466: references are illegal and the assignments must be made on a byte-wise
467: basis. If the target machine allows word accesses on arbitrary
468: boundaries,\^ the VAX code may be used (assuming \*MOPNDSIZE\fP is equal to
469: \*Msizeof(int)\fP).
470: If not,\^ but operands are the same size as \*Mint\fPs,\^
471: the PDP-11 code may be used.
472: Other situations may require ingenuity. Be sure to alter the first \*MPORT\fP
473: section in \*Mbackpatch\fP to contain an appropriate declaration for
474: \*Mq\fP (that section currently contains a declaration for \*Mq\fP and
475: a \*Mreturn\fP).
476: .PP
477: When the linker has been compiled,\^
478: refer to [5] for directions on
479: testing.
480: .nr $1 2
481: .nr $2 0
482: .NH 1
483: Porting the Icon Interpreter
484: .NH 2
485: Introduction
486: .PP
487: The Icon interpreter,\^ known as \fIiconx\fP,\^ is the third major logical
488: component of the system. The interpreter takes
489: interpretable files produced by the linker and ``executes'' them.
490: The interpreter is run by:
491: .Ds
492: iconx hello
493: .De
494: where \*Mhello\fP has been produced by the linker.
495: .PP
496: Due to the stack manipulations that the interpreter performs,\^ it is
497: necessary for a small portion of the interpreter to be written in
498: assembly language rather than in C. On the VAX,\^ about 550 lines of
499: assembly instructions are required. The coding of these assembly
500: instructions is the most difficult part of the
501: port.
502: .NH 2
503: Source File Layout
504: .LP
505: The interpreter is divided into four parts:
506: .DS
507: .ft R
508: start-up code
509: the main loop
510: primary subroutines
511: support subroutines
512: .DE
513: .LP
514: The start-up code initializes the interpreter and passes control
515: to the main loop. The main loop,\^ referred to as \*Minterp\fP,\^
516: fetches interpreter instructions
517: and executes them. An interpreter instruction may be entirely
518: performed by \*Minterp\fP or \*Minterp\fP may call a \fIprimary
519: subroutine\fP to perform the operation. In turn,\^ a primary subroutine
520: may call a number of \fIsupport subroutines\fP.
521: Each primary subroutine has a direct correspondence to a source language
522: operation of some type or to a stack manipulation.
523: .PP
524: While the translator and linker sources files are in their own
525: directories,\^ the interpreter source files are segregated into several
526: directories.
527: .nr a \w'\*Moperators\fR'+1m
528: .IP \*Miconx\fP (\na)u
529: The start-up code and the main interpreter loop reside in this
530: directory. Files of particular interest are: \*Mstart.s\fP,\^ which
531: is entered when the interpreter is run and does some low-level
532: initialization; \*Minit.c\fP,\^ which is called from \*Mstart.s\fP and
533: completes initialization of the interpreter; and \*Minterp.s\fP,\^ which
534: is the interpreter loop itself.
535: .IP \*Mfunctions\fP (\na)u
536: This directory contains code for the built-in procedures.
537: For example,\^ \*Mwrite.c\fP contains
538: the source for the \*Mwrite\fP function. The source for each
539: built-in procedure appears in a file of its own.
540: .IP \*Moperators\fP (\na)u
541: This directory contains code for the Icon operators. The routines in
542: this directory
543: implement the various Icon source level operators. For
544: example,\^ \*Mplus.c\fP is called to perform the \*M+\fP (addition)
545: operation,\^ and \*Mbang.c\fP is called to perform the \*M!\fP (element
546: generation) operation. As with the built-in procedures,\^ there is
547: one operator per file.
548: .IP \*Mlib\fP (\na)u
549: This directory contains routines that
550: do not fit anywhere else. First of all,\^ there is
551: code for routines that perform actions similar in nature to those in
552: \*Mfunctions\fP and \*Moperators\fP,\^ but that do not have a functional or
553: operator syntax. For example,\^ \*Mllist.c\fP creates a list
554: that is specified syntactically as
555: \*M\^[\*(e0,\^\*(e1,\^\*(El,\^\*(en]\fR,\^ and \*Mfield.c\fP handles record element
556: accesses that arise from \*M\*(e1.\*(e2\fR.
557: .sp .8
558: \*Mlib\fP also contains routines such as \*Mesusp.s\fP and \*Mefail.s\fP
559: that handle stack manipulations during expression evaluation. The
560: routines \*Mpret.s\fP and \*Mpfail.s\fP handle procedure return and
561: failure respectively.
562: .sp .8
563: The directories \*Mfunctions\fP,\^ \*Moperators\fP,\^ and \*Mlib\fP
564: compose the primary subroutines mentioned above.
565: .IP \*Mrt\fP (\na)u
566: The support subroutines are contained in the \*Mrt\fP directory.
567: The primary subroutines are autonomous with respect to each other and
568: use the \*Mrt\fP routines for common operations. For example,\^
569: \*Mcvstr.c\fP is used to convert a value to a string,\^ \*Mtrace.c\fP
570: produces various types of tracing messages,\^ and \*Mgc.c\fP is the
571: garbage collector.
572: .IP \*Mh\fP (\na)u
573: This directory contains a number of header files that are
574: \*M#include\fPd in the other files that compose the interpreter.
575: Of particular interest is \*Mrt.h\fP,\^ which defines a number of
576: constants and data structures.
577: .NH 2
578: Overview of the Porting Process
579: .PP
580: The following steps are to be followed when porting the interpreter.
581: .Ls
582: .Np
583: Determination of layout of procedure,\^ generator,\^ and expression
584: markers and associated frame pointers.
585: .Np
586: Setting of implementation specific constants in \*Mh/rt.h\fP and
587: creation of \*Mh/defs.s\fP from \*Mrt.h\fP.
588: .Np
589: Complete system compilation.
590: .Np
591: Coding of a ``basis'' of routines for the interpreter,\^ consisting of
592: \*Miconx/start.s\fP,\^ \*Mrt/setbound.s\fP,\^ \*Mlib/invoke.s\fP,\^
593: \*Miconx/interp.s\fP,\^ \*Mlib/efail.s\fP,\^
594: \*Mlib/pfail.s\fP.
595: .Np
596: Testing of the basis routines for the interpreter.
597: .Np
598: Coding and testing of
599: .Ds
600: rt/arith.s
601: rt/fail.s
602: lib/pret.s
603: lib/esusp.s
604: lib/lsusp.s
605: lib/psusp.s
606: rt/suspend.s
607: functions/display.c
608: .De
609: in an incremental fashion. Test programs are provided
610: to test the system after adding each routine.
611: .Np
612: Coding of \*Mrt/gcollect.s\fP and \*Mrt/sweep.c\fP.
613: Testing of garbage collection.
614: .Np
615: Complete system testing.
616: .Le
617: .PP
618: This document does not explain how to port the sections of the system
619: that are related to co-expressions. The involved files are
620: \*Mlib/coact.s\fP,\^ \*Mlib/cofail.s\fP,\^ \*Mlib/coret.s\fP,\^
621: \*Mlib/create.c\fP,\^ and \*Moperators/refresh.c\fP. Icon
622: works properly with these sections of code left unimplemented,\^
623: provided no attempt is made to use co-expressions,\^ in which case
624: the system notes it as a fatal error.
625: .NH 2
626: Porting Procedure
627: .SH
628: Determination of Frame Layouts
629: .PP
630: Unfortunately,\^ one of the most far-reaching decisions that must be
631: made during the porting process is also one of the first decisions
632: that must be made. The decision (actually,\^ a number of decisions) is
633: how to layout the procedure,\^ generator,\^ and
634: expression frames and what registers should be used as frame
635: pointers. The various frames and their usages are explained in
636: detail in \^[1] and the portions of this document that describe
637: routines that manipulate a particular frame also provide further
638: explanations. The porter should have a good
639: understanding of what the frames are used for before setting frame
640: layouts as they are pervasive throughout the assembly language
641: portions of the system.
642: .PP
643: This document is rather tightly bound to the VAX implementation of
644: Icon. Because of this,\^ the stack model that is used is that
645: of the VAX. Specifically,\^ the VAX stack starts in high memory and
646: grows downward. Thus,\^ when something is pushed on the stack,\^ the
647: stack pointer goes down. When something is removed,\^ the stack pointer
648: goes up.
649: The only time that this convention is departed from is in the use of
650: the phrase ``the top of the stack''. The top of the stack is the
651: stack word that has the \fIlowest\fP memory address.
652: .PP
653: The procedure frame layout is the first to be determined. The layout
654: is somewhat fixed by the C compiler and target machine,\^
655: so the task is a combination
656: of making a decision and also recognizing what has been pre-determined.
657: On most machines,\^ the
658: task of the porter is more one of recognition than of design.
659: .PP
660: The first thing to determine is the
661: frame layout imposed by the target machine and the C compiler.
662: Create a file containing the following
663: .Ds
664: f()
665: {
666: x(1,\^2);
667: }
668: .De
669: Compile the file using \fIcc\fP
670: in such a manner as to catch the assembly code that is
671: generated in a file. The \*M\-S\fP option of \fIcc\fP should cause
672: assembly code to be placed in a file. On the VAX,\^ the code
673: generated by \*Mx(1,\^2)\fP is
674: .Ds
675: .ta .7i
676: pushl $2
677: pushl $1
678: calls $2,\^_x
679: .De
680: From this it can be seen that arguments are pushed on the stack
681: using the \*Mpushl\fP instruction,\^ and that the \*Mcalls\fP
682: instruction does the actual procedure call. The first argument
683: to \*Mcalls\fP is the number of arguments that are on the stack.
684: When a return is made from a procedure called with a \*Mcalls\fP
685: instruction,\^ the arguments are removed from the stack by the return
686: mechanism. On some machines,\^ the removal of arguments after a subroutine
687: call is left to the programmer (or code generator,\^ in this case).
688: This is usually done by adding a value to the stack pointer or
689: incrementing the stack pointer several times.
690: .PP
691: Examine the assembly code produced on the target machine by the
692: given C statements. Determine what actions are taken by the machine
693: when the appropriate call instruction is performed. It is important
694: to completely and totally understand what the target machine does
695: when a call is performed.
696: Next,\^ determine what sort of procedure frame is used by C routines.
697: Compile the following C function using \*M\-S\fP.
698: .Ds
699: .ta .7i
700: f(a,\^b,\^c)
701: int a; char b; char *c;
702: {
703: int x,\^y;
704:
705: x = a;
706: a = 1;
707: y = 2;
708: }
709: .De
710: Look at the generated
711: code and try to get a feel for what is going on. The things that
712: need to be determined are:
713: .Ds
714: .ft R
715: how arguments are accessed
716: the format of the C call frame
717: register saving and restoring conventions
718: .De
719: For example,\^ on the VAX,\^ the following code is generated
720: for the test procedure.
721: .Ds
722: .Pt
723: .word L12 register save mask,\^ filled in later
724: jbr L14 jump to end to make stack space
725: L15:
726: movl 4(ap),\^-4(fp) x = a
727: movl $1,\^4(ap) a = 1
728: movl $2,\^-8(fp) y = 2
729: ret return
730: .set L12,\^0x0 set register mask
731: L14:
732: subl2 $8,\^sp make room for two local variables
733: of four bytes each
734: jbr L15 jump to start of routine
735: .De
736: Several inferences can be made. First of all,\^ arguments are accessed
737: relative to \*Map\fP,\^ the argument pointer. Secondly,\^ local variables
738: are accessed relative to \*Mfp\fP,\^ the frame pointer. On the VAX,\^
739: because of the hardware register save and restoration based on the
740: entry mask (the first word of the routine),\^ no subroutine calls are
741: required to save registers.
742: .PP
743: The Icon procedure frame must have the following attributes:
744: .Ls
745: .Np
746: The values on the stack at the time of call to the procedure appear
747: as arguments to the procedure. Furthermore,\^ the values must be
748: accessible in a deterministic fashion.
749: .Np
750: Register values are saved in the frame and can be accessed deterministically.
751: .Np
752: \*M_line\fP and \*M_file\fP appear in the procedure frame just below
753: the last word pushed on the stack as part of the C procedure calling
754: protocol.
755: .Np
756: The region for local variables begins at the lower end of the
757: ``constant'' portion of the frame. Local variables must be
758: be accessible via deterministic means.
759: .Np
760: The procedure frame created by a C procedure call must be a subset
761: of the procedure frame selected. That is,\^ the Icon procedure frame
762: must be an augmentation of the C procedure frame.
763: .Le
764: .LP
765: The VAX uses this procedure frame layout:
766: .Ds
767: .St
768: .ft R
769: arguments
770: 4 number of arguments (\*Mnargs\fR)
771: \*Map\fR \*(ar 0 number of words in argument list (\*Mnwords\fR)
772: saved \*Mr11\fR (\*Mefp\fR)
773: saved \*Mr10\fR (\*Mgfp\fR)
774: \*(El
775: last saved register
776: 16 saved \*Mpc\fR
777: 12 saved \*Mfp\fR
778: 8 saved \*Map\fR
779: 4 program status word and register mask
780: \*Mfp\fR \*(ar 0 0 (condition handler address)
781: -4 saved value of \*M_line\fR
782: -8 saved value of \*M_file\fR
783: \*Msp\fR \*(ar Icon local variables
784: .De
785: .PP
786: Actually,\^ on the VAX,\^ most of the decisions are predetermined by
787: the VAX architecture. The arguments are present on the stack,\^ so they
788: are the high end of the frame. The registers are saved on the stack
789: by the \*Mcalls\fP instruction. The values of \*M_line\fP and \*M_file\fP
790: naturally fit after the saved registers. The locals then appear on
791: the lower end and extend for a variable distance (on a per-procedure
792: basis). Note that the first local is at \*M\-16(fp)\fP and the \fIlast\fP
793: argument is at \*M8(ap)\fP.
794: .PP
795: The VAX hardware takes care of saving and restoring registers upon
796: subroutine entry and exit. It is quite possible that the target
797: machine will not have this capability and the task must be delegated
798: to software. This is usually evidenced by a call to a routine with a
799: name such as \*Mcsave\fP as the very first thing in the routine and a
800: call to a routine with a name such as \*Mcrestore\fP at the end of a
801: routine. If this is the case,\^ the actions of
802: the saving and restoring routines must be taken into account when determining
803: the procedure frame layout.
804: .PP
805: In addition to determining the procedure frame layout,\^ a procedure
806: frame pointer must also be selected. On the VAX,\^
807: the \*Mfp\fP stays constant throughout execution of a C procedure;
808: it is used as the procedure frame pointer. For the target machine,\^
809: there should be some register on which references to local variables
810: (and perhaps parameters) are based. That register should be used
811: as the procedure frame pointer (sometimes referred to as the
812: \*Mpfp\fP).
813: The \*Mpfp\fP need not point at the lowest word pushed on the stack
814: as part of the procedure call; it only needs to be constant while
815: a procedure is executing. Of course,\^ the \*Mpfp\fP changes while the
816: program is executing; by ``pointing at'' a particular word,\^ it is
817: meant that the \*Mpfp\fP always references a certain word in the
818: procedure frame marker. An \*Mrt.h\fP constant,\^ \*MFRAMELIMIT\fP,\^ is
819: dependent on the number of words between the lowest word of the
820: procedure marker and the word that the \*Mpfp\fP points to. Setting
821: \*MFRAMELIMIT\fP is described below.
822: .PP
823: A point about terminology should be stressed. The procedure frame marker is
824: bounded by arguments on one end and the Icon local variables on the other.
825: A procedure marker,\^ the arguments,\^ the Icon
826: local variables,\^ and the stack below
827: the local variables compose a procedure frame.
828: .\"\^[Note in here about variable size of marker,\^ forced saving of efp,\^ gfp.,\^
829: .\"ap being needed]
830: .PP
831: Determining the procedure frame layout
832: is by no means a deterministic process. It takes work,\^ but once
833: it's successfully set,\^ the single hardest task of the port is complete.
834: .PP
835: Once the procedure frame has been set,\^ the generator frame layout follows
836: rather easily. A generator frame is merely an augmented procedure
837: frame. The generator frame has two additional pieces of information,\^
838: a saved value of \*M_k_level\fP,\^ and a saved value for the boundary.
839: It is recommended that the generator frame
840: be identical to a procedure frame except that the two extra words
841: required be located between the lowest word that is pushed on the
842: stack by the procedure call mechanism and the saved value of \*M_line\fP.
843: Thus,\^ on the VAX,\^ the generator frame \fImarker\fP is
844: .Ds
845: .ft R
846: .St
847: saved \*Mr11\fR
848: saved \*Mr10\fR
849: \*(El
850: last saved register
851: 20 reactivation address
852: 16 saved \*Mfp\fR
853: 12 saved \*Map\fR
854: 8 program status word and register mask
855: 4 0 (condition handler address)
856: \*Mgfp\fR \*(ar 0 saved value of the boundary
857: -4 saved value of \*M_k_level\fR
858: -8 saved value of \*M_line\fR
859: -12 saved value of \*M_file\fR
860: .De
861: Note that instead of a saved \*Mpc\fR value,\^ the generator frame marker
862: holds a reactivation address. Control passes to this address when
863: the generator is reactivated. Reactivation is fully explained in
864: later sections.
865: .PP
866: A generator frame pointer (\*Mgfp\fP) is associated with a generator
867: frame. On the VAX,\^ \*Mr10\fP is the \*Mgfp\fP. The choice of a \*Mgfp\fP
868: is indirectly determined by the machine architecture and is
869: intertwined with the selection of an expression frame pointer.
870: The selection of the register to use as the \*Mgfp\fP is discussed below.
871: It is recommended that the \*Mgfp\fP point
872: at the word containing the saved boundary value.
873: .PP
874: The third type of frame marker is the expression frame marker.
875: Expression frame markers are totally machine independent and contain
876: three pieces of information: a saved expression marker address,\^
877: a saved generator marker address,\^ and a failure label that is to
878: be given control in certain circumstances. On the VAX,\^ the
879: expression marker layout is
880: .Ds
881: .ft R
882: .St
883: \*Mefp\fR \*(ar 0 saved \*Mefp\fR value
884: -4 saved \*Mgfp\fR value
885: -8 failure address
886: .De
887: This same format should be used on the target machine and there is no
888: apparent reason for needing an alternative format. The expression
889: frame pointer (\*Mefp\fP) should point at the high word of the
890: expression marker.
891: .PP
892: The registers that should be used for the \*Mgfp\fP and \*Mefp\fP are
893: indirectly dependent on the procedure call mechanism. The primary
894: requirement for the registers used as the \*Mefp\fP and \*Mgfp\fP is that
895: they are saved across procedure calls. The secondary requirement is
896: that the \*Mgfp\fP and \*Mefp\fP always be saved in a procedure frame.
897: If the target machine has two general purpose registers that are
898: always saved in a procedure frame,\^ those two registers are quite
899: suitable for the \*Mgfp\fP and \*Mefp\fP.
900: .PP
901: If the procedure call mechanism does not always save a pair of general
902: purpose registers,\^ the problem is more complicated.
903: There are stack manipulations that are performed that
904: \fIrequire\fP saved values of \*Mefp\fP and \*Mgfp\fP to be present
905: in procedure and generator frames.
906: For built-in procedures and Icon procedures
907: this is no problem because \*Minvoke\fP creates the procedure frame
908: for them and can insure that the registers are saved. On the VAX,\^ for the C
909: routines that are directly called from \*Minterp\fP,\^ no such
910: assurances can be made because the VAX C compiler directs
911: only the registers used in a routine to be saved in the C procedure
912: frame. This creates a problem because Icon counts on the registers
913: being saved. The problem is countered by making the C compiler think
914: that certain registers are used in certain routines. Specifically,\^
915: declarations for a pair of \*Mregister int\fP variables are placed at
916: the start of appropriate routines. On the VAX,\^ the first two local
917: variables declared in a C routine \fIalways\fP get allocated to \*Mr10\fP and
918: \*Mr11\fP. Thus,\^ \*Mr10\fP and \*Mr11\fP are used for the \*Mgfp\fP
919: and the \*Mefp\fP respectively. If the target machine is like
920: the VAX in that it doesn't always save certain registers,\^ a similar
921: tactic may need to be used. If this is the case,\^ try compiling a
922: routine with a pair of \*Mregister int\fP variables declared and see
923: what the compiler does. If the compiler saves the two registers
924: assigned to the variables,\^ use those registers for the \*Mgfp\fP and
925: the \*Mefp\fP. It is wise to attempt to be sure that the compiler is
926: deterministic in making its choice of registers to allocate to the
927: variables. Routines that require this ruse to be employed have a line
928: containing the string \*MDclSave\fP as the first line of the
929: declarations. \*MDclSave\fP is defined in \*Mrt.h\fP and should be
930: set to an appropriate value. It may be the case that no registers
931: need to be saved. If so,\^ define \*MDclSave\fP,\^ but specify no value.
932: This is done for the PDP-11.
933: .PP
934: It is also necessary to select a register to use as the interpreter
935: program counter (\*Mipc\fP). Any general register that is preserved
936: across procedure calls is suitable. The VAX uses \*Mr9\fP for
937: the \*Mipc\fP.
938: .NH 2
939: Machine and System Specific Values
940: .PP
941: Edit \*Mh/rt.h\fP and search for the first \*MPORT\fP section.
942: Define the various constant values as outlined below.
943: .IP \*MMAXHEAPSIZE\fP
944: .br
945: The size of the heap storage region in bytes. The VAX uses 50k and
946: the PDP-11 uses 10k. If you have a small machine,\^ use 10k. Larger
947: machines should use larger values,\^ such as that for VAX.
948: .IP \*MMAXSTRSPACE\fP
949: .br
950: The size of the string storage region in bytes. As with
951: \*MMAXHEAPSIZE\fP,\^ this value is somewhat arbitrary. A value similar
952: to that used for the heap size should be used.
953: .IP \*MSTACKSIZE\fP
954: .br
955: The size of co-expression stacks in words. Use 1000 for smaller
956: machines,\^ 2000 for larger ones.
957: .IP \*MMAXSTACKS\fP
958: .br
959: The number of co-expression stacks initially allocated. Use 2 for
960: smaller machines,\^ 4 for larger ones.
961: .IP \*MNUMBUF\fP
962: .br
963: The number of i/o buffers available. When a file is opened,\^ a buffer
964: is assigned to the file if one is available. A value from 5 to
965: 10 is recommended.
966: .IP \*MINTSIZE\fP
967: .IP \*MLOGINTSIZE\fP
968: .IP \*MLONGS\fP
969: .IP \*MMINSHORT\fP
970: .IP \*MMAXSHORT\fP
971: .br
972: These constants must be set to the values they were given (if any) in
973: \*Mlink/ilink.h\fP.
974: .IP \*MMINLONG\fP
975: .br
976: The smallest value that can be represented in a \*Mlong\fP.
977: .IP \*MMAXLONG\fP
978: .br
979: The largest value that can be represented in a \*Mlong\fP.
980: .IP \*MLGHUGE\fP
981: .br
982: The highest base-10 exponent plus 1 representable by a \*Mfloat\fP.
983: For example,\^ on the VAX,\^ the highest number representable by a \*Mfloat\fP
984: is about 1.7x10\u38\d. Thus,\^ \*MLGHUGE\fP is 39 on the VAX.
985: .IP \*MFRAMELIMIT\fP
986: .br
987: As discussed above,\^ set \*MFRAMELIMIT\fP to the number of words
988: between the low word of the procedure frame marker and the word that
989: the procedure frame pointer references.
990: .IP \*MSTKBASE\fP
991: .br
992: This value represents the approximate base of the stack when
993: execution begins. On machines such as the VAX,\^ where the stack grows
994: down from high memory,\^ \*MSTKBASE\fP should have a high value,\^ where
995: on machines where the stack grows up from low memory,\^ \*MSTKBASE\fP
996: should have a low value. The \fIman\fP page for \fIexec(2)\fP usually
997: specifies the initial value for the stack pointer when program
998: execution begins. If uncertain,\^ be extreme with the value.
999: .IP \*MGRANSIZE\fP
1000: .br
1001: The granularity of memory allocations. Calls to \fIbrk(2)\fP are
1002: used to expand the main memory that is being used. When \fIbrk\fP
1003: is given an address to expand to,\^ it rounds it to a multiple of
1004: a certain number. That number should be used for \*MGRANSIZE\fP.
1005: The \fIman\fP page for \fIbrk(2)\fP should state what value is used
1006: on a particular system.
1007: .IP \*MDclSave\fP
1008: .br
1009: Give \*MDclSave\fP the value needed as previously described.
1010: .IP \*MEntryPoint(x)\fP
1011: .br
1012: \*MEntryPoint\fP is a macro that is used to yield the address of the
1013: first instruction of the C routine \*Mx\fP that is past any procedure
1014: entry protocol instructions. On the VAX,\^ the register mask is two
1015: bytes long and thus the first executable instruction of a routine \*Mx\fP
1016: is at \*M(char *)x + 2\fP. On the PDP-11,\^ there is a four-byte instruction
1017: at the start of each routine that calls the routine \*Mcsv\fP to
1018: save registers and establish the procedure frame. Thus for the
1019: PDP-11,\^ \*MEntryPoint(x)\fP is \*M(char *)x + 4\fP. Values calculated
1020: by \*MEntryPoint\fP are used in \*Minvoke\fP.
1021: .IP \*MDummyFcn(name)\fP
1022: .br
1023: Initially,\^ each of the assembly language
1024: portions of the system that must be filled in
1025: consist of a single line of the form \*MDummyFcn(name)\fP.
1026: \*MDummyFcn\fP should be defined to generate \fIassembly\fP language
1027: statements that
1028: form a dummy routine with the label \*Mname\fP. This can be as
1029: simple as a label and a global declaration. It is advisable to include
1030: as part of the definition something that will cause a program abort.
1031: A halt instruction usually does the job. Thus,\^ the system can be
1032: built and will function normally unless an incomplete routine is
1033: called.
1034: .IP \*MDummyDcl(x)\fP
1035: .br
1036: A macro that should expand into an assembly language declaration that
1037: allocates a word of storage for a variable named \*Mx\fP.
1038: .IP \*MDummyRef(x)\fP
1039: .br
1040: A macro that should expand into an assembly language reference to the
1041: variable \*Mx\fP.
1042: .IP \*MGlobal(x)\fP
1043: .br
1044: A macro that should expand into an assembly language
1045: declaration of \*Mx\fP as a global symbol.
1046: .IP \*Mfp\fP,\^\ \*Mefp\fP,\^\ \*Mgfp\fP,\^\ \*Mipc\fP
1047: .br
1048: It is advisable to use \*M#define\fPs for these registers rather than
1049: explicitly name them in the code.
1050: .IP \*Mcset_display\fP
1051: .br
1052: This is a rather complicated macro that is used to initialize the
1053: values of \*Mcset\fPs such as \*M&cset\fP and \*M&lcase\fP. If the
1054: target machine has \*Mint\fPs with 32 or 16 bits,\^ then the VAX or
1055: PDP-11 definition (respectively) of \*Mcset_display\fP may be used.
1056: If this is not the case,\^ \*Mcset_display\fP will have to be
1057: hand-crafted and the various uses of it will have to be altered for
1058: the machine in question. Briefly,\^ a \*Mcset_display\fP specifies
1059: which of the 256 bits that comprise a cset are to be set to 1.
1060: For example,\^ the \*Mcset_display\fP for \*M&cset\fP has all the bits
1061: set to 1,\^ while \*M&ascii\fP has the first 128 bits set to 1.
1062: \*Mcset\fPs are accessed using the \*Msetb\fP and \*Mtstb\fP macros
1063: which are also defined in \*Mrt.h\fP.
1064: \*Mcset_display\fPs appear in \*Miconx/init.c\fP,\^
1065: \*Mfunctions/bal.c\fP,\^ and \*Mfunctions/trim.c\fP. It may also be
1066: necessary to modify the definitions of \*MCSETSIZE\fP,\^ \*Msetb\fP,\^
1067: and \*Mtstb\fP.
1068: .PP
1069: Search for the second \*MPORT\fP section.
1070: \*MF_NQUAL\fP,\^ \*MF_VAR\fP,\^ \*MF_TVAR\fP,\^ \*MF_PTR\fP,\^ \*MF_NUM\fP,\^
1071: \*MF_INT\fP,\^ and \*MF_AGGR\fP should be given the
1072: same values they have in \*Mlink/datatype.h\fP.
1073: .PP
1074: Once \*Mrt.h\fP has been completed,\^ an analogous file,\^ \*Mh/defs.s\fP
1075: must tailored. \*Mdefs.s\fP is a subset of \*Mrt.h\fP that is
1076: included in assembly language files. The \*MPORT\fP section of \*Mdefs.s\fP
1077: lists a number of constants that must be defined. Use the appropriate
1078: values from \*Mrt.h\fP for each constant. If all assemblers used a
1079: default radix of 10 for constants,\^ it would be possible to tailor
1080: \*Mdefs.s\fP mechanically,\^ but since this is not the case,\^
1081: \*Mdefs.s\fP must be modified by hand.
1082: .NH 2
1083: Complete System Compilation
1084: .PP
1085: In order to determine if there are serious C compiler problems with
1086: the interpreter source,\^ the entire system should be made at this
1087: point. Do a
1088: .Ds
1089: make Icon
1090: .De
1091: in the root directory of the Icon distribution.
1092: The entire
1093: system should compile without any problems. The resulting
1094: interpreter will be completely disfunctional,\^ but if it is built without
1095: any problems,\^ it provides further evidence that the C compiler is
1096: up to the task.
1097: .NH 2
1098: Porting the Assembly Language Routines
1099: .PP
1100: The porting of the assembly language routines is the most difficult part of
1101: porting Icon. This document has a section for each assembly language routine
1102: and each routine is described in three ways:
1103: .Ds
1104: .ft R
1105: overview
1106: generic operation
1107: the routine on the VAX
1108: .De
1109: .PP
1110: The overview section briefly describes the action of the routine
1111: and how the routine may be encountered during the course of execution.
1112: The generic operation section tells what steps the routine
1113: takes to perform its given task. Each major step that the routine takes
1114: is described. These steps should be very similar from machine to
1115: machine.
1116: The section about the routine on the VAX details the
1117: operation of the routine on the VAX. This section complements
1118: the comments contained in the source code for the routine and should
1119: be read with the source code at hand.
1120: This section is very machine specific. (Ideally there would be one
1121: such section for each existing Icon implementation.)
1122: .PP
1123: Each routine must be formulated for the target machine. For the most
1124: part,\^ the best approach is to take the same steps that are
1125: taken on the VAX. It is important to select the right level for
1126: modeling the VAX routines. Try to recognize the steps that are
1127: made rather than following the operations on a per-instruction basis.
1128: The most important thing is to have a good understanding of what actions
1129: are performed and how these can be done on the target machine.
1130: .PP
1131: The first goal is to get a very simple Icon program working. This
1132: first program is \*Mtest/hello.icn\fP. It is quite short:
1133: .Ds
1134: procedure main()
1135: write("hello world")
1136: end
1137: .De
1138: The basis of routines mentioned above
1139: (\*Mstart.s\fP,\^ \*Msetbound.s\fP,\^ \*Minvoke.s\fP,\^ \*Minterp.s\fP,\^
1140: \*Mefail.s\fP,\^ and \*Mpfail.s\fP)
1141: must be implemented for even a very simple Icon program to work.
1142: However,\^ all these
1143: routines do not need to be written to make \*Mhello\fP \fIbegin\fP to work.
1144: .PP
1145: Translate and link \*Mhello\fP by running the translator and the
1146: linker:
1147: .Ds
1148: tran/itran hello.icn
1149: link/ilink hello.u1
1150: .De
1151: This creates an interpretable file named \*Mhello\fP. Just to
1152: get the feel of things,\^ run the interpreter on the file:
1153: .Ds
1154: iconx/iconx hello
1155: .De
1156: A message of some type and a core dump should be produced.
1157: .PP
1158: The files \*Mtran/itran\fP,\^ \*Mlink/ilink\fP,\^ and \*Miconx/iconx\fP,\^
1159: are copied into the \*Mbin\fP directory as the last action of
1160: .Ds
1161: make Icon
1162: .De
1163: in the root directory.
1164: The porter may find it convenient to link
1165: these files to the \*Mbin\fP directory and then place the full pathname
1166: in his search path. It is necessary to
1167: remove \*Mitran\fP,\^ \*Milink\fP,\^ and \*Miconx\fP in the \*Mbin\fP
1168: directory before linking them. Also,\^ if the files are linked,\^ the last
1169: step of \fImake\fP in the root directory will fail. This failure is
1170: inconsequential.
1171: .PP
1172: As \*Mstart.s\fP et al. are written,\^ try stepping through them to be
1173: sure the correct actions are being performed. Most of the assembly
1174: language source
1175: files are straight line code with a branch or two and it is possible to
1176: do a large amount of verification of the assembly code by single stepping
1177: through it with a debugger.
1178: .PP
1179: When a routine has been completed,\^ it may be added to the interpreter
1180: by doing a \fImake\fP in the directory containing the routine and
1181: then doing another \fImake\fP in the directory \*Miconx\fP.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.