2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 2008,2009,2010,2011,2013
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::
29 * Object File Format::
37 For a long time, Guile only had an interpreter. Guile's interpreter
38 operated directly on the S-expression representation of Scheme source
41 But while the interpreter was highly optimized and hand-tuned, it still
42 performed many needless computations during the course of evaluating an
43 expression. For example, application of a function to arguments
44 needlessly consed up the arguments in a list. Evaluation of an
45 expression always had to figure out what the car of the expression is --
46 a procedure, a memoized form, or something else. All values have to be
47 allocated on the heap. Et cetera.
49 The solution to this problem was to compile the higher-level language,
50 Scheme, into a lower-level language for which all of the checks and
51 dispatching have already been done---the code is instead stripped to
52 the bare minimum needed to ``do the job''.
54 The question becomes then, what low-level language to choose? There
55 are many options. We could compile to native code directly, but that
56 poses portability problems for Guile, as it is a highly cross-platform
59 So we want the performance gains that compilation provides, but we
60 also want to maintain the portability benefits of a single code path.
61 The obvious solution is to compile to a virtual machine that is
62 present on all Guile installations.
64 The easiest (and most fun) way to depend on a virtual machine is to
65 implement the virtual machine within Guile itself. This way the
66 virtual machine provides what Scheme needs (tail calls, multiple
67 values, @code{call/cc}) and can provide optimized inline instructions
68 for Guile (@code{cons}, @code{struct-ref}, etc.).
70 So this is what Guile does. The rest of this section describes that VM
71 that Guile implements, and the compiled procedures that run on it.
73 Before moving on, though, we should note that though we spoke of the
74 interpreter in the past tense, Guile still has an interpreter. The
75 difference is that before, it was Guile's main evaluator, and so was
76 implemented in highly optimized C; now, it is actually implemented in
77 Scheme, and compiled down to VM bytecode, just like any other program.
78 (There is still a C interpreter around, used to bootstrap the compiler,
79 but it is not normally used at runtime.)
81 The upside of implementing the interpreter in Scheme is that we preserve
82 tail calls and multiple-value handling between interpreted and compiled
83 code. The downside is that the interpreter in Guile 2.2 is still slower
84 than the interpreter in 1.8. We hope the that the compiler's speed makes
85 up for the loss. In any case, once we have native compilation for
86 Scheme code, we expect the new self-hosted interpreter to beat the old
87 hand-tuned C implementation.
89 Also note that this decision to implement a bytecode compiler does not
90 preclude native compilation. We can compile from bytecode to native
91 code at runtime, or even do ahead of time compilation. More
92 possibilities are discussed in @ref{Extending the Compiler}.
95 @subsection VM Concepts
97 Compiled code is run by a virtual machine (VM). Each thread has its own
98 VM. The virtual machine executes the sequence of instructions in a
101 Each VM instruction starts by indicating which operation it is, and then
102 follows by encoding its source and destination operands. Each procedure
103 declares that it has some number of local variables, including the
104 function arguments. These local variables form the available operands
105 of the procedure, and are accessed by index.
107 The local variables for a procedure are stored on a stack. Calling a
108 procedure typically enlarges the stack, and returning from a procedure
109 shrinks it. Stack memory is exclusive to the virtual machine that owns
112 In addition to their stacks, virtual machines also have access to the
113 global memory (modules, global bindings, etc) that is shared among other
114 parts of Guile, including other VMs.
116 The registers that a VM has are as follows:
119 @item ip - Instruction pointer
120 @item sp - Stack pointer
121 @item fp - Frame pointer
124 In other architectures, the instruction pointer is sometimes called the
125 ``program counter'' (pc). This set of registers is pretty typical for
126 virtual machines; their exact meanings in the context of Guile's VM are
127 described in the next section.
130 @subsection Stack Layout
132 The stack of Guile's virtual machine is composed of @dfn{frames}. Each
133 frame corresponds to the application of one compiled procedure, and
134 contains storage space for arguments, local variables, and some
135 bookkeeping information (such as what to do after the frame is
138 While the compiler is free to do whatever it wants to, as long as the
139 semantics of a computation are preserved, in practice every time you
140 call a function, a new frame is created. (The notable exception of
141 course is the tail call case, @pxref{Tail Calls}.)
143 The structure of the top stack frame is as follows:
146 /------------------\ <- top of stack
150 | Local 0 | <- fp = SCM_FRAME_LOCALS_ADDRESS (fp)
153 | Dynamic link | <- fp - 2 = SCM_FRAME_LOWER_ADDRESS (fp)
155 | | <- fp - 3 = SCM_FRAME_PREVIOUS_SP (fp)
158 In the above drawing, the stack grows upward. Usually the procedure
159 being applied is in local 0, followed by the arguments from local 1.
160 After that are enough slots to store the various lexically-bound and
161 temporary values that are needed in the function's application.
163 The @dfn{return address} is the @code{ip} that was in effect before this
164 program was applied. When we return from this activation frame, we will
165 jump back to this @code{ip}. Likewise, the @dfn{dynamic link} is the
166 @code{fp} in effect before this program was applied.
168 To prepare for a non-tail application, Guile's VM will emit code that
169 shuffles the function to apply and its arguments into appropriate stack
170 slots, with two free slots below them. The call then initializes those
171 free slots with the current @code{ip} and @code{fp}, and updates
172 @code{ip} to point to the function entry, and @code{fp} to point to the
175 In this way, the dynamic link links the current frame to the previous
176 frame. Computing a stack trace involves traversing these frames.
178 @node Variables and the VM
179 @subsection Variables and the VM
181 Consider the following Scheme code as an example:
185 (lambda (b) (list foo a b)))
188 Within the lambda expression, @code{foo} is a top-level variable,
189 @code{a} is a lexically captured variable, and @code{b} is a local
192 Another way to refer to @code{a} and @code{b} is to say that @code{a} is
193 a ``free'' variable, since it is not defined within the lambda, and
194 @code{b} is a ``bound'' variable. These are the terms used in the
195 @dfn{lambda calculus}, a mathematical notation for describing functions.
196 The lambda calculus is useful because it is a language in which to
197 reason precisely about functions and variables. It is especially good
198 at describing scope relations, and it is for that reason that we mention
201 Guile allocates all variables on the stack. When a lexically enclosed
202 procedure with free variables---a @dfn{closure}---is created, it copies
203 those variables into its free variable vector. References to free
204 variables are then redirected through the free variable vector.
206 If a variable is ever @code{set!}, however, it will need to be
207 heap-allocated instead of stack-allocated, so that different closures
208 that capture the same variable can see the same value. Also, this
209 allows continuations to capture a reference to the variable, instead
210 of to its value at one point in time. For these reasons, @code{set!}
211 variables are allocated in ``boxes''---actually, in variable cells.
212 @xref{Variables}, for more information. References to @code{set!}
213 variables are indirected through the boxes.
215 Thus perhaps counterintuitively, what would seem ``closer to the
216 metal'', viz @code{set!}, actually forces an extra memory allocation
219 Going back to our example, @code{b} may be allocated on the stack, as
222 @code{a} may also be allocated on the stack, as it too is never
223 mutated. Within the enclosed lambda, its value will be copied into
224 (and referenced from) the free variables vector.
226 @code{foo} is a top-level variable, because @code{foo} is not
227 lexically bound in this example.
230 @subsection Compiled Procedures are VM Programs
232 By default, when you enter in expressions at Guile's REPL, they are
233 first compiled to bytecode. Then that bytecode is executed to produce a
234 value. If the expression evaluates to a procedure, the result of this
235 process is a compiled procedure.
237 A compiled procedure is a compound object consisting of its bytecode and
238 a reference to any captured lexical variables. In addition, when a
239 procedure is compiled, it has associated metadata written to side
240 tables, for instance a line number mapping, or its docstring. You can
241 pick apart these pieces with the accessors in @code{(system vm
242 program)}. @xref{Compiled Procedures}, for a full API reference.
244 A procedure may reference data that was statically allocated when the
245 procedure was compiled. For example, a pair of immediate objects
246 (@pxref{Immediate objects}) can be allocated directly in the memory
247 segment that contains the compiled bytecode, and accessed directly by
250 Another use for statically allocated data is to serve as a cache for a
251 bytecode. Top-level variable lookups are handled in this way. If the
252 @code{toplevel-box} instruction finds that it does not have a cached
253 variable for a top-level reference, it accesses other static data to
254 resolve the reference, and fills in the cache slot. Thereafter all
255 access to the variable goes through the cache cell. The variable's
256 value may change in the future, but the variable itself will not.
258 We can see how these concepts tie together by disassembling the
259 @code{foo} function we defined earlier to see what is going on:
262 scheme@@(guile-user)> (define (foo a) (lambda (b) (list foo a b)))
263 scheme@@(guile-user)> ,x foo
264 Disassembly of #<procedure foo (a)> at #x203be34:
266 0 (assert-nargs-ee/locals 2 1) ;; 1 arg, 1 local at (unknown file):1:0
267 1 (make-closure 2 6 1) ;; anonymous procedure at #x203be50 (1 free var)
268 4 (free-set! 2 1 0) ;; free var 0
271 ----------------------------------------
272 Disassembly of anonymous procedure at #x203be50:
274 0 (assert-nargs-ee/locals 2 3) ;; 1 arg, 3 locals at (unknown file):1:0
275 1 (toplevel-box 2 73 57 71 #t) ;; `foo'
277 7 (make-short-immediate 3 772) ;; ()
279 9 (free-ref 4 0 0) ;; free var 0
285 First there's some prelude, where @code{foo} checks that it was called
286 with only 1 argument. Then at @code{ip} 1, we allocate a new closure
287 and store it in slot 2. The `6' in the @code{(make-closure 2 6 1)} is a
288 relative offset from the instruction pointer of the code for the
291 A closure is code with data. We already have the code part initialized;
292 what remains is to set the data. @code{Ip} 4 initializes free variable
293 0 in the new closure with the value from local variable 1, which
294 corresponds to the first argument of @code{foo}: `a'. Finally we return
297 The second stanza disassembles the code for the closure. After the
298 prelude, we load the variable for the toplevel variable @code{foo} into
299 local variable 2. This lookup occurs lazily, the first time the
300 variable is actually referenced, and the location of the lookup is
301 cached so that future references are very cheap. @xref{Top-Level
302 Environment Instructions}, for more details. The @code{box-ref}
303 dereferences the variable cell, replacing the contents of local 2.
305 What follows is a sequence of conses to build up the result list.
306 @code{Ip} 7 makes the tail of the list. @code{Ip} 8 conses on the value
307 in local 1, corresponding to the first argument to the closure: `b'.
308 @code{Ip} 9 loads free variable 0 of local 0 -- the procedure being
309 called -- into slot 4, then @code{ip} 11 conses it onto the list.
310 Finally we cons local 2, containing the @code{foo} toplevel, onto the
311 front of the list, and we return it.
314 @node Object File Format
315 @subsection Object File Format
317 To compile a file to disk, we need a format in which to write the
318 compiled code to disk, and later load it into Guile. A good @dfn{object
319 file format} has a number of characteristics:
322 @item Above all else, it should be very cheap to load a compiled file.
323 @item It should be possible to statically allocate constants in the
324 file. For example, a bytevector literal in source code can be emitted
325 directly into the object file.
326 @item The compiled file should enable maximum code and data sharing
327 between different processes.
328 @item The compiled file should contain debugging information, such as
329 line numbers, but that information should be separated from the code
330 itself. It should be possible to strip debugging information if space
334 These characteristics are not specific to Scheme. Indeed, mainstream
335 languages like C and C++ have solved this issue many times in the past.
336 Guile builds on their work by adopting ELF, the object file format of
337 GNU and other Unix-like systems, as its object file format. Although
338 Guile uses ELF on all platforms, we do not use platform support for ELF.
339 Guile implements its own linker and loader. The advantage of using ELF
340 is not sharing code, but sharing ideas. ELF is simply a well-designed
343 An ELF file has two meta-tables describing its contents. The first
344 meta-table is for the loader, and is called the @dfn{program table} or
345 sometimes the @dfn{segment table}. The program table divides the file
346 into big chunks that should be treated differently by the loader.
347 Mostly the difference between these @dfn{segments} is their
350 Typically all segments of an ELF file are marked as read-only, except
351 that part that represents modifiable static data or static data that
352 needs load-time initialization. Loading an ELF file is as simple as
353 mmapping the thing into memory with read-only permissions, then using
354 the segment table to mark a small sub-region of the file as writable.
355 This writable section is typically added to the root set of the garbage
358 One ELF segment is marked as ``dynamic'', meaning that it has data of
359 interest to the loader. Guile uses this segment to record the Guile
360 version corresponding to this file. There is also an entry in the
361 dynamic segment that points to the address of an initialization thunk
362 that is run to perform any needed link-time initialization. (This is
363 like dynamic relocations for normal ELF shared objects, except that we
364 compile the relocations as a procedure instead of having the loader
365 interpret a table of relocations.) Finally, the dynamic segment marks
366 the location of the ``entry thunk'' of the object file. This thunk is
367 returned to the caller of @code{load-thunk-from-memory} or
368 @code{load-thunk-from-file}. When called, it will execute the ``body''
369 of the compiled expression.
371 The other meta-table in an ELF file is the @dfn{section table}. Whereas
372 the program table divides an ELF file into big chunks for the loader,
373 the section table specifies small sections for use by introspective
374 tools like debuggers or the like. One segment (program table entry)
375 typically contains many sections. There may be sections outside of any
378 Typical sections in a Guile @code{.go} file include:
384 Data that needs initialization, or which may be modified at runtime.
386 Statically allocated data that needs no run-time initialization, and
387 which therefore can be shared between processes.
389 The dynamic section, discussed above.
392 A table mapping addresses in the @code{.rtl-text} to procedure names.
393 @code{.strtab} is used by @code{.symtab}.
394 @item .guile.procprops
395 @itemx .guile.arities
396 @itemx .guile.arities.strtab
397 @itemx .guile.docstrs
398 @itemx .guile.docstrs.strtab
399 Side tables of procedure properties, arities, and docstrings.
405 Debugging information, in DWARF format. See the DWARF specification,
406 for more information.
408 Section name string table.
411 For more information, see @uref{http://linux.die.net/man/5/elf,,the
412 elf(5) man page}. See @uref{http://dwarfstd.org/,the DWARF
413 specification} for more on the DWARF debugging format. Or if you are an
414 adventurous explorer, try running @code{readelf} or @code{objdump} on
415 compiled @code{.go} files. It's good times!
418 @node Instruction Set
419 @subsection Instruction Set
421 There are currently about 130 instructions in Guile's virtual machine.
422 These instructions represent atomic units of a program's execution.
423 Ideally, they perform one task without conditional branches, then
424 dispatch to the next instruction in the stream.
426 Instructions themselves are composed of 1 or more 32-bit units. The low
427 8 bits of the first word indicate the opcode, and the rest of
428 instruction describe the operands. There are a number of different ways
429 operands can be encoded.
433 An unsigned @var{n}-bit integer. Usually indicates the index of a local
434 variable, but some instructions interpret these operands as immediate
437 An offset from the current @code{ip}, in 32-bit units, as a signed
438 24-bit value. Indicates a bytecode address, for a relative jump.
441 An immediate Scheme value (@pxref{Immediate objects}), encoded directly
445 An immediate Scheme value, encoded as a pair of 32-bit words.
446 @code{a32} and @code{b32} values always go together on the same opcode,
447 and indicate the high and low bits, respectively. Normally only used on
450 A statically allocated non-immediate. The address of the non-immediate
451 is encoded as a signed 32-bit integer, and indicates a relative offset
452 in 32-bit units. Think of it as @code{SCM x = ip + offset}.
454 Indirect scheme value, like @code{n32} but indirected. Think of it as
455 @code{SCM *x = ip + offset}.
458 An ip-relative address, as a signed 32-bit integer. Could indicate a
459 bytecode address, as in @code{make-closure}, or a non-immediate address,
460 as with @code{static-patch!}.
462 @code{l32} and @code{lo32} are the same from the perspective of the
463 virtual machine. The difference is that an assembler might want to
464 allow an @code{lo32} address to be specified as a label and then some
465 number of words offset from that label, for example when patching a
466 field of a statically allocated object.
468 A boolean value: 1 for true, otherwise 0.
470 An ignored sequence of @var{n} bits.
473 An instruction is specified by giving its name, then describing its
474 operands. The operands are packed by 32-bit words, with earlier
475 operands occupying the lower bits.
477 For example, consider the following instruction specification:
479 @deftypefn Instruction {} free-set! u12:@var{dst} u12:@var{src} x8:@var{_} u24:@var{idx}
480 Set free variable @var{idx} from the closure @var{dst} to @var{src}.
483 The first word in the instruction will start with the 8-bit value
484 corresponding to the @var{free-set!} opcode in the low bits, followed by
485 @var{dst} and @var{src} as 12-bit values. The second word starts with 8
486 dead bits, followed by the index as a 24-bit immediate value.
488 Sometimes the compiler can figure out that it is compiling a special
489 case that can be run more efficiently. So, for example, while Guile
490 offers a generic test-and-branch instruction, it also offers specific
491 instructions for special cases, so that the following cases all have
492 their own test-and-branch instructions:
496 (if (not pred) then else)
497 (if (null? l) then else)
498 (if (not (null? l)) then else)
501 In addition, some Scheme primitives have their own inline
502 implementations. For example, in the previous section we saw
505 Guile's instruction set is a @emph{complete} instruction set, in that it
506 provides the instructions that are suited to the problem, and is not
507 concerned with making a minimal, orthogonal set of instructions. More
508 instructions may be added over time.
511 * Lexical Environment Instructions::
512 * Top-Level Environment Instructions::
513 * Procedure Call and Return Instructions::
514 * Function Prologue Instructions::
515 * Trampoline Instructions::
516 * Branch Instructions::
517 * Constant Instructions::
518 * Dynamic Environment Instructions::
519 * Miscellaneous Instructions::
520 * Inlined Scheme Instructions::
521 * Inlined Mathematical Instructions::
522 * Inlined Bytevector Instructions::
526 @node Lexical Environment Instructions
527 @subsubsection Lexical Environment Instructions
529 These instructions access and mutate the lexical environment of a
530 compiled procedure---its free and bound variables. @xref{Stack Layout},
531 for more information on the format of stack frames.
533 @deftypefn Instruction {} mov u12:@var{dst} u12:@var{src}
534 @deftypefnx Instruction {} long-mov u24:@var{dst} x8:@var{_} u24:@var{src}
535 Copy a value from one local slot to another.
537 As discussed previously, procedure arguments and local variables are
538 allocated to local slots. Guile's compiler tries to avoid shuffling
539 variables around to different slots, which often makes @code{mov}
540 instructions redundant. However there are some cases in which shuffling
541 is necessary, and in those cases, @code{mov} is the thing to use.
544 @deftypefn Instruction {} make-closure u24:@var{dst} l32:@var{offset} x8:@var{_} u24:@var{nfree}
545 Make a new closure, and write it to @var{dst}. The code for the closure
546 will be found at @var{offset} words from the current @code{ip}.
547 @var{offset} is a signed 32-bit integer. Space for @var{nfree} free
548 variables will be allocated.
550 The size of a closure is currently two words, plus one word per free
554 @deftypefn Instruction {} free-ref u12:@var{dst} u12:@var{src} x8:@var{_} u24:@var{idx}
555 Load free variable @var{idx} from the closure @var{src} into local slot
559 @deftypefn Instruction {} free-set! u12:@var{dst} u12:@var{src} x8:@var{_} u24:@var{idx}
560 Set free variable @var{idx} from the closure @var{dst} to @var{src}.
562 This instruction is usually used when initializing a closure's free
563 variables, but not to mutate free variables, as variables that are
567 Recall that variables that are assigned are usually allocated in boxes,
568 so that continuations and closures can capture their identity and not
569 their value at one point in time. Variables are also used in the
570 implementation of top-level bindings; see the next section for more
573 @deftypefn Instruction {} box u12:@var{dst} u12:@var{src}
574 Create a new variable holding @var{src}, and place it in @var{dst}.
577 @deftypefn Instruction {} box-ref u12:@var{dst} u12:@var{src}
578 Unpack the variable at @var{src} into @var{dst}, asserting that the
579 variable is actually bound.
582 @deftypefn Instruction {} box-set! u12:@var{dst} u12:@var{src}
583 Set the contents of the variable at @var{dst} to @var{set}.
587 @node Top-Level Environment Instructions
588 @subsubsection Top-Level Environment Instructions
590 These instructions access values in the top-level environment: bindings
591 that were not lexically apparent at the time that the code in question
594 The location in which a toplevel binding is stored can be looked up once
595 and cached for later. The binding itself may change over time, but its
596 location will stay constant.
598 @deftypefn Instruction {} current-module u24:@var{dst}
599 Store the current module in @var{dst}.
602 @deftypefn Instruction {} resolve u24:@var{dst} b1:@var{bound?} x7:@var{_} u24:@var{sym}
603 Resolve @var{sym} in the current module, and place the resulting
604 variable in @var{dst}. An error will be signalled if no variable is
605 found. If @var{bound?} is true, an error will be signalled if the
609 @deftypefn Instruction {} define! u12:@var{sym} u12:@var{val}
610 Look up a binding for @var{sym} in the current module, creating it if
611 necessary. Set its value to @var{val}.
614 @deftypefn Instruction {} toplevel-box u24:@var{dst} s32:@var{var-offset} s32:@var{mod-offset} n32:@var{sym-offset} b1:@var{bound?} x31:@var{_}
615 Load a value. The value will be fetched from memory, @var{var-offset}
616 32-bit words away from the current instruction pointer.
617 @var{var-offset} is a signed value. Up to here, @code{toplevel-box} is
618 like @code{static-ref}.
620 Then, if the loaded value is a variable, it is placed in @var{dst}, and
621 control flow continues.
623 Otherwise, we have to resolve the variable. In that case we load the
624 module from @var{mod-offset}, just as we loaded the variable. Usually
625 the module gets set when the closure is created. @var{sym-offset}
626 specifies the name, as an offset to a symbol.
628 We use the module and the symbol to resolve the variable, placing it in
629 @var{dst}, and caching the resolved variable so that we will hit the
630 cache next time. If @var{bound?} is true, an error will be signalled if
631 the variable is unbound.
634 @deftypefn Instruction {} module-box u24:@var{dst} s32:@var{var-offset} n32:@var{mod-offset} n32:@var{sym-offset} b1:@var{bound?} x31:@var{_}
635 Like @code{toplevel-box}, except @var{mod-offset} points at a module
636 identifier instead of the module itself. A module identifier is a
637 module name, as a list, prefixed by a boolean. If the prefix is true,
638 then the variable is resolved relative to the module's public interface
639 instead of its private interface.
643 @node Procedure Call and Return Instructions
644 @subsubsection Procedure Call and Return Instructions
646 As described earlier (@pxref{Stack Layout}), Guile's calling convention
647 is that arguments are passed and values returned on the stack.
649 For calls, both in tail position and in non-tail position, we require
650 that the procedure and the arguments already be shuffled into place
651 befor the call instruction. ``Into place'' for a tail call means that
652 the procedure should be in slot 0, and the arguments should follow. For
653 a non-tail call, if the procedure is in slot @var{n}, the arguments
654 should follow from slot @var{n}+1, and there should be two free slots at
655 @var{n}-1 and @var{n}-2 in which to save the @code{ip} and @code{fp}.
657 Returning values is similar. Multiple-value returns should have values
658 already shuffled down to start from slot 1 before emitting
659 @code{return-values}. There is a short-cut in the single-value case, in
660 that @code{return} handles the trivial shuffling itself. We start from
661 slot 1 instead of slot 0 to make tail calls to @code{values} trivial.
663 In both calls and returns, the @code{sp} is used to indicate to the
664 callee or caller the number of arguments or return values, respectively.
665 After receiving return values, it is the caller's responsibility to
666 @dfn{restore the frame} by resetting the @code{sp} to its former value.
668 @deftypefn Instruction {} call u24:@var{proc} x8:@var{_} u24:@var{nlocals}
669 Call a procedure. @var{proc} is the local corresponding to a procedure.
670 The two values below @var{proc} will be overwritten by the saved call
671 frame data. The new frame will have space for @var{nlocals} locals: one
672 for the procedure, and the rest for the arguments which should already
675 When the call returns, execution proceeds with the next instruction.
676 There may be any number of values on the return stack; the precise
677 number can be had by subtracting the address of @var{proc} from the
681 @deftypefn Instruction {} tail-call u24:@var{nlocals}
682 Tail-call a procedure. Requires that the procedure and all of the
683 arguments have already been shuffled into position. Will reset the
684 frame to @var{nlocals}.
687 @deftypefn Instruction {} tail-call/shuffle u24:@var{from}
688 Tail-call a procedure. The procedure should already be set to slot 0.
689 The rest of the args are taken from the frame, starting at @var{from},
690 shuffled down to start at slot 0. This is part of the implementation of
691 the @code{call-with-values} builtin.
694 @deftypefn Instruction {} receive u12:@var{dst} u12:@var{proc} x8:@var{_} u24:@var{nlocals}
695 Receive a single return value from a call whose procedure was in
696 @var{proc}, asserting that the call actually returned at least one
697 value. Afterwards, resets the frame to @var{nlocals} locals.
700 @deftypefn Instruction {} receive-values u24:@var{proc} b1:@var{allow-extra?} x7:@var{_} u24:@var{nvalues}
701 Receive a return of multiple values from a call whose procedure was in
702 @var{proc}. If fewer than @var{nvalues} values were returned, signal an
703 error. Unless @var{allow-extra?} is true, require that the number of
704 return values equals @var{nvalues} exactly. After @code{receive-values}
705 has run, the values can be copied down via @code{mov}, or used in place.
708 @deftypefn Instruction {} return u24:@var{src}
712 @deftypefn Instruction {} return-values x24:@var{_}
713 Return a number of values from a call frame. This opcode corresponds to
714 an application of @code{values} in tail position. As with tail calls,
715 we expect that the values have already been shuffled down to a
716 contiguous array starting at slot 1. We also expect the frame has
720 @deftypefn Instruction {} call/cc x24:@var{_}
721 Capture the current continuation, and tail-apply the procedure in local
722 slot 1 to it. This instruction is part of the implementation of
723 @code{call/cc}, and is not generated by the compiler.
727 @node Function Prologue Instructions
728 @subsubsection Function Prologue Instructions
730 A function call in Guile is very cheap: the VM simply hands control to
731 the procedure. The procedure itself is responsible for asserting that it
732 has been passed an appropriate number of arguments. This strategy allows
733 arbitrarily complex argument parsing idioms to be developed, without
734 harming the common case.
736 For example, only calls to keyword-argument procedures ``pay'' for the
737 cost of parsing keyword arguments. (At the time of this writing, calling
738 procedures with keyword arguments is typically two to four times as
739 costly as calling procedures with a fixed set of arguments.)
741 @deftypefn Instruction {} assert-nargs-ee u24:@var{expected}
742 @deftypefnx Instruction {} assert-nargs-ge u24:@var{expected}
743 @deftypefnx Instruction {} assert-nargs-le u24:@var{expected}
744 If the number of actual arguments is not @code{==}, @code{>=}, or
745 @code{<=} @var{expected}, respectively, signal an error.
747 The number of arguments is determined by subtracting the frame pointer
748 from the stack pointer (@code{sp + 1 - fp}). @xref{Stack Layout}, for
749 more details on stack frames. Note that @var{expected} includes the
753 @deftypefn Instruction {} br-if-nargs-ne u24:@var{expected} x8:@var{_} l24:@var{offset}
754 @deftypefnx Instruction {} br-if-nargs-lt u24:@var{expected} x8:@var{_} l24:@var{offset}
755 @deftypefnx Instruction {} br-if-nargs-gt u24:@var{expected} x8:@var{_} l24:@var{offset}
756 If the number of actual arguments is not equal, less than, or greater
757 than @var{expected}, respectively, add @var{offset}, a signed 24-bit
758 number, to the current instruction pointer. Note that @var{expected}
759 includes the procedure itself.
761 These instructions are used to implement multiple arities, as in
762 @code{case-lambda}. @xref{Case-lambda}, for more information.
765 @deftypefn Instruction {} alloc-frame u24:@var{nlocals}
766 Ensure that there is space on the stack for @var{nlocals} local
767 variables, setting them all to @code{SCM_UNDEFINED}, except those values
768 that are already on the stack.
771 @deftypefn Instruction {} reset-frame u24:@var{nlocals}
772 Like @code{alloc-frame}, but doesn't check that the stack is big enough,
773 and doesn't initialize values to @code{SCM_UNDEFINED}. Used to reset
774 the frame size to something less than the size that was previously set
778 @deftypefn Instruction {} assert-nargs-ee/locals u12:@var{expected} u12:@var{nlocals}
779 Equivalent to a sequence of @code{assert-nargs-ee} and
780 @code{reserve-locals}. The number of locals reserved is @var{expected}
784 @deftypefn Instruction {} br-if-npos-gt u24:@var{nreq} x8:@var{_} u24:@var{npos} x8:@var{_} l24:@var{offset}
785 Find the first positional argument after @var{nreq}. If it is greater
786 than @var{npos}, jump to @var{offset}.
788 This instruction is only emitted for functions with multiple clauses,
789 and an earlier clause has keywords and no rest arguments.
790 @xref{Case-lambda}, for more on how @code{case-lambda} chooses the
794 @deftypefn Instruction {} bind-kwargs u24:@var{nreq} u8:@var{flags} u24:@var{nreq-and-opt} x8:@var{_} u24:@var{ntotal} n32:@var{kw-offset}
795 @var{flags} is a bitfield, whose lowest bit is @var{allow-other-keys},
796 second bit is @var{has-rest}, and whose following six bits are unused.
798 Find the last positional argument, and shuffle all the rest above
799 @var{ntotal}. Initialize the intervening locals to
800 @code{SCM_UNDEFINED}. Then load the constant at @var{kw-offset} words
801 from the current @var{ip}, and use it and the @var{allow-other-keys}
802 flag to bind keyword arguments. If @var{has-rest}, collect all shuffled
803 arguments into a list, and store it in @var{nreq-and-opt}. Finally,
804 clear the arguments that we shuffled up.
806 The parsing is driven by a keyword arguments association list, looked up
807 using @var{kw-offset}. The alist is a list of pairs of the form
808 @code{(@var{kw} . @var{index})}, mapping keyword arguments to their
809 local slot indices. Unless @code{allow-other-keys} is set, the parser
810 will signal an error if an unknown key is found.
812 A macro-mega-instruction.
815 @deftypefn Instruction {} bind-rest u24:@var{dst}
816 Collect any arguments at or above @var{dst} into a list, and store that
821 @node Trampoline Instructions
822 @subsubsection Trampoline Instructions
824 Though most applicable objects in Guile are procedures implemented in
825 bytecode, not all are. There are primitives, continuations, and other
826 procedure-like objects that have their own calling convention. Instead
827 of adding special cases to the @code{call} instruction, Guile wraps
828 these other applicable objects in VM trampoline procedures, then
829 provides special support for these objects in bytecode.
831 Trampoline procedures are typically generated by Guile at runtime, for
832 example in response to a call to @code{scm_c_make_gsubr}. As such, a
833 compiler probably shouldn't emit code with these instructions. However,
834 it's still interesting to know how these things work, so we document
835 these trampoline instructions here.
837 @deftypefn Instruction {} subr-call u24:@var{ptr-idx}
838 Call a subr, passing all locals in this frame as arguments. Fetch the
839 foreign pointer from @var{ptr-idx}, a free variable. Return from the
843 @deftypefn Instruction {} foreign-call u12:@var{cif-idx} u12:@var{ptr-idx}
844 Call a foreign function. Fetch the @var{cif} and foreign pointer from
845 @var{cif-idx} and @var{ptr-idx}, both free variables. Return from the calling
846 frame. Arguments are taken from the stack.
849 @deftypefn Instruction {} continuation-call u24:@var{contregs}
850 Return to a continuation, nonlocally. The arguments to the continuation
851 are taken from the stack. @var{contregs} is a free variable containing
852 the reified continuation.
855 @deftypefn Instruction {} compose-continuation u24:@var{cont}
856 Compose a partial continution with the current continuation. The
857 arguments to the continuation are taken from the stack. @var{cont} is a
858 free variable containing the reified continuation.
861 @deftypefn Instruction {} tail-apply x24:@var{_}
862 Tail-apply the procedure in local slot 0 to the rest of the arguments.
863 This instruction is part of the implementation of @code{apply}, and is
864 not generated by the compiler.
867 @deftypefn Instruction {} builtin-ref u12:@var{dst} u12:@var{idx}
868 Load a builtin stub by index into @var{dst}.
872 @node Branch Instructions
873 @subsubsection Branch Instructions
875 All offsets to branch instructions are 24-bit signed numbers, which
876 count 32-bit units. This gives Guile effectively a 26-bit address range
879 @deftypefn Instruction {} br l24:@var{offset}
880 Add @var{offset} to the current instruction pointer.
883 All the conditional branch instructions described below have an
884 @var{invert} parameter, which if true reverses the test:
885 @code{br-if-true} becomes @code{br-if-false}, and so on.
887 @deftypefn Instruction {} br-if-true u24:@var{test} b1:@var{invert} x7:@var{_} l24:@var{offset}
888 If the value in @var{test} is true for the purposes of Scheme, add
889 @var{offset} to the current instruction pointer.
892 @deftypefn Instruction {} br-if-null u24:@var{test} b1:@var{invert} x7:@var{_} l24:@var{offset}
893 If the value in @var{test} is the end-of-list or Lisp nil, add
894 @var{offset} to the current instruction pointer.
897 @deftypefn Instruction {} br-if-nil u24:@var{test} b1:@var{invert} x7:@var{_} l24:@var{offset}
898 If the value in @var{test} is false to Lisp, add @var{offset} to the
899 current instruction pointer.
902 @deftypefn Instruction {} br-if-pair u24:@var{test} b1:@var{invert} x7:@var{_} l24:@var{offset}
903 If the value in @var{test} is a pair, add @var{offset} to the current
907 @deftypefn Instruction {} br-if-struct u24:@var{test} b1:@var{invert} x7:@var{_} l24:@var{offset}
908 If the value in @var{test} is a struct, add @var{offset} number to the
909 current instruction pointer.
912 @deftypefn Instruction {} br-if-char u24:@var{test} b1:@var{invert} x7:@var{_} l24:@var{offset}
913 If the value in @var{test} is a char, add @var{offset} to the current
917 @deftypefn Instruction {} br-if-tc7 u24:@var{test} b1:@var{invert} u7:@var{tc7} l24:@var{offset}
918 If the value in @var{test} has the TC7 given in the second word, add
919 @var{offset} to the current instruction pointer. TC7 codes are part of
920 the way Guile represents non-immediate objects, and are deep wizardry.
921 See @code{libguile/tags.h} for all the details.
924 @deftypefn Instruction {} br-if-eq u12:@var{a} u12:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
925 @deftypefnx Instruction {} br-if-eqv u12:@var{a} u12:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
926 @deftypefnx Instruction {} br-if-equal u12:@var{a} u12:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
927 If the value in @var{a} is @code{eq?}, @code{eqv?}, or @code{equal?} to
928 the value in @var{b}, respectively, add @var{offset} to the current
932 @deftypefn Instruction {} br-if-= u12:@var{a} u12:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
933 @deftypefnx Instruction {} br-if-< u12:@var{a} u12:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
934 @deftypefnx Instruction {} br-if-<= u12:@var{a} u12:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
935 If the value in @var{a} is @code{=}, @code{<}, or @code{<=} to the value
936 in @var{b}, respectively, add @var{offset} to the current instruction
941 @node Constant Instructions
942 @subsubsection Constant Instructions
944 The following instructions load literal data into a program. There are
947 The first set of instructions loads immediate values. These
948 instructions encode the immediate directly into the instruction stream.
950 @deftypefn Instruction {} make-short-immediate u8:@var{dst} i16:@var{low-bits}
951 Make an immediate whose low bits are @var{low-bits}, and whose top bits are
955 @deftypefn Instruction {} make-long-immediate u24:@var{dst} i32:@var{low-bits}
956 Make an immediate whose low bits are @var{low-bits}, and whose top bits are
960 @deftypefn Instruction {} make-long-long-immediate u24:@var{dst} a32:@var{high-bits} b32:@var{low-bits}
961 Make an immediate with @var{high-bits} and @var{low-bits}.
964 Non-immediate constant literals are referenced either directly or
965 indirectly. For example, Guile knows at compile-time what the layout of
966 a string will be like, and arranges to embed that object directly in the
967 compiled image. A reference to a string will use
968 @code{make-non-immediate} to treat a pointer into the compilation unit
969 as a @code{SCM} value directly.
971 @deftypefn Instruction {} make-non-immediate u24:@var{dst} n32:@var{offset}
972 Load a pointer to statically allocated memory into @var{dst}. The
973 object's memory is will be found @var{offset} 32-bit words away from the
974 current instruction pointer. Whether the object is mutable or immutable
975 depends on where it was allocated by the compiler, and loaded by the
979 Some objects must be unique across the whole system. This is the case
980 for symbols and keywords. For these objects, Guile arranges to
981 initialize them when the compilation unit is loaded, storing them into a
982 slot in the image. References go indirectly through that slot.
983 @code{static-ref} is used in this case.
985 @deftypefn Instruction {} static-ref u24:@var{dst} s32:@var{offset}
986 Load a @var{scm} value into @var{dst}. The @var{scm} value will be fetched from
987 memory, @var{offset} 32-bit words away from the current instruction
988 pointer. @var{offset} is a signed value.
991 Fields of non-immediates may need to be fixed up at load time, because
992 we do not know in advance at what address they will be loaded. This is
993 the case, for example, for a pair containing a non-immediate in one of
994 its fields. @code{static-ref} and @code{static-patch!} are used in
997 @deftypefn Instruction {} static-set! u24:@var{src} lo32:@var{offset}
998 Store a @var{scm} value into memory, @var{offset} 32-bit words away from the
999 current instruction pointer. @var{offset} is a signed value.
1002 @deftypefn Instruction {} static-patch! x24:@var{_} lo32:@var{dst-offset} l32:@var{src-offset}
1003 Patch a pointer at @var{dst-offset} to point to @var{src-offset}. Both offsets
1004 are signed 32-bit values, indicating a memory address as a number
1005 of 32-bit words away from the current instruction pointer.
1008 Many kinds of literals can be loaded with the above instructions, once
1009 the compiler has prepared the statically allocated data. This is the
1010 case for vectors, strings, uniform vectors, pairs, and procedures with
1011 no free variables. Other kinds of data might need special initializers;
1012 those instructions follow.
1014 @deftypefn Instruction {} string->number u12:@var{dst} u12:@var{src}
1015 Parse a string in @var{src} to a number, and store in @var{dst}.
1018 @deftypefn Instruction {} string->symbol u12:@var{dst} u12:@var{src}
1019 Parse a string in @var{src} to a symbol, and store in @var{dst}.
1022 @deftypefn Instruction {} symbol->keyword u12:@var{dst} u12:@var{src}
1023 Make a keyword from the symbol in @var{src}, and store it in @var{dst}.
1026 @deftypefn Instruction {} load-typed-array u8:@var{dst} u8:@var{type} u8:@var{shape} n32:@var{offset} u32:@var{len}
1027 Load the contiguous typed array located at @var{offset} 32-bit words away
1028 from the instruction pointer, and store into @var{dst}. @var{len} is a byte
1029 length. @var{offset} is signed.
1033 @node Dynamic Environment Instructions
1034 @subsubsection Dynamic Environment Instructions
1036 Guile's virtual machine has low-level support for @code{dynamic-wind},
1037 dynamic binding, and composable prompts and aborts.
1039 @deftypefn Instruction {} abort x24:@var{_}
1040 Abort to a prompt handler. The tag is expected in slot 1, and the rest
1041 of the values in the frame are returned to the prompt handler. This
1042 corresponds to a tail application of abort-to-prompt.
1044 If no prompt can be found in the dynamic environment with the given tag,
1045 an error is signalled. Otherwise all arguments are passed to the
1046 prompt's handler, along with the captured continuation, if necessary.
1048 If the prompt's handler can be proven to not reference the captured
1049 continuation, no continuation is allocated. This decision happens
1050 dynamically, at run-time; the general case is that the continuation may
1051 be captured, and thus resumed. A reinstated continuation will have its
1052 arguments pushed on the stack from slot 1, as if from a multiple-value
1053 return, and control resumes in the caller. Thus to the calling
1054 function, a call to @code{abort-to-prompt} looks like any other function
1058 @deftypefn Instruction {} prompt u24:@var{tag} b1:@var{escape-only?} x7:@var{_} u24:@var{proc-slot} x8:@var{_} l24:@var{handler-offset}
1059 Push a new prompt on the dynamic stack, with a tag from @var{tag} and a
1060 handler at @var{handler-offset} words from the current @var{ip}.
1062 If an abort is made to this prompt, control will jump to the handler.
1063 The handler will expect a multiple-value return as if from a call with
1064 the procedure at @var{proc-slot}, with the reified partial continuation
1065 as the first argument, followed by the values returned to the handler.
1066 If control returns to the handler, the prompt is already popped off by
1067 the abort mechanism. (Guile's @code{prompt} implements Felleisen's
1068 @dfn{--F--} operator.)
1070 If @var{escape-only?} is nonzero, the prompt will be marked as
1071 escape-only, which allows an abort to this prompt to avoid reifying the
1074 @xref{Prompts}, for more information on prompts.
1077 @deftypefn Instruction {} wind u12:@var{winder} u12:@var{unwinder}
1078 Push wind and unwind procedures onto the dynamic stack. Note that
1079 neither are actually called; the compiler should emit calls to wind and
1080 unwind for the normal dynamic-wind control flow. Also note that the
1081 compiler should have inserted checks that they wind and unwind procs are
1082 thunks, if it could not prove that to be the case. @xref{Dynamic Wind}.
1085 @deftypefn Instruction {} unwind x24:@var{_}
1086 @var{a} normal exit from the dynamic extent of an expression. Pop the top
1087 entry off of the dynamic stack.
1090 @deftypefn Instruction {} push-fluid u12:@var{fluid} u12:@var{value}
1091 Dynamically bind @var{value} to @var{fluid} by creating a with-fluids
1092 object and pushing that object on the dynamic stack. @xref{Fluids and
1096 @deftypefn Instruction {} pop-fluid x24:@var{_}
1097 Leave the dynamic extent of a @code{with-fluid*} expression, restoring
1098 the fluid to its previous value. @code{push-fluid} should always be
1099 balanced with @code{pop-fluid}.
1102 @deftypefn Instruction {} fluid-ref u12:@var{dst} u12:@var{src}
1103 Reference the fluid in @var{src}, and place the value in @var{dst}.
1106 @deftypefn Instruction {} fluid-set u12:@var{fluid} u12:@var{val}
1107 Set the value of the fluid in @var{dst} to the value in @var{src}.
1111 @node Miscellaneous Instructions
1112 @subsubsection Miscellaneous Instructions
1114 @deftypefn Instruction {} halt x24:@var{_}
1115 Bring the VM to a halt, returning all the values from the stack. Used
1116 in the ``boot continuation'', which is used when entering the VM from C.
1120 @node Inlined Scheme Instructions
1121 @subsubsection Inlined Scheme Instructions
1123 The Scheme compiler can recognize the application of standard Scheme
1124 procedures. It tries to inline these small operations to avoid the
1125 overhead of creating new stack frames. This allows the compiler to
1128 @deftypefn Instruction {} make-vector/immediate u8:@var{dst} u8:@var{length} u8:@var{init}
1129 Make a short vector of known size and write it to @var{dst}. The vector
1130 will have space for @var{length} slots, an immediate value. They will
1131 be filled with the value in slot @var{init}.
1134 @deftypefn Instruction {} vector-length u12:@var{dst} u12:@var{src}
1135 Store the length of the vector in @var{src} in @var{dst}.
1138 @deftypefn Instruction {} vector-ref u8:@var{dst} u8:@var{src} u8:@var{idx}
1139 Fetch the item at position @var{idx} in the vector in @var{src}, and
1140 store it in @var{dst}.
1143 @deftypefn Instruction {} vector-ref/immediate u8:@var{dst} u8:@var{src} u8:@var{idx}
1144 Fill @var{dst} with the item @var{idx} elements into the vector at
1145 @var{src}. Useful for building data types using vectors.
1148 @deftypefn Instruction {} vector-set! u8:@var{dst} u8:@var{idx} u8:@var{src}
1149 Store @var{src} into the vector @var{dst} at index @var{idx}.
1152 @deftypefn Instruction {} vector-set!/immediate u8:@var{dst} u8:@var{idx} u8:@var{src}
1153 Store @var{src} into the vector @var{dst} at index @var{idx}. Here
1154 @var{idx} is an immediate value.
1157 @deftypefn Instruction {} struct-vtable u12:@var{dst} u12:@var{src}
1158 Store the vtable of @var{src} into @var{dst}.
1161 @deftypefn Instruction {} allocate-struct/immediate u8:@var{dst} u8:@var{vtable} u8:@var{nfields}
1162 Allocate a new struct with @var{vtable}, and place it in @var{dst}. The
1163 struct will be constructed with space for @var{nfields} fields, which
1164 should correspond to the field count of the @var{vtable}.
1167 @deftypefn Instruction {} struct-ref/immediate u8:@var{dst} u8:@var{src} u8:@var{idx}
1168 Fetch the item at slot @var{idx} in the struct in @var{src}, and store
1169 it in @var{dst}. @var{idx} is an immediate unsigned 8-bit value.
1172 @deftypefn Instruction {} struct-set!/immediate u8:@var{dst} u8:@var{idx} u8:@var{src}
1173 Store @var{src} into the struct @var{dst} at slot @var{idx}. @var{idx}
1174 is an immediate unsigned 8-bit value.
1177 @deftypefn Instruction {} class-of u12:@var{dst} u12:@var{type}
1178 Store the vtable of @var{src} into @var{dst}.
1181 @deftypefn Instruction {} make-array u12:@var{dst} u12:@var{type} x8:@var{_} u12:@var{fill} u12:@var{bounds}
1182 Make a new array with @var{type}, @var{fill}, and @var{bounds}, storing it in @var{dst}.
1185 @deftypefn Instruction {} string-length u12:@var{dst} u12:@var{src}
1186 Store the length of the string in @var{src} in @var{dst}.
1189 @deftypefn Instruction {} string-ref u8:@var{dst} u8:@var{src} u8:@var{idx}
1190 Fetch the character at position @var{idx} in the string in @var{src}, and store
1194 @deftypefn Instruction {} cons u8:@var{dst} u8:@var{car} u8:@var{cdr}
1195 Cons @var{car} and @var{cdr}, and store the result in @var{dst}.
1198 @deftypefn Instruction {} car u12:@var{dst} u12:@var{src}
1199 Place the car of @var{src} in @var{dst}.
1202 @deftypefn Instruction {} cdr u12:@var{dst} u12:@var{src}
1203 Place the cdr of @var{src} in @var{dst}.
1206 @deftypefn Instruction {} set-car! u12:@var{pair} u12:@var{car}
1207 Set the car of @var{dst} to @var{src}.
1210 @deftypefn Instruction {} set-cdr! u12:@var{pair} u12:@var{cdr}
1211 Set the cdr of @var{dst} to @var{src}.
1214 Note that @code{caddr} and friends compile to a series of @code{car}
1215 and @code{cdr} instructions.
1218 @node Inlined Mathematical Instructions
1219 @subsubsection Inlined Mathematical Instructions
1221 Inlining mathematical operations has the obvious advantage of handling
1222 fixnums without function calls or allocations. The trick, of course,
1223 is knowing when the result of an operation will be a fixnum, and there
1224 might be a couple bugs here.
1226 More instructions could be added here over time.
1228 All of these operations place their result in their first operand,
1231 @deftypefn Instruction {} add u8:@var{dst} u8:@var{a} u8:@var{b}
1232 Add @var{a} to @var{b}.
1235 @deftypefn Instruction {} add1 u12:@var{dst} u12:@var{src}
1236 Add 1 to the value in @var{src}.
1239 @deftypefn Instruction {} sub u8:@var{dst} u8:@var{a} u8:@var{b}
1240 Subtract @var{b} from @var{a}.
1243 @deftypefn Instruction {} sub1 u12:@var{dst} u12:@var{src}
1244 Subtract 1 from @var{src}.
1247 @deftypefn Instruction {} mul u8:@var{dst} u8:@var{a} u8:@var{b}
1248 Multiply @var{a} and @var{b}.
1251 @deftypefn Instruction {} div u8:@var{dst} u8:@var{a} u8:@var{b}
1252 Divide @var{a} by @var{b}.
1255 @deftypefn Instruction {} quo u8:@var{dst} u8:@var{a} u8:@var{b}
1256 Divide @var{a} by @var{b}.
1259 @deftypefn Instruction {} rem u8:@var{dst} u8:@var{a} u8:@var{b}
1260 Divide @var{a} by @var{b}.
1263 @deftypefn Instruction {} mod u8:@var{dst} u8:@var{a} u8:@var{b}
1264 Compute the modulo of @var{a} by @var{b}.
1267 @deftypefn Instruction {} ash u8:@var{dst} u8:@var{a} u8:@var{b}
1268 Shift @var{a} arithmetically by @var{b} bits.
1271 @deftypefn Instruction {} logand u8:@var{dst} u8:@var{a} u8:@var{b}
1272 Compute the bitwise @code{and} of @var{a} and @var{b}.
1275 @deftypefn Instruction {} logior u8:@var{dst} u8:@var{a} u8:@var{b}
1276 Compute the bitwise inclusive @code{or} of @var{a} with @var{b}.
1279 @deftypefn Instruction {} logxor u8:@var{dst} u8:@var{a} u8:@var{b}
1280 Compute the bitwise exclusive @code{or} of @var{a} with @var{b}.
1284 @node Inlined Bytevector Instructions
1285 @subsubsection Inlined Bytevector Instructions
1287 Bytevector operations correspond closely to what the current hardware
1288 can do, so it makes sense to inline them to VM instructions, providing
1289 a clear path for eventual native compilation. Without this, Scheme
1290 programs would need other primitives for accessing raw bytes -- but
1291 these primitives are as good as any.
1293 @deftypefn Instruction {} bv-u8-ref u8:@var{dst} u8:@var{src} u8:@var{idx}
1294 @deftypefnx Instruction {} bv-s8-ref u8:@var{dst} u8:@var{src} u8:@var{idx}
1295 @deftypefnx Instruction {} bv-u16-ref u8:@var{dst} u8:@var{src} u8:@var{idx}
1296 @deftypefnx Instruction {} bv-s16-ref u8:@var{dst} u8:@var{src} u8:@var{idx}
1297 @deftypefnx Instruction {} bv-u32-ref u8:@var{dst} u8:@var{src} u8:@var{idx}
1298 @deftypefnx Instruction {} bv-s32-ref u8:@var{dst} u8:@var{src} u8:@var{idx}
1299 @deftypefnx Instruction {} bv-u64-ref u8:@var{dst} u8:@var{src} u8:@var{idx}
1300 @deftypefnx Instruction {} bv-s64-ref u8:@var{dst} u8:@var{src} u8:@var{idx}
1301 @deftypefnx Instruction {} bv-f32-ref u8:@var{dst} u8:@var{src} u8:@var{idx}
1302 @deftypefnx Instruction {} bv-f64-ref u8:@var{dst} u8:@var{src} u8:@var{idx}
1304 Fetch the item at byte offset @var{idx} in the bytevector @var{src}, and
1305 store it in @var{dst}. All accesses use native endianness.
1308 @deftypefn Instruction {} bv-u8-set! u8:@var{dst} u8:@var{idx} u8:@var{src}
1309 @deftypefnx Instruction {} bv-s8-set! u8:@var{dst} u8:@var{idx} u8:@var{src}
1310 @deftypefnx Instruction {} bv-u16-set! u8:@var{dst} u8:@var{idx} u8:@var{src}
1311 @deftypefnx Instruction {} bv-s16-set! u8:@var{dst} u8:@var{idx} u8:@var{src}
1312 @deftypefnx Instruction {} bv-u32-set! u8:@var{dst} u8:@var{idx} u8:@var{src}
1313 @deftypefnx Instruction {} bv-s32-set! u8:@var{dst} u8:@var{idx} u8:@var{src}
1314 @deftypefnx Instruction {} bv-u64-set! u8:@var{dst} u8:@var{idx} u8:@var{src}
1315 @deftypefnx Instruction {} bv-s64-set! u8:@var{dst} u8:@var{idx} u8:@var{src}
1316 @deftypefnx Instruction {} bv-f32-set! u8:@var{dst} u8:@var{idx} u8:@var{src}
1317 @deftypefnx Instruction {} bv-f64-set! u8:@var{dst} u8:@var{idx} u8:@var{src}
1319 Store @var{src} into the bytevector @var{dst} at byte offset @var{idx}.
1320 Multibyte values are written using native endianness.