2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 2008,2009,2010
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
7 @node A Virtual Machine for Guile
8 @section A Virtual Machine for Guile
10 Guile has both an interpreter and a compiler. To a user, the difference
11 is transparent---interpreted and compiled procedures can call each other
14 The difference is that the compiler creates and interprets bytecode
15 for a custom virtual machine, instead of interpreting the
16 S-expressions directly. Loading and running compiled code is faster
17 than loading and running source code.
19 The virtual machine that does the bytecode interpretation is a part of
20 Guile itself. This section describes the nature of Guile's virtual
27 * Variables and the VM::
36 For a long time, Guile only had an interpreter. Guile's interpreter
37 operated directly on the S-expression representation of Scheme source
40 But while the interpreter was highly optimized and hand-tuned, it still
41 performs many needless computations during the course of evaluating an
42 expression. For example, application of a function to arguments
43 needlessly consed up the arguments in a list. Evaluation of an
44 expression always had to figure out what the car of the expression is --
45 a procedure, a memoized form, or something else. All values have to be
46 allocated on the heap. Et cetera.
48 The solution to this problem was to compile the higher-level language,
49 Scheme, into a lower-level language for which all of the checks and
50 dispatching have already been done---the code is instead stripped to
51 the bare minimum needed to ``do the job''.
53 The question becomes then, what low-level language to choose? There
54 are many options. We could compile to native code directly, but that
55 poses portability problems for Guile, as it is a highly cross-platform
58 So we want the performance gains that compilation provides, but we
59 also want to maintain the portability benefits of a single code path.
60 The obvious solution is to compile to a virtual machine that is
61 present on all Guile installations.
63 The easiest (and most fun) way to depend on a virtual machine is to
64 implement the virtual machine within Guile itself. This way the
65 virtual machine provides what Scheme needs (tail calls, multiple
66 values, @code{call/cc}) and can provide optimized inline instructions
67 for Guile (@code{cons}, @code{struct-ref}, etc.).
69 So this is what Guile does. The rest of this section describes that VM
70 that Guile implements, and the compiled procedures that run on it.
72 Before moving on, though, we should note that though we spoke of the
73 interpreter in the past tense, Guile still has an interpreter. The
74 difference is that before, it was Guile's main evaluator, and so was
75 implemented in highly optimized C; now, it is actually implemented in
76 Scheme, and compiled down to VM bytecode, just like any other program.
77 (There is still a C interpreter around, used to bootstrap the compiler,
78 but it is not normally used at runtime.)
80 The upside of implementing the interpreter in Scheme is that we preserve
81 tail calls and multiple-value handling between interpreted and compiled
82 code. The downside is that the interpreter in Guile 2.0 is slower than
83 the interpreter in 1.8. We hope the that the compiler's speed makes up
86 Also note that this decision to implement a bytecode compiler does not
87 preclude native compilation. We can compile from bytecode to native
88 code at runtime, or even do ahead of time compilation. More
89 possibilities are discussed in @ref{Extending the Compiler}.
92 @subsection VM Concepts
94 Compiled code is run by a virtual machine (VM). Each thread has its own
95 VM. When a compiled procedure is run, Guile looks up the virtual machine
96 for the current thread and executes the procedure using that VM.
98 Guile's virtual machine is a stack machine---that is, it has few
99 registers, and the instructions defined in the VM operate by pushing
100 and popping values from a stack.
102 Stack memory is exclusive to the virtual machine that owns it. In
103 addition to their stacks, virtual machines also have access to the
104 global memory (modules, global bindings, etc) that is shared among
105 other parts of Guile, including other VMs.
107 A VM has generic instructions, such as those to reference local
108 variables, and instructions designed to support Guile's languages --
109 mathematical instructions that support the entire numerical tower, an
110 inlined implementation of @code{cons}, etc.
112 The registers that a VM has are as follows:
115 @item ip - Instruction pointer
116 @item sp - Stack pointer
117 @item fp - Frame pointer
120 In other architectures, the instruction pointer is sometimes called
121 the ``program counter'' (pc). This set of registers is pretty typical
122 for stack machines; their exact meanings in the context of Guile's VM
123 are described in the next section.
125 @c wingo: The following is true, but I don't know in what context to
126 @c describe it. A documentation FIXME.
128 @c A VM may have one of three engines: reckless, regular, or debugging.
129 @c Reckless engine is fastest but dangerous. Regular engine is normally
130 @c fail-safe and reasonably fast. Debugging engine is safest and
131 @c functional but very slow.
133 @c (Actually we have just a regular and a debugging engine; normally
134 @c we use the latter, it's almost as fast as the ``regular'' engine.)
137 @subsection Stack Layout
139 While not strictly necessary to understand how to work with the VM, it
140 is instructive and sometimes entertaining to consider the structure of
143 Logically speaking, a VM stack is composed of ``frames''. Each frame
144 corresponds to the application of one compiled procedure, and contains
145 storage space for arguments, local variables, intermediate values, and
146 some bookkeeping information (such as what to do after the frame
149 While the compiler is free to do whatever it wants to, as long as the
150 semantics of a computation are preserved, in practice every time you
151 call a function, a new frame is created. (The notable exception of
152 course is the tail call case, @pxref{Tail Calls}.)
154 Within a frame, you have the data associated with the function
155 application itself, which is of a fixed size, and the stack space for
156 intermediate values. Sometimes only the former is referred to as the
157 ``frame'', and the latter is the ``stack'', although all pending
158 application frames can have some intermediate computations interleaved
161 The structure of the fixed part of an application frame is as follows:
166 | Intermed. val. 0 | <- fp + bp->nargs + bp->nlocs = SCM_FRAME_UPPER_ADDRESS (fp)
169 | Local variable 0 | <- fp + bp->nargs
172 | Program | <- fp - 1
176 | Dynamic link | <- fp - 4 = SCM_FRAME_DATA_ADDRESS (fp) = SCM_FRAME_LOWER_ADDRESS (fp)
181 In the above drawing, the stack grows upward. The intermediate values
182 stored in the application of this frame are stored above
183 @code{SCM_FRAME_UPPER_ADDRESS (fp)}. @code{bp} refers to the
184 @code{struct scm_objcode} data associated with the program at
185 @code{fp - 1}. @code{nargs} and @code{nlocs} are properties of the
186 compiled procedure, which will be discussed later.
188 The individual fields of the frame are as follows:
192 The @code{ip} that was in effect before this program was applied. When
193 we return from this activation frame, we will jump back to this
196 @item MV return address
197 The @code{ip} to return to if this application returns multiple
198 values. For continuations that only accept one value, this value will
199 be @code{NULL}; for others, it will be an @code{ip} that points to a
200 multiple-value return address in the calling code. That code will
201 expect the top value on the stack to be an integer---the number of
202 values being returned---and that below that integer there are the
203 values being returned.
206 This is the @code{fp} in effect before this program was applied. In
207 effect, this and the return address are the registers that are always
208 ``saved''. The dynamic link links the current frame to the previous
209 frame; computing a stack trace involves traversing these frames.
211 @item Local variable @var{n}
212 Lambda-local variables that are all allocated as part of the frame.
213 This makes access to variables very cheap.
215 @item Argument @var{n}
216 The calling convention of the VM requires arguments of a function
217 application to be pushed on the stack, and here they are. References
218 to arguments dispatch to these locations on the stack.
221 This is the program being applied. For more information on how
222 programs are implemented, @xref{VM Programs}.
225 @node Variables and the VM
226 @subsection Variables and the VM
228 Consider the following Scheme code as an example:
232 (lambda (b) (list foo a b)))
235 Within the lambda expression, @code{foo} is a top-level variable, @code{a} is a
236 lexically captured variable, and @code{b} is a local variable.
238 Another way to refer to @code{a} and @code{b} is to say that @code{a}
239 is a ``free'' variable, since it is not defined within the lambda, and
240 @code{b} is a ``bound'' variable. These are the terms used in the
241 @dfn{lambda calculus}, a mathematical notation for describing
242 functions. The lambda calculus is useful because it allows one to
243 prove statements about functions. It is especially good at describing
244 scope relations, and it is for that reason that we mention it here.
246 Guile allocates all variables on the stack. When a lexically enclosed
247 procedure with free variables---a @dfn{closure}---is created, it copies
248 those variables into its free variable vector. References to free
249 variables are then redirected through the free variable vector.
251 If a variable is ever @code{set!}, however, it will need to be
252 heap-allocated instead of stack-allocated, so that different closures
253 that capture the same variable can see the same value. Also, this
254 allows continuations to capture a reference to the variable, instead
255 of to its value at one point in time. For these reasons, @code{set!}
256 variables are allocated in ``boxes''---actually, in variable cells.
257 @xref{Variables}, for more information. References to @code{set!}
258 variables are indirected through the boxes.
260 Thus perhaps counterintuitively, what would seem ``closer to the
261 metal'', viz @code{set!}, actually forces an extra memory allocation
264 Going back to our example, @code{b} may be allocated on the stack, as
267 @code{a} may also be allocated on the stack, as it too is never
268 mutated. Within the enclosed lambda, its value will be copied into
269 (and referenced from) the free variables vector.
271 @code{foo} is a top-level variable, because @code{foo} is not
272 lexically bound in this example.
275 @subsection Compiled Procedures are VM Programs
277 By default, when you enter in expressions at Guile's REPL, they are
278 first compiled to VM object code, then that VM object code is executed
279 to produce a value. If the expression evaluates to a procedure, the
280 result of this process is a compiled procedure.
282 A compiled procedure is a compound object, consisting of its bytecode,
283 a reference to any captured lexical variables, an object array, and
284 some metadata such as the procedure's arity, name, and documentation.
285 You can pick apart these pieces with the accessors in @code{(system vm
286 program)}. @xref{Compiled Procedures}, for a full API reference.
290 The object array of a compiled procedure, also known as the
291 @dfn{object table}, holds all Scheme objects whose values are known
292 not to change across invocations of the procedure: constant strings,
293 symbols, etc. The object table of a program is initialized right
294 before a program is loaded with @code{load-program}.
295 @xref{Loading Instructions}, for more information.
297 Variable objects are one such type of constant object: when a global
298 binding is defined, a variable object is associated to it and that
299 object will remain constant over time, even if the value bound to it
300 changes. Therefore, toplevel bindings only need to be looked up once.
301 Thereafter, references to the corresponding toplevel variables from
302 within the program are then performed via the @code{toplevel-ref}
303 instruction, which uses the object vector, and are almost as fast as
304 local variable references.
306 We can see how these concepts tie together by disassembling the
307 @code{foo} function we defined earlier to see what is going on:
310 scheme@@(guile-user)> (define (foo a) (lambda (b) (list foo a b)))
311 scheme@@(guile-user)> ,x foo
312 Disassembly of #<procedure foo (a)>:
314 0 (assert-nargs-ee 0 1)
315 3 (reserve-locals 0 1)
316 6 (object-ref 1) ;; #<procedure 85bfec0 at <current input>:0:16 (b)>
317 8 (local-ref 0) ;; `a'
318 10 (make-closure 0 1)
321 ----------------------------------------
322 Disassembly of #<procedure 85bfec0 at <current input>:0:16 (b)>:
324 0 (assert-nargs-ee 0 1)
325 3 (reserve-locals 0 1)
326 6 (toplevel-ref 1) ;; `foo'
327 8 (free-ref 0) ;; (closure variable)
328 10 (local-ref 0) ;; `b'
329 12 (list 0 3) ;; 3 elements at (unknown file):0:28
333 First there's some prelude, where @code{foo} checks that it was called with only
334 1 argument. Then at @code{ip} 6, we load up the compiled lambda. @code{Ip} 8
335 loads up `a', so that it can be captured into a closure by at @code{ip}
336 10---binding code (from the compiled lambda) with data (the free-variable
337 vector). Finally we return the closure.
339 The second stanza disassembles the compiled lambda. After the prelude, we note
340 that toplevel variables are resolved relative to the module that was current
341 when the procedure was created. This lookup occurs lazily, at the first time the
342 variable is actually referenced, and the location of the lookup is cached so
343 that future references are very cheap. @xref{Environment Control Instructions},
346 Then we see a reference to a free variable, corresponding to @code{a}. The
347 disassembler doesn't have enough information to give a name to that variable, so
348 it just marks it as being a ``closure variable''. Finally we see the reference
349 to @code{b}, then the @code{list} opcode, an inline implementation of the
350 @code{list} scheme routine.
352 @node Instruction Set
353 @subsection Instruction Set
355 There are about 150 instructions in Guile's virtual machine. These
356 instructions represent atomic units of a program's execution. Ideally,
357 they perform one task without conditional branches, then dispatch to
358 the next instruction in the stream.
360 Instructions themselves are one byte long. Some instructions take
361 parameters, which follow the instruction byte in the instruction
364 Sometimes the compiler can figure out that it is compiling a special
365 case that can be run more efficiently. So, for example, while Guile
366 offers a generic test-and-branch instruction, it also offers specific
367 instructions for special cases, so that the following cases all have
368 their own test-and-branch instructions:
372 (if (not pred) then else)
373 (if (null? l) then else)
374 (if (not (null? l)) then else)
377 In addition, some Scheme primitives have their own inline
378 implementations, e.g. @code{cons}, and @code{list}, as we saw in the
381 So Guile's instruction set is a @emph{complete} instruction set, in
382 that it provides the instructions that are suited to the problem, and
383 is not concerned with making a minimal, orthogonal set of
384 instructions. More instructions may be added over time.
387 * Environment Control Instructions::
388 * Branch Instructions::
389 * Loading Instructions::
390 * Procedural Instructions::
391 * Data Control Instructions::
392 * Miscellaneous Instructions::
393 * Inlined Scheme Instructions::
394 * Inlined Mathematical Instructions::
395 * Inlined Bytevector Instructions::
398 @node Environment Control Instructions
399 @subsubsection Environment Control Instructions
401 These instructions access and mutate the environment of a compiled
402 procedure---the local bindings, the free (captured) bindings, and the
405 Some of these instructions have @code{long-} variants, the difference
406 being that they take 16-bit arguments, encoded in big-endianness,
407 instead of the normal 8-bit range.
409 @deffn Instruction local-ref index
410 @deffnx Instruction long-local-ref index
411 Push onto the stack the value of the local variable located at
412 @var{index} within the current stack frame.
414 Note that arguments and local variables are all in one block. Thus the
415 first argument, if any, is at index 0, and local bindings follow the
419 @deffn Instruction local-set index
420 @deffnx Instruction long-local-ref index
421 Pop the Scheme object located on top of the stack and make it the new
422 value of the local variable located at @var{index} within the current
426 @deffn Instruction free-ref index
427 Push the value of the captured variable located at position
428 @var{index} within the program's vector of captured variables.
431 @deffn Instruction free-boxed-ref index
432 @deffnx Instruction free-boxed-set index
433 Get or set a boxed free variable. Note that there is no free-set
434 instruction, as variables that are @code{set!} must be boxed.
436 These instructions assume that the value at position @var{index} in
437 the free variables vector is a variable.
440 @deffn Instruction make-closure
441 Pop a vector and a program object off the stack, in that order, and
442 push a new program object with the given free variables vector. The
443 new program object shares state with the original program.
445 At the time of this writing, the space overhead of closures is 4 words
449 @deffn Instruction fix-closure index
450 Pop a vector off the stack, and set it as the @var{index}th local
451 variable's free variable vector. The @var{index}th local variable is
452 assumed to be a procedure.
454 This instruction is part of a hack for allocating mutually recursive
455 procedures. The hack is to first perform a @code{local-set} for all of
456 the recursive procedures, then fix up the procedures' free variable
457 bindings in place. This allows most @code{letrec}-bound procedures to
458 be allocated unboxed on the stack.
460 One could of course do a @code{local-ref}, then @code{make-closure},
461 then @code{local-set}, but this macroinstruction helps to speed up the
465 @deffn Instruction box index
466 Pop a value off the stack, and set the @var{index}nth local variable
467 to a box containing that value. A shortcut for @code{make-variable}
468 then @code{local-set}, used when binding boxed variables.
471 @deffn Instruction empty-box index
472 Set the @var{indext}h local variable to a box containing a variable
473 whose value is unbound. Used when compiling some @code{letrec}
477 @deffn Instruction toplevel-ref index
478 @deffnx Instruction long-toplevel-ref index
479 Push the value of the toplevel binding whose location is stored in at
480 position @var{index} in the object table.
482 Initially, a cell in the object table that is used by
483 @code{toplevel-ref} is initialized to one of two forms. The normal
484 case is that the cell holds a symbol, whose binding will be looked up
485 relative to the module that was current when the current program was
488 Alternately, the lookup may be performed relative to a particular
489 module, determined at compile-time (e.g. via @code{@@} or
490 @code{@@@@}). In that case, the cell in the object table holds a list:
491 @code{(@var{modname} @var{sym} @var{public?})}. The symbol @var{sym}
492 will be looked up in the module named @var{modname} (a list of
493 symbols). The lookup will be performed against the module's public
494 interface, unless @var{public?} is @code{#f}, which it is for example
495 when compiling @code{@@@@}.
497 In any case, if the symbol is unbound, an error is signalled.
498 Otherwise the initial form is replaced with the looked-up variable, an
499 in-place mutation of the object table. This mechanism provides for
500 lazy variable resolution, and an important cached fast-path once the
501 variable has been successfully resolved.
503 This instruction pushes the value of the variable onto the stack.
506 @deffn Instruction toplevel-set index
507 @deffnx Instruction long-toplevel-set index
508 Pop a value off the stack, and set it as the value of the toplevel
509 variable stored at @var{index} in the object table. If the variable
510 has not yet been looked up, we do the lookup as in
514 @deffn Instruction define
515 Pop a symbol and a value from the stack, in that order. Look up its
516 binding in the current toplevel environment, creating the binding if
517 necessary. Set the variable to the value.
520 @deffn Instruction link-now
521 Pop a value, @var{x}, from the stack. Look up the binding for @var{x},
522 according to the rules for @code{toplevel-ref}, and push that variable
523 on the stack. If the lookup fails, an error will be signalled.
525 This instruction is mostly used when loading programs, because it can
526 do toplevel variable lookups without an object vector.
529 @deffn Instruction variable-ref
530 Dereference the variable object which is on top of the stack and
531 replace it by the value of the variable it represents.
534 @deffn Instruction variable-set
535 Pop off two objects from the stack, a variable and a value, and set
536 the variable to the value.
539 @deffn Instruction make-variable
540 Replace the top object on the stack with a variable containing it.
541 Used in some circumstances when compiling @code{letrec} expressions.
544 @deffn Instruction object-ref n
545 @deffnx Instruction long-object-ref n
546 Push @var{n}th value from the current program's object vector. The
547 ``long'' variant has a 16-bit index instead of an 8-bit index.
550 @node Branch Instructions
551 @subsubsection Branch Instructions
553 All the conditional branch instructions described below work in the
557 @item They pop off Scheme object(s) located on the stack for use in the
559 @item If the condition is true, then the instruction pointer is
560 increased by the offset passed as an argument to the branch
562 @item Program execution proceeds with the next instruction (that is,
563 the one to which the instruction pointer points).
566 Note that the offset passed to the instruction is encoded as three 8-bit
567 integers, in big-endian order, effectively giving Guile a 24-bit
568 relative address space.
570 @deffn Instruction br offset
571 Jump to @var{offset}. No values are popped.
574 @deffn Instruction br-if offset
575 Jump to @var{offset} if the object on the stack is not false.
578 @deffn Instruction br-if-not offset
579 Jump to @var{offset} if the object on the stack is false.
582 @deffn Instruction br-if-eq offset
583 Jump to @var{offset} if the two objects located on the stack are
584 equal in the sense of @var{eq?}. Note that, for this instruction, the
585 stack pointer is decremented by two Scheme objects instead of only
589 @deffn Instruction br-if-not-eq offset
590 Same as @var{br-if-eq} for non-@code{eq?} objects.
593 @deffn Instruction br-if-null offset
594 Jump to @var{offset} if the object on the stack is @code{'()}.
597 @deffn Instruction br-if-not-null offset
598 Jump to @var{offset} if the object on the stack is not @code{'()}.
602 @node Loading Instructions
603 @subsubsection Loading Instructions
605 In addition to VM instructions, an instruction stream may contain
606 variable-length data embedded within it. This data is always preceded
607 by special loading instructions, which interpret the data and advance
608 the instruction pointer to the next VM instruction.
610 All of these loading instructions have a @code{length} parameter,
611 indicating the size of the embedded data, in bytes. The length itself
612 is encoded in 3 bytes.
614 @deffn Instruction load-number length
615 Load an arbitrary number from the instruction stream. The number is
616 embedded in the stream as a string.
618 @deffn Instruction load-string length
619 Load a string from the instruction stream. The string is assumed to be
620 encoded in the ``latin1'' locale.
622 @deffn Instruction load-wide-string length
623 Load a UTF-32 string from the instruction stream. @var{length} is the
624 length in bytes, not in codepoints
626 @deffn Instruction load-symbol length
627 Load a symbol from the instruction stream. The symbol is assumed to be
628 encoded in the ``latin1'' locale. Symbols backed by wide strings may
629 be loaded via @code{load-wide-string} then @code{make-symbol}.
631 @deffn Instruction load-array length
632 Load a uniform array from the instruction stream. The shape and type
633 of the array are popped off the stack, in that order.
636 @deffn Instruction load-program
637 Load bytecode from the instruction stream, and push a compiled
640 This instruction pops one value from the stack: the program's object
641 table, as a vector, or @code{#f} in the case that the program has no
642 object table. A program that does not reference toplevel bindings and
643 does not use @code{object-ref} does not need an object table.
645 This instruction is unlike the rest of the loading instructions,
646 because instead of parsing its data, it directly maps the instruction
647 stream onto a C structure, @code{struct scm_objcode}. @xref{Bytecode
648 and Objcode}, for more information.
650 The resulting compiled procedure will not have any free variables
651 captured, so it may be loaded only once but used many times to create
655 @node Procedural Instructions
656 @subsubsection Procedural Instructions
658 @deffn Instructions new-frame
659 Push a new frame on the stack, reserving space for the dynamic link,
660 return address, and the multiple-values return address. The frame
661 pointer is not yet updated, because the frame is not yet active -- it
662 has to be patched by a @code{call} instruction to get the return
666 @deffn Instruction call nargs
667 Call the procedure located at @code{sp[-nargs]} with the @var{nargs}
668 arguments located from @code{sp[-nargs + 1]} to @code{sp[0]}.
670 This instruction requires that a new frame be pushed on the stack
671 before the procedure, via @code{new-frame}. @xref{Stack Layout}, for
672 more information. It patches up that frame with the current @code{ip}
673 as the return address, then dispatches to the first instruction in the
674 called procedure, relying on the called procedure to return one value
675 to the newly-created continuation. Because the new frame pointer will
676 point to sp[-nargs + 1], the arguments don't have to be shuffled
677 around -- they are already in place.
679 For non-compiled procedures (continuations, primitives, and
680 interpreted procedures), @code{call} will pop the frame, procedure,
681 and arguments off the stack, and push the result of calling
685 @deffn Instruction tail-call nargs
686 Like @code{call}, but reusing the current continuation. This
687 instruction implements tail calls as required by RnRS.
689 For compiled procedures, that means that @code{tail-call} simply
690 shuffles down the procedure and arguments to the current stack frame.
692 For non-VM procedures, the result is the same, but the current VM
693 invocation remains on the C stack. True tail calls are not currently
694 possible between compiled and non-compiled procedures.
697 @deffn Instruction apply nargs
698 @deffnx Instruction tail-apply nargs
699 Like @code{call} and @code{tail-call}, except that the top item on the
700 stack must be a list. The elements of that list are then pushed on the
701 stack and treated as additional arguments, replacing the list itself,
702 then the procedure is invoked as usual.
705 @deffn Instruction call/nargs
706 @deffnx Instruction tail-call/nargs
707 These are like @code{call} and @code{tail-call}, except they take the
708 number of arguments from the stack instead of the instruction stream.
709 These instructions are used in the implementation of multiple value
710 returns, where the actual number of values is pushed on the stack.
713 @deffn Instruction mv-call nargs offset
714 Like @code{call}, except that a multiple-value continuation is created
715 in addition to a single-value continuation.
717 The offset (a two-byte value) is an offset within the instruction
718 stream; the multiple-value return address in the new frame
719 (@pxref{Stack Layout}) will be set to the normal return address plus
720 this offset. Instructions at that offset will expect the top value of
721 the stack to be the number of values, and below that values
722 themselves, pushed separately.
725 @deffn Instruction return
726 Free the program's frame, returning the top value from the stack to
727 the current continuation. (The stack should have exactly one value on
730 Specifically, the @code{sp} is decremented to one below the current
731 @code{fp}, the @code{ip} is reset to the current return address, the
732 @code{fp} is reset to the value of the current dynamic link, and then
733 the top item on the stack (formerly the procedure being applied) is
734 set to the returned value.
737 @deffn Instruction return/values nvalues
738 Return the top @var{nvalues} to the current continuation.
740 If the current continuation is a multiple-value continuation,
741 @code{return/values} pushes the number of values on the stack, then
742 returns as in @code{return}, but to the multiple-value return address.
744 Otherwise if the current continuation accepts only one value, i.e. the
745 multiple-value return address is @code{NULL}, then we assume the user
746 only wants one value, and we give them the first one. If there are no
747 values, an error is signaled.
750 @deffn Instruction return/values* nvalues
751 Like a combination of @code{apply} and @code{return/values}, in which
752 the top value on the stack is interpreted as a list of additional
753 values. This is an optimization for the common @code{(apply values
757 @deffn Instruction truncate-values nbinds nrest
758 Used in multiple-value continuations, this instruction takes the
759 values that are on the stack (including the number-of-values marker)
760 and truncates them for a binding construct.
762 For example, a call to @code{(receive (x y . z) (foo) ...)} would,
763 logically speaking, pop off the values returned from @code{(foo)} and
764 push them as three values, corresponding to @code{x}, @code{y}, and
765 @code{z}. In that case, @var{nbinds} would be 3, and @var{nrest} would
766 be 1 (to indicate that one of the bindings was a rest argument).
768 Signals an error if there is an insufficient number of values.
771 @deffn Instruction call/cc
772 @deffnx Instruction tail-call/cc
773 Capture the current continuation, and then call (or tail-call) the
774 procedure on the top of the stack, with the continuation as the
777 @code{call/cc} does not require a @code{new-frame} to be pushed on the
778 stack, as @code{call} does, because it needs to capture the stack
779 before the frame is pushed.
781 Both the VM continuation and the C continuation are captured.
784 @node Data Control Instructions
785 @subsubsection Data Control Instructions
787 These instructions push simple immediate values onto the stack, or
788 manipulate lists and vectors on the stack.
790 @deffn Instruction make-int8 value
791 Push @var{value}, an 8-bit integer, onto the stack.
794 @deffn Instruction make-int8:0
795 Push the immediate value @code{0} onto the stack.
798 @deffn Instruction make-int8:1
799 Push the immediate value @code{1} onto the stack.
802 @deffn Instruction make-int16 value
803 Push @var{value}, a 16-bit integer, onto the stack.
806 @deffn Instruction make-uint64 value
807 Push @var{value}, an unsigned 64-bit integer, onto the stack. The
808 value is encoded in 8 bytes, most significant byte first (big-endian).
811 @deffn Instruction make-int64 value
812 Push @var{value}, a signed 64-bit integer, onto the stack. The value
813 is encoded in 8 bytes, most significant byte first (big-endian), in
814 twos-complement arithmetic.
817 @deffn Instruction make-false
818 Push @code{#f} onto the stack.
821 @deffn Instruction make-true
822 Push @code{#t} onto the stack.
825 @deffn Instruction make-nil
826 Push @code{#nil} onto the stack.
829 @deffn Instruction make-eol
830 Push @code{'()} onto the stack.
833 @deffn Instruction make-char8 value
834 Push @var{value}, an 8-bit character, onto the stack.
837 @deffn Instruction make-char32 value
838 Push @var{value}, an 32-bit character, onto the stack. The value is
839 encoded in big-endian order.
842 @deffn Instruction make-symbol
843 Pops a string off the stack, and pushes a symbol.
846 @deffn Instruction make-keyword value
847 Pops a symbol off the stack, and pushes a keyword.
850 @deffn Instruction list n
851 Pops off the top @var{n} values off of the stack, consing them up into
852 a list, then pushes that list on the stack. What was the topmost value
853 will be the last element in the list. @var{n} is a two-byte value,
854 most significant byte first.
857 @deffn Instruction vector n
858 Create and fill a vector with the top @var{n} values from the stack,
859 popping off those values and pushing on the resulting vector. @var{n}
860 is a two-byte value, like in @code{vector}.
863 @node Miscellaneous Instructions
864 @subsubsection Miscellaneous Instructions
866 @deffn Instruction nop
867 Does nothing! Used for padding other instructions to certain
871 @deffn Instruction halt
872 Exits the VM, returning a SCM value. Normally, this instruction is
873 only part of the ``bootstrap program'', a program run when a virtual
874 machine is first entered; compiled Scheme procedures will not contain
877 If multiple values have been returned, the SCM value will be a
878 multiple-values object (@pxref{Multiple Values}).
881 @deffn Instruction break
882 Does nothing, but invokes the break hook.
885 @deffn Instruction drop
886 Pops off the top value from the stack, throwing it away.
889 @deffn Instruction dup
890 Re-pushes the top value onto the stack.
893 @deffn Instruction void
894 Pushes ``the unspecified value'' onto the stack.
897 @node Inlined Scheme Instructions
898 @subsubsection Inlined Scheme Instructions
900 The Scheme compiler can recognize the application of standard Scheme
901 procedures. It tries to inline these small operations to avoid the
902 overhead of creating new stack frames.
904 Since most of these operations are historically implemented as C
905 primitives, not inlining them would entail constantly calling out from
906 the VM to the interpreter, which has some costs---registers must be
907 saved, the interpreter has to dispatch, called procedures have to do
908 much typechecking, etc. It's much more efficient to inline these
909 operations in the virtual machine itself.
911 All of these instructions pop their arguments from the stack and push
912 their results, and take no parameters from the instruction stream.
913 Thus, unlike in the previous sections, these instruction definitions
914 show stack parameters instead of parameters from the instruction
917 @deffn Instruction not x
918 @deffnx Instruction not-not x
919 @deffnx Instruction eq? x y
920 @deffnx Instruction not-eq? x y
921 @deffnx Instruction null?
922 @deffnx Instruction not-null?
923 @deffnx Instruction eqv? x y
924 @deffnx Instruction equal? x y
925 @deffnx Instruction pair? x y
926 @deffnx Instruction list? x
927 @deffnx Instruction set-car! pair x
928 @deffnx Instruction set-cdr! pair x
929 @deffnx Instruction slot-ref struct n
930 @deffnx Instruction slot-set struct n x
931 @deffnx Instruction cons x y
932 @deffnx Instruction car x
933 @deffnx Instruction cdr x
934 @deffnx Instruction vector-ref x y
935 @deffnx Instruction vector-set x n y
936 Inlined implementations of their Scheme equivalents.
939 Note that @code{caddr} and friends compile to a series of @code{car}
940 and @code{cdr} instructions.
942 @node Inlined Mathematical Instructions
943 @subsubsection Inlined Mathematical Instructions
945 Inlining mathematical operations has the obvious advantage of handling
946 fixnums without function calls or allocations. The trick, of course,
947 is knowing when the result of an operation will be a fixnum, and there
948 might be a couple bugs here.
950 More instructions could be added here over time.
952 As in the previous section, the definitions below show stack
953 parameters instead of instruction stream parameters.
955 @deffn Instruction add x y
956 @deffnx Instruction add1 x
957 @deffnx Instruction sub x y
958 @deffnx Instruction sub1 x
959 @deffnx Instruction mul x y
960 @deffnx Instruction div x y
961 @deffnx Instruction quo x y
962 @deffnx Instruction rem x y
963 @deffnx Instruction mod x y
964 @deffnx Instruction ee? x y
965 @deffnx Instruction lt? x y
966 @deffnx Instruction gt? x y
967 @deffnx Instruction le? x y
968 @deffnx Instruction ge? x y
969 Inlined implementations of the corresponding mathematical operations.
972 @node Inlined Bytevector Instructions
973 @subsubsection Inlined Bytevector Instructions
975 Bytevector operations correspond closely to what the current hardware
976 can do, so it makes sense to inline them to VM instructions, providing
977 a clear path for eventual native compilation. Without this, Scheme
978 programs would need other primitives for accessing raw bytes -- but
979 these primitives are as good as any.
981 As in the previous section, the definitions below show stack
982 parameters instead of instruction stream parameters.
984 The multibyte formats (@code{u16}, @code{f64}, etc) take an extra
985 endianness argument. Only aligned native accesses are currently
986 fast-pathed in Guile's VM.
988 @deffn Instruction bv-u8-ref bv n
989 @deffnx Instruction bv-s8-ref bv n
990 @deffnx Instruction bv-u16-native-ref bv n
991 @deffnx Instruction bv-s16-native-ref bv n
992 @deffnx Instruction bv-u32-native-ref bv n
993 @deffnx Instruction bv-s32-native-ref bv n
994 @deffnx Instruction bv-u64-native-ref bv n
995 @deffnx Instruction bv-s64-native-ref bv n
996 @deffnx Instruction bv-f32-native-ref bv n
997 @deffnx Instruction bv-f64-native-ref bv n
998 @deffnx Instruction bv-u16-ref bv n endianness
999 @deffnx Instruction bv-s16-ref bv n endianness
1000 @deffnx Instruction bv-u32-ref bv n endianness
1001 @deffnx Instruction bv-s32-ref bv n endianness
1002 @deffnx Instruction bv-u64-ref bv n endianness
1003 @deffnx Instruction bv-s64-ref bv n endianness
1004 @deffnx Instruction bv-f32-ref bv n endianness
1005 @deffnx Instruction bv-f64-ref bv n endianness
1006 @deffnx Instruction bv-u8-set bv n val
1007 @deffnx Instruction bv-s8-set bv n val
1008 @deffnx Instruction bv-u16-native-set bv n val
1009 @deffnx Instruction bv-s16-native-set bv n val
1010 @deffnx Instruction bv-u32-native-set bv n val
1011 @deffnx Instruction bv-s32-native-set bv n val
1012 @deffnx Instruction bv-u64-native-set bv n val
1013 @deffnx Instruction bv-s64-native-set bv n val
1014 @deffnx Instruction bv-f32-native-set bv n val
1015 @deffnx Instruction bv-f64-native-set bv n val
1016 @deffnx Instruction bv-u16-set bv n val endianness
1017 @deffnx Instruction bv-s16-set bv n val endianness
1018 @deffnx Instruction bv-u32-set bv n val endianness
1019 @deffnx Instruction bv-s32-set bv n val endianness
1020 @deffnx Instruction bv-u64-set bv n val endianness
1021 @deffnx Instruction bv-s64-set bv n val endianness
1022 @deffnx Instruction bv-f32-set bv n val endianness
1023 @deffnx Instruction bv-f64-set bv n val endianness
1024 Inlined implementations of the corresponding bytevector operations.