![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tr83-10c.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-10c.roff CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / icon / docs |
1.1 ! root 1: .NH 3 ! 2: \*Mrt/arith.s\fR ! 3: .SH ! 4: Overview ! 5: .PP ! 6: \*Marith.s\fP contains code for routines that add,\^ subtract,\^ and ! 7: multiply integers and check for overflow. If overflow occurs,\^ ! 8: run-time error 203 is produced. ! 9: .PP ! 10: The arguments to \*Mckadd\fP,\^ \*Mcksub\fP,\^ and \*Mckmul\fP are ! 11: two C \*Mlong\fP integers on which to operate. For example,\^ ! 12: if \*Mckadd\fP were written in C,\^ it would be declared ! 13: .Ds ! 14: long ckadd(a,\^b) ! 15: long a,\^b; ! 16: { ! 17: \&\*(El ! 18: } ! 19: .De ! 20: The routines return the result of the operation ! 21: using standard C return conventions. ! 22: .SH ! 23: \*Marith\fP on the VAX ! 24: .PP ! 25: The two arguments appear on the stack; \*Ma\fP is at \*M4(ap)\fP and ! 26: \*Mb\fP is at \*M8(ap)\fP. The appropriate 3-operand VAX instruction ! 27: is used to perform the operation and the result is placed in \*Mr0\fP ! 28: in accordance with C return conventions. If overflow occurs ! 29: during the operation,\^ the overflow bit in the program status word ! 30: is set. ! 31: .PP ! 32: After the operation is performed,\^ the overflow bit is ! 33: checked. If it is on,\^ indicating that an overflow occurred,\^ a branch ! 34: is taken to \*Moflow\fP,\^ where \*Mrunerr(203,\^0)\fP is called. ! 35: If overflow did not occur,\^ the routine returns and the value in ! 36: \*Mr0\fP is the value returned to the calling expression. ! 37: .PP ! 38: \*Marith.s\fP is trivial on the VAX because the hardware supports ! 39: operations on C \*Mlong\fP integers. This may not be the case on the ! 40: target machine. If so,\^ \*Marith.s\fP will be considerably more ! 41: complicated. However,\^ it usually is not difficult to locate routines ! 42: that perform these functions. As a last resort,\^ look at the code the C ! 43: compiler generates for the various arithmetic operations on long ! 44: integers. ! 45: .NH 3 ! 46: \*Mrt/fail.s\fR ! 47: .SH ! 48: Overview ! 49: .PP ! 50: \*Mfail\fP handles the failure of built-in procedures and operations. ! 51: Built-in procedures and operations are C routines and they signal ! 52: failure by calling \*Mfail()\fP. When a failure of this type ! 53: occurs,\^ the failure must be transmitted to the Icon expression ! 54: whose evaluation is in progress and that requires the services of ! 55: a C routine. ! 56: .SH ! 57: Generic Operation ! 58: .PP ! 59: \*Mfail\fP itself does very little,\^ the real work is done by ! 60: \*Mefail\fP. \*Mfail\fP pops the stack ! 61: back to where it was before the C routine was called and then ! 62: branches to \*Mefail\fP to make the enclosing expression fail. ! 63: .PP ! 64: \*Mfail\fP is akin to \*Mpfail\fP in that it pops the stack back ! 65: to a state that it was in when an expression was being evaluated ! 66: and then causes failure of the expression. The primary difference ! 67: is that an Icon procedure frame is being removed in \*Mpfail\fP and ! 68: it contains extra information that must be restored. ! 69: .SH ! 70: \*Mfail\fP on the VAX ! 71: .PP ! 72: \*M_boundary\fP points to the procedure frame for the first C routine ! 73: that was called from Icon. \*Mfp\fP is loaded from \*M_boundary\fP and ! 74: this puts the stack back to the state that it was in when the ! 75: C routine was entered. The C routine is for either a built-in procedure ! 76: such as \*Mread\fP or for an operator such as \*M+\fP. For a ! 77: built-in procedure,\^ the procedure frame now on the top of the stack ! 78: (after loading \*Mfp\fP from \*M_boundary\fP) is the frame constructed ! 79: in \*Minvoke\fP. For an operator,\^ the frame on the stack is the ! 80: one constructed when the interpreter loop called the C routine ! 81: for the operator. ! 82: .PP ! 83: The task at hand is to remove the procedure frame and restore the ! 84: registers that were saved in the frame. The mask/psw word of the ! 85: frame is manipulated so that the mask portion of the word resides ! 86: in bits 0:11 of \*Mr0\fP and the remaining bits of \*Mr0\fP are 0. ! 87: The VAX \*Mpopr\fP instruction takes a register mask as an operand ! 88: and pops words from the stack into the registers indicated by ! 89: the mask. For example,\^ ! 90: .Ds ! 91: popr $0x0005 ! 92: .De ! 93: moves the top word of the stack into \*Mr0\fP and the second stack ! 94: word into \*Mr2\fP. \*Msp\fP is then incremented by 8. ! 95: .PP ! 96: The saved registers start at \*M20(fp)\fP and \*Msp\fP is loaded ! 97: with this address. Then \*Mpopr r0\fP restores the registers ! 98: that are saved in the frame. Note that the manipulations of the ! 99: mask/psw are necessary because it is not known \fIa priori\fP which ! 100: registers were saved. In particular,\^ \*Mpopr $0x0fff\fP would ! 101: be disastrous. ! 102: .PP ! 103: After the registers have been restored,\^ \*Map\fP and \*Mfp\fP are ! 104: restored from the saved \*Map\fP and \*Mfp\fP values in the ! 105: frame. ! 106: .PP ! 107: At this point,\^ the stack is as it was before the frame for ! 108: the built-in procedure or operator was created. All that ! 109: remains is to signal failure in the expression being evaluated ! 110: and this is done by branching to \*Mefail\fP. ! 111: .ne 1i ! 112: .NH 3 ! 113: \*Mlib/pret.s\fR ! 114: .SH ! 115: Overview ! 116: .PP ! 117: \*Mpret\fP handles the return of a value from an Icon procedure. ! 118: \*Mpret\fP is called from the interpreter loop with a single ! 119: argument (which is on the stack) ! 120: that is the value being returned. The value is dereferenced ! 121: if necessary. If tracing is on,\^ a trace message is produced. The ! 122: return value is copied over \*(e0 in the frame of the procedure that ! 123: is returning a value. The procedure frame is removed,\^ leaving ! 124: the result on the stack,\^ and \*Mpret\fP returns. ! 125: .SH ! 126: Generic Operation ! 127: .LP ! 128: .Ls ! 129: .Np ! 130: \*M&level\fP is decremented because a procedure is being exited. ! 131: .Np ! 132: The stack address where the return value is ! 133: to be placed is calculated. Recall that when a procedure is invoked,\^ the ! 134: return value (if any) ultimately replaces \*(e0,\^ the descriptor ! 135: for the procedure returning the value. ! 136: .Np ! 137: The value being returned must be dereferenced if it is a local ! 138: variable or argument. This is because local variables and arguments ! 139: are on the stack and the portion of the stack associated with ! 140: a procedure ``goes away'' when a procedure returns. If the ! 141: return value is a variable (is of type \*MT_VAR\fP) ! 142: and its address ! 143: is between the base of the current expression stack*,\^ ! 144: and the stack pointer,\^ it is dereferenced. ! 145: If it is a substring trapped variable (is of type \*MT_TVAR\fP ! 146: and points to a block of type \*MT_TVSUBS\fP),\^ and the address of the ! 147: variable containing the substring ! 148: is between the base of the current expression stack ! 149: and the stack pointer,\^ it is dereferenced. ! 150: .FS ! 151: *For purposes of uniformity,\^ the system stack is treated ! 152: as if it were a co-expression stack. The global variable ! 153: \*Mcurrent\fP is a pointer to the descriptor for the co-expression ! 154: stack block for the current co-expression. Co-expressions ! 155: need not be implemented; it is only important that \*Mcurrent\fP ! 156: and the descriptor that it points to be initialized correctly. ! 157: This is done in \*Miconx/init.c\fP. ! 158: .FE ! 159: .Np ! 160: If \*M&trace\fP is non-zero,\^ \*Mrtrace\fP is called with the ! 161: address of the block for the returning procedure and the ! 162: address of the value being returned. ! 163: .Np ! 164: \*Mfp\fP,\^ \*M_line\fP,\^ and ! 165: \*M_file\fP are restored from the returning procedure. ! 166: Because the impending return restores control to the Icon ! 167: environment,\^ \*M_boundary\fP is cleared. ! 168: .Np ! 169: \*Mpret\fP returns from the Icon procedure by executing ! 170: a return instruction. Because the current \*Mfp\fP points to the ! 171: procedure frame for the Icon procedure,\^ and the frame was ! 172: built by \*Minvoke\fP,\^ the return is effectively a return ! 173: from \*Minvoke\fP and the net result is the return value ! 174: left on the stack. ! 175: .Le ! 176: .SH ! 177: \*Mpret\fP on the VAX ! 178: .PP ! 179: \*Mpret\fP does not save any registers because the frame built ! 180: upon entry to \*Mpret\fP is discarded. ! 181: .PP ! 182: \*M_boundary\fP is set because \*Mderef\fP may be called and \*Mderef\fP ! 183: can cause a garbage collection. ! 184: .PP ! 185: \*M_k_level\fP is decremented because a procedure is being exited. ! 186: .PP ! 187: \*Mpret\fP needs to know the address of the descriptor for the Icon ! 188: procedure that is returning. Before \*Mpret\fP was called,\^ \*Mfp\fP ! 189: pointed at the procedure frame for the current Icon procedure (which ! 190: is now returning),\^ and \*Map\fP pointed at its argument list. The ! 191: call to \*Mpret\fP created a procedure frame which contains the old ! 192: \*Map\fP. This value is extracted and used in conjunction with ! 193: \fInargs\fP to calculate the address of the descriptor for the ! 194: procedure. This value is stored in \*Mr11\fP for future use. ! 195: .PP ! 196: As described,\^ the value being returned needs to be dereferenced ! 197: in certain cases. The return value is a descriptor and is the ! 198: argument to \*Mpret\fP. The first word of this descriptor ! 199: lies at \*M8(ap)\fP and contains type and flag information. This ! 200: word is placed in \*Mr1\fP for further examination. ! 201: .PP ! 202: The VAX \*Mbitl\fP instruction tests a set of bits. The two ! 203: operand values are ANDed together and the condition codes ! 204: are set according to the value of the result. The result itself ! 205: is discared. The instruction ! 206: .Ds ! 207: bitl $F_NQUAL,\^r1 ! 208: .De ! 209: ANDs the type and flags word with the \*MF_NQUAL\fP mask. ! 210: The \*MF_NQUAL\fP bit is set if a descriptor is \fInot\fP a ! 211: string qualifier. ! 212: If the \*MF_NQUAL\fP bit is not on,\^ the result of the ! 213: AND is a 0. The test is followed by ! 214: .Ds ! 215: beql chktrace ! 216: .De ! 217: Thus,\^ if the return value \fIis\fP a string qualifier,\^ a branch ! 218: is taken to \*Mchktrace\fP,\^ and no dereferencing is performed. ! 219: .PP ! 220: If the return value does have the \*MF_NQUAL\fP attribute,\^ it ! 221: is checked to see if it is a variable. The \*MF_VAR\fP bit is tested. ! 222: If it is not on,\^ the return value is not a variable and does ! 223: not have to be dereferenced. A branch is made to \*Mchktrace\fP if ! 224: this is the case. ! 225: .PP ! 226: If a variable is in hand,\^ the \*MF_TVAR\fP bit is checked to see ! 227: if it is a trapped variable. If it is not a trapped variable,\^ the ! 228: address field of the return value's descriptor is moved into \*Mr1\fP for ! 229: further testing and a branch is taken to \*Mchkloc\fP. ! 230: .PP ! 231: If the return value is a substring trapped variable,\^ it may reference ! 232: a local variable or an argument. The type bits of the descriptor ! 233: are isolated by ORing it with \*MTYPEMASK\fP. If the type ! 234: is not \*MT_TVSUBS\fP,\^ no dereferencing is needed and a branch ! 235: is taken to \*Mchktrace\fP. If it is a substring trapped variable,\^ ! 236: the address of the variable containing the substring is obtained ! 237: from the trapped variable's data block and is loaded into \*Mr1\fP. ! 238: .PP ! 239: At this point (\*Mchkloc\fP),\^ \*Mr1\fP points to a descriptor ! 240: that is directly or indirectly referenced by the return value. ! 241: If the descriptor is in the current expression stack,\^ the return ! 242: value must be dereferenced. \*Mr1\fP is first compared to ! 243: \*Msp\fP. If it is less than \*Msp\fP,\^ the descriptor is below ! 244: the stack and a branch is made to \*Mchktrace\fP. Otherwise,\^ ! 245: \*Mr1\fP is compared to the base address of the current expression ! 246: stack. If \*Mr1\fP is greater than the base of stack,\^ it is ! 247: above the stack and a branch is made to \*Mchktrace\fP. ! 248: .PP ! 249: It is now certain that the return value must be ! 250: dereferenced,\^ lest it ``disappear'' when the portion of the stack ! 251: it is in is re-used. The address of the return value is pushed ! 252: on the stack and \*Mderef\fP is called. Note that \*Mderef\fP completely ! 253: handles dereferencing of substring trapped variables and thus no ! 254: special provisions need to be made. ! 255: .PP ! 256: At \*Mchktrace\fP,\^ the return value has been dereferenced if ! 257: necessary and it is time to produce a tracing message if \*M&trace\fP ! 258: is non-zero. \*Mrtrace\fP does the work and it ! 259: requires two arguments: the address of the block for the returning ! 260: procedure,\^ and the address of the return value. Earlier,\^ the ! 261: address of descriptor for the procedure block was calculated and left ! 262: in \*Mr11\fP. The second word of this descriptor is pushed on ! 263: the stack along with the address of the return value. ! 264: .PP ! 265: \*Mpret\fP ``returns'' the designated ! 266: value by overwriting the procedure's descriptor ! 267: with the descriptor of the return value. \*Mr11\fP points at the ! 268: descriptor for the procedure and \*M8(ap)\fP still points at the ! 269: descriptor for the return value,\^ so ! 270: .Ds ! 271: movq 8(ap),\^(r11) ! 272: .De ! 273: does the trick. ! 274: .PP ! 275: Everything is set,\^ the actual return must be performed. The \*Mfp\fP ! 276: saved in the current frame is the procedure frame pointer of the Icon ! 277: procedure and the saved value is loaded into \*Mfp\fP to bring ! 278: the Icon procedure frame to the top of the stack. \*M_line\fP and ! 279: \*M_file\fP are restored from the Icon procedure frame. ! 280: \*M_boundary\fP is cleared because the return will take execution back ! 281: into an Icon realm. ! 282: .PP ! 283: A \*Mret\fP is executed. The return goes through the procedure ! 284: frame built by \*Minvoke\fP. Thus,\^ control is returned to the point ! 285: just after the call to \*Minvoke\fP and it appears as if \*Minvoke\fP ! 286: itself had just returned. ! 287: .NH 3 ! 288: \*Mlib/esusp.s\fR ! 289: .SH ! 290: Overview ! 291: .LP ! 292: \*Mesusp\fP suspends a value from an expression. \*Mesusp\fP is ! 293: called from the interpreter loop and the value to suspend appears ! 294: as an argument. A generator frame hiding the current expression ! 295: is created. The surrounding expression frame is duplicated. ! 296: \*Mesusp\fP leaves the value being suspended on the top of the stack. ! 297: .PP ! 298: The \*Mesusp\fP operation arises from the alternation ! 299: (\*M\*(x1\ |\ \^\*(x2\fR) control ! 300: structure. For example ! 301: .Ds ! 302: p(5 | 10) ! 303: .De ! 304: indicates that the call \*Mp(5)\fP should be made and if it fails,\^ then ! 305: \*Mp(10)\fP should be called. ! 306: .PP ! 307: The function of \*Mesusp\fP is best explained using an example. ! 308: The following ucode is generated for \*Mp(5 | 10)\fP ! 309: .Ds ! 310: .ta .8i +.8i +.8i +.8i ! 311: mark L1 ! 312: var 0 \fR(the variable \*Mp\fR)\*M ! 313: mark L2 ! 314: int 0 \fR(constant 5)\*M ! 315: esusp ! 316: goto L3 ! 317: lab L2 ! 318: int 1 \fR(constant 10)\*M ! 319: lab L3 ! 320: invoke 1 ! 321: unmark 1 ! 322: lab L1 ! 323: .De ! 324: When execution reaches \*Mesusp\fP,\^ the stack looks like ! 325: .Ds ! 326: .ft R ! 327: .ta 1i ! 328: expression marker with \*ML1\fR as failure address ! 329: descriptor for variable \*Mp\fR ! 330: \*Mefp\fR \*(ar expression marker with \*ML2\fR as failure address ! 331: \*Msp\fR \*(ar descriptor for constant 5 ! 332: .De ! 333: \*Mgfp\fP is zero at this point. ! 334: After the \*Mesusp\fP is performed,\^ the stack is ! 335: .Ds ! 336: .ft R ! 337: .ta 1i ! 338: \*Mefp\fR \*(ar expression marker with \*ML1\fR as failure address ! 339: descriptor for variable \*Mp\fR ! 340: expression marker with \*ML2\fR as failure address ! 341: descriptor for constant 5 ! 342: \*Mgfp\fR \*(ar generator frame built by \*Mesusp\fR ! 343: .ta 1i 3.3i ! 344: descriptor for variable \*Mp\fR } duplicated region ! 345: \*Msp\fR \*(ar descriptor for constant 5 ! 346: .De ! 347: A branch is taken to \*ML3\fP,\^ where \*Minvoke 1\fP is performed. ! 348: This invokes \*Mp\fP with one argument,\^ the constant 5 on the ! 349: stack. If \*Mp(5)\fP succeeds,\^ the \*Munmark 1\fP is performed ! 350: and the stack is popped back through the \*ML1\fP expression frame,\^ ! 351: the current location of \*Mefp\fP. ! 352: .PP ! 353: Suppose that instead of succeeding,\^ \*Mp(5)\fP fails. ! 354: \*Mp\fP fails by calling \*Mpfail\fP,\^ which removes the ! 355: procedure frame from the stack and then calls \*Mefail\fP. The ! 356: previous stack picture shows what the stack looks like after the ! 357: procedure frame has been removed. \*Mefail\fP finds that ! 358: \*Mgfp\fP is not null and restores certain values that are saved ! 359: in the generator frame. The frame,\^ which was created by \*Mesusp\fP,\^ ! 360: contains a return address that points to \*Mefail\fP. Thus,\^ when ! 361: \*Mefail\fP removes the frame by returning through it,\^ control goes ! 362: back to the start of \*Mefail\fP and the stack is ! 363: .Ds ! 364: .ft R ! 365: .ta 1i ! 366: expression marker with \*ML1\fR as failure address ! 367: descriptor for variable \*Mp\fR ! 368: \*Mefp\fR \*(ar expression marker with \*ML2\fR as failure address ! 369: \*Msp\fR \*(ar descriptor for constant 5 ! 370: .De ! 371: This time around,\^ \*Mgfp\fP is zero,\^ so \*Mefail\fP must remove ! 372: the current expression frame and branch to the failure address in ! 373: the frame's marker. When the expression frame is removed,\^ the ! 374: stack looks like ! 375: .Ds ! 376: .ft R ! 377: .ta 1i ! 378: expression marker with \*ML1\fR as failure address ! 379: \*Msp\fR \*(ar descriptor for variable \*Mp\fR ! 380: .De ! 381: The failure address in the expression frame was \*ML2\fP,\^ so control ! 382: is transferred to \*Mlabel L2\fP in the ucode. (Note how much went ! 383: on as the result of the \*Minvoke\fP being executed.) The ! 384: instruction \*Mint 1\fP is executed and a descriptor for the constant ! 385: 10 is pushed on the stack giving: ! 386: .Ds ! 387: .ft R ! 388: .ta 1i ! 389: expression marker with \*ML1\fR as failure address ! 390: descriptor for variable \*Mp\fR ! 391: \*Msp\fR \*(ar descriptor for constant 10 ! 392: .De ! 393: \*Minvoke 1\fP is performed again,\^ which does \*Mp(10)\fP. ! 394: .PP ! 395: If \*Mp(10)\fP succeeds,\^ the \*Munmark 1\fP is executed,\^ which ! 396: removes the \*ML1\fP marker and transfers control to \*ML1\fP. ! 397: If \*Mp(10)\fP fails,\^ the same thing happens,\^ but \*Mefail\fP ! 398: does the work rather than \*Munmark\fP. ! 399: .SH ! 400: Generic Operation ! 401: .LP ! 402: .Ls ! 403: .Np ! 404: The procedure frame created by the call to \*Mesusp\fP partially ! 405: forms the generator frame. The frame is completed by pushing ! 406: \*M_boundary\fP,\^ \*M_k_level\fP,\^ \*M_line\fP,\^ and \*M_file\fP. ! 407: The generator frame pointer is set to point at the word of the ! 408: frame which contains the boundary. ! 409: .Np ! 410: The bounds of the expression frame to be duplicated are determined. ! 411: The lower bound is the stack word above the current expression frame ! 412: marker. ! 413: The upper bound is dependent on \*Mefp\fP and \*Mgfp\fP ! 414: values saved in the current expression marker. If the saved \*Mgfp\fP is ! 415: non-zero,\^ the upper bound is the first word below the generator ! 416: frame marker. If the saved \*Mgfp\fP is zero,\^ the upper bound is ! 417: the first word below the expression frame marker referenced by the ! 418: saved \*Mefp\fP. In the example,\^ this region only contains ! 419: the descriptor for the variable \*Mp\fP. ! 420: The region is copied to the top of the stack. The stack pointer is ! 421: adjusted to point to the new top of stack. ! 422: .Np ! 423: The value being suspended is pushed on the stack. ! 424: .Np ! 425: The return address in the new generator frame is replaced by the address of ! 426: \*Mefail\fP so that when \*Mefail\fP removes the frame by returning through ! 427: it,\^ \*Mefail\fP regains control. The old return address is ! 428: momentarily retained. The procedure frame pointer and argument ! 429: pointer are restored. \*M_boundary\fP is cleared because control is ! 430: returning to Icon code. ! 431: .Np ! 432: \*Mefp\fP in the current expression ! 433: marker replaces the expression frame pointer. Thus,\^ if an \*Munmark\fP ! 434: is performed,\^ the entire expression frame is removed. In the example,\^ ! 435: this happens if \*Mp(5)\fP or \*Mp(10)\fP succeeds. ! 436: .Np ! 437: The return \*Mpc\fP value which was saved is jumped to. This is in ! 438: effect a return from \*Mesusp\fP,\^ but the stack is untouched. ! 439: .Le ! 440: .SH ! 441: \*Mesusp\fP on the VAX ! 442: .PP ! 443: When \*Mesusp\fP is entered,\^ the generator frame is partially ! 444: constructed. \*Mipc\fP,\^ \*Mgfp\fP,\^ and \*Mefp\fP are saved in ! 445: the frame. \*M_boundary\fP is set to the current \*Mfp\fP value ! 446: and is pushed on the stack. The generator frame pointer,\^ is pointed at ! 447: the word containing the boundary. ! 448: The frame is completed by pushing \*M_k_level\fP,\^ \*M_line\fP,\^ ! 449: and \*M_file\fP on the stack. ! 450: .PP ! 451: The lower bound of the region to copy is the first word above the ! 452: current expression frame marker. Recall that an expression frame ! 453: looks like ! 454: .Ds ! 455: .ft R ! 456: .St ! 457: \*Mefp\fR \*(ar 0 old expression frame pointer ! 458: -4 old generator frame pointer ! 459: -8 failure address ! 460: .De ! 461: Thus,\^ ! 462: .Ds ! 463: addl3 $4,\^efp,\^r0 ! 464: .De ! 465: points \*Mr0\fP at the lower end of the region to copy. ! 466: .PP ! 467: The upper bound of the region to copy is the low word of the marker ! 468: for the enclosing generator or expression frame. If \*Mgfp\fP ! 469: is non-zero the generator frame marker is used. ! 470: Otherwise,\^ the expression frame marker is used. Recall that a ! 471: generator frame looks like ! 472: .Ds ! 473: .ft R ! 474: .St ! 475: saved registers ! 476: 20 reactivation address (saved \*Mpc\fR) ! 477: 16 saved \*Mfp\fR ! 478: 12 saved \*Map\fR ! 479: 8 \*Mpsw\fR and register mask ! 480: 4 0 ! 481: \*Mgfp\fR \*(ar 0 boundary ! 482: -4 saved \*M_k_level\fR ! 483: -8 saved \*M_line\fR ! 484: -12 saved \*M_file\fR ! 485: .De ! 486: So,\^ if the saved \*Mgfp\fP is non-zero,\^ the upper bound of the region ! 487: to copy is ! 488: .Ds ! 489: .ft R ! 490: saved \*Mgfp\fR - 12 ! 491: .De ! 492: Otherwise,\^ it is ! 493: .Ds ! 494: .ft R ! 495: saved \*Mefp\fR - 8 ! 496: .De ! 497: The appropriate calculation is performed and \*Mr2\fP pointed at the ! 498: bounding word. ! 499: .LP ! 500: At this point,\^ the stack looks something like ! 501: .Ds ! 502: .ft R ! 503: .St ! 504: \*Mr2\fR \*(ar low word of expression or generator frame marker ! 505: last word of region to copy ! 506: \*(El ! 507: \*Mr0\fR \*(ar 4 first word of region to copy ! 508: \*Mefp\fR \*(ar 0 saved expression frame pointer ! 509: -4 saved generator frame pointer expression marker ! 510: -8 failure label ! 511: 8 descriptor for value to suspend ! 512: 4 \*Mnargs\fR (1) ! 513: \*Map\fR \*(ar 0 \*Mnwords\fR (3) ! 514: -4 saved \*Mr11\fR (\*Mefp\fR) ! 515: saved \*Mr10\fR (\*Mgfp\fR) ! 516: 24 saved \*Mr9\fR (\*Mipc\fR) ! 517: 20 reactivation address (saved \*Mpc\fR) ! 518: 16 saved \*Mfp\fR ! 519: 12 saved \*Map\fR generator marker ! 520: 8 \*Mpsw\fR and register mask ! 521: 4 0 ! 522: 0 boundary (\*Mfp\fR at entry to \*Mesusp\fR) ! 523: -4 \*M_k_level\fR ! 524: -8 \*M_line\fR ! 525: \*Msp\fR \*(ar -12 \*M_file\fR ! 526: .De ! 527: .PP ! 528: The region starting at \*Mr0\fP and extending to \*Mr2\fP is to be ! 529: copied to the top of the stack. The length of the region in bytes is ! 530: calculated in \*Mr2\fP. ! 531: The value of \*Mr2\fP is subtracted from \*Msp\fP,\^ moving \*Msp\fP ! 532: down to accommodate the region. The region is then copied using ! 533: .Ds ! 534: movc3 r2,\^(r0),\^(sp) ! 535: .De ! 536: which moves \*Mr2\fP bytes starting at \*M0(r0)\fP to \*M0(sp)\fP. ! 537: .PP ! 538: The descriptor for the value to suspend is at \*M8(ap)\fP and it ! 539: is pushed on the stack using ! 540: .Ds ! 541: movq 8(ap),\^(sp) ! 542: .De ! 543: .LP ! 544: The stack now looks like ! 545: .Ds ! 546: .ft R ! 547: .ta 0.90i ! 548: \*Mr2\fR \*(ar low word of expression or generator frame marker ! 549: last word of region to copy ! 550: \*(El ! 551: \*Mr0\fR \*(ar first word of region to copy ! 552: \*Mefp\fR \*(ar expression frame marker ! 553: \*M8(ap)\fR \*(ar descriptor for value to suspend ! 554: \*(El ! 555: \*Mgfp\fR \*(ar generator frame marker ! 556: last word of copied region ! 557: \*(El ! 558: first word of copied region ! 559: \*Msp\fR \*(ar descriptor for value to suspend ! 560: .De ! 561: .PP ! 562: The reactivation address that is saved in the generator frame is moved ! 563: into \*Mr1\fP for later use. It is then replaced by the address ! 564: of \*Mefail\fP so that when the frame is returned through,\^ control ! 565: will go to \*Mefail\fP. ! 566: .PP ! 567: \*Mfp\fP and \*Map\fP are restored from the generator frame. \*M_boundary\fP ! 568: is cleared because control is being returned to Icon code. ! 569: .PP ! 570: \*Mefp\fP is pointed at the previous expression frame. That is,\^ \*Mefp\fP ! 571: is moved back one step in the expression frame chain. ! 572: .PP ! 573: Control is returned to the interpreter loop by branching to ! 574: \*M0(r1)\fP,\^ the reactivation address originally saved in the generator frame. ! 575: .NH 3 ! 576: \*Mlib/lsusp.s\fR ! 577: .SH ! 578: Overview ! 579: .PP ! 580: \*Mlsusp\fP suspends a value from a limited expression. A limited ! 581: expression arises from a source code expression of the form ! 582: .Ds ! 583: \*(x1\ \e\ \^\*(x2 ! 584: .De ! 585: This limits \*(x1 to at most \*(x2 results. (\*(x2 ! 586: must be a non-negative integer.) ! 587: .PP ! 588: \*Mlsusp\fP is just like \*Mesusp\fP except that it has provisions for ! 589: checking and decrementing the limit counter and taking the appropriate ! 590: action when the counter reaches zero. As a simple example,\^ consider ! 591: .Ds ! 592: p(x\ \e\ \^2) ! 593: .De ! 594: which generates the ucode ! 595: .Ds ! 596: .ta .8i +.8i +.8i ! 597: mark L1 ! 598: var 0 \fR(variable \*Mp\fR)\*M ! 599: int 0 \fR(constant 2)\*M ! 600: limit ! 601: mark L0 ! 602: var 1 \fR(variable \*Mx\fR)\*M ! 603: lsusp ! 604: invoke 1 ! 605: unmark 1 ! 606: \*(El ! 607: .De ! 608: When control reaches the \*Mlsusp\fP,\^ the stack looks like ! 609: .Ds ! 610: .ft R ! 611: .S1 ! 612: expression marker with \*ML1\fR as failure label ! 613: descriptor for variable \*Mp\fR ! 614: descriptor for integer with value of 2 ! 615: \*Mefp\fR \*(ar expression marker with \*ML0\fR as failure label ! 616: \*Msp\fR \*(ar descriptor for variable \*Mx\fR ! 617: .De ! 618: The \*Mlimit\fP instruction insures that the value on the top of ! 619: the stack (its argument) is a non-negative integer. After \*Mlsusp\fP,\^ the ! 620: stack is ! 621: .Ds ! 622: .ft R ! 623: .ta 0.75i 3.3i ! 624: \*Mefp\fR \*(ar expression marker with \*ML1\fR as failure label ! 625: descriptor for variable \*Mp\fR ! 626: descriptor for integer with value of 2 ! 627: expression marker with \*ML0\fR as failure label ! 628: descriptor for variable \*Mx\fR ! 629: \*Mgfp\fR \*(ar generator frame built by \*Mlsusp\fR ! 630: descriptor for variable \*Mp\fR } duplicated region ! 631: \*Msp\fR \*(ar descriptor for variable \*Mx\fR ! 632: .De ! 633: This is the same thing that \*Mesusp\fP would do,\^ with the ! 634: exception that the limit counter,\^ the integer descriptor,\^ is not ! 635: part of the duplicated region. ! 636: .SH ! 637: Generic Operation ! 638: .LP ! 639: .Ls ! 640: .Np ! 641: The procedure frame created by the call to \*Mesusp\fP partially ! 642: forms the generator frame. ! 643: .Np ! 644: The limit counter is decremented and if it is zero,\^ no suspension ! 645: is performed. Instead,\^ the current expression frame is removed ! 646: and the limit counter is replaced by the value that would have been ! 647: suspended had the limitation not been in effect. \*Mlsusp\fP returns,\^ ! 648: leaving the value on the top of the stack. ! 649: .Np ! 650: If the limit counter is not zero,\^ execution proceeds exactly ! 651: as it does for \*Mesusp\fP with the exception that the determination ! 652: of the region to copy takes the limit counter into consideration and ! 653: does not include it in the region that is copied. ! 654: .Le ! 655: .SH ! 656: \*Mlsusp\fP on the VAX ! 657: .PP ! 658: When \*Mlsusp\fP is entered,\^ the generator frame is partially ! 659: constructed. \*Mipc\fP,\^ \*Mgfp\fP,\^ and \*Mefp\fP are saved in ! 660: the frame. ! 661: .PP ! 662: The expression frame and associated limit counter have the following ! 663: layout: ! 664: .Ds ! 665: .ft R ! 666: .St ! 667: 8 number of results left ! 668: \u limit counter\d ! 669: .sp -1 ! 670: 4 \*MD_INTEGER\fR (type and flags word) ! 671: \*Mefp\fR \*(ar 0 old expression frame pointer ! 672: -4 old generator frame pointer expression frame ! 673: -8 failure label ! 674: .De ! 675: .PP ! 676: The limit counter is decremented and if it is not zero,\^ control ! 677: passes to \*Mdosusp:\fP and from then on execution proceeds ! 678: exactly as it does in \*Mesusp\fP. Specifically,\^ ! 679: the code beginning at \*Mdosusp:\fP ! 680: is an exact duplicate of that in \*Mesusp\fP with the ! 681: exception of the instruction that determines the lower bound of ! 682: the region to be duplicated. \*Mesusp\fP uses ! 683: .Ds ! 684: addl3 $4,\^efp,\^r0 ! 685: .De ! 686: which points \*Mr0\fP at the word immediately above the expression ! 687: frame. \*Mlsusp\fP uses ! 688: .Ds ! 689: addl3 $12,\^efp,\^r0 ! 690: .De ! 691: which points \*Mr0\fP at the word above the limit counter that is ! 692: directly above the expression frame. ! 693: .PP ! 694: If the limit counter is zero,\^ the counter is to be replaced with the ! 695: value which was to be suspended. The value appears as an argument to ! 696: \*Mlsusp\fP. This is accomplished with ! 697: .Ds ! 698: movq 8(ap),\^4(efp) ! 699: .De ! 700: .PP ! 701: The value of \*Mgfp\fP that is stored in the ! 702: expression frame is restored. ! 703: .PP ! 704: The saved \*Mpc\fP in \*Mlsusp\fP's frame is moved into \*Mr0\fP for ! 705: later use. ! 706: .PP ! 707: The expression frame is removed by moving \*Mefp\fP into \*Msp\fP,\^ ! 708: which leaves the expression frame marker word that contains the old ! 709: \*Mefp\fP on the top of the stack. This word is popped of the stack ! 710: and moved into \*Mefp\fP,\^ restoring \*Mefp\fP and leaving the ! 711: return (would-be suspended) value on the top of the stack. ! 712: .PP ! 713: \*Map\fP and \*Mfp\fP are restored from the procedure frame made upon ! 714: entry to \*Mlsusp\fP. ! 715: .PP ! 716: \*Mlsusp\fP ``returns'' by jumping to \*M0(r0)\fP,\^ the return point ! 717: that was saved in the frame. The value that was to be suspended,\^ but ! 718: was not because of the limitation,\^ is left on the top of the stack. ! 719: .NH 3 ! 720: \*Mlib/psusp.s\fR ! 721: .SH ! 722: Overview ! 723: .PP ! 724: \*Mpsusp\fP suspends a result from an Icon procedure. \*Mpsusp\fP is ! 725: called from the interpreter loop and the value to suspend appears ! 726: as an argument to \*Mpsusp\fP. A generator frame is created and ! 727: the generator or expression frame immediately containing the frame ! 728: for the suspending procedure ! 729: is duplicated on top of the stack. \*Mpsusp\fP returns through ! 730: the duplicated frame,\^ leaving the suspending value on top ! 731: of the stack. A return from \*Mpsusp\fP is manifested as a return ! 732: from \*Minvoke\fP. ! 733: .PP ! 734: The \*Mpsusp\fP operation arises from the \*Msuspend \*(xx\fR statement. ! 735: .PP ! 736: \*Mpsusp\fP is conceptually similar to \*Mesusp\fP,\^ the difference ! 737: being that a procedure frame is part of the expression frame ! 738: being duplicated and that requires some extra work. ! 739: To get a feel for what \*Mpsusp\fP does,\^ consider a simple example: ! 740: .PP ! 741: .Ds ! 742: .ta .5i +.5i +.5i +.5i +.5i ! 743: procedure main() ! 744: f(p(3)) ! 745: end ! 746: ! 747: procedure p(a) ! 748: suspend a ! 749: end ! 750: .De ! 751: .LP ! 752: The generated ucode for \*Mmain\fP is ! 753: .Ds ! 754: .ta .8i +.8i +.8i +.8i +.8i ! 755: \*(El ! 756: mark L1 ! 757: var 0 \fR(the variable \*Mf\fR)\*M ! 758: var 1 \fR(the variable \*Mp\fR)\*M ! 759: int 0 \fR(the constant 3)\*M ! 760: invoke 1 ! 761: invoke 1 ! 762: \*(El ! 763: lab L1 ! 764: .De ! 765: and the generated code for \*Mp\fP is ! 766: .Ds ! 767: mark p.L1 ! 768: mark L0 ! 769: var 0 \fR(the argument \*Ma\fR)\*M ! 770: psusp ! 771: \*(El ! 772: lab p.L1 ! 773: .De ! 774: .LP ! 775: When control reaches the \*Minvoke\fP instruction,\^ the stack resembles ! 776: .Ds ! 777: .ft R ! 778: .S1 ! 779: \*Mefp\fR \*(ar expression marker with \*ML1\fR as failure address ! 780: descriptor for variable \*Mf\fR ! 781: descriptor for variable \*Mp\fR ! 782: \*Msp\fR \*(ar descriptor for constant 3 ! 783: .De ! 784: after \*Mp\fP has been invoked,\^ just before the \*Mpsusp\fP is ! 785: executed the stack is ! 786: .Ds ! 787: .ft R ! 788: .S1 ! 789: expression marker with \*ML1\fR as failure address ! 790: descriptor for variable \*Mf\fR ! 791: descriptor for variable \*Mp\fR ! 792: descriptor for constant 3 (becomes argument \*Ma\fR) ! 793: procedure frame for \*Mp\fR (created by \*Minvoke\fR) ! 794: expression marker with \*Mp.L1\fR as failure address ! 795: \*Mefp\fR \*(ar expression marker with \*ML0\fR as failure address ! 796: \*Msp\fR \*(ar descriptor for argument \*Ma\fR ! 797: .De ! 798: Just before control returns from \*Mpsusp\fP,\^ the stack is ! 799: .Ds ! 800: .ta 0.75i 3.25i ! 801: .ft R ! 802: expression marker with \*ML1\fR as failure address ! 803: descriptor for variable \*Mf\fR ! 804: descriptor for variable \*Mp\fR ! 805: descriptor for constant 3 ! 806: procedure frame for \*Mp\fR ! 807: expression marker with \*Mp.L1\fR as failure address ! 808: expression marker with \*ML0\fR as failure address ! 809: descriptor for argument \*Ma\fR (being suspended) ! 810: \*Mgfp\fR \*(ar generator frame built by \*Mpsusp\fR ! 811: descriptor for variable \*Mf\fR ! 812: descriptor for variable \*Mp\fR duplicated region ! 813: descriptor for constant 3 ! 814: \*Msp\fR \*(ar procedure frame for \*Mp\fR ! 815: .De ! 816: After \*Mpsusp\fP returns,\^ the situation is ! 817: .Ds ! 818: \*Mefp\fR \*(ar expression marker with \*ML1\fR as failure address ! 819: descriptor for variable \*Mf\fR ! 820: descriptor for variable \*Mp\fR ! 821: descriptor for constant 3 ! 822: procedure frame for \*Mp\fR ! 823: expression marker with \*Mp.L1\fR as failure address ! 824: expression marker with \*ML0\fR as failure address ! 825: descriptor for argument \*Ma\fR ! 826: \*Mgfp\fR \*(ar generator frame built by \*Mpsusp\fR ! 827: descriptor for variable \*Mf\fR ! 828: \*Msp\fR \*(ar descriptor for constant 3 (the suspended value) ! 829: .De ! 830: .PP ! 831: The return from \*Mpsusp\fP goes to the second \*Minvoke\fP,\^ which ! 832: calls \*Mf\fP with one argument,\^ the constant 3 that was ! 833: suspended. If \*Mf(3)\fP fails,\^ the procedure frame for ! 834: \*Mf\fP is removed. \*Mefail\fP takes control and returns through ! 835: the generator frame built by \*Mpsusp\fP. This leaves the ! 836: descriptor for \*Ma\fP on top of the stack. Execution continues ! 837: by \*Mp\fP failing,\^ and then \*Mmain\fP failing. ! 838: .SH ! 839: Generic Operation ! 840: .LP ! 841: .Ls ! 842: .Np ! 843: The procedure frame created by the call to \*Mpsusp\fP partially forms ! 844: the generator frame. \*M_boundary\fP is set as the current location ! 845: of \*Mfp\fP and it is added to the generator frame. ! 846: .Np ! 847: As in \*Mpret\fP,\^ the value being suspended must be dereferenced ! 848: in certain cases. For example,\^ if the value is a local variable ! 849: or an argument,\^ it is dereferenced. The same code that handles ! 850: dereferencing in \*Mpret\fP appears in \*Mpsusp\fP as well. ! 851: Note that while suspension leaves the local variables and arguments ! 852: of a procedure intact,\^ if the enclosing expression frame should ! 853: be removed by an \*Munmark\fP,\^ the procedure frame would be destroyed,\^ ! 854: leaving undeferenced values pointing at meaningless data. ! 855: .Np ! 856: The generator frame is completed by pointing \*Mgfp\fP at the boundary ! 857: value already in the frame and by adding \*M_k_level\fP,\^ \*M_line\fP,\^ ! 858: and \*M_file\fP. ! 859: .Np ! 860: The bounds of the expression frame to be duplicated are determined. ! 861: The lower bound is the low word of the procedure frame for the ! 862: suspending procedure and the upper bound is the marker for the ! 863: expression frame or generator frame which is just prior to the ! 864: procedure frame. As in \*Mesusp\fP,\^ if \*Mgfp\fP is non-zero,\^ ! 865: the marker it points to is used. Otherwise,\^ the marker referenced ! 866: by \*Mefp\fP is used. The \*Mgfp\fP and \*Mefp\fP values used ! 867: are those found in the procedure frame of the suspending procedure. ! 868: The region is copied to the top of the stack. ! 869: In the example,\^ the duplicated region contained the procedure ! 870: frame marker for \*Mp\fP,\^ and the descriptors for the constant 3,\^ ! 871: and the variables \*Mp\fP and \*Mf\fP. ! 872: .Np ! 873: If \*M&trace\fP is non-zero,\^ \*Mstrace\fP is called to produce ! 874: a trace message noting that the procedure is suspending a value. ! 875: \*Mstrace\fP requires the address of the block for the suspending ! 876: procedure and the address of the descriptor for the value being ! 877: suspended. ! 878: .Np ! 879: \*M_line\fP and \*M_file\fP are restored from the frame of the ! 880: suspending procedure. This is done because when \*Mpsusp\fP is ! 881: finished,\^ it is as if the Icon procedure had returned. Thus,\^ ! 882: the line number and file name need to be what they were before ! 883: the procedure was called. ! 884: .Np ! 885: The generator frame pointer saved in the duplicated procedure frame ! 886: on the top of the stack is replaced by the current value of ! 887: \*Mgfp\fP,\^ which points to the newly created generator frame. ! 888: When \*Mpsusp\fP returns through the frame on the top of the stack,\^ ! 889: \*Mgfp\fP is restored from the value in the frame and \*Mgfp\fP ! 890: then references the new generator frame. ! 891: .Np ! 892: The descriptor for \*(a0 in the argument list of the Icon procedure ! 893: that is suspending is a descriptor for the procedure itself. This ! 894: descriptor is replaced with the descriptor for the value being ! 895: suspended. When \*Mpsusp\fP is done,\^ this descriptor is left on the ! 896: top of the stack. ! 897: .Np ! 898: \*M_boundary\fP is cleared because control is returning to Icon code. ! 899: .Np ! 900: \*Mpsusp\fP returns. The return uses the duplicated procedure frame ! 901: on the top of the stack. The result is that it appears as if the ! 902: \*Minvoke\fP that originally called the suspending procedure has ! 903: returned. ! 904: .Le ! 905: .SH ! 906: \*Mpsusp\fP on the VAX ! 907: .PP ! 908: When \*Mpsusp\fP is entered,\^ the generator frame is partially ! 909: constructed as a result of the call. \*M_boundary\fP is set to the ! 910: current value of \*Mfp\fP and this value is pushed on the stack ! 911: as part of the generator frame. ! 912: .PP ! 913: The value being suspended needs to be dereferenced if it is a local ! 914: variable or an argument. This operation is the same as is done in ! 915: \*Mpret\fP; consult the section on it for details of the actions ! 916: taken. ! 917: .PP ! 918: The generator frame is completed by pointing \*Mgfp\fP at the frame ! 919: word containing the boundary value and by adding \*M_k_level\fP,\^ ! 920: \*M_line\fP,\^ and \*M_file\fP to the frame. ! 921: .PP ! 922: The region to be duplicated is determined. The low word to be copied ! 923: is the low word of the procedure frame of the suspending procedure. ! 924: (The word that contains the 0.) This is readily accessible as the ! 925: \*Mfp\fP saved the procedure frame of \*Mpsusp\fP and is placed in \*Mr7\fP. ! 926: .PP ! 927: The high word to be copied is dependent upon the expression and generator ! 928: environment of the suspending procedure. If the \*Mgfp\fP ! 929: in the suspender's environment is not zero,\^ the word just below the ! 930: generator frame marker is the highest word to be copied. If ! 931: \*Mgfp\fP is zero,\^ the word just below the expression marker pointed at ! 932: by \*Mefp\fP in the suspender's environment is the highest word to ! 933: be copied. ! 934: .PP ! 935: The fact that the saved \*Mefp\fP and \*Mgfp\fP ! 936: appear on the stack just below the \fInwords\fP word (referenced by ! 937: \*M0(ap)\fP) is used to retrieve and test them. As in \*Mesusp\fP,\^ ! 938: if the saved \*Mgfp\fP is non-zero,\^ ! 939: .Ds ! 940: .ft R ! 941: saved \*Mgfp\fR - 12 ! 942: .De ! 943: is used for the lower bound,\^ otherwise ! 944: .Ds ! 945: .ft R ! 946: saved \*Mefp\fR - 8 ! 947: .De ! 948: is the lower bound. \*Mr4\fP is pointed at the appropriate word on ! 949: the upper end. As in \*Mesusp\fP,\^ \*Msp\fP is moved down to ! 950: accommodate the region to be duplicated and the region is copied to ! 951: the top of the stack using a \*Mmovc3\fP. ! 952: .PP ! 953: After \*M_k_level\fP is decremented,\^ \*M_k_trace\fP is checked to see ! 954: if a trace message should be produced. If so,\^ \*Mstrace\fP is called with ! 955: pointers to the descriptors for the suspending procedure and the ! 956: value being suspended. The address of the value being suspended is ! 957: \*M8(ap)\fP and the address of the descriptor for the procedure is ! 958: determined using the standard ! 959: .Ds ! 960: &\*(a0 = (nargs * 8) + 8 + ap ! 961: .De ! 962: calculation. ! 963: .PP ! 964: The values of \*M_line\fP and \*M_file\fP are restored from the ! 965: suspender's frame. ! 966: .PP ! 967: The saved \*Mgfp\fP in the duplicated procedure frame on the top of ! 968: the stack must be replaced by the current value of \*Mgfp\fP. Finding the ! 969: location of the saved \*Mgfp\fP is a little tricky. The distance ! 970: between \*Mfp\fP and \*Map\fP in the duplicated frame is calculated ! 971: by subtracting the value of \*Mfp\fP from the \*Map\fP value and putting ! 972: the result in \*Mr0\fP. The value in \*Mr0\fP represents the distance ! 973: from the top of the stack to \*M0(ap)\fP. Adding the ! 974: current \*Msp\fP (which points at the low word of the duplicated ! 975: procedure frame) to \*Mr0\fP points \*Mr0\fP at the \fInwords\fP word ! 976: of the new frame. \*Map\fP normally points at the \fInwords\fP word,\^ ! 977: so \*Mr0\fP serves as a pseudo-\*Map\fP. It is known that the saved \*Mgfp\fP ! 978: is the second word below the \fInwords\fP word; thus the new \*Mgfp\fP ! 979: is stored in \*M\-8(r0)\fP,\^ replacing the old value. Thus,\^ when \*Mpsusp\fP ! 980: returns through the duplicated frame,\^ the value just stored is ! 981: the restored value of \*Mgfp\fP. ! 982: .PP ! 983: The descriptor for the suspending procedure must be replaced by the ! 984: descriptor for the return value. The previous calculation left ! 985: \*Mr0\fP pointing at \*M0(ap)\fP in the duplicated frame. The ! 986: address of \*(a0 is calculated using ! 987: .Ds ! 988: &\*(a0 = (nwords * 4) + 4 + r0 ! 989: .De ! 990: Note that \*M+ 4\fP accounts for the four bytes that the \fInwords\fP ! 991: word itself occupies. The descriptor for the return value is put in ! 992: place using a \*Mmovq\fP. ! 993: .PP ! 994: \*Msp\fP is moved into \*Mfp\fP so that the pending return uses the ! 995: new frame on the top of the stack. ! 996: .PP ! 997: \*M_boundary\fP is cleared because control is going back into Icon ! 998: code. ! 999: .PP ! 1000: A \*Mret\fP is executed to return from \*Mpsusp\fP. This return uses ! 1001: the duplicated procedure frame and thus the duplicated frame is ! 1002: removed. The final result is that it looks like the original call to ! 1003: \*Minvoke\fP that started the Icon procedure has returned and ! 1004: the suspended value is left on the top of the stack. ! 1005: .ne 3v ! 1006: .NH 3 ! 1007: \*Mrt/suspend.s\fR ! 1008: .SH ! 1009: Overview ! 1010: .PP ! 1011: \*Msuspend\fP suspends a value from a built-in procedure or operator. ! 1012: \*Msuspend\fP is similar to \*Mpsusp\fP and amounts to little ! 1013: more than a simplified version of it. Recall that built-in ! 1014: procedures are C functions; thus,\^ \*Msuspend\fP is directly called ! 1015: from C. ! 1016: .PP ! 1017: A generator frame is created and the generator or expression frame ! 1018: immediately containing the frame for the suspending procedure ! 1019: is duplicated on the top of the stack. \*Msuspend\fP returns through ! 1020: the duplicated frame,\^ leaving the value being suspended on the top ! 1021: of the stack. When \*Msuspend\fP returns,\^ it appears as a return ! 1022: from the original call to the built-in procedure. ! 1023: .PP ! 1024: Note that \*Msuspend\fP handles the suspension of values from both ! 1025: built-in procedures such as \*Mupto\fP and from operators such as ! 1026: the element generation operator,\^ \*M!\fP. For built-in procedures,\^ ! 1027: the procedure frame is built by \*Minvoke\fP,\^ while for operators,\^ ! 1028: the procedure frame is built directly by the call to the appropriate ! 1029: function from the interpreter loop. ! 1030: The value being suspended by the C function is represented ! 1031: by the \*(a0 descriptor in the argument list. When ! 1032: \*Msuspend\fP is called,\^ the value to suspend is in place in ! 1033: \*Marg0\fP. ! 1034: .SH ! 1035: Generic Operation ! 1036: .PP ! 1037: \*Msuspend\fP can be considered as a ``subset'' of \*Mpsusp\fP. The ! 1038: descriptions of operations in this section and the next are excerpts ! 1039: from \*Mpsusp\fP. ! 1040: .LP ! 1041: The actions of \*Mpsusp\fP that are \fInot\fP taken by \*Msuspend\fP are: ! 1042: .Ls ! 1043: .Np ! 1044: The return value does not need to be dereferenced because the ! 1045: suspending function has already taken care of that. ! 1046: .Np ! 1047: No tracing message is produced because tracing is only done ! 1048: for Icon procedures. ! 1049: .Np ! 1050: The return value does not need to be moved into the duplicated ! 1051: procedure frame because it is already in place in the original procedure ! 1052: frame and when the frame is duplicated,\^ the return value is ! 1053: duplicated along with it. ! 1054: .Np ! 1055: \*M_k_level\fP is not decremented because \*M&level\fP keeps track of ! 1056: Icon procedure calls and \*Msuspend\fP is returning from a C routine. ! 1057: \*M_line\fP,\^ and \*M_file\fP are not restored because they are ! 1058: not part of the procedure frame of the built-in procedure. ! 1059: .Le ! 1060: .LP ! 1061: The operations that are performed by \*Msuspend\fP are: ! 1062: .Ls ! 1063: .Np ! 1064: The procedure frame created by the call to \*Msuspend\fP partially forms ! 1065: the generator frame. \*M_boundary\fP is set as the current location ! 1066: of \*Mfp\fP and it is added to the generator frame. ! 1067: .Np ! 1068: The bounds of the expression frame to be duplicated are determined. ! 1069: The lower bound is the low word of the procedure frame for the ! 1070: suspending procedure and the upper bound is the marker for the ! 1071: expression frame or generator frame which is just prior to the ! 1072: procedure frame. As in \*Mesusp\fP,\^ if \*Mgfp\fP is non-zero,\^ ! 1073: the marker it points to is used. Otherwise,\^ the marker referenced ! 1074: by \*Mefp\fP is used. The \*Mgfp\fP and \*Mefp\fP values used ! 1075: are those found in the procedure frame of the suspending procedure. ! 1076: The region is copied to the top of the stack. ! 1077: .Np ! 1078: The generator frame pointer saved in the duplicated procedure frame ! 1079: on the top of the stack is replaced by the current value of ! 1080: \*Mgfp\fP,\^ which points to the newly created generator frame. ! 1081: When \*Msuspend\fP returns through the frame on the top of the stack,\^ ! 1082: \*Mgfp\fP is restored from the value in the frame and \*Mgfp\fP ! 1083: then references the new generator frame. ! 1084: .Np ! 1085: \*M_boundary\fP is cleared because control is returning to Icon code. ! 1086: .Np ! 1087: \*Msuspend\fP returns. The return uses the duplicated procedure frame ! 1088: on the top of the stack. The result is that it appears as if the ! 1089: original call to the suspending procedure has returned. ! 1090: .Le ! 1091: .SH ! 1092: \*Msuspend\fP on the VAX ! 1093: .PP ! 1094: When \*Msuspend\fP is entered,\^ the generator frame is partially ! 1095: constructed as a result of the call. \*M_boundary\fP is set to the ! 1096: current value of \*Mfp\fP and this value is pushed on the stack ! 1097: as part of the generator frame. ! 1098: The generator frame is completed by pointing \*Mgfp\fP at the frame ! 1099: word containing the boundary value and by adding \*M_k_level\fP,\^ ! 1100: \*M_line\fP,\^ and \*M_file\fP to the frame. ! 1101: .PP ! 1102: The region to be duplicated is determined. The low word to be copied ! 1103: is the low word of the procedure frame of the suspending function. ! 1104: (The word that contains the 0.) This is readily accessible as the ! 1105: \*Mfp\fP saved in the procedure frame of \*Msuspend\fP and \*Mr7\fP is ! 1106: pointed at the word containing the saved \*Mfp\fP. ! 1107: .PP ! 1108: The high word to be copied is dependent upon the expression and generator ! 1109: environment of the suspending function. If the \*Mgfp\fP ! 1110: in the suspender's environment is not zero,\^ the word just below the ! 1111: generator frame marker is the highest word to be copied. If ! 1112: \*Mgfp\fP is zero,\^ the just word below the expression marker pointed at ! 1113: by \*Mefp\fP in the suspender's environment is the highest word to ! 1114: be copied. ! 1115: .PP ! 1116: The fact that the saved \*Mefp\fP and \*Mgfp\fP ! 1117: appear on the stack just below the \fInwords\fP word (referenced by ! 1118: \*M0(ap)\fP) is used to retrieve and test them. As in \*Mesusp\fP,\^ ! 1119: if the saved \*Mgfp\fP is non-zero,\^ ! 1120: .Ds ! 1121: .ft R ! 1122: saved \*Mgfp\fR - 12 ! 1123: .De ! 1124: is used for the lower bound,\^ otherwise ! 1125: .Ds ! 1126: .ft R ! 1127: saved \*Mefp\fR - 8 ! 1128: .De ! 1129: is the lower bound. \*Mr4\fP is pointed at the appropriate word on ! 1130: the upper end. As in \*Mesusp\fP,\^ \*Msp\fP is moved down to ! 1131: accommodate the region to be duplicated and the region is copied to ! 1132: the top of the stack using a \*Mmovc3\fP. ! 1133: .PP ! 1134: The saved \*Mgfp\fP in the duplicated procedure frame on the top of ! 1135: the stack must be replaced by the current value of \*Mgfp\fP. Finding the ! 1136: location of the saved \*Mgfp\fP is a little tricky. The distance ! 1137: between \*Mfp\fP and \*Map\fP in the duplicated frame is calculated ! 1138: by subtracting the \*Mfp\fP value from the \*Map\fP value and putting ! 1139: the result in \*Mr0\fP. The value in \*Mr0\fP represents the distance ! 1140: from the top of the stack to \*M0(ap)\fP. Adding the ! 1141: current \*Msp\fP (which points at the low word of the duplicated ! 1142: procedure frame) to \*Mr0\fP points \*Mr0\fP at the \fInwords\fP word ! 1143: of the new frame. \*Map\fP normally points at the \fInwords\fP word,\^ ! 1144: so \*Mr0\fP serves as a pseudo-\*Map\fP. It is known that the saved \*Mgfp\fP ! 1145: is the second word below the \fInwords\fP word and thus the new \*Mgfp\fP ! 1146: is stored in \*M\-8(r0)\fP,\^ replacing the old value. Thus,\^ when \*Msuspend\fP ! 1147: returns through the duplicated frame,\^ the value just stored is ! 1148: the restored value of \*Mgfp\fP. ! 1149: .PP ! 1150: A \*Mret\fP is executed to return from \*Msuspend\fP. This return uses ! 1151: the duplicated procedure frame and thus the duplicated frame is ! 1152: removed. The final result is that it looks like the original call to ! 1153: function has returned and ! 1154: the suspended value is left on the top of the stack. ! 1155: .ne 2i ! 1156: .NH 3 ! 1157: \*Mfunctions/display.c\fR ! 1158: .SH ! 1159: Overview ! 1160: .PP ! 1161: \*Mdisplay.c\fP implements the Icon function \*Mdisplay()\fP. ! 1162: \*Mdisplay\fP traces back through Icon procedure frames printing various ! 1163: sorts of information. Therefore,\^ some of the code in \*Mdisplay\fP ! 1164: is machine dependent. ! 1165: .SH ! 1166: Generic Operation ! 1167: .PP ! 1168: \*Mdisplay\fP makes one calculation that is machine dependent. The ! 1169: calculation is to take a frame whose address is contained in the ! 1170: variable \*Mfp\fP and calculate the address of the procedure ! 1171: descriptor in the frame that is pointed at by the \*Mfp\fP value ! 1172: saved in the frame that \*Mfp\fP references. ! 1173: .SH ! 1174: \*Mdisplay\fP on the VAX ! 1175: .PP ! 1176: \*Map\fP and \*Mfp\fP are restored from the frame referenced by ! 1177: \*Mfp\fP. The number of arguments to the procedure is contained in ! 1178: \*Map\^[1]\fP. This is loaded into the variable \*Mn\fP. The address ! 1179: of the procedure descriptor (\*(a0) is calculated using: ! 1180: .Ds ! 1181: dp = ap + 2 + 2*n ! 1182: .De ! 1183: Note that this is the same computation that is made at several points ! 1184: in the assembly language routines. As in \*Msweep\fP,\^ the calculations are ! 1185: being made using \*Mint *\fP variables and thus the constants ! 1186: represent word counts instead of byte counts as they do in the ! 1187: assembly language routines. ! 1188: ! 1189: .NH 3 ! 1190: \*Mrt/gcollect.s\fR ! 1191: .SH ! 1192: Overview ! 1193: .PP ! 1194: \*Mgcollect\fP is a simple routine that insures that garbage ! 1195: collections are done using the stack for the main co-expression. ! 1196: This done by saving certain values in the co-expression block of the ! 1197: current co-expression,\^ restoring values from the co-expression block ! 1198: for \*M&main\fP,\^ calling the garbage collector,\^ and then restoring ! 1199: the original values. ! 1200: \*Mgcollect\fP takes a single argument that is passed directly ! 1201: to \*Mcollect\fP. ! 1202: .PP ! 1203: If co-expressions are not implemented,\^ \*Mgcollect\fP need only ! 1204: consist of a call to \*Mcollect\fP,\^ being sure to pass its argument ! 1205: on through. ! 1206: .SH ! 1207: \*Mgcollect\fP on the VAX ! 1208: .PP ! 1209: \*Mr0\fP is pointed at the heap block for the current co-expression. ! 1210: \*Msp\fP,\^ \*Map\fP,\^ and \*M_boundary\fP are saved in the appropriate ! 1211: words of the block. ! 1212: .PP ! 1213: \*Mr0\fP is pointed at the heap block for \*M&main\fP,\^ the ! 1214: co-expression that is initially active. \*Msp\fP,\^ \*Map\fP,\^ and \*M_boundary\fP ! 1215: are restored from values saved in the block. ! 1216: .PP ! 1217: The argument to \*Mgcollect\fP is pushed on the stack,\^ and ! 1218: \*Mcollect\fP is called with one argument. ! 1219: .PP ! 1220: \*Mr0\fP is pointed at the heap block for the current co-expression ! 1221: and the \*Msp\fP,\^ \*Map\fP,\^ and \*M_boundary\fP values saved at the ! 1222: start of the routine are restored. ! 1223: .PP ! 1224: \*Mgcollect\fP returns. ! 1225: .NH 3 ! 1226: \*Mrt/sweep.c\fR ! 1227: .SH ! 1228: Overview ! 1229: .PP ! 1230: \*Msweep\fP is used during garbage collection to sweep a stack,\^ ! 1231: marking all the descriptors in the stack. \*Msweep\fP begins at ! 1232: the low word (the top) of a stack and moves up through the stack,\^ ! 1233: looking for descriptors and marking them. ! 1234: A stack is composed of four kinds of ! 1235: objects: descriptors,\^ and markers for procedure,\^ ! 1236: generator,\^ and expression frames. \*Msweep\fP uses knowledge of ! 1237: frame marker formats to skip over markers and to process the ! 1238: intervening descriptors. ! 1239: .PP ! 1240: Although \*Msweep\fP is written in C,\^ the knowledge of frame formats that it ! 1241: employs requires that it be written on a per-machine basis. ! 1242: .SH ! 1243: Generic Operation ! 1244: .PP ! 1245: There are three places that descriptors can appear on the stack: ! 1246: above an expression marker,\^ in an argument list,\^ and above an ! 1247: argument list. This can be considered as only two places because ! 1248: descriptors above the argument list can be considered as part of the ! 1249: argument list. ! 1250: .PP ! 1251: \*Msweep\fP is called with a single argument that is the address of ! 1252: the first word of a stack to mark. For purposes of discussion assume ! 1253: that \*Msp\fP references the stack word of current interest. ! 1254: \*Msweep\fP has a loop and each time through the loop,\^ one of four actions ! 1255: is taken based on the word that \*Msp\fP is pointing at: ! 1256: .Ls ! 1257: .Np ! 1258: If \*Msp\fP is pointing at the low word of a procedure frame marker,\^ \*Msp\fP ! 1259: is moved to point at the low word of the argument list of the ! 1260: procedure. \*Mefp\fP,\^ \*Mgfp\fP,\^ and \*Mpfp\fP are restored from the ! 1261: procedure frame. The number of arguments to the procedure is placed ! 1262: in \fInargs\fP. ! 1263: .Np ! 1264: If \*Msp\fP is pointing at the low word of a generator frame marker,\^ ! 1265: \*Mfp\fP is restored from the boundary word of the generator frame ! 1266: and \*Msp\fP is pointed at the low word of the frame referenced by \*Mfp\fP. ! 1267: .Np ! 1268: If \*Msp\fP is pointing at the low word of an expression frame ! 1269: marker,\^ \*Mgfp\fP and \*Mefp\fP are restored from the marker and ! 1270: \*Msp\fP is pointed at the word above the marker. ! 1271: .Np ! 1272: If none of the preceding conditions are true,\^ the word that \*Msp\fP ! 1273: points at is assumed to be the low word of a descriptor and that ! 1274: descriptor is marked. \*Msp\fP is incremented by 2 to move past ! 1275: the descriptor. If \fInargs\fP is not zero,\^ it is decremented. ! 1276: .Le ! 1277: .PP ! 1278: This process continues as long as \*Mfp\fP and \fInargs\fP are not ! 1279: both zero. \fInargs\fP is used so that the arguments in the very ! 1280: last frame are processed. The \*Mfp\fP at that point is 0. ! 1281: .SH ! 1282: \*Msweep\fP on the VAX ! 1283: .PP ! 1284: The routine \*Mgetap\fP is used by \*Msweep\fP. \*Mgetap\fP ! 1285: takes the address of a frame and returns the address of \*M0(ap)\fP ! 1286: in that frame. That is,\^ it returns the address of the start of the ! 1287: argument list for the frame. ! 1288: .PP ! 1289: Note that the C code uses \*Mint *\fP variables for the various ! 1290: calculations that are performed. Thus,\^ a calculation such as ! 1291: \*Mx + 2\fP is actually performing \*Mx + 8\fP. Similarly,\^ ! 1292: \*Mx\^[\-1]\fP would be the address \*Mx \- 4\fP. ! 1293: .PP ! 1294: \*Msweep\fP is called with a single parameter,\^ \*Mfp\fP. \*Mfp\fP ! 1295: holds the address of the frame with which to start the marking process. This ! 1296: address is a \*M_boundary\fP value,\^ and thus it ! 1297: points to the 0 (condition handler) word of a procedure frame. ! 1298: .PP ! 1299: \*Msp\fP is set to \*Mfp \- FRAMELIMIT\fP,\^ so that the first time ! 1300: throughout the loop,\^ the procedure frame on the top of the stack ! 1301: is processed. This gets the ball rolling,\^ so to speak. ! 1302: .PP ! 1303: \*Msweep\fP loops while \*Mfp\fP and \fInargs\fP are not both zero. ! 1304: It should be noted that the variables used in \*Msweep\fP have no ! 1305: connection to actual registers other than having the same name. ! 1306: .PP ! 1307: If \*Msp\fP is equal to \*Mfp \- FRAMELIMIT\fP,\^ it indicates that \*Msp\fP ! 1308: is pointing at a procedure frame marker. ! 1309: \*MFRAMELIMIT\fP is 2 on the VAX because ! 1310: there are two words,\^ the saved values of \*M_line\fP and \*M_file\fP,\^ ! 1311: that lie below the word in the frame that \*Mfp\fP points at. ! 1312: .PP ! 1313: When a procedure frame marker is encountered,\^ \*Mefp\fP and \*Mgfp\fP values ! 1314: are restored using negative displacements from \*Map\fP. \*Map\fP ! 1315: points at the \fInwords\fP word of the frame,\^ and \*Msp\fP is set to ! 1316: \*Map + 2\fP so that it points at the descriptor for the first ! 1317: argument. \fInargs\fP is loaded from the argument list. \*Map\fP ! 1318: and \*Mfp\fP are restored from the frame ! 1319: .PP ! 1320: A generator frame is indicated by \*Msp\fP being equal to \*Mgfp \- ! 1321: 3\fP. This is because there are three words,\^ \*M_line\fP,\^ ! 1322: \*M_file\fP,\^ and \*M_k_level\fP in the generator frame below the ! 1323: word that generator frame pointer points at. \*Mfp\fP is restored ! 1324: from the frame. A new \*Map\fP value is calculated from \*Mfp\fP ! 1325: using \*Mgetap\fP. \*Msp\fP is set to \*Mfp \- FRAMELIMIT\fP to cause ! 1326: recognition of a procedure frame the next time around. ! 1327: .PP ! 1328: An expression frame marker is indicated by \*Msp\fP being equal to \*Mefp \- ! 1329: 2\fP. \*Mefp\fP and \*Mgfp\fP are restored from the marker. ! 1330: \*Msp\fP is incremented by 3 which leaves it pointing at the word ! 1331: above the marker,\^ which may be a descriptor. ! 1332: .PP ! 1333: If \*Msp\fP suits none of the preceding criteria,\^ it is assumed to ! 1334: point at a descriptor. \*Mmark\fP is called with the value of \*Msp\fP as ! 1335: its argument. \*Msp\fP is incremented by 2 to move past the ! 1336: descriptor just marked. If \fInargs\fP is non-zero,\^ it is ! 1337: decremented. ! 1338: .bp ! 1339: .SH ! 1340: Acknowledgements ! 1341: .PP ! 1342: Ralph Griswold patiently suffered through a number of drafts of this ! 1343: document and made innumerable suggestions about grammar,\^ form,\^ and content. ! 1344: Steve Wampler graciously answered a number of questions about the internal ! 1345: workings of Icon and also made a number of comments on a late draft. ! 1346: .SH ! 1347: References ! 1348: .LP ! 1349: .IP 1. ! 1350: R. E. Griswold,\^ R. K. McConeghy,\^ and W. H. Mitchell,\^ \fIA Tour Through the ! 1351: C Implementation of Icon; Version 5.9\fR,\^ ! 1352: Technical Report 84-11, Department of Computer Science, The University of ! 1353: Arizona, August 1984. ! 1354: .IP 2. ! 1355: \fIVAX Architecture Handbook\fP,\^ Digital Equipment Corporation,\^ ! 1356: Maynard,\^ Massachusetts,\^ 1982. ! 1357: .IP 3. ! 1358: D. M. Ritchie,\^ A Tour Through the UNIX C Compiler,\^ \fIUNIX Programmers ! 1359: Manual,\^ Volume 2B\fP,\^ Bell Telephone Laboratories,\^ Inc.,\^ Murray Hill,\^ ! 1360: New Jersey,\^ 1979. ! 1361: .IP 4. ! 1362: S. C. Johnson,\^ A Tour Through the Portable C Compiler,\^ \fIUNIX Programmers ! 1363: Manual,\^ Volume 2B\fP,\^ Bell Telephone Laboratories,\^ Inc.,\^ Murray Hill,\^ ! 1364: New Jersey,\^ 1979. ! 1365: .IP 5. ! 1366: R. E. Griswold,\^ \fIAn Overview of the Porting Process for Version 5.9 ! 1367: of Icon\fR, ! 1368: Department of Computer Science,\^ The University of Arizona,\^ August 1984.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.