![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tr83-10b.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-10b.roff CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / icon / docs |
1.1 root 1: .de Ip
2: .IP \\$1
3: .br
4: ..
5: .nr $1 3
6: .nr $2 7
7: .nr $3 0
8: .NH 3
9: \*Miconx/start.s\fR
10: .SH
11: Overview
12: .PP
13: The routine \*Mmstart\fP in \*Mstart.s\fP is used to get Icon started.
14: When the Icon interpreter is executed,\^ the C routine \*Mmain\fP passes
15: control to \*Mmstart\fP,\^ and merely serves as a front-end for \*Mmstart\fP.
16: .SH
17: Generic Operation
18: .Ls
19: .Np
20: Call the routine \*Minit\fR with the name of the
21: file to interpret as its argument.
22: .Np
23: Make an Icon list out of the command line arguments using
24: the \*Mllist\fR function.
25: .Np
26: Invoke the main procedure of the Icon program.
27: .Le
28: .SH
29: \*Mstart\fP on the VAX
30: .PP
31: There is a short main program in \*Miconx/main.c\fP that calls \*Mmstart\fP
32: with two arguments:
33: .Ds
34: .S1
35: main(argc, argv)
36: int argc;
37: char **argv;
38: {
39: mstart(argc, argv);
40: }
41: .De
42: .PP
43: The number of command line arguments is in \*Margc\fP, and \*Margv\fP is a
44: pointer to an array of pointers to strings representing the arguments.
45: \*Margv\^[0]\fP is the command used to invoke the interpreter and \*Margv\^[1]\fP
46: is the name of the file being interpreted. Additional command line arguments
47: are passed along to the main procedure of the Icon program. When
48: \*Mmstart\fP gets control, \*M4(ap)\fP is the \*Margc\fP value and
49: \*M8(ap)\fP is the argv value.
50: .PP
51: The first action taken by \*Mmstart\fP is to call \*Minit\fR to initialize the
52: Icon run-time system. \*Minit\fR loads the header and code portions of
53: the interpretable file into memory,\^ so \*Minit\fR needs the
54: name of the interpretable file. The word at \*M8(ap)\fP is loaded into
55: \*Mr9\fP, pointing it at \*Margv\^[0]\fP. Then the name of the file to interpret
56: (\*Margv\^[1]\fP), residing at \*M4(r9)\fP, is pushed on the stack as the
57: argument for \*Minit\fP, which is then called.
58: .PP
59: In order to provide conformity with the usual execution environment
60: of Icon procedures,\^ an expression frame is created for the execution
61: of the main procedure. Both the old expression frame pointer and the
62: old generator frame pointer are set to be 0 in the expression frame
63: for \*Mmain\fP. The failure label must point to an interpreter opcode that
64: will terminate execution of the program. The opcode 0 is used
65: for this purpose. A word of storage,\^ \*Mflab\fR,\^ is declared and
66: initialized to 0. The failure label points to \*Mflab\fR. Thus,\^ if
67: \*Mmain\fP fails,\^ the interpreter executes the \*Mquit\fR opcode.
68: .PP
69: The next task is to push the descriptor for the procedure main
70: on the stack for later use by \*Minvoke\fR. The variable
71: \*M_globals\fR contains the address of the list of global variable
72: descriptors.
73: The first global variable descriptor is always the one for the
74: procedure main; if no main procedure was found when the program
75: was linked,\^ the descriptor
76: will be \*M&null\fR. The value of \*M_globals\fR is loaded into
77: \*Mr0\fR and the word then referenced by \*Mr0\fR is checked to see if it
78: is equal to \*MD_PROC\fR. (The first word of a descriptor for a procedure
79: is always equal to \*MD_PROC\fR.)
80: .\"\^[? not sure if we really need to check for D_PROC,\^
81: .\"I think just checking for ~= 0 will suffice.]
82: If the word is not equal
83: to \*MD_PROC\fR,\^ a branch is made to \*Mnomain\fR which generates
84: the appropriate run-time error. Otherwise,\^ the descriptor
85: for \*Mmain\fP is pushed onto the stack. (The effect of the instruction
86: \*Mmovq\ (r0),\^\-(sp)\fR
87: is to move 8 bytes (the size of a quadword)
88: starting at the address referenced by \*Mr0\fR to the
89: 8 bytes referenced by the \*Msp\fR after subtracting 8 from the
90: \*Msp\fR.)
91: .PP
92: The main procedure is to be invoked with a list consisting of the command
93: line arguments (if any). The Icon run-time routine \*Mllist\fR is used to
94: make the list that is passed to the main procedure. \*Mllist\fR stores
95: the descriptor for the list that it creates in the descriptor above its
96: first argument descriptor,\^ so to accommodate the result,\^ a null descriptor
97: is pushed on the stack using the \*Mclrq\fR instruction. Note that
98: because \*Mllist\fP calls \*Msetbound\fP and \*Mclrbound\fP,\^ it is not
99: possible to execute all of \*Mstart\fP until \*Mrt/setbound.s\fP has been
100: completed.
101: .PP
102: At the beginning of this routine,\^ \*Mr9\fR was set to point
103: at the first word of the argument list.
104: Neither the name of the Icon interpreter nor the name of the interpretable
105: file is desired in the argument list passed to main,\^ so \*Mr9\fR is
106: twice incremented by 4 (the size in bytes of a word)
107: to point it at the first actual program argument.
108: .PP
109: The next step is to construct the argument list for \*Mllist\fR. For
110: each command line argument,\^ the address of the string and then its
111: length are pushed on the stack. The length and address pairs form
112: descriptors that \*Mllist\fP makes an Icon list from.
113: \*Mr8\fR is used to count the arguments.
114: After the addresses and lengths of each argument have been pushed,\^ the
115: number of arguments is pushed on the stack.
116: At this point,\^ the stack looks like this:
117: .Ds
118: .ft R
119: .S1
120: descriptor for main procedure (2 4-byte words)
121: a null descriptor (2 words containing 0)
122: address of first argument to Icon program
123: length of first argument
124: \*(El
125: address of last argument to Icon program
126: length of last argument
127: \*Msp\fR \*(ar number of arguments
128: .De
129: .LP
130: All addresses and lengths are one word in size. The \*Mcalls\fR
131: instruction needs to be told how many words are in its argument list.
132: (This is necessary because when a return is made from the subroutine,\^
133: the specified number of words are removed from the stack.) There
134: are two words for each argument and an additional word for the number
135: of arguments. (Do not confuse the argument count for the \*Mllist\fR
136: subroutine and the argument list size.)
137: \*Mr8*2+1\fP is calculated in \*Mr8\fP. This value is used
138: as the argument list length for the \*Mcalls\fR instruction.
139: When \*Mllist\fR returns,\^ the arguments are stripped from the
140: stack and the stack looks like this:
141: .Ds
142: .ft R
143: .S1
144: descriptor for main procedure
145: \*Msp\fR \*(ar descriptor for list of command line arguments
146: .De
147: .LP
148: Note that the null descriptor pushed earlier received the result of
149: the \*Mllist\fR function.
150: .PP
151: At this point,\^ the main procedure is ready to be invoked. The descriptor for
152: the main procedure is \*(a0 and the descriptor for the list of
153: command line arguments is \*(a1. Before invoking the main procedure,\^
154: the procedure frame pointer and the generator frame pointer are cleared.
155: The main procedure is being invoked with one argument,\^ so a constant
156: 1 is pushed on the stack. The \*Mcalls\fR instruction is given an
157: argument of 3 because a word is used for the number of arguments and
158: two additional words are used for the descriptor for the list of command
159: line arguments.
160: .PP
161: If the main procedure fails,\^ the interpreter will encounter the
162: 0 opcode discussed earlier. If the main procedure returns (this
163: usually isn't done),\^ the return will manifest itself as \f3invoke\fR
164: returning. If this happens,\^ \*M_c_exit\fR is called with an
165: argument of 0. Incidentally,\^ this also happens when the interpreter
166: hits the 0 opcode.
167: .PP
168: There is a block of code labeled \*Mnomain\fR that is executed when
169: no main procedure is found. This calls the routine \*Mrunerr\fR to
170: produce an error message. The actual call made is \*Mrunerr(117,\^0)\fR.
171: The number 117 is looked up in a table of run-time errors. If the second
172: argument to \*Mrunerr\fR is non-zero,\^ it is interpreted as being the
173: address of a descriptor and the descriptor is examined to produce
174: an ``offending value'' to accompany the run-time error.
175: .PP
176: The last portion of executable code in \f3start.s\fR is the subroutine
177: \*M_c_exit\fR. If the variable \*M_monres\fR is non-zero,\^ it indicates
178: that profiling is on,\^ and it must be turned off. This is accomplished
179: by calling \*M_monitor(0)\fR. The routine \*M__cleanup\fR is then
180: called to shut down the i/o system. Finally,\^ \*M_exit\fR is called
181: with the argument of \*M_c_exit\fR to terminate execution of the
182: Icon interpreter.
183: .PP
184: There are several data declarations in \*Mstart.s\fR. The first data
185: declaration is a \*M.space 60\fR. This is an accommodation for the
186: garbage collector. It
187: insures that enough of the start of the data section
188: is used up to force the addresses of other data objects to be
189: greater than the defined constant \*MMAXTYPE\fR in \f3h/rt.h\fR.
190: .PP
191: Some assorted declarations are next. \*Mflab\fR is referenced
192: by the interpreter if the main procedure fails. It must be at
193: least a byte long and contain a 0. \*M_boundary\fR must be a
194: word long and contain a 0. \*M_environ\fR must be a word long;
195: its contents are unimportant as it is written into at the beginning
196: of \*Mstart.s\fR.
197: .PP
198: The \*M_tended\fR array is also used in conjunction with garbage
199: collection. It must declare space for five descriptors (two words
200: per descriptor) that are initialized to 0.
201: .\"\^[?]
202: The label \*M_etended\fR
203: is used to mark the end of the \*M_tended\fR array.
204: .ne 1i
205: .NH 3
206: \*Mrt/setbound.s\fR
207: .SH
208: Overview
209: .PP
210: \*Msetbound.s\fP contains code for \*Msetbound\fP and \*Mclrbound\fP.
211: \*Msetbound\fP sets \*M_boundary\fP under appropriate conditions and
212: \*Mclrbound\fP clears \*M_boundary\fP under appropriate conditions.
213: .SH
214: Generic Operation
215: .PP
216: When a call is made from Icon into C,\^ \*M_boundary\fP must be set to point
217: at the procedure frame on the top of the stack. C routines that can
218: be called from Icon have a call to \*Msetbound\fP as their first
219: operation. If \*Msetbound\fP is called and \*M_boundary\fP is not
220: set,\^ that is,\^ \*M_boundary\fP has a value of zero,\^ \*Mboundary\fP is
221: set to value of the \*Mfp\fP of the calling procedure.
222: .PP
223: When a C routine returns to Icon,\^ \*M_boundary\fP must be cleared.
224: If \*M_boundary\fP has the same value as \*Mfp\fP,\^ the routine was
225: called from Icon and thus when it returns,\^ it returns to Icon.
226: At appropriate return points in routines,\^ a call to \*Mclrbound\fP is
227: made. If the return takes control back to Icon,\^ \*M_boundary\fP
228: is cleared.
229: .SH
230: \*Msetbound\fP on the VAX
231: .PP
232: The value of \*M_boundary\fP is tested. If \*Mboundary\fP is not set,\^
233: that is,\^ if it has a value of zero,\^ it is set to the value of the
234: \*Mfp\fP in the calling procedure. Because the call to
235: \*Msetbound\fP creates a procedure frame,\^ the \*Mfp\fP value saved in
236: the frame is used. If \*M_boundary\fP is already set,\^ it is not
237: changed.
238: .SH
239: \*Mclrbound\fP on the VAX
240: .PP
241: The value of \*M_boundary\fP is compared to the \*Mfp\fP in the
242: calling procedure. If the values are the same,\^ the calling procedure
243: was called from Icon and when it returns it returns to Icon.
244: If this is the case,\^ \*M_boundary\fP is cleared.
245: .SH
246: An Alternative Approach
247: .PP
248: If the C system on the target machine uses calls at the beginning and
249: end of C routines to save and restore registers,\^ it is possible to
250: modify these routines to set and clear the boundary. This approach is
251: used on the PDP-11.
252: .PP
253: The file \*Mrt/csv.s\fP contains replacement
254: routines for \*Mcsv\fP and \*Mcret\fP. When \*Mcsv\fP is called to
255: save registers,\^ if \*M_boundary\fP is 0,\^ \*Msp\fP is saved in
256: \*M_boundary\fP. This insures that the first call from Icon into C
257: leaves \*M_boundary\fP at the top of the stack at that point.
258: When \*Mcret\fP is called to restore registers,\^ if the procedure
259: frame pointer is equal to \*M_boundary\fP,\^ the return is taking
260: control back to Icon code and \*M_boundary\fP is cleared.
261: .PP
262: Note the resemblance between calling \*Msetbound\fP at the start of a
263: C routine and having \*Mcsv\fP set \*M_boundary\fP whenever a C routine
264: is entered. Similarly,\^ there is a resemblance between calling
265: \*Mclrbound\fP at appropriate points and having \*Mcret\fP clear
266: \*M_boundary\fP when necessary.
267: .PP
268: The initial implementation of Icon was on the PDP-11 and the modified
269: \*Mcsv\fP and \*Mcret\fP approach was used. When the system was
270: ported to the VAX,\^ the subsumption of \*Mcsv\fP and \*Mcret\fP by the
271: hardware required that a software approach be taken. The trade-offs
272: are marginal if the target machine uses save and restore routines.
273: Having a distinct \*Msetbound\fP and \*Mclrbound\fP may be easier to
274: implement,\^ but using modified save and restore routines is
275: definitely faster.
276: .PP
277: If this approach is used,\^ then \*MSetBound\fP and \*MClearBound\fP in
278: \*Mrt.h\fP should be defined,\^ but given no value.
279: .NH 3
280: \*Mlib/invoke.s\fR
281: .SH
282: Overview
283: .LP
284: \*Minvoke.s\fP handles four specific tasks. These are
285: .Ds
286: .ft R
287: call a built-in function
288: call an Icon procedure
289: create a record
290: perform mutual evaluation
291: .De
292: .LP
293: Note that all of these operations rise from a source code
294: expression of the form
295: .Ds
296: \*(e0(\*(e1,\^\*(El,\^\*(en)
297: .De
298: where each \*(ai is an expression of some type.
299: Icon has strict left-to-right evaluation and thus,\^ for the preceding
300: expression,\^ \*(e0 is evaluated first,\^ then \*(e1,\^ and so forth
301: through \*(en. As each expression is evaluated,\^ its result
302: is pushed on the stack. After the expressions have been evaluated
303: (and assuming none failed),\^ the stack looks something like
304: .Ds
305: .ft R
306: .S1
307: value from \*(e0
308: value from \*(e1
309: \*(El
310: value from \*(ei
311: \*(El
312: \*Msp\fR \*(ar value from \*(en
313: .De
314: Then,\^ \*(e0 is \fIinvoked\fP.
315: .PP
316: Recall that stacks are represented as growing downward. Thus,\^
317: \*(en is on the ``top'' of the stack. Also note that each
318: ``value'' on the stack is actually a two-word descriptor.
319: .\"The various \*(ei may be referred to as \fIarguments\fP.
320: .SH
321: Generic Operation
322: .PP
323: \*Minvoke\fP is an interpreter opcode that takes a single operand
324: specifying how many \*(ei are present (\*(e0 is not counted).
325: \*Minvoke\fP is also called from \*Mstart.s\fP to invoke the \*Mmain\fP
326: procedure.
327: .Ls
328: .Np
329: \*Minvoke\fP must determine whether it is to call a built-in function,\^
330: call an Icon procedure,\^ create a record,\^ or perform mutual evaluation. If
331: \*(e0 is not something that can be invoked,\^
332: \*Minvoke\fP notes this as a run-time error.
333: .Np
334: If mutual evaluation is to be done,\^ \*Minvoke\fP selects the
335: value of \*(ei that corresponds to the value of \*(e0. That is,\^
336: if \*(e0 is 2,\^ then \*(e2 is selected and returned. If \*(e0
337: references a value that is out of range,\^ \*Minvoke\fP fails.
338: .Np
339: If an Icon procedure or built-in procedure
340: is being called,\^ the argument list is adjusted
341: to conform to the number of arguments that the procedure or function
342: is expecting.
343: This may mean supplying \*M&null\fP for missing values,\^ or discarding
344: the last few \*(ei. Some built-in functions take a variable number of
345: arguments,\^ but all Icon procedures take a fixed number of arguments.
346: If the desired operation is creation of a record,\^ \*Minvoke\fP treats
347: this just like invocation of a built-in procedure.
348: .Le
349: .LP
350: Built-in functions and Icon procedures are handled in very different ways.
351: If a built-in function is being invoked,\^ it is simply called. (The
352: calling sequence is somewhat convoluted on the VAX and is
353: described later.)
354: Calling an Icon procedure is more involved; the following actions
355: are taken.
356: .Ls
357: .Np
358: Each \*(ei in the (adjusted) argument list is dereferenced.
359: .Np
360: If \*M&trace\fP has a non-zero value,\^ the function \*Mctrace\fP is
361: called with appropriate arguments. \*Mctrace\fP produces output
362: that includes the name of the procedure being called and the arguments
363: that are being passed to it.
364: .Np
365: The remainder of the procedure frame (partially constructed by the
366: call itself) is built. This includes pushing values for \*M_file\fP
367: and \*M_line\fP on the stack. \*M_file\fP is a pointer to a string
368: that names the source file from which the code currently being
369: executed came. \*M_line\fP is the number of the source line
370: that is currently being executed. A descriptor for
371: \*M&null\fP is pushed on the
372: stack for each dynamic local of the procedure.
373: .Np
374: The generator frame pointer is cleared (because a new expression
375: context is being entered). \*Mipc\fP
376: is loaded with the entry point of the procedure being called.
377: Control is then passed back to the interpreter using a jump
378: instruction.
379: .Le
380: .SH
381: \*Minvoke\fP on the VAX
382: .PP
383: On the VAX,\^ immediately after \*Minvoke\fP has been entered,\^ the stack is
384: .Ds
385: .ft R
386: .St
387: value from \*(e0
388: value from \*(e1
389: \*(El
390: 8 value from \*(en
391: 4 number of expressions \- 1 (\*Mnargs\fR)
392: \*Map\fR \*(ar 0 number of words in argument list (\*Mnwords\fR)
393: -4 saved \*Mr11\fR
394: -8 saved \*Mr10\fR
395: \*(El
396: saved \*Mr1\fR
397: saved \*Mpc\fR
398: 12 saved \*Mfp\fR
399: 8 saved \*Map\fR
400: 4 program status word and register mask
401: \*Msp\fR,\^ \*Mfp\fR \*(ar 0 0 (condition handler address)
402: .De
403: .PP
404: The first action of \*Minvoke\fP is to set \*M_boundary\fP to the
405: value of \*Mfp\fP. This is done because \*Minvoke\fP may be
406: invoking a built-in procedure.
407: .PP
408: The number of arguments with which \*(e0 is to be invoked is contained
409: in the \fInargs\fP word,\^ which resides at \*M4(ap)\fP. This value
410: is frequently used and is put into \*Mr8\fP.
411: .PP
412: \*Minvoke\fP makes
413: frequent use of \*(e0,\^ but its address is not a fixed distance
414: from any known point. Rather,\^ the address of \*(e0 must be calculated
415: using the address of \*(en and the number of arguments. The VAX
416: \*Mmovaq\fP instruction makes this calculation easy. The desired
417: calculation is
418: .Ds
419: r11 = 8 + ap + (r8 * 8)
420: .De
421: and is performed by
422: .Ds
423: movaq 8(ap)\^[r8],\^r11
424: .De
425: \*(e0 may be a
426: variable and if so,\^ it needs to be dereferenced.
427: \*Mr11\fP,\^ which contains the address of \*(e0 is pushed on
428: the stack and \*Mderef\fP is called. The dereferencing is done
429: ``in place''; the previous value of \*(e0 is replaced with the
430: dereferenced value. The dereferenced value is a descriptor
431: whose first word contains type information and whose second word
432: (in some cases) contains the address of a data block which holds
433: the actual value of the object. Note that \*Mr11\fP points to
434: the first word of this descriptor.
435: .PP
436: Recall that the first task of \*Minvoke\fP is to determine what
437: \*(e0 is and to act accordingly. The simplest case is when \*(e0
438: is a procedure. That is checked for by comparing \*M0(r11)\fP with
439: \*MD_PROC\fP. If \*(e0 is a procedure,\^ a forward jump is made to
440: \*Mdoinvk\fP.
441: .PP
442: It is more interesting if \*(e0 is not a procedure. The first
443: alternative investigated is mutual evaluation. mutual evaluation is similar to a procedure
444: call,\^ but rather than \*(e0 being a procedure,\^ it is an integer
445: that selects one of the \*(ei. The selected \*(ei is the outcome of
446: the mutual evaluation. The routine \*Mcvint\fP is used to
447: try to convert \*(e0 to an integer. If \*(e0 cannot be converted to
448: an integer,\^ a forward branch is taken to \*Mtrystr\fP to explore another
449: possibility.
450: For mutual evaluation,\^ a non-positive value of \*(e0
451: is acceptable and is converted to a positive value using the
452: \*Mcvpos\fP routine. (Expressions in the argument list are indexed
453: the same way that characters in a string are indexed.) If the
454: position is greater than the number of expressions in the list,\^ that
455: is,\^ if the reference is out of range,\^ the mutual evaluation fails by calling
456: the routine \*Mfail\fP. If the position is in range,\^ the selected
457: \*(ei must be returned as the result of the invocation (and the
458: result of the mutual evaluation). The \*(ei to return is selected by multiplying
459: the position by 8 (each \*(ei is a descriptor) and subtracting
460: that from \*Mr11\fP,\^ which points at \*(e0. The descriptor thus
461: referenced is copied into the location of \*(e0. (Recall that \*(e0
462: is used to receive the result of an operation.) \*M_boundary\fP
463: is then cleared and \*Minvoke\fP returns.
464: .PP
465: If \*(e0 is not convertible to an integer,\^ conversion to a
466: procedure is attempted. (Note that this is an experimental extension
467: to Icon.) \*(e0 is first converted to a string
468: using \*Mcvstr\fP. If the conversion is successful,\^ the routine
469: \*Mstrprc\fP is called to see if the string ``names'' a procedure.
470: The conversion performed by \*Mstrprc\fP is ``in place'',\^ i.e.,\^
471: \*(e0 becomes a descriptor for a procedure. If either the
472: conversion in \*Mcvstr\fP or \*Mstrprc\fP fails,\^ \*(e0 is deemed
473: to be uninvocable and this is noted by run-time Error 106.
474: .PP
475: At this point (the label \*Mdoinvk\fP),\^ \*(e0 is a descriptor to a procedure
476: to be invoked and \*Mr11\fP points to \*(e0.
477: .PP
478: The next operation is to make the number of arguments supplied
479: conform to the number of arguments that the procedure is expecting.
480: The number of arguments that a procedure expects is in the fifth
481: word of its procedure block. This value for the procedure being
482: invoked is obtained and placed in \*Mr10\fP.
483: If the value is negative,\^ the number
484: of arguments that the procedure expects is variable. Only built-in
485: procedures can have a variable number of arguments,\^ so if the
486: desired argument count is negative,\^ control passes to the label
487: \*Mbuiltin\fP.
488: .PP
489: \*Mr8\fP contains the number of arguments given and \*Mr10\fP contains
490: the number of arguments desired. The value of \*Mr10\fP is subtracted
491: from \*Mr8\fP,\^ leaving \*Mr8\fP with the difference. If the
492: number of arguments supplied is the same as the number expected,\^
493: no adjustment is needed and a forward jump is made to
494: \*Mdoderef\fP. Otherwise,\^ the stack must be adjusted.
495: .PP
496: First,\^ \fInwords\fR and \fInargs\fR on the stack are adjusted. Recall
497: that \fInargs\fR
498: is used by Icon and is the number of arguments for a procedure.
499: \fInwords\fR is used by the VAX hardware and is the number of words that
500: the argument list for a subroutine occupies. \fInargs\fR resides at
501: \*M4(ap)\fP and is updated by storing \*Mr10\fP in \*M4(ap)\fP.
502: \fInwords\fR is trickier because only the low-order byte of the \fInwords\fR word
503: is to be used for the word count. The low-order byte of \*Mr10\fP is
504: stored in \*M0(ap)\fP,\^ doubled,\^ and then incremented by one. (The
505: increment by one is to allow for the \fInargs\fR word that is part of
506: the argument list.)
507: .PP
508: The deletion of excess arguments or addition of \*M&null\fP for
509: missing arguments is accomplished by moving the lower portion of
510: the stack up or down to overwrite excess arguments or to leave
511: space for missing arguments. Consider the following: A procedure
512: that expects one argument has been invoked with three arguments.
513: The stack is
514: .Ds
515: .ft R
516: .St
517: 128 \*(e0
518: 120 \*(e1
519: 112 \*(e2
520: 104 \*(e3
521: 100 \*Mnargs\fR (3 at call,\^ 1 after adjustment)
522: \*Map\fR \*(ar 96 \*Mnwords\fR (7 at call,\^ 3 after adjustment)
523: 92 \*Mr11\fR
524: \*(El
525: 48 \*Mr1\fR
526: 44 \*Mpc\fR
527: 40 \*Mfp\fR
528: 36 \*Map\fR
529: 32 \*Mpsw\fR
530: \*Msp\fR,\^ \*Mfp\fR \*(ar 28 0
531: .De
532: The situation desired is
533: .Ds
534: .ft R
535: 128 \*(e0
536: 120 \*(e1
537: 116 \*Mnargs\fR (1)
538: \*Map\fR \*(ar 112 \*Mnwords\fR (3)
539: 108 \*Mr11\fR
540: \*(El
541: 64 \*Mr1\fR
542: 60 \*Mpc\fR
543: 56 \*Mfp\fR
544: 52 \*Map\fR
545: 48 \*Mpsw\fR
546: \*Msp\fR,\^ \*Mfp\fR \*(ar 44 0
547: .De
548: Note the address field (which has been arbitrarily assigned).
549: Observe that \*(e0 and \*(e1 are in
550: the same place,\^ but that the lower portion of the stack has moved up.
551: Consider what would be desired if the
552: procedure being invoked requires five arguments and only three are
553: supplied. The desired stack configuration is
554: .Ds
555: .ft R
556: .St
557: 128 \*(e0
558: 120 \*(e1
559: 112 \*(e2
560: 104 \*(e3
561: 96 \*M&null\fP (\*(e4)
562: 88 \*M&null\fP (\*(e5)
563: 84 \*Mnargs\fR (5)
564: \*Map\fR \*(ar 80 \*Mnwords\fR (11)
565: 76 \*Mr11\fR
566: \*(El
567: 32 \*Mr1\fR
568: 28 \*Mpc\fR
569: 24 \*Mfp\fR
570: 20 \*Map\fR
571: 16 \*Mpsw\fR
572: \*Msp\fR,\^ \*Mfp\fR \*(ar 12 0
573: .De
574: As before,\^ the ``good'' arguments are in the same place,\^ but the
575: stack has moved down to make room for \*(e4 and \*(e5 and a value
576: of \*M&null\fP is supplied for them.
577: .PP
578: The VAX hardware makes these stack manipulations easy. Recall that
579: \*Mr8\fP contains
580: .Ds
581: .ft R
582: number of arguments expected \- number of arguments supplied
583: .De
584: Thus,\^ in the first case \*Mr8\fP has a value of 2,\^ while in the second
585: case \*Mr8\fP is \-2. The value of \*Mr8\fP is multiplied by
586: 8 to turn the argument count into a byte count. This byte count
587: is added to \*Msp\fP,\^ effectively moving it to where it should
588: be. Now,\^ a block of memory starting at where \*Mfp\fP points
589: must be moved to where \*Msp\fP points. The size of the
590: block needs to be considered. It starts at the fp and contains
591: the condition handler,\^ the old psw,\^ \*Map\fP,\^ \*Mfp\fP and \*Mpc\fP
592: \(em five words.
593: Eleven saved registers are included; eleven more words. (A constant,\^
594: \*MINVREGS\fP,\^ is used to represent the number of saved registers.)
595: Finally,\^ two words for \fInargs\fR and \fInwords\fR \(em a total of 18
596: words. The VAX
597: instruction that makes the move is
598: .Ds
599: movc3 $(INVREGS+7)*4,\^(fp),\^(sp)
600: .De
601: which moves 18*4 (=72) bytes from where \*Mfp\fP is pointing to
602: where \*Msp\fP pointing. The VAX allows the source and
603: destination fields to overlap without producing ``curious'' results.
604: .PP
605: Some housekeeping must be performed after the move is made.
606: \*Mfp\fP is set to point to the same word \*Msp\fP points to,\^
607: and the boundary is set to point to the same place. \*Map\fP is
608: adjusted to point to the \fInwords\fR word.
609: .PP
610: If arguments were deleted,\^ the adjustment process is done. If
611: arguments were added,\^ \*M&null\fP must be supplied as the value
612: for each argument that was added. Because the descriptor for
613: \*M&null\fP consists of two words containing 0,\^ the task amounts to filling
614: in null bytes in the ``hole'' that was made. \*Mr8\fP contains
615: the number of bytes in the ``hole''. \*Mr8\fP is negative and it
616: is negated to obtain a positive byte count. The instruction
617: .Ds
618: movc5 $0,\^(r0),\^$0,\^r8,\^(INVREGS+7)*4(sp)
619: .De
620: does all the work. Specifically,\^ this instruction moves bytes of zeroes
621: starting at \*M(r0)\fP to a field that starts at \*M72(sp)\fP and
622: extends for \*Mr8\fP bytes. The third operand of the instruction
623: is a ``fill character'' that is used in the event that the destination
624: field is longer than the source field. In this case,\^ the source
625: field is 0 bytes long,\^ and a null-byte fill character is moved into
626: each byte of the destination field. This is the usual way to zero
627: out a block of memory on the VAX.
628: .PP
629: At this point,\^ the correct number of arguments for the procedure
630: are on the stack.
631: .PP
632: For an Icon procedure,\^ all arguments must be dereferenced before
633: the procedure is called. Procedure blocks have a field that tells
634: how many dynamic local variables the procedure has. For built-in
635: procedures this field has a value of \-1. If a built-in procedure
636: is to be invoked,\^ control jumps to the label \*Mbuiltin\fP.
637: If an Icon procedure is to be invoked,\^ but it has no arguments (and
638: thus they do not need to be dereferenced),\^ a forward jump is made
639: to \*Mcktrace\fP.
640: .PP
641: \*Mr11\fP points to the descriptor for \*(e0. The address of \*(e1
642: is used later in \*Minvoke\fP,\^ and its address is calculated using \*Mr11\fP
643: because it's handy. \*Mr10\fP contains the number of arguments and
644: this value is stored in \*Mr5\fP for subsequent use of \*Mr5\fP as a
645: counter. The arguments must be dereferenced,\^ this is done by calling
646: \*Mderef\fP with the address of each argument. The instruction
647: .Ds
648: pushaq -(r11)
649: .De
650: is used to decrement \*Mr11\fP by 8 and then push the value of \*Mr11\fP
651: on the stack. Because \*Mr11\fP initially references \*(e0,\^ the first
652: time through \*Mr11\fP is decremented to point at \*(e1 and
653: \*Mderef\fP is called with the address of \*(e1. \*Mr11\fP is backed
654: down through the expression list,\^ with each \*(ei being dereferenced
655: in turn. Note that the \*Msobgeq\fP instruction is used as a loop
656: controller,\^ decrementing \*Mr5\fP and jumping back to \*Mnxtarg\fP as
657: long as \*Mr5\fP is not 0.
658: .PP
659: At this point,\^ an Icon procedure is being
660: invoked; it has the correct number of arguments and they
661: have been dereferenced.
662: .PP
663: If tracing is on,\^ (indicated by a non-zero value for \*M_k_trace\fP),\^
664: a trace message must be produced at this point.
665: The routine \*Mctrace\fP does all the work. It needs to be called
666: with the appropriate arguments. \*Mctrace\fP requires three
667: arguments: procedure block address,\^ number of arguments,\^ and the
668: address of the first argument. These are pushed on the stack and
669: \*Mctrace\fP is called.
670: .PP
671: The portion of the stack from \*(e0 on down constitutes a partial
672: procedure frame and it must be completed. \*M_line\fP and \*M_file\fP
673: are pushed on the stack. To complete the frame,\^ the local variables
674: must be pushed on the stack. Local variables have an initial value
675: of \*M&null\fP,\^ and the \*Mmovc5\fP idiom used previously is used
676: again to zero out the space required for the local variables.
677: .PP
678: Because an Icon procedure is being invoked,\^ the boundary is cleared and
679: \*M_k_level\fP (the \*M&level\fP keyword) is incremented. The entry
680: point for a procedure is stored in the third word of the procedure
681: block. This value is loaded into \*Mipc\fP.
682: A new expression context is being entered,\^ and both
683: \*Mgfp\fP and \*Mefp\fP are cleared using a \*Mclrq\fP instruction.
684: .PP
685: Control is passed back to the main loop of the interpreter
686: by jumping to \*Minterp\fP.
687: The Icon procedure is now being executed. The procedure
688: eventually terminates by use of \*Mpret\fP or \*Mpfail\fP.
689: .LP
690: The section of code following \*Mbuiltin:\fP
691: handles the case where a built-in procedure is to be invoked.
692: .PP
693: If nothing is changed,\^ when a built-in function returns,\^ it would
694: return to the instruction after the call to \*Minvoke\fP. This
695: is unsatisfactory,\^ since the boundary needs to be cleared because
696: of the transition from the C environment to the Icon environment.
697: Rather than having a call to \*Mclrbound\fP at
698: the end of each built-in procedure,\^ the boundary is cleared at
699: a common return point.
700: .PP
701: The \*Mpc\fP value that is stored at \*M16(fp)\fP is ``hidden''
702: at \*M20(fp)\fP where the value of \*Mr1\fP should be saved.
703: \*M16(fp)\fP is replaced with the address of the forward label
704: \*Mbprtn\fP. Thus,\^ when the built-in procedure returns,\^ it goes
705: right to \*Mbprtn\fP. Because a C environment is being entered,\^
706: the boundary is set to the current value of \*Mfp\fP. The third
707: word of the procedure block contains the entry point of the built-in
708: procedure and it is jumped to. It is important to understand that
709: the procedure is not called because the call frame has already been
710: constructed. Also,\^ the entry point address stored in the procedure
711: block \fImust\fR be past any instructions that are used to establish
712: the stack environment for the routine because this environment
713: should already be on the stack.
714: .PP
715: When the built-in procedure returns,\^ it comes to \*Mbprtn\fP.
716: The boundary is cleared because execution is back in an Icon
717: environment. The procedure return restores \*Mr1\fP,\^ which contains
718: the \*Mpc\fP value that \*Minvoke\fP should return to. Because
719: the return has already swept off the old frame,\^ \*M0(r1)\fP is
720: jumped to and \*Minvoke\fP is finished. Note that the built-in
721: procedure has left its result in \*(e0,\^ which is left on the
722: stack. Thus,\^ the direct result of \*Minvoke\fP is an additional
723: value on the stack.
724: .SH
725: Some Comments on \*Minvoke\fR
726: .PP
727: It is important to understand the purpose of \*Minvoke\fP. Unless
728: mutual evaluation is being performed,\^
729: the task of \*Minvoke\fP is to create a procedure frame for an Icon or
730: built-in procedure and then transfer control to the procedure.
731: .PP
732: On the VAX and the PDP-11,\^ the call to \*Minvoke\fP partially
733: creates the procedure frame. \*Minvoke\fP then completes the
734: frame. For Icon procedures,\^ control eventually passes out of
735: \*Minvoke\fP and goes back to the interpreter loop. However,\^
736: for built-in procedures,\^ after the frame is built,\^ \*Minvoke\fP
737: \fIbranches into\fP the C code for the procedure. Thus,\^ it appears
738: that the built-in procedure was called directly. This scheme is
739: facilitated by the fact that entry points of C routines on the
740: VAX and PDP-11 are a constant distance from the start of the routine.
741: (The \*MEntryPoint\fP macro in \*Mrt.h\fP specifies the distance.)
742: On some machines this may not be practical and other schemes may need
743: to be developed.
744: .PP
745: Another point that needs to be addressed is that of argument removal.
746: When a built-in procedure,\^ Icon procedure,\^ or built-in operation is
747: performed,\^ the net result almost always is
748: simply the addition of a descriptor to the stack. More precisely,\^
749: the new descriptor is actually a replacement for \*(a0,\^ which
750: is the descriptor for the procedure being called,\^ or in the case
751: of a built-in operation is \*M&null\fP. Recall that arguments are below \*(a0
752: on the stack. The \*(a0 word must be on top of the
753: stack when a procedure or operation is complete. The VAX does
754: this via hardware,\^ which manages the stack and removes arguments when
755: a procedure call is complete. The PDP-11 does not have such hardware
756: facilities and thus the arguments must be removed manually. The
757: problem is compounded by the fact that for built-in operations,\^
758: \*Minvoke\fP is never called; rather,\^ the interpreter loop calls the
759: appropriate subroutine directly.
760: .PP
761: The method employed on the PDP-11 uses the \*Mcret\fP routine to
762: remove arguments. \*Mcret\fP is called at the end of each C routine
763: to restore registers. Icon has a replacement for \*Mcret\fP that
764: restores registers but also removes arguments when appropriate.
765: \*Mrt/csv.s\fP contains the replacement routine. When \*Mcret\fP is
766: called,\^ if \*Mr5\fP (the \*Mpfp\fP on the PDP-11) is equal to
767: \*M_boundary\fP,\^ then \*Mcret\fP is returning to Icon code and any
768: arguments on the stack are removed,\^ leaving \*(a0 on the top of the
769: stack.
770: A similar technique may be needed on the target machine.
771: .PP
772: \*Mrt/csv.s\fP also contains a replacement for the \*Mcsv\fP routine
773: which saves registers upon entry to C functions
774: on the PDP-11. Both \*Mcsv\fP and \*Mcret\fP also contain code that
775: is used to set and clear the boundary at appropriate times. See
776: the description of \*Mrt/setbound.s\fP for more details.
777: .NH 3
778: \*Miconx/interp.s\fR
779: .SH
780: Overview
781: .PP
782: \*Minterp.s\fP is the main loop for the interpreter.
783: The execution of an Icon program is stack based.
784: As the interpreter executes an Icon program,\^ it
785: fetches instructions and accompanying operands out of the instruction
786: stream of the interpretable file. Operands for
787: interpreter instructions are pushed on the stack and results
788: accumulate on the stack as operands for other instructions.
789: In addition to simple incremental and decremental stack changes,\^
790: the expression evaluation mechanism may cause portions of the
791: stack to be duplicated and may also cause the top portion of
792: the stack to be removed.
793: .SH
794: Generic Operation
795: .PP
796: An Icon program is executed by interpreting the interpretable file
797: produced by the linker. The interpretation process itself is fairly
798: simple. \*Mipc\fP points at the next
799: instruction to be executed. (Recall that the interpretable file is
800: loaded into memory.) The opcode of the instruction is fetched
801: and the corresponding
802: word in the jump table is taken as the address of a sequence of
803: instructions that perform the desired operations. A branch is
804: taken to the referenced location and the operation is performed.
805: The operation may require operands; if so,\^ they appear in the
806: instruction stream following the opcode. The segment of code that
807: performs a particular operation is responsible for fetching the
808: appropriate operands out of the stream. When the
809: operation is complete,\^ a jump is taken to the top of the interpreter
810: loop and the process continues.
811: .PP
812: Interpreter operations are of two types. Operations of the first type
813: call a routine to perform a task. Operations of the second type are
814: executed entirely by the interpreter; no subroutine call is necessary.
815: .PP
816: Operations that require a call to be made call routines in the
817: \*Moperators\fP or \*Mlib\fP directories. The routine being called
818: may require one or more arguments. If arguments are required,\^ they
819: appear on the stack. When the routine returns,\^ it removes
820: any arguments that it was called with from the stack and leaves its
821: result on the top of the stack.
822: .PP
823: To facilitate the calling of
824: routines,\^ a table known as \*Moptab\fP parallels the jump table.
825: An opcode \fIn\fP references the \fIn\fPth word of the jump table.
826: If the operation designated by the opcode requires a call,\^ the
827: \fIn\fPth word of \*Moptab\fP contains the address of the routine
828: that should be called.
829: .PP
830: The interpreter saves space in its
831: instruction stream by encoding operand information in some opcodes.
832: For example,\^ the \*Mline\fP instruction has one operand that
833: is used to set the value of \*M_line\fP,\^ the current source line
834: number. The \*Mlinex\fP instruction is an alternate form of
835: \*Mline\fP which encodes the line number as the low order bits of the
836: opcode. Specifically,\^ the opcodes from 192 to 256 are \*Mlinex\fP
837: opcodes. For example,\^ opcode 195 is equivalent to a \*Mline\fP
838: opcode with an operand of 3.
839: .SH
840: Implementing the Interpreter Loop
841: .PP
842: \*Minterp.s\fP stands alone among the assembly language files as one that is
843: well suited to coding in a macro fashion. Most of the interpreter loop is
844: written in terms of \fIcpp\fP macros and thus porting it is largely a
845: matter of writing the macros for the target machine.
846: .LP
847: The following \*M#define\fPs must be made.
848: .Ip \*MOp\ \ \ \ \ \fP
849: .br
850: The operand register. Any general purpose register will do. The
851: value of the register need not preserved between instructions; its
852: lifetime is only from the time that an operand is fetched until the
853: next opcode is fetched or a routine is called.
854: .Ip \*MGetOp\fP
855: This must expand into code that fetches the next operand out of
856: the instruction stream and places it in the register \*MOp\fP.
857: Recall that operand size is determined by
858: the \*M#define\fP for \*MOPNDSIZE\fP in the linker.
859: On the VAX,\^ \*MGetOp\fP is merely
860: .Ds
861: .ta 0.6i +0.6i +0.6i +0.6i
862: movl (ipc)+,\^Op
863: .De
864: This is because operands are one word long and can begin on any byte
865: boundary. If the VAX did not support word fetching from arbitrary
866: boundaries,\^ it would be necessary to get the bytes from the
867: instruction stream one at a time and make a word out of them using
868: boolean operations. If such were the case,\^ a reasonable alternative
869: would be to make opcodes one word in size and thus all instruction
870: stream objects (opcodes,\^ operands,\^ and words),\^ would be of the same
871: size and lie on word boundaries.
872: .\".IP \*MGetWord\fP
873: .\"\*MGetWord\fP is similar to \*MGetOp\fP,\^ but rather than loading the
874: .\"next operand,\^ it loads the next \fIword\fP from the instruction stream into
875: .\"the \*MOp\fP register. Recall that the size of a word is defined by
876: .\"the \*MWORDSIZE\fP in the linker. If words are the same size as
877: .\"operands on the target machine,\^ \*MGetWord\fP should be identical to
878: .\"\*MGetOp\fP.
879: .Ip \*MPushOp\fP
880: Push the \*MOp\fP register on the stack. The VAX uses
881: .ta .6i
882: .Ds
883: pushl Op
884: .De
885: .Ip \*MPushNull\fP
886: Push a descriptor for \*M&null\fP on the stack. That is,\^ push two
887: words of zeroes. The VAX \*Mclrq\fP instruction does the trick:
888: .Ds
889: clrq -(sp)
890: .De
891: .Ip \*MPush_R(x)\fP,\^\ \*MPush_S(x)\fP,\^\ \*MPush_K(x)\fP
892: Push the value of \*Mx\fP on the stack. To accommodate machines with
893: non-orthogonal instruction sets,\^ \*MPush_R\fP is used to push a register
894: value,\^ and \*MPush_S\fP is used to push the contents of a storage
895: location. \*MPush_K\fP is used to push a constant value.
896: The VAX uses
897: .Ds
898: pushl x
899: .De
900: for both \*MPush_R(x)\fP and \*MPush_S(x)\fP,\^ while
901: .Ds
902: pushl $x
903: .De
904: is used for \*MPush_K(x)\fP.
905: .Ip \*MPushOpSum_R(x)\fP,\^\ \*MPushOpSum_S(x)\fP
906: \*MPushOpSum_R(x)\fP adds the value
907: of the register \*Mx\fP to \*MOp\fP and pushes the result on the stack.
908: \*MPushOpSum_S(x)\fP is similar,\^ adding the value in the memory
909: location \*Mx\fP to \*MOp\fP and pushing the result. On the VAX,\^
910: .Ds
911: addl3 Op,\^x,\^-(sp)
912: .De
913: is used for both.
914: .Ip \*MNextInst\fP
915: Branch to the top of the interpreter loop. The VAX uses
916: .Ds
917: jmp _interp
918: .De
919: .Ip \*MCallN(n)\fP
920: Call the routine corresponding to the current opcode with \*Mn\fP
921: arguments. On the VAX,\^ the opcode fetching segment loads \*Mr0\fP
922: with a byte offset into the jump table. This same byte offset
923: references the location in \*Moptab\fP which contains the address
924: of the routine which corresponds to the current opcode.
925: \*MCallN(n)\fP expands to
926: .Ds
927: pushl $n
928: calls $((n*2)+1),\^*optab(r0)
929: .De
930: \*Mpushl $n\fP pushes the number of arguments on the stack. This
931: word becomes the \fInargs\fP word of the procedure frame. The
932: first of operand of the \*Mcalls\fP instruction is the length of
933: words in the argument list,\^ since each argument is a two word
934: descriptor and the \fInargs\fP word occupies another word,\^
935: \*Mn*2+1\fP is used as the length of the argument list. The
936: address contained in the \*Moptab\fP word referenced by \*Mr0\fP is
937: the routine to call.
938: .Ip \*MCallNameN(n,\^f)\fP
939: Call the routine named \*Mf\fP with \*Mn\fP arguments. This is very
940: similar to \*MCallN\fP,\^ the only difference being that the routine
941: to call is explicitly named rather than being implicitly determined
942: from the opcode value. The VAX uses
943: .Ds
944: pushl $n
945: calls $((n*2)+1),\^f
946: .De
947: .Ip \*MBitClear(m)\fP
948: The constant value \*Mm\fP designates bits in the \*MOp\fP register
949: to leave on. All other bits in \*MOp\fP should be turned off. That
950: is,\^ the complement of \*Mm\fP is \*MAND\fPed with the contents of
951: \*MOp\fP and the result is placed in \*MOp\fP. This is used to
952: decode opcodes with encoded operands. The VAX uses
953: .Ds
954: bicl2 $0!m,\^Op
955: .De
956: .Ip \*MJump(lab)\fP
957: Branch to the label \*Mlab\fP. The destination label is close to the
958: jump,\^ so a short jump of some type may be used. The VAX uses
959: .Ds
960: jbr lab
961: .De
962: .Ip \*MLongJump(lab)\fP
963: \*MLongJump\fP is like \*MJump\fP with the exception that \*Mlab\fP
964: may be quite distant. The VAX uses
965: .Ds
966: jmp lab
967: .De
968: .Ip \*MLabel(lab)\fP
969: Generate a label declaration for \*Mlab\fP. The VAX uses
970: .Ds
971: lab:
972: .De
973: .SH
974: VAX Specific Sections of \*Minterp\fR
975: .PP
976: Several sections of \*Minterp\fP are machine specific and must be
977: coded on a per-machine basis. The sections in question are explained
978: on an individual basis:
979: .Ip \*M_interp\fP
980: The next opcode is fetched and loaded into \*Mr0\fP. \*Mmovzbl\fP
981: moves a byte and zero extends it to a word value. Because a byte was
982: fetched,\^ \*Mipc\fP is incremented by 1. The opcode is saved in
983: \*MOp\fP in case it contains an encoded operand. \*Mr0\fP is
984: multiplied by 4 to turn it into a byte offset. A jump is made to the
985: address indexed by \*Mr0\fP in \*Mjumptab\fP to perform the desired
986: operation. Eventually,\^ a jump returns control to the label
987: \*M_interp\fP to fetch and execute the next instruction.
988: .Ip \*Mop_bscan\fP
989: A descriptor for \*M_k_subject\fP is pushed on the stack. Then
990: the value of \*M_k_pos\fP is pushed,\^ followed by the constant
991: \*MD_INTEGER\fP. The routine corresponding to \*Mop_bscan\fP,\^
992: \*M_bscan\fP,\^ is called with 0 arguments. (This causes the
993: descriptors for \*M_k_subject\fP and the value of \*M_k_pos\fP to be
994: left on the stack.) When \*M_bscan\fP returns,\^ a branch is made to
995: \*M_interp\fP.
996: .Ip \*Mop_ccase\fP
997: A null descriptor is pushed on the stack. The word immediately
998: above the current expression frame is then pushed on the stack.
999: .Ip \*Mop_chfail\fP
1000: The operand of \*Mchfail\fP is fetched into \*MOp\fP. \*MOp\fP and
1001: \*Mipc\fP are added together and the result replaces the failure
1002: address in the current expression frame.
1003: .Ip \*Mop_dup\fP
1004: A null descriptor is pushed on the stack. The value that was on top
1005: of the stack is now at \*M8(sp)\fP,\^ and it is copied to the top of the
1006: stack using a \*Mmovq\fP.
1007: .Ip \*Mop_eret\fP
1008: \*Meret\fP gets the value on top of the stack,\^ removes the current
1009: expression frame and puts the previous top of stack value back on the
1010: top of the stack. First of all,\^
1011: .Ds
1012: movq (sp)+,\^r0
1013: .De
1014: moves the descriptor on the top of the stack into the \*Mr0\-r1\fP
1015: register pair and increments the stack pointer by 8. The \*Mgfp\fP
1016: is loaded with the \*Mgfp\fP value stored in the expression frame
1017: marker. \*Msp\fP is loaded from \*Mefp\fP,\^ bringing the expression
1018: marker to the top of the stack. The old \*Mefp\fP value from the
1019: marker is loaded into \*Mefp\fP. Finally,\^ the value stored in the
1020: \*Mr0\-r1\fP pair is pushed on the stack.
1021: .Ip \*Mop_file\fP
1022: The operand of \*Mfile\fP is loaded into \*MOp\fP. \*MOp\fP and the
1023: value of \*M_ident\fP are added and the result in placed in
1024: \*M_file\fP.
1025: .Ip \*Mop_goto\fP
1026: The operand is loaded into \*MOp\fP and then added to \*Mipc\fP.
1027: .Ip \*Mop_incres\fP
1028: The eighth word of the co-expression heap block for the current
1029: expression is incremented by one.
1030: .Ip \*Mop_init\fP
1031: This one is tricky. The \*Minit\fP instruction arises from the
1032: \*Minitial\fP statement in Icon and is used to effect one-time
1033: execution of a segment of code. The operand of \*Minit\fP is the
1034: address of the first instruction after the segment that is to be
1035: executed once. The instruction
1036: .Ds
1037: movb $59,\^-(ipc)
1038: .De
1039: decrements \*Mipc\fP by 1 and then stores the constant 59 in the byte
1040: that \*Mipc\fP references,\^ which is the \*Minit\fP opcode. The magic
1041: number 59 is the opcode for \*Mgoto\fP,\^ so in effect,\^ the \*Minit\fP
1042: had been made into a goto that skips a section of code. By adding 5
1043: to \*Mipc\fP,\^ it leaves \*Mipc\fP pointing at the first instruction
1044: of the \*Minitial\fP code. The constant 5 is derived from the
1045: width of the opcode and associated operand,\^ i.e.,\^
1046: \*MOPSIZE+OPNDSIZE\fP.
1047: .Ip \*Mop_invoke\fP
1048: This section has two entry points: \*Mop_invoke\fP gets control if
1049: \*Minvoke\fP has an operand,\^ and \*Mop_invkx\fP gets control if the
1050: operand is encoded in the opcode. If an operand is specified,\^ it is
1051: fetched into \*MOp\fP. If the operand is encoded,\^ \*MBitClear(7)\fP is
1052: used to isolate the operand in \*MOp\fP. Control converges at
1053: \*Mdoinvoke\fP. The operand is the number of arguments to
1054: invoke the procedure with and it is pushed on the stack as
1055: the \fInargs\fP word. (The arguments are already on the stack.)
1056: The \*Mcalls\fP instruction needs the length of the argument list,\^ so
1057: \*MOp\fP is multiplied by 2 and then incremented by 1. \*Minvoke\fP
1058: is called.
1059: .Ip \*Mop_int\fP
1060: As in \*Mop_invoke\fP,\^ \*Mop_int\fP has a secondary entry point,\^
1061: \*Mop_intx\fP,\^ for operands encoded in the opcode. At the \*Mop_int\fP
1062: entry point,\^ a \*MWORDSIZE\fP value is fetched out of the instruction
1063: stream and loaded into \*MOp\fP. At the \*Mop_intx\fP entry point,\^
1064: the \*MOp\fP value is decoded from the operand. The \*MOp\fP value is
1065: pushed on the stack and is followed by a \*MD_INTEGER\fP word,\^ forming
1066: an integer descriptor.
1067: .Ip \*Mop_line\fP
1068: Like \*Mop_invoke\fP and \*Mop_int\fP,\^ \*Mop_line\fP has a secondary
1069: entry point. The operand value is obtained and then moved into \*M_line\fP.
1070: .Ip \*Mop_llist\fP
1071: \*Mllist\fP is similar to \*Minvoke\fP in that it has a number of
1072: arguments already on the stack and that the operand specifies the
1073: number. The operand is fetched into \*MOp\fP and pushed on the
1074: stack to become the \fInargs\fP argument of \*Mllist\fP. \*MOp\fP is
1075: then multiplied by 2 and incremented by 1 to serve as an argument
1076: list size for \*Mcalls\fP.
1077: .Ip \*Mop_mark\fP
1078: The operand is fetched into \*MOp\fP and \*Mipc\fP is added to it.
1079: \*Mefp\fP is pushed on the stack and the new \*Msp\fP value is put in
1080: \*Mefp\fP. \*Mgfp\fP is pushed on the stack and cleared. \*MOp\fP
1081: is pushed on the stack.
1082: .Ip \*Mop_mark0\fP
1083: Like \*Mop_mark\fP,\^ with an implicit operand value of zero.
1084: .Ip \*Mop_pop\fP
1085: The two \*Mtstl\fP instructions serve to add 8 to \*Msp\fP which
1086: removes the top value from the stack.
1087: .Ip \*Mop_sdup\fP
1088: The descriptor on the top of the stack is pushed on the stack,\^
1089: duplicating it.
1090: .Ip \*Mop_unmark\fP
1091: The operand,\^ the number of expression frames to remove from the
1092: stack,\^ is fetched into \*MOp\fP. \*Mefp\fP is
1093: restored from the current expression frame. The instruction
1094: .Ds
1095: sobgtr Op,\^unmkjmp
1096: .De
1097: decrements \*MOp\fP and then branches to \*Mdounmark\fP if \*MOp\fP is not
1098: zero. This chains through the number of expression frames specified
1099: by the operand. \*Mgfp\fP is restored from the current expression
1100: marker. \*Mefp\fP is loaded into \*Msp\fP to move the expression
1101: marker to the top of the stack. Finally,\^ \*Mefp\fP is restored
1102: from the marker and \*Msp\fP is incremented to remove the last word
1103: of the marker.
1104: .Ip \*Mop_unmk1-7\fP
1105: Similar to \*Munmark\fP,\^ but uses successive restorations of
1106: \*Mefp\fP rather than a loop.
1107: .Ip \*Mop_global\fP
1108: Dual entry points are used to deal with possible operand encoding.
1109: The operand,\^ which is a number of a variable in the global region,\^
1110: is multiplied by 8 to provide a byte offset from the start of
1111: the global region. The sum of \*MOp\fP and the value of \*Mglobals\fP
1112: is pushed on the stack to provide a descriptor address. The constant
1113: \*MD_VAR\fP is pushed on the stack to complete the descriptor for the
1114: global variable.
1115: .Ip \*Mop_static\fP
1116: Identical to \*Mop_global\fP except that \*Mstatics\fP is used
1117: instead of \*Mglobals\fP.
1118: .Ip \*Mop_local\fP
1119: The operand value is the number of a local variable for which a
1120: variable descriptor is to be pushed on the stack. Recall that the
1121: local variables lie below the procedure frame and,\^ on the VAX,\^ the
1122: descriptor for the first one is at \*M\-16(fp)\fP. \*MOp\fP is
1123: negated. The instruction
1124: .Ds
1125: pushaq -16(fp)\^[Op]
1126: .De
1127: performs the calculation
1128: .Ds
1129: -16 + fp + (Op * 8)
1130: .De
1131: which computes the address of the descriptor of the desired variable
1132: and pushes it on the stack. The variable descriptor is completed by
1133: pushing \*MD_VAR\fP on the stack.
1134: .Ip \*Mop_arg\fP
1135: Like \*Mop_local\fP,\^ but it uses \*M8(ap)\fP as the base for the
1136: address calculation and the operand value is not negated.
1137: .Ip \*Mquit\ \ \ \ \ \fP
1138: Push a 0 on the stack and call the routine \*M_c_exit\fP to terminate
1139: execution of the Icon program.
1140: .Ip \*Merr\ \ \ \ \ \fP
1141: \*Merr\fP should never be encountered during normal execution.
1142: Reaching it indicates that an invalid opcode was encountered.
1143: It need not do anything more than abort execution. On the VAX,\^
1144: it calls \*Msprintf\fP to create a string containing the invalid
1145: opcode and the \*Mipc\fP where it was encountered and then calls
1146: \*Msyserr\fP with the string as an argument.
1147: .NH 3
1148: \*Mlib/efail.s\fR
1149: .SH
1150: Overview
1151: .PP
1152: \*Mefail\fP handles the failure of an expression. When
1153: Icon evaluates an expression,\^ it tries to produce a result from it.
1154: If at some point in the evaluation of an expression the expression
1155: fails,\^ Icon resumes inactive generators in the expression in
1156: an attempt to make the expression succeed. \*Mefail\fP is at the
1157: heart of this activity.
1158: .LP
1159: \*Mefail\fP has three distinct outcomes:
1160: .Ls
1161: .Np
1162: Resumption of the newest inactive generator in the current
1163: expression frame.
1164: .Np
1165: Failure of the current expression with execution continuing
1166: at the failure address contained in the expression marker.
1167: .Np
1168: Failure of the current expression with propagation of failure
1169: to the enclosing expression frame. This is similar to (2),\^
1170: but occurs when the failure address is 0. After the current
1171: expression fails,\^ \*Mefail\fP loops back to its entry point
1172: to fail again.
1173: .Le
1174: .PP
1175: \*Mefail\fP is branched to rather than being
1176: called. This is because it
1177: serves as a ``back-end'' for several failure
1178: actions that may occur during the course of execution:
1179: .Ls
1180: .Np
1181: When a built-in procedure fails,\^ it calls the routine \*Mfail\fP,\^ which
1182: in turn branches to \*Mefail\fP.
1183: .Np
1184: When an Icon procedure fails via the \*Mpfail\fP routine,\^ \*Mpfail\fP
1185: terminates by branching to \*Mefail\fP.
1186: .Np
1187: When the \*Mefail\fP opcode is executed by the interpreter,\^ \*Mefail\fP
1188: is branched to.
1189: .Np
1190: The generator frames built by \*Mesusp\fP and \*Mlsusp\fP use \*Mefail\fP
1191: as a return address. This is explained in detail later.
1192: .Le
1193: .SH
1194: Generic Operation
1195: .PP
1196: \*Mefail\fP is essentially a simple routine. There are two separate
1197: paths of execution that \*Mefail\fP may take. The first is to
1198: resume an inactive generator. The second is to cause failure of
1199: the expression in lieu of an inactive generator.
1200: .PP
1201: If there is an inactive generator in the current expression frame,\^
1202: it must be resumed.
1203: If the generator is an Icon procedure and tracing is in on,\^
1204: \*Matrace\fP is called with appropriate arguments. \*M_k_level\fP,\^
1205: \*M_line\fP,\^ and \*M_file\fP are restored from the generator frame. A return
1206: is performed and the net result is that the stack is restored to
1207: the state that it was in before the suspension that created the
1208: generator.
1209: .PP
1210: If there are no inactive generators that can be resumed,\^ the
1211: expression being evaluated must fail. This is done by popping
1212: the stack back through the current expression frame and resuming
1213: execution at the point indicated by the failure address in
1214: the expression marker. This is a two-step process. The first
1215: is to pop the frame and the second is to resume execution.
1216: When the frame is popped,\^ the expression has failed. The
1217: failure address in the expression marker is saved before
1218: the frame is popped. If this address is not zero,\^ execution
1219: is continued by branching to the address. If the address is
1220: zero,\^ the failure is propagated to the enclosing expression by
1221: branching to efail.
1222: .PP
1223: Zero failure addresses are generated by the ucode instruction
1224: .Ds
1225: mark L0
1226: .De
1227: Such instructions are used to avoid a special case during code
1228: generation and the only purpose they serve during program execution
1229: is to create an expression marker for the corresponding
1230: \*Munmark\fP instruction to remove. (\*Mmark\fP and \*Munmark\fP
1231: instructions are paired.)
1232: Thus,\^ whenever \*Mefail\fP pops an expression whose marker has a
1233: zero failure address,\^ \*Mefail\fP causes failure in the enclosing
1234: expression.
1235: .SH
1236: \*Mefail\fP on the VAX
1237: .PP
1238: The first action is to determine if there is an inactive generator
1239: that can be reactivated. If the generator frame pointer
1240: is non-zero,\^ it points to the newest inactive generator.
1241: Note that whenever a new expression frame is created,\^ the generator
1242: frame pointer is zeroed. Thus,\^ if \*Mgfp\fP is non-zero,\^ the
1243: generator frame that it points to belongs to a generator in the
1244: current expression frame.
1245: .PP
1246: If an inactive generator is available,\^ it must be reactivated.
1247: First,\^ \*M_boundary\fP is restored from the generator frame.
1248: The stack is popped back to the generator frame by loading
1249: \*Mfp\fP from \*Mgfp\fP. But,\^ before \*Mfp\fP is loaded,\^
1250: its value is saved in \*Mr0\fP. \*Mfp\fP now points at
1251: word 0 of the generator frame,\^ but that is a word below the
1252: actual stack frame that it should be pointing at,\^ so \*Mfp\fP is
1253: incremented by 4 using a \*Mtstl\fP.
1254: .LP
1255: There are three types of generators that may be encountered
1256: by \*Mefail\fP.
1257: .Ls
1258: .Np
1259: An Icon procedure that did a \*Msuspend\fP. In such cases,\^ the
1260: routine \*Mpsusp\fP handled the suspension.
1261: .Np
1262: A built-in procedure that called the C function \*Msuspend()\fP.
1263: .Np
1264: A generator created by an \*Mesusp\fP or \*Mlsusp\fP instruction.
1265: Such generators
1266: arise from source code constructs like \*M\*(x1 |\ \^\*(x2\fP,\^ \*M|\*(xx\fR,\^ and
1267: \*M\*(x1 \e\ \^\*(x2\fR,\^ which are referred to as \fIcontrol regimes\fP.
1268: .Le
1269: .PP
1270: The generators may be treated the same way as far as resumption goes.
1271: However,\^ if an Icon procedure is being resumed,\^ a tracing message must
1272: be generated if \*M_k_trace\fP is not 0.
1273: .PP
1274: If the value of \*M_boundary\fP is not the same as \*Mfp\fP,\^ the
1275: generator is a built-in procedure and tracing is not done.
1276: If the \*Mfp\fP saved in the current frame is the same as the
1277: \*Mfp\fP was upon entry to \*Mefail\fP (the value was saved in
1278: \*Mr0\fP),\^ the generator was made by an \*Mesusp\fP or an \*Mlsusp\fP
1279: and tracing is not done.
1280: .PP
1281: Otherwise,\^ the generator is an Icon procedure,\^ and \*Matrace\fP must
1282: be called. \*Matrace\fP takes one argument,\^ the address of the
1283: procedure block for the procedure being resumed. Recall that \*(e0 on the
1284: stack is a descriptor for the procedure block. The address of
1285: \*(e0 is calculated using
1286: .Ds
1287: &\*(e0 = ap + 8 + (8 * nargs)
1288: .De
1289: The resulting address is used as the single argument for \*Matrace\fP.
1290: .PP
1291: The generator is now ready to be resumed.
1292: \*M_k_level\fP,\^ \*M_line\fP,\^ and \*M_file\fP are restored by popping them
1293: from the generator frame. If the generator is a built-in procedure,\^
1294: \*M_boundary\fP is cleared. A return is performed to activate the
1295: generator.
1296: .PP
1297: The return has different effects depending on the type of generator
1298: being resumed.
1299: .PP
1300: If the generator is a built-in procedure,\^ the return
1301: restores the stack to the state it was in before \*Msuspend\fP was
1302: called,\^ and execution proceeds at the point just after \*Msuspend()\fP.
1303: In this case the \*Mpc\fP value being returned to references an instruction
1304: in the built-in procedure.
1305: .PP
1306: If the generator is an Icon procedure,\^ the stack is restored to
1307: the state it was in before the \*Mpsusp\fP ucode instruction
1308: was executed. The \*Mpc\fP value being returned to references an
1309: instruction in the interpreter loop. Execution of the program
1310: continues with the interpreter instruction following the \*Mpsusp\fP.
1311: .PP
1312: If the generator is a control regime,\^ the stack is restored to
1313: the state it was in before the \*Mesusp\fP or \*Mlsusp\fP that
1314: created the generator was performed. The
1315: return \*Mpc\fP points to \*Mefail\fP itself. Thus,\^ when the
1316: return is done,\^ the stack is cleared,\^ and an \*Mefail\fP is performed.
1317: This has the effect of transferring control to the failure label
1318: in the expression marker of the bounding expression frame.
1319: .\"(The failure label lies at the start of code for the alternative.)
1320: .PP
1321: If there is no generator to reactivate,\^ the expression must fail.
1322: This is handled at the label \*Mnogen\fP. \*Mefp\fP points to the
1323: expression frame marker. \*Mipc\fP is loaded
1324: from \*M\-8(efp)\fP which contains the address to go to in the
1325: event that the current expression fails. (As it has.)
1326: \*Mgfp\fP is restored from the expression marker.
1327: \*Mefp\fP is restored from the marker and the marker is popped off the stack.
1328: .PP
1329: If the failure address in \*Mipc\fP is non-zero,\^ control is passed
1330: back to the interpreter via a branch and execution of the ucode
1331: resumes at the failure address. If \*Mipc\fP is zero,\^ the expression
1332: failure is transmitted to the surrounding expression frame
1333: by a branch to \*Mefail\fP. (Recall that a zero failure address
1334: comes from a \*Mmark L0\fP instruction and that a failure that
1335: reaches a \*Mmark L0\fP marker must be propagated to the next
1336: expression marker.)
1337: .NH 3
1338: \*Mlib/pfail.s\fR
1339: .SH
1340: Overview
1341: .LP
1342: \*Mpfail\fP handles the failure of an Icon procedure. An Icon
1343: procedure can fail by
1344: .Ds
1345: .ft R
1346: executing a \*Mfail\fP expression
1347: executing \*Mreturn \fIexpr\fR when \fIexpr\fR fails
1348: allowing the flow of control to reach the end of a procedure
1349: .De
1350: \*Mpfail\fP is entered via a branch when
1351: the interpreter encounters the \*Mpfail\fP instruction.
1352: .SH
1353: Generic Operation
1354: .PP
1355: The task of \*Mpfail\fP is to signal failure in the expression that
1356: contains the procedure call being evaluated. This is done
1357: by removing the Icon procedure frame from the stack,\^ restoring
1358: appropriate registers and values,\^ and calling \*Mefail\fP. The key is that
1359: all \*Mpfail\fP needs to do is to remove the procedure frame
1360: from the stack and from then on things can be handled just like expression
1361: failure.
1362: Thus,\^ \*Mefail\fP does most of the work.
1363: .PP
1364: \*Mpfail\fP calls \*Mftrace\fP to produce a trace message if
1365: tracing is on. \*Mpfail\fP also decrements \*M_k_level\fP because
1366: a procedure is being exited.
1367: .PP
1368: Note that the procedure frame on the stack is a frame that
1369: was created by \*Minvoke\fP.
1370: .SH
1371: \*Mpfail\fP on the VAX
1372: .PP
1373: After \*M_k_level\fP is decremented,\^ \*M_k_trace\fP is checked to
1374: see if a trace message should be produced. If tracing is on,\^
1375: \*Mftrace\fP must be called. \*Mftrace\fP takes one argument,\^
1376: the address of the procedure block for the failing procedure.
1377: \*(e0 is the descriptor for the procedure block,\^ and the address
1378: of \*(e0 is calculated using
1379: .Ds
1380: &\*(e0 = (\fInargs\fP * 8) + 8 + ap
1381: .De
1382: The resulting address is pushed on the stack and \*Mftrace\fP is
1383: called.
1384: .PP
1385: Execution continues at \*Mdofail\fP to remove the procedure frame
1386: from the stack. The frame cannot be merely popped because it
1387: contains state information that must be restored. \*M_line\fP and
1388: \*M_file\fP are extracted from the frame. \*Mefp\fP,\^ \*Mgfp\fP,\^ and
1389: \*Mipc\fP are restored from the frame using addresses
1390: relative to \*Map\fP. Note that this works because \*Minvoke\fP saves
1391: these registers and their location is known.
1392: .PP
1393: \*Map\fP and \*Mfp\fP are restored from the frame. When \*Mfp\fP is
1394: restored,\^ it serves to remove the procedure frame (made by
1395: \*Minvoke\fP) from the stack. At this point,\^ the stack is the
1396: same state it was in before the interpreter performed the
1397: \*Minvoke\fP instruction. A branch is made to \*Mefail\fP to
1398: cause failure in the enclosing expression.
1399: .NH 2
1400: Testing the Basis
1401: .PP
1402: At this point,\^ enough of the system has been written to run some
1403: very simple Icon
1404: programs. \*Mtest/hello.icn\fP should be functional
1405: and more complete testing is in order. Refer to \fITesting the
1406: Basis\fP in \^[5].
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.