vm.texi 73 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693
  1. @c -*-texinfo-*-
  2. @c This is part of the GNU Guile Reference Manual.
  3. @c Copyright (C) 2008-2011, 2013, 2015, 2018
  4. @c Free Software Foundation, Inc.
  5. @c See the file guile.texi for copying conditions.
  6. @node A Virtual Machine for Guile
  7. @section A Virtual Machine for Guile
  8. Guile has both an interpreter and a compiler. To a user, the difference
  9. is transparent---interpreted and compiled procedures can call each other
  10. as they please.
  11. The difference is that the compiler creates and interprets bytecode
  12. for a custom virtual machine, instead of interpreting the
  13. S-expressions directly. Loading and running compiled code is faster
  14. than loading and running source code.
  15. The virtual machine that does the bytecode interpretation is a part of
  16. Guile itself. This section describes the nature of Guile's virtual
  17. machine.
  18. @menu
  19. * Why a VM?::
  20. * VM Concepts::
  21. * Stack Layout::
  22. * Variables and the VM::
  23. * VM Programs::
  24. * Object File Format::
  25. * Instruction Set::
  26. @end menu
  27. @node Why a VM?
  28. @subsection Why a VM?
  29. @cindex interpreter
  30. For a long time, Guile only had an interpreter. Guile's interpreter
  31. operated directly on the S-expression representation of Scheme source
  32. code.
  33. But while the interpreter was highly optimized and hand-tuned, it still
  34. performed many needless computations during the course of evaluating an
  35. expression. For example, application of a function to arguments
  36. needlessly consed up the arguments in a list. Evaluation of an
  37. expression always had to figure out what the car of the expression is --
  38. a procedure, a memoized form, or something else. All values have to be
  39. allocated on the heap. Et cetera.
  40. The solution to this problem was to compile the higher-level language,
  41. Scheme, into a lower-level language for which all of the checks and
  42. dispatching have already been done---the code is instead stripped to
  43. the bare minimum needed to ``do the job''.
  44. The question becomes then, what low-level language to choose? There
  45. are many options. We could compile to native code directly, but that
  46. poses portability problems for Guile, as it is a highly cross-platform
  47. project.
  48. So we want the performance gains that compilation provides, but we
  49. also want to maintain the portability benefits of a single code path.
  50. The obvious solution is to compile to a virtual machine that is
  51. present on all Guile installations.
  52. The easiest (and most fun) way to depend on a virtual machine is to
  53. implement the virtual machine within Guile itself. Guile contains a
  54. bytecode interpreter (written in C) and a Scheme to bytecode compiler
  55. (written in Scheme). This way the virtual machine provides what Scheme
  56. needs (tail calls, multiple values, @code{call/cc}) and can provide
  57. optimized inline instructions for Guile (@code{cons}, @code{struct-ref},
  58. etc.).
  59. So this is what Guile does. The rest of this section describes that VM
  60. that Guile implements, and the compiled procedures that run on it.
  61. Before moving on, though, we should note that though we spoke of the
  62. interpreter in the past tense, Guile still has an interpreter. The
  63. difference is that before, it was Guile's main evaluator, and so was
  64. implemented in highly optimized C; now, it is actually implemented in
  65. Scheme, and compiled down to VM bytecode, just like any other program.
  66. (There is still a C interpreter around, used to bootstrap the compiler,
  67. but it is not normally used at runtime.)
  68. The upside of implementing the interpreter in Scheme is that we preserve
  69. tail calls and multiple-value handling between interpreted and compiled
  70. code. The downside is that the interpreter in Guile 2.2 is still about
  71. twice as slow as the interpreter in 1.8. Since Scheme users are mostly
  72. running compiled code, the compiler's speed more than makes up for the
  73. loss. In any case, once we have native compilation for Scheme code, we
  74. expect the self-hosted interpreter to handily beat the old hand-tuned C
  75. implementation.
  76. Also note that this decision to implement a bytecode compiler does not
  77. preclude native compilation. We can compile from bytecode to native
  78. code at runtime, or even do ahead of time compilation. More
  79. possibilities are discussed in @ref{Extending the Compiler}.
  80. @node VM Concepts
  81. @subsection VM Concepts
  82. Compiled code is run by a virtual machine (VM). Each thread has its own
  83. VM. The virtual machine executes the sequence of instructions in a
  84. procedure.
  85. Each VM instruction starts by indicating which operation it is, and then
  86. follows by encoding its source and destination operands. Each procedure
  87. declares that it has some number of local variables, including the
  88. function arguments. These local variables form the available operands
  89. of the procedure, and are accessed by index.
  90. The local variables for a procedure are stored on a stack. Calling a
  91. procedure typically enlarges the stack, and returning from a procedure
  92. shrinks it. Stack memory is exclusive to the virtual machine that owns
  93. it.
  94. In addition to their stacks, virtual machines also have access to the
  95. global memory (modules, global bindings, etc) that is shared among other
  96. parts of Guile, including other VMs.
  97. The registers that a VM has are as follows:
  98. @itemize
  99. @item ip - Instruction pointer
  100. @item sp - Stack pointer
  101. @item fp - Frame pointer
  102. @end itemize
  103. In other architectures, the instruction pointer is sometimes called the
  104. ``program counter'' (pc). This set of registers is pretty typical for
  105. virtual machines; their exact meanings in the context of Guile's VM are
  106. described in the next section.
  107. @node Stack Layout
  108. @subsection Stack Layout
  109. The stack of Guile's virtual machine is composed of @dfn{frames}. Each
  110. frame corresponds to the application of one compiled procedure, and
  111. contains storage space for arguments, local variables, and some
  112. bookkeeping information (such as what to do after the frame is
  113. finished).
  114. While the compiler is free to do whatever it wants to, as long as the
  115. semantics of a computation are preserved, in practice every time you
  116. call a function, a new frame is created. (The notable exception of
  117. course is the tail call case, @pxref{Tail Calls}.)
  118. The structure of the top stack frame is as follows:
  119. @example
  120. | ... |
  121. +==================+ <- fp + 2 = SCM_FRAME_PREVIOUS_SP (fp)
  122. | Dynamic link |
  123. +------------------+
  124. | Return address |
  125. +==================+ <- fp
  126. | Local 0 |
  127. +------------------+
  128. | Local 1 |
  129. +------------------+
  130. | ... |
  131. +------------------+
  132. | Local N-1 |
  133. \------------------/ <- sp
  134. @end example
  135. In the above drawing, the stack grows downward. At the beginning of a
  136. function call, the procedure being applied is in local 0, followed by
  137. the arguments from local 1. After the procedure checks that it is being
  138. passed a compatible set of arguments, the procedure allocates some
  139. additional space in the frame to hold variables local to the function.
  140. Note that once a value in a local variable slot is no longer needed,
  141. Guile is free to re-use that slot. This applies to the slots that were
  142. initially used for the callee and arguments, too. For this reason,
  143. backtraces in Guile aren't always able to show all of the arguments: it
  144. could be that the slot corresponding to that argument was re-used by
  145. some other variable.
  146. The @dfn{return address} is the @code{ip} that was in effect before this
  147. program was applied. When we return from this activation frame, we will
  148. jump back to this @code{ip}. Likewise, the @dfn{dynamic link} is the
  149. offset of the @code{fp} that was in effect before this program was
  150. applied, relative to the current @code{fp}.
  151. To prepare for a non-tail application, Guile's VM will emit code that
  152. shuffles the function to apply and its arguments into appropriate stack
  153. slots, with two free slots below them. The call then initializes those
  154. free slots with the current @code{ip} and @code{fp}, and updates
  155. @code{ip} to point to the function entry, and @code{fp} to point to the
  156. new call frame.
  157. In this way, the dynamic link links the current frame to the previous
  158. frame. Computing a stack trace involves traversing these frames.
  159. Each stack local in Guile is 64 bits wide, even on 32-bit architectures.
  160. This allows Guile to preserve its uniform treatment of stack locals
  161. while allowing for unboxed arithmetic on 64-bit integers and
  162. floating-point numbers. @xref{Instruction Set}, for more on unboxed
  163. arithmetic.
  164. As an implementation detail, we actually store the dynamic link as an
  165. offset and not an absolute value because the stack can move at runtime
  166. as it expands or during partial continuation calls. If it were an
  167. absolute value, we would have to walk the frames, relocating frame
  168. pointers.
  169. @node Variables and the VM
  170. @subsection Variables and the VM
  171. Consider the following Scheme code as an example:
  172. @example
  173. (define (foo a)
  174. (lambda (b) (list foo a b)))
  175. @end example
  176. Within the lambda expression, @code{foo} is a top-level variable,
  177. @code{a} is a lexically captured variable, and @code{b} is a local
  178. variable.
  179. Another way to refer to @code{a} and @code{b} is to say that @code{a} is
  180. a ``free'' variable, since it is not defined within the lambda, and
  181. @code{b} is a ``bound'' variable. These are the terms used in the
  182. @dfn{lambda calculus}, a mathematical notation for describing functions.
  183. The lambda calculus is useful because it is a language in which to
  184. reason precisely about functions and variables. It is especially good
  185. at describing scope relations, and it is for that reason that we mention
  186. it here.
  187. Guile allocates all variables on the stack. When a lexically enclosed
  188. procedure with free variables---a @dfn{closure}---is created, it copies
  189. those variables into its free variable vector. References to free
  190. variables are then redirected through the free variable vector.
  191. If a variable is ever @code{set!}, however, it will need to be
  192. heap-allocated instead of stack-allocated, so that different closures
  193. that capture the same variable can see the same value. Also, this
  194. allows continuations to capture a reference to the variable, instead
  195. of to its value at one point in time. For these reasons, @code{set!}
  196. variables are allocated in ``boxes''---actually, in variable cells.
  197. @xref{Variables}, for more information. References to @code{set!}
  198. variables are indirected through the boxes.
  199. Thus perhaps counterintuitively, what would seem ``closer to the
  200. metal'', viz @code{set!}, actually forces an extra memory allocation and
  201. indirection. Sometimes Guile's optimizer can remove this allocation,
  202. but not always.
  203. Going back to our example, @code{b} may be allocated on the stack, as
  204. it is never mutated.
  205. @code{a} may also be allocated on the stack, as it too is never
  206. mutated. Within the enclosed lambda, its value will be copied into
  207. (and referenced from) the free variables vector.
  208. @code{foo} is a top-level variable, because @code{foo} is not
  209. lexically bound in this example.
  210. @node VM Programs
  211. @subsection Compiled Procedures are VM Programs
  212. By default, when you enter in expressions at Guile's REPL, they are
  213. first compiled to bytecode. Then that bytecode is executed to produce a
  214. value. If the expression evaluates to a procedure, the result of this
  215. process is a compiled procedure.
  216. A compiled procedure is a compound object consisting of its bytecode and
  217. a reference to any captured lexical variables. In addition, when a
  218. procedure is compiled, it has associated metadata written to side
  219. tables, for instance a line number mapping, or its docstring. You can
  220. pick apart these pieces with the accessors in @code{(system vm
  221. program)}. @xref{Compiled Procedures}, for a full API reference.
  222. A procedure may reference data that was statically allocated when the
  223. procedure was compiled. For example, a pair of immediate objects
  224. (@pxref{Immediate objects}) can be allocated directly in the memory
  225. segment that contains the compiled bytecode, and accessed directly by
  226. the bytecode.
  227. Another use for statically allocated data is to serve as a cache for a
  228. bytecode. Top-level variable lookups are handled in this way. If the
  229. @code{toplevel-box} instruction finds that it does not have a cached
  230. variable for a top-level reference, it accesses other static data to
  231. resolve the reference, and fills in the cache slot. Thereafter all
  232. access to the variable goes through the cache cell. The variable's
  233. value may change in the future, but the variable itself will not.
  234. We can see how these concepts tie together by disassembling the
  235. @code{foo} function we defined earlier to see what is going on:
  236. @smallexample
  237. scheme@@(guile-user)> (define (foo a) (lambda (b) (list foo a b)))
  238. scheme@@(guile-user)> ,x foo
  239. Disassembly of #<procedure foo (a)> at #xea4ce4:
  240. 0 (assert-nargs-ee/locals 2 0) ;; 2 slots (1 arg) at (unknown file):1:0
  241. 1 (make-closure 1 7 1) ;; anonymous procedure at #xea4d04 (1 free var)
  242. 4 (free-set! 1 0 0) ;; free var 0
  243. 6 (mov 0 1)
  244. 7 (return-values 2) ;; 1 value
  245. ----------------------------------------
  246. Disassembly of anonymous procedure at #xea4d04:
  247. 0 (assert-nargs-ee/locals 2 2) ;; 4 slots (1 arg) at (unknown file):1:16
  248. 1 (toplevel-box 1 74 58 68 #t) ;; `foo'
  249. 6 (box-ref 1 1)
  250. 7 (make-short-immediate 0 772) ;; () at (unknown file):1:28
  251. 8 (cons 2 2 0)
  252. 9 (free-ref 3 3 0) ;; free var 0
  253. 11 (cons 3 3 2)
  254. 12 (cons 2 1 3)
  255. 13 (return-values 2) ;; 1 value
  256. @end smallexample
  257. First there's some prelude, where @code{foo} checks that it was called
  258. with only 1 argument. Then at @code{ip} 1, we allocate a new closure
  259. and store it in slot 1, relative to the @code{sp}.
  260. At run-time, local variables in Guile are usually addressed relative to
  261. the stack pointer, which leads to a pleasantly efficient
  262. @code{sp[@var{n}]} access. However it can make the disassembly hard to
  263. read, because the @code{sp} can change during the function, and because
  264. incoming arguments are relative to the @code{fp}, not the @code{sp}.
  265. To know what @code{fp}-relative slot corresponds to an
  266. @code{sp}-relative reference, scan up in the disassembly until you get
  267. to a ``@var{n} slots'' annotation; in our case, 2, indicating that the
  268. frame has space for 2 slots. Thus a zero-indexed @code{sp}-relative
  269. slot of 1 corresponds to the @code{fp}-relative slot of 0, which
  270. initially held the value of the closure being called. This means that
  271. Guile doesn't need the value of the closure to compute its result, and
  272. so slot 0 was free for re-use, in this case for the result of making a
  273. new closure.
  274. A closure is code with data. The @code{6} in the @code{(make-closure 1
  275. 6 1)} is a relative offset from the instruction pointer of the code for
  276. the closure, and the final @code{1} indicates that the closure has space
  277. for 1 free variable. @code{Ip} 4 initializes free variable 0 in the new
  278. closure with the value from @code{sp}-relative slot 0, which corresponds
  279. to @code{fp}-relative slot 1, the first argument of @code{foo}:
  280. @code{a}. Finally we return the closure.
  281. The second stanza disassembles the code for the closure. After the
  282. prelude, we load the variable for the toplevel variable @code{foo} into
  283. slot 1. This lookup occurs lazily, the first time the variable is
  284. actually referenced, and the location of the lookup is cached so that
  285. future references are very cheap. @xref{Top-Level Environment
  286. Instructions}, for more details. The @code{box-ref} dereferences the
  287. variable cell, replacing the contents of slot 1.
  288. What follows is a sequence of conses to build up the result list.
  289. @code{Ip} 7 makes the tail of the list. @code{Ip} 8 conses on the value
  290. in slot 2, corresponding to the first argument to the closure: @code{b}.
  291. @code{Ip} 9 loads free variable 0 of slot 3 -- the procedure being
  292. called, in @code{fp}-relative slot 0 -- into slot 3, then @code{ip} 11
  293. conses it onto the list. Finally we cons the value in slot 1,
  294. containing the @code{foo} toplevel, onto the front of the list, and we
  295. return it.
  296. @node Object File Format
  297. @subsection Object File Format
  298. To compile a file to disk, we need a format in which to write the
  299. compiled code to disk, and later load it into Guile. A good @dfn{object
  300. file format} has a number of characteristics:
  301. @itemize
  302. @item Above all else, it should be very cheap to load a compiled file.
  303. @item It should be possible to statically allocate constants in the
  304. file. For example, a bytevector literal in source code can be emitted
  305. directly into the object file.
  306. @item The compiled file should enable maximum code and data sharing
  307. between different processes.
  308. @item The compiled file should contain debugging information, such as
  309. line numbers, but that information should be separated from the code
  310. itself. It should be possible to strip debugging information if space
  311. is tight.
  312. @end itemize
  313. These characteristics are not specific to Scheme. Indeed, mainstream
  314. languages like C and C++ have solved this issue many times in the past.
  315. Guile builds on their work by adopting ELF, the object file format of
  316. GNU and other Unix-like systems, as its object file format. Although
  317. Guile uses ELF on all platforms, we do not use platform support for ELF.
  318. Guile implements its own linker and loader. The advantage of using ELF
  319. is not sharing code, but sharing ideas. ELF is simply a well-designed
  320. object file format.
  321. An ELF file has two meta-tables describing its contents. The first
  322. meta-table is for the loader, and is called the @dfn{program table} or
  323. sometimes the @dfn{segment table}. The program table divides the file
  324. into big chunks that should be treated differently by the loader.
  325. Mostly the difference between these @dfn{segments} is their
  326. permissions.
  327. Typically all segments of an ELF file are marked as read-only, except
  328. that part that represents modifiable static data or static data that
  329. needs load-time initialization. Loading an ELF file is as simple as
  330. mmapping the thing into memory with read-only permissions, then using
  331. the segment table to mark a small sub-region of the file as writable.
  332. This writable section is typically added to the root set of the garbage
  333. collector as well.
  334. One ELF segment is marked as ``dynamic'', meaning that it has data of
  335. interest to the loader. Guile uses this segment to record the Guile
  336. version corresponding to this file. There is also an entry in the
  337. dynamic segment that points to the address of an initialization thunk
  338. that is run to perform any needed link-time initialization. (This is
  339. like dynamic relocations for normal ELF shared objects, except that we
  340. compile the relocations as a procedure instead of having the loader
  341. interpret a table of relocations.) Finally, the dynamic segment marks
  342. the location of the ``entry thunk'' of the object file. This thunk is
  343. returned to the caller of @code{load-thunk-from-memory} or
  344. @code{load-thunk-from-file}. When called, it will execute the ``body''
  345. of the compiled expression.
  346. The other meta-table in an ELF file is the @dfn{section table}. Whereas
  347. the program table divides an ELF file into big chunks for the loader,
  348. the section table specifies small sections for use by introspective
  349. tools like debuggers or the like. One segment (program table entry)
  350. typically contains many sections. There may be sections outside of any
  351. segment, as well.
  352. Typical sections in a Guile @code{.go} file include:
  353. @table @code
  354. @item .rtl-text
  355. Bytecode.
  356. @item .data
  357. Data that needs initialization, or which may be modified at runtime.
  358. @item .rodata
  359. Statically allocated data that needs no run-time initialization, and
  360. which therefore can be shared between processes.
  361. @item .dynamic
  362. The dynamic section, discussed above.
  363. @item .symtab
  364. @itemx .strtab
  365. A table mapping addresses in the @code{.rtl-text} to procedure names.
  366. @code{.strtab} is used by @code{.symtab}.
  367. @item .guile.procprops
  368. @itemx .guile.arities
  369. @itemx .guile.arities.strtab
  370. @itemx .guile.docstrs
  371. @itemx .guile.docstrs.strtab
  372. Side tables of procedure properties, arities, and docstrings.
  373. @item .guile.docstrs.strtab
  374. Side table of frame maps, describing the set of live slots for ever
  375. return point in the program text, and whether those slots are pointers
  376. are not. Used by the garbage collector.
  377. @item .debug_info
  378. @itemx .debug_abbrev
  379. @itemx .debug_str
  380. @itemx .debug_loc
  381. @itemx .debug_line
  382. Debugging information, in DWARF format. See the DWARF specification,
  383. for more information.
  384. @item .shstrtab
  385. Section name string table.
  386. @end table
  387. For more information, see @uref{http://linux.die.net/man/5/elf,,the
  388. elf(5) man page}. See @uref{http://dwarfstd.org/,the DWARF
  389. specification} for more on the DWARF debugging format. Or if you are an
  390. adventurous explorer, try running @code{readelf} or @code{objdump} on
  391. compiled @code{.go} files. It's good times!
  392. @node Instruction Set
  393. @subsection Instruction Set
  394. There are currently about 175 instructions in Guile's virtual machine.
  395. These instructions represent atomic units of a program's execution.
  396. Ideally, they perform one task without conditional branches, then
  397. dispatch to the next instruction in the stream.
  398. Instructions themselves are composed of 1 or more 32-bit units. The low
  399. 8 bits of the first word indicate the opcode, and the rest of
  400. instruction describe the operands. There are a number of different ways
  401. operands can be encoded.
  402. @table @code
  403. @item s@var{n}
  404. An unsigned @var{n}-bit integer, indicating the @code{sp}-relative index
  405. of a local variable.
  406. @item f@var{n}
  407. An unsigned @var{n}-bit integer, indicating the @code{fp}-relative index
  408. of a local variable. Used when a continuation accepts a variable number
  409. of values, to shuffle received values into known locations in the
  410. frame.
  411. @item c@var{n}
  412. An unsigned @var{n}-bit integer, indicating a constant value.
  413. @item l24
  414. An offset from the current @code{ip}, in 32-bit units, as a signed
  415. 24-bit value. Indicates a bytecode address, for a relative jump.
  416. @item i16
  417. @itemx i32
  418. An immediate Scheme value (@pxref{Immediate objects}), encoded directly
  419. in 16 or 32 bits.
  420. @item a32
  421. @itemx b32
  422. An immediate Scheme value, encoded as a pair of 32-bit words.
  423. @code{a32} and @code{b32} values always go together on the same opcode,
  424. and indicate the high and low bits, respectively. Normally only used on
  425. 64-bit systems.
  426. @item n32
  427. A statically allocated non-immediate. The address of the non-immediate
  428. is encoded as a signed 32-bit integer, and indicates a relative offset
  429. in 32-bit units. Think of it as @code{SCM x = ip + offset}.
  430. @item r32
  431. Indirect scheme value, like @code{n32} but indirected. Think of it as
  432. @code{SCM *x = ip + offset}.
  433. @item l32
  434. @item lo32
  435. An ip-relative address, as a signed 32-bit integer. Could indicate a
  436. bytecode address, as in @code{make-closure}, or a non-immediate address,
  437. as with @code{static-patch!}.
  438. @code{l32} and @code{lo32} are the same from the perspective of the
  439. virtual machine. The difference is that an assembler might want to
  440. allow an @code{lo32} address to be specified as a label and then some
  441. number of words offset from that label, for example when patching a
  442. field of a statically allocated object.
  443. @item b1
  444. A boolean value: 1 for true, otherwise 0.
  445. @item x@var{n}
  446. An ignored sequence of @var{n} bits.
  447. @end table
  448. An instruction is specified by giving its name, then describing its
  449. operands. The operands are packed by 32-bit words, with earlier
  450. operands occupying the lower bits.
  451. For example, consider the following instruction specification:
  452. @deftypefn Instruction {} free-set! s12:@var{dst} s12:@var{src} x8:@var{_} c24:@var{idx}
  453. Set free variable @var{idx} from the closure @var{dst} to @var{src}.
  454. @end deftypefn
  455. The first word in the instruction will start with the 8-bit value
  456. corresponding to the @var{free-set!} opcode in the low bits, followed by
  457. @var{dst} and @var{src} as 12-bit values. The second word starts with 8
  458. dead bits, followed by the index as a 24-bit immediate value.
  459. Sometimes the compiler can figure out that it is compiling a special
  460. case that can be run more efficiently. So, for example, while Guile
  461. offers a generic test-and-branch instruction, it also offers specific
  462. instructions for special cases, so that the following cases all have
  463. their own test-and-branch instructions:
  464. @example
  465. (if pred then else)
  466. (if (not pred) then else)
  467. (if (null? l) then else)
  468. (if (not (null? l)) then else)
  469. @end example
  470. In addition, some Scheme primitives have their own inline
  471. implementations. For example, in the previous section we saw
  472. @code{cons}.
  473. Finally, for instructions with operands that encode references to the
  474. stack, the interpretation of those stack values is up to the instruction
  475. itself. Most instructions expect their operands to be tagged SCM values
  476. (@code{scm} representation), but some instructions expect unboxed
  477. integers (@code{u64} and @code{s64} representations) or floating-point
  478. numbers (@var{f64} representation). Instructions have static types:
  479. they must receive their operands in the format they expect. It's up to
  480. the compiler to ensure this is the case. Unless otherwise mentioned,
  481. all operands and results are boxed as SCM values.
  482. @menu
  483. * Lexical Environment Instructions::
  484. * Top-Level Environment Instructions::
  485. * Procedure Call and Return Instructions::
  486. * Function Prologue Instructions::
  487. * Trampoline Instructions::
  488. * Branch Instructions::
  489. * Constant Instructions::
  490. * Dynamic Environment Instructions::
  491. * Miscellaneous Instructions::
  492. * Inlined Scheme Instructions::
  493. * Inlined Atomic Instructions::
  494. * Inlined Mathematical Instructions::
  495. * Inlined Bytevector Instructions::
  496. * Unboxed Integer Arithmetic::
  497. * Unboxed Floating-Point Arithmetic::
  498. @end menu
  499. @node Lexical Environment Instructions
  500. @subsubsection Lexical Environment Instructions
  501. These instructions access and mutate the lexical environment of a
  502. compiled procedure---its free and bound variables. @xref{Stack Layout},
  503. for more information on the format of stack frames.
  504. @deftypefn Instruction {} mov s12:@var{dst} s12:@var{src}
  505. @deftypefnx Instruction {} long-mov s24:@var{dst} x8:@var{_} s24:@var{src}
  506. Copy a value from one local slot to another.
  507. As discussed previously, procedure arguments and local variables are
  508. allocated to local slots. Guile's compiler tries to avoid shuffling
  509. variables around to different slots, which often makes @code{mov}
  510. instructions redundant. However there are some cases in which shuffling
  511. is necessary, and in those cases, @code{mov} is the thing to use.
  512. @end deftypefn
  513. @deftypefn Instruction {} long-fmov f24:@var{dst} x8:@var{_} f24:@var{src}
  514. Copy a value from one local slot to another, but addressing slots
  515. relative to the @code{fp} instead of the @code{sp}. This is used when
  516. shuffling values into place after multiple-value returns.
  517. @end deftypefn
  518. @deftypefn Instruction {} make-closure s24:@var{dst} l32:@var{offset} x8:@var{_} c24:@var{nfree}
  519. Make a new closure, and write it to @var{dst}. The code for the closure
  520. will be found at @var{offset} words from the current @code{ip}.
  521. @var{offset} is a signed 32-bit integer. Space for @var{nfree} free
  522. variables will be allocated.
  523. The size of a closure is currently two words, plus one word per free
  524. variable.
  525. @end deftypefn
  526. @deftypefn Instruction {} free-ref s12:@var{dst} s12:@var{src} x8:@var{_} c24:@var{idx}
  527. Load free variable @var{idx} from the closure @var{src} into local slot
  528. @var{dst}.
  529. @end deftypefn
  530. @deftypefn Instruction {} free-set! s12:@var{dst} s12:@var{src} x8:@var{_} c24:@var{idx}
  531. Set free variable @var{idx} from the closure @var{dst} to @var{src}.
  532. This instruction is usually used when initializing a closure's free
  533. variables, but not to mutate free variables, as variables that are
  534. assigned are boxed.
  535. @end deftypefn
  536. Recall that variables that are assigned are usually allocated in boxes,
  537. so that continuations and closures can capture their identity and not
  538. their value at one point in time. Variables are also used in the
  539. implementation of top-level bindings; see the next section for more
  540. information.
  541. @deftypefn Instruction {} box s12:@var{dst} s12:@var{src}
  542. Create a new variable holding @var{src}, and place it in @var{dst}.
  543. @end deftypefn
  544. @deftypefn Instruction {} box-ref s12:@var{dst} s12:@var{src}
  545. Unpack the variable at @var{src} into @var{dst}, asserting that the
  546. variable is actually bound.
  547. @end deftypefn
  548. @deftypefn Instruction {} box-set! s12:@var{dst} s12:@var{src}
  549. Set the contents of the variable at @var{dst} to @var{set}.
  550. @end deftypefn
  551. @node Top-Level Environment Instructions
  552. @subsubsection Top-Level Environment Instructions
  553. These instructions access values in the top-level environment: bindings
  554. that were not lexically apparent at the time that the code in question
  555. was compiled.
  556. The location in which a toplevel binding is stored can be looked up once
  557. and cached for later. The binding itself may change over time, but its
  558. location will stay constant.
  559. @deftypefn Instruction {} current-module s24:@var{dst}
  560. Store the current module in @var{dst}.
  561. @end deftypefn
  562. @deftypefn Instruction {} resolve s24:@var{dst} b1:@var{bound?} x7:@var{_} s24:@var{sym}
  563. Resolve @var{sym} in the current module, and place the resulting
  564. variable in @var{dst}. An error will be signalled if no variable is
  565. found. If @var{bound?} is true, an error will be signalled if the
  566. variable is unbound.
  567. @end deftypefn
  568. @deftypefn Instruction {} define! s12:@var{dst} s12:@var{sym}
  569. Look up a binding for @var{sym} in the current module, creating it if
  570. necessary. Store that variable to @var{dst}.
  571. @end deftypefn
  572. @deftypefn Instruction {} toplevel-box s24:@var{dst} r32:@var{var-offset} r32:@var{mod-offset} n32:@var{sym-offset} b1:@var{bound?} x31:@var{_}
  573. Load a value. The value will be fetched from memory, @var{var-offset}
  574. 32-bit words away from the current instruction pointer.
  575. @var{var-offset} is a signed value. Up to here, @code{toplevel-box} is
  576. like @code{static-ref}.
  577. Then, if the loaded value is a variable, it is placed in @var{dst}, and
  578. control flow continues.
  579. Otherwise, we have to resolve the variable. In that case we load the
  580. module from @var{mod-offset}, just as we loaded the variable. Usually
  581. the module gets set when the closure is created. @var{sym-offset}
  582. specifies the name, as an offset to a symbol.
  583. We use the module and the symbol to resolve the variable, placing it in
  584. @var{dst}, and caching the resolved variable so that we will hit the
  585. cache next time. If @var{bound?} is true, an error will be signalled if
  586. the variable is unbound.
  587. @end deftypefn
  588. @deftypefn Instruction {} module-box s24:@var{dst} r32:@var{var-offset} n32:@var{mod-offset} n32:@var{sym-offset} b1:@var{bound?} x31:@var{_}
  589. Like @code{toplevel-box}, except @var{mod-offset} points at a module
  590. identifier instead of the module itself. A module identifier is a
  591. module name, as a list, prefixed by a boolean. If the prefix is true,
  592. then the variable is resolved relative to the module's public interface
  593. instead of its private interface.
  594. @end deftypefn
  595. @node Procedure Call and Return Instructions
  596. @subsubsection Procedure Call and Return Instructions
  597. As described earlier (@pxref{Stack Layout}), Guile's calling convention
  598. is that arguments are passed and values returned on the stack.
  599. For calls, both in tail position and in non-tail position, we require
  600. that the procedure and the arguments already be shuffled into place
  601. before the call instruction. ``Into place'' for a tail call means that
  602. the procedure should be in slot 0, relative to the @code{fp}, and the
  603. arguments should follow. For a non-tail call, if the procedure is in
  604. @code{fp}-relative slot @var{n}, the arguments should follow from slot
  605. @var{n}+1, and there should be two free slots at @var{n}-1 and @var{n}-2
  606. in which to save the @code{ip} and @code{fp}.
  607. Returning values is similar. Multiple-value returns should have values
  608. already shuffled down to start from @code{fp}-relative slot 1 before
  609. emitting @code{return-values}. We start from slot 1 instead of slot 0
  610. to make tail calls to @code{values} trivial.
  611. In both calls and returns, the @code{sp} is used to indicate to the
  612. callee or caller the number of arguments or return values, respectively.
  613. After receiving return values, it is the caller's responsibility to
  614. @dfn{restore the frame} by resetting the @code{sp} to its former value.
  615. @deftypefn Instruction {} call f24:@var{proc} x8:@var{_} c24:@var{nlocals}
  616. Call a procedure. @var{proc} is the local corresponding to a procedure.
  617. The two values below @var{proc} will be overwritten by the saved call
  618. frame data. The new frame will have space for @var{nlocals} locals: one
  619. for the procedure, and the rest for the arguments which should already
  620. have been pushed on.
  621. When the call returns, execution proceeds with the next instruction.
  622. There may be any number of values on the return stack; the precise
  623. number can be had by subtracting the address of @var{proc} from the
  624. post-call @code{sp}.
  625. @end deftypefn
  626. @deftypefn Instruction {} call-label f24:@var{proc} x8:@var{_} c24:@var{nlocals} l32:@var{label}
  627. Call a procedure in the same compilation unit.
  628. This instruction is just like @code{call}, except that instead of
  629. dereferencing @var{proc} to find the call target, the call target is
  630. known to be at @var{label}, a signed 32-bit offset in 32-bit units from
  631. the current @code{ip}. Since @var{proc} is not dereferenced, it may be
  632. some other representation of the closure.
  633. @end deftypefn
  634. @deftypefn Instruction {} tail-call c24:@var{nlocals}
  635. Tail-call a procedure. Requires that the procedure and all of the
  636. arguments have already been shuffled into position. Will reset the
  637. frame to @var{nlocals}.
  638. @end deftypefn
  639. @deftypefn Instruction {} tail-call-label c24:@var{nlocals} l32:@var{label}
  640. Tail-call a known procedure. As @code{call} is to @code{call-label},
  641. @code{tail-call} is to @code{tail-call-label}.
  642. @end deftypefn
  643. @deftypefn Instruction {} tail-call/shuffle f24:@var{from}
  644. Tail-call a procedure. The procedure should already be set to slot 0.
  645. The rest of the args are taken from the frame, starting at @var{from},
  646. shuffled down to start at slot 0. This is part of the implementation of
  647. the @code{call-with-values} builtin.
  648. @end deftypefn
  649. @deftypefn Instruction {} receive f12:@var{dst} f12:@var{proc} x8:@var{_} c24:@var{nlocals}
  650. Receive a single return value from a call whose procedure was in
  651. @var{proc}, asserting that the call actually returned at least one
  652. value. Afterwards, resets the frame to @var{nlocals} locals.
  653. @end deftypefn
  654. @deftypefn Instruction {} receive-values f24:@var{proc} b1:@var{allow-extra?} x7:@var{_} c24:@var{nvalues}
  655. Receive a return of multiple values from a call whose procedure was in
  656. @var{proc}. If fewer than @var{nvalues} values were returned, signal an
  657. error. Unless @var{allow-extra?} is true, require that the number of
  658. return values equals @var{nvalues} exactly. After @code{receive-values}
  659. has run, the values can be copied down via @code{mov}, or used in place.
  660. @end deftypefn
  661. @deftypefn Instruction {} return-values c24:@var{nlocals}
  662. Return a number of values from a call frame. This opcode corresponds to
  663. an application of @code{values} in tail position. As with tail calls,
  664. we expect that the values have already been shuffled down to a
  665. contiguous array starting at slot 1. If @var{nlocals} is nonzero, reset
  666. the frame to hold that number of locals. Note that a frame reset to 1
  667. local returns 0 values.
  668. @end deftypefn
  669. @deftypefn Instruction {} call/cc x24:@var{_}
  670. Capture the current continuation, and tail-apply the procedure in local
  671. slot 1 to it. This instruction is part of the implementation of
  672. @code{call/cc}, and is not generated by the compiler.
  673. @end deftypefn
  674. @node Function Prologue Instructions
  675. @subsubsection Function Prologue Instructions
  676. A function call in Guile is very cheap: the VM simply hands control to
  677. the procedure. The procedure itself is responsible for asserting that it
  678. has been passed an appropriate number of arguments. This strategy allows
  679. arbitrarily complex argument parsing idioms to be developed, without
  680. harming the common case.
  681. For example, only calls to keyword-argument procedures ``pay'' for the
  682. cost of parsing keyword arguments. (At the time of this writing, calling
  683. procedures with keyword arguments is typically two to four times as
  684. costly as calling procedures with a fixed set of arguments.)
  685. @deftypefn Instruction {} assert-nargs-ee c24:@var{expected}
  686. @deftypefnx Instruction {} assert-nargs-ge c24:@var{expected}
  687. @deftypefnx Instruction {} assert-nargs-le c24:@var{expected}
  688. If the number of actual arguments is not @code{==}, @code{>=}, or
  689. @code{<=} @var{expected}, respectively, signal an error.
  690. The number of arguments is determined by subtracting the stack pointer
  691. from the frame pointer (@code{fp - sp}). @xref{Stack Layout}, for more
  692. details on stack frames. Note that @var{expected} includes the
  693. procedure itself.
  694. @end deftypefn
  695. @deftypefn Instruction {} br-if-nargs-ne c24:@var{expected} x8:@var{_} l24:@var{offset}
  696. @deftypefnx Instruction {} br-if-nargs-lt c24:@var{expected} x8:@var{_} l24:@var{offset}
  697. @deftypefnx Instruction {} br-if-nargs-gt c24:@var{expected} x8:@var{_} l24:@var{offset}
  698. If the number of actual arguments is not equal, less than, or greater
  699. than @var{expected}, respectively, add @var{offset}, a signed 24-bit
  700. number, to the current instruction pointer. Note that @var{expected}
  701. includes the procedure itself.
  702. These instructions are used to implement multiple arities, as in
  703. @code{case-lambda}. @xref{Case-lambda}, for more information.
  704. @end deftypefn
  705. @deftypefn Instruction {} alloc-frame c24:@var{nlocals}
  706. Ensure that there is space on the stack for @var{nlocals} local
  707. variables, setting them all to @code{SCM_UNDEFINED}, except those values
  708. that are already on the stack.
  709. @end deftypefn
  710. @deftypefn Instruction {} reset-frame c24:@var{nlocals}
  711. Like @code{alloc-frame}, but doesn't check that the stack is big enough,
  712. and doesn't initialize values to @code{SCM_UNDEFINED}. Used to reset
  713. the frame size to something less than the size that was previously set
  714. via alloc-frame.
  715. @end deftypefn
  716. @deftypefn Instruction {} assert-nargs-ee/locals c12:@var{expected} c12:@var{nlocals}
  717. Equivalent to a sequence of @code{assert-nargs-ee} and
  718. @code{reserve-locals}. The number of locals reserved is @var{expected}
  719. + @var{nlocals}.
  720. @end deftypefn
  721. @deftypefn Instruction {} br-if-npos-gt c24:@var{nreq} x8:@var{_} c24:@var{npos} x8:@var{_} l24:@var{offset}
  722. Find the first positional argument after @var{nreq}. If it is greater
  723. than @var{npos}, jump to @var{offset}.
  724. This instruction is only emitted for functions with multiple clauses,
  725. and an earlier clause has keywords and no rest arguments.
  726. @xref{Case-lambda}, for more on how @code{case-lambda} chooses the
  727. clause to apply.
  728. @end deftypefn
  729. @deftypefn Instruction {} bind-kwargs c24:@var{nreq} c8:@var{flags} c24:@var{nreq-and-opt} x8:@var{_} c24:@var{ntotal} n32:@var{kw-offset}
  730. @var{flags} is a bitfield, whose lowest bit is @var{allow-other-keys},
  731. second bit is @var{has-rest}, and whose following six bits are unused.
  732. Find the last positional argument, and shuffle all the rest above
  733. @var{ntotal}. Initialize the intervening locals to
  734. @code{SCM_UNDEFINED}. Then load the constant at @var{kw-offset} words
  735. from the current @var{ip}, and use it and the @var{allow-other-keys}
  736. flag to bind keyword arguments. If @var{has-rest}, collect all shuffled
  737. arguments into a list, and store it in @var{nreq-and-opt}. Finally,
  738. clear the arguments that we shuffled up.
  739. The parsing is driven by a keyword arguments association list, looked up
  740. using @var{kw-offset}. The alist is a list of pairs of the form
  741. @code{(@var{kw} . @var{index})}, mapping keyword arguments to their
  742. local slot indices. Unless @code{allow-other-keys} is set, the parser
  743. will signal an error if an unknown key is found.
  744. A macro-mega-instruction.
  745. @end deftypefn
  746. @deftypefn Instruction {} bind-rest f24:@var{dst}
  747. Collect any arguments at or above @var{dst} into a list, and store that
  748. list at @var{dst}.
  749. @end deftypefn
  750. @node Trampoline Instructions
  751. @subsubsection Trampoline Instructions
  752. Though most applicable objects in Guile are procedures implemented in
  753. bytecode, not all are. There are primitives, continuations, and other
  754. procedure-like objects that have their own calling convention. Instead
  755. of adding special cases to the @code{call} instruction, Guile wraps
  756. these other applicable objects in VM trampoline procedures, then
  757. provides special support for these objects in bytecode.
  758. Trampoline procedures are typically generated by Guile at runtime, for
  759. example in response to a call to @code{scm_c_make_gsubr}. As such, a
  760. compiler probably shouldn't emit code with these instructions. However,
  761. it's still interesting to know how these things work, so we document
  762. these trampoline instructions here.
  763. @deftypefn Instruction {} subr-call x24:@var{_}
  764. Call a subr, passing all locals in this frame as arguments. Return from
  765. the calling frame.
  766. @end deftypefn
  767. @deftypefn Instruction {} foreign-call c12:@var{cif-idx} c12:@var{ptr-idx}
  768. Call a foreign function. Fetch the @var{cif} and foreign pointer from
  769. @var{cif-idx} and @var{ptr-idx}, both free variables. Return from the calling
  770. frame. Arguments are taken from the stack.
  771. @end deftypefn
  772. @deftypefn Instruction {} continuation-call c24:@var{contregs}
  773. Return to a continuation, nonlocally. The arguments to the continuation
  774. are taken from the stack. @var{contregs} is a free variable containing
  775. the reified continuation.
  776. @end deftypefn
  777. @deftypefn Instruction {} compose-continuation c24:@var{cont}
  778. Compose a partial continution with the current continuation. The
  779. arguments to the continuation are taken from the stack. @var{cont} is a
  780. free variable containing the reified continuation.
  781. @end deftypefn
  782. @deftypefn Instruction {} tail-apply x24:@var{_}
  783. Tail-apply the procedure in local slot 0 to the rest of the arguments.
  784. This instruction is part of the implementation of @code{apply}, and is
  785. not generated by the compiler.
  786. @end deftypefn
  787. @deftypefn Instruction {} builtin-ref s12:@var{dst} c12:@var{idx}
  788. Load a builtin stub by index into @var{dst}.
  789. @end deftypefn
  790. @deftypefn Instruction {} apply-non-program x24:@var{_}
  791. An instruction used only by a special trampoline that the VM uses to
  792. apply non-programs. Using that trampoline allows profilers and
  793. backtrace utilities to avoid seeing the instruction pointer from the
  794. calling frame.
  795. @end deftypefn
  796. @node Branch Instructions
  797. @subsubsection Branch Instructions
  798. All offsets to branch instructions are 24-bit signed numbers, which
  799. count 32-bit units. This gives Guile effectively a 26-bit address range
  800. for relative jumps.
  801. @deftypefn Instruction {} br l24:@var{offset}
  802. Add @var{offset} to the current instruction pointer.
  803. @end deftypefn
  804. All the conditional branch instructions described below have an
  805. @var{invert} parameter, which if true reverses the test:
  806. @code{br-if-true} becomes @code{br-if-false}, and so on.
  807. @deftypefn Instruction {} br-if-true s24:@var{test} b1:@var{invert} x7:@var{_} l24:@var{offset}
  808. If the value in @var{test} is true for the purposes of Scheme, add
  809. @var{offset} to the current instruction pointer.
  810. @end deftypefn
  811. @deftypefn Instruction {} br-if-null s24:@var{test} b1:@var{invert} x7:@var{_} l24:@var{offset}
  812. If the value in @var{test} is the end-of-list or Lisp nil, add
  813. @var{offset} to the current instruction pointer.
  814. @end deftypefn
  815. @deftypefn Instruction {} br-if-nil s24:@var{test} b1:@var{invert} x7:@var{_} l24:@var{offset}
  816. If the value in @var{test} is false to Lisp, add @var{offset} to the
  817. current instruction pointer.
  818. @end deftypefn
  819. @deftypefn Instruction {} br-if-pair s24:@var{test} b1:@var{invert} x7:@var{_} l24:@var{offset}
  820. If the value in @var{test} is a pair, add @var{offset} to the current
  821. instruction pointer.
  822. @end deftypefn
  823. @deftypefn Instruction {} br-if-struct s24:@var{test} b1:@var{invert} x7:@var{_} l24:@var{offset}
  824. If the value in @var{test} is a struct, add @var{offset} number to the
  825. current instruction pointer.
  826. @end deftypefn
  827. @deftypefn Instruction {} br-if-char s24:@var{test} b1:@var{invert} x7:@var{_} l24:@var{offset}
  828. If the value in @var{test} is a char, add @var{offset} to the current
  829. instruction pointer.
  830. @end deftypefn
  831. @deftypefn Instruction {} br-if-tc7 s24:@var{test} b1:@var{invert} u7:@var{tc7} l24:@var{offset}
  832. If the value in @var{test} has the TC7 given in the second word, add
  833. @var{offset} to the current instruction pointer. TC7 codes are part of
  834. the way Guile represents non-immediate objects, and are deep wizardry.
  835. See @code{libguile/tags.h} for all the details.
  836. @end deftypefn
  837. @deftypefn Instruction {} br-if-eq s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  838. @deftypefnx Instruction {} br-if-eqv s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  839. If the value in @var{a} is @code{eq?} or @code{eqv?} to the value in
  840. @var{b}, respectively, add @var{offset} to the current instruction
  841. pointer.
  842. @end deftypefn
  843. @deftypefn Instruction {} br-if-= s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  844. @deftypefnx Instruction {} br-if-< s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  845. @deftypefnx Instruction {} br-if-<= s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  846. If the value in @var{a} is @code{=}, @code{<}, or @code{<=} to the value
  847. in @var{b}, respectively, add @var{offset} to the current instruction
  848. pointer.
  849. @end deftypefn
  850. @deftypefn Instruction {} br-if-logtest s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  851. If the bitwise intersection of the integers in @var{a} and @var{b} is
  852. nonzero, add @var{offset} to the current instruction pointer.
  853. @end deftypefn
  854. @node Constant Instructions
  855. @subsubsection Constant Instructions
  856. The following instructions load literal data into a program. There are
  857. two kinds.
  858. The first set of instructions loads immediate values. These
  859. instructions encode the immediate directly into the instruction stream.
  860. @deftypefn Instruction {} make-short-immediate s8:@var{dst} i16:@var{low-bits}
  861. Make an immediate whose low bits are @var{low-bits}, and whose top bits are
  862. 0.
  863. @end deftypefn
  864. @deftypefn Instruction {} make-long-immediate s24:@var{dst} i32:@var{low-bits}
  865. Make an immediate whose low bits are @var{low-bits}, and whose top bits are
  866. 0.
  867. @end deftypefn
  868. @deftypefn Instruction {} make-long-long-immediate s24:@var{dst} a32:@var{high-bits} b32:@var{low-bits}
  869. Make an immediate with @var{high-bits} and @var{low-bits}.
  870. @end deftypefn
  871. Non-immediate constant literals are referenced either directly or
  872. indirectly. For example, Guile knows at compile-time what the layout of
  873. a string will be like, and arranges to embed that object directly in the
  874. compiled image. A reference to a string will use
  875. @code{make-non-immediate} to treat a pointer into the compilation unit
  876. as a @code{SCM} value directly.
  877. @deftypefn Instruction {} make-non-immediate s24:@var{dst} n32:@var{offset}
  878. Load a pointer to statically allocated memory into @var{dst}. The
  879. object's memory is will be found @var{offset} 32-bit words away from the
  880. current instruction pointer. Whether the object is mutable or immutable
  881. depends on where it was allocated by the compiler, and loaded by the
  882. loader.
  883. @end deftypefn
  884. Some objects must be unique across the whole system. This is the case
  885. for symbols and keywords. For these objects, Guile arranges to
  886. initialize them when the compilation unit is loaded, storing them into a
  887. slot in the image. References go indirectly through that slot.
  888. @code{static-ref} is used in this case.
  889. @deftypefn Instruction {} static-ref s24:@var{dst} r32:@var{offset}
  890. Load a @var{scm} value into @var{dst}. The @var{scm} value will be fetched from
  891. memory, @var{offset} 32-bit words away from the current instruction
  892. pointer. @var{offset} is a signed value.
  893. @end deftypefn
  894. Fields of non-immediates may need to be fixed up at load time, because
  895. we do not know in advance at what address they will be loaded. This is
  896. the case, for example, for a pair containing a non-immediate in one of
  897. its fields. @code{static-ref} and @code{static-patch!} are used in
  898. these situations.
  899. @deftypefn Instruction {} static-set! s24:@var{src} lo32:@var{offset}
  900. Store a @var{scm} value into memory, @var{offset} 32-bit words away from the
  901. current instruction pointer. @var{offset} is a signed value.
  902. @end deftypefn
  903. @deftypefn Instruction {} static-patch! x24:@var{_} lo32:@var{dst-offset} l32:@var{src-offset}
  904. Patch a pointer at @var{dst-offset} to point to @var{src-offset}. Both offsets
  905. are signed 32-bit values, indicating a memory address as a number
  906. of 32-bit words away from the current instruction pointer.
  907. @end deftypefn
  908. Many kinds of literals can be loaded with the above instructions, once
  909. the compiler has prepared the statically allocated data. This is the
  910. case for vectors, strings, uniform vectors, pairs, and procedures with
  911. no free variables. Other kinds of data might need special initializers;
  912. those instructions follow.
  913. @deftypefn Instruction {} string->number s12:@var{dst} s12:@var{src}
  914. Parse a string in @var{src} to a number, and store in @var{dst}.
  915. @end deftypefn
  916. @deftypefn Instruction {} string->symbol s12:@var{dst} s12:@var{src}
  917. Parse a string in @var{src} to a symbol, and store in @var{dst}.
  918. @end deftypefn
  919. @deftypefn Instruction {} symbol->keyword s12:@var{dst} s12:@var{src}
  920. Make a keyword from the symbol in @var{src}, and store it in @var{dst}.
  921. @end deftypefn
  922. @deftypefn Instruction {} load-typed-array s24:@var{dst} x8:@var{_} s24:@var{type} x8:@var{_} s24:@var{shape} n32:@var{offset} u32:@var{len}
  923. Load the contiguous typed array located at @var{offset} 32-bit words away
  924. from the instruction pointer, and store into @var{dst}. @var{len} is a byte
  925. length. @var{offset} is signed.
  926. @end deftypefn
  927. @node Dynamic Environment Instructions
  928. @subsubsection Dynamic Environment Instructions
  929. Guile's virtual machine has low-level support for @code{dynamic-wind},
  930. dynamic binding, and composable prompts and aborts.
  931. @deftypefn Instruction {} abort x24:@var{_}
  932. Abort to a prompt handler. The tag is expected in slot 1, and the rest
  933. of the values in the frame are returned to the prompt handler. This
  934. corresponds to a tail application of abort-to-prompt.
  935. If no prompt can be found in the dynamic environment with the given tag,
  936. an error is signalled. Otherwise all arguments are passed to the
  937. prompt's handler, along with the captured continuation, if necessary.
  938. If the prompt's handler can be proven to not reference the captured
  939. continuation, no continuation is allocated. This decision happens
  940. dynamically, at run-time; the general case is that the continuation may
  941. be captured, and thus resumed. A reinstated continuation will have its
  942. arguments pushed on the stack from slot 1, as if from a multiple-value
  943. return, and control resumes in the caller. Thus to the calling
  944. function, a call to @code{abort-to-prompt} looks like any other function
  945. call.
  946. @end deftypefn
  947. @deftypefn Instruction {} prompt s24:@var{tag} b1:@var{escape-only?} x7:@var{_} f24:@var{proc-slot} x8:@var{_} l24:@var{handler-offset}
  948. Push a new prompt on the dynamic stack, with a tag from @var{tag} and a
  949. handler at @var{handler-offset} words from the current @var{ip}.
  950. If an abort is made to this prompt, control will jump to the handler.
  951. The handler will expect a multiple-value return as if from a call with
  952. the procedure at @var{proc-slot}, with the reified partial continuation
  953. as the first argument, followed by the values returned to the handler.
  954. If control returns to the handler, the prompt is already popped off by
  955. the abort mechanism. (Guile's @code{prompt} implements Felleisen's
  956. @dfn{--F--} operator.)
  957. If @var{escape-only?} is nonzero, the prompt will be marked as
  958. escape-only, which allows an abort to this prompt to avoid reifying the
  959. continuation.
  960. @xref{Prompts}, for more information on prompts.
  961. @end deftypefn
  962. @deftypefn Instruction {} wind s12:@var{winder} s12:@var{unwinder}
  963. Push wind and unwind procedures onto the dynamic stack. Note that
  964. neither are actually called; the compiler should emit calls to wind and
  965. unwind for the normal dynamic-wind control flow. Also note that the
  966. compiler should have inserted checks that they wind and unwind procs are
  967. thunks, if it could not prove that to be the case. @xref{Dynamic Wind}.
  968. @end deftypefn
  969. @deftypefn Instruction {} unwind x24:@var{_}
  970. @var{a} normal exit from the dynamic extent of an expression. Pop the top
  971. entry off of the dynamic stack.
  972. @end deftypefn
  973. @deftypefn Instruction {} push-fluid s12:@var{fluid} s12:@var{value}
  974. Dynamically bind @var{value} to @var{fluid} by creating a with-fluids
  975. object and pushing that object on the dynamic stack. @xref{Fluids and
  976. Dynamic States}.
  977. @end deftypefn
  978. @deftypefn Instruction {} pop-fluid x24:@var{_}
  979. Leave the dynamic extent of a @code{with-fluid*} expression, restoring
  980. the fluid to its previous value. @code{push-fluid} should always be
  981. balanced with @code{pop-fluid}.
  982. @end deftypefn
  983. @deftypefn Instruction {} fluid-ref s12:@var{dst} s12:@var{src}
  984. Reference the fluid in @var{src}, and place the value in @var{dst}.
  985. @end deftypefn
  986. @deftypefn Instruction {} fluid-set! s12:@var{fluid} s12:@var{val}
  987. Set the value of the fluid in @var{dst} to the value in @var{src}.
  988. @end deftypefn
  989. @deftypefn Instruction {} current-thread s24:@var{dst}
  990. Write the value of the current thread to @var{dst}.
  991. @end deftypefn
  992. @deftypefn Instruction {} push-dynamic-state s24:@var{state}
  993. Save the current set of fluid bindings on the dynamic stack and instate
  994. the bindings from @var{state} instead. @xref{Fluids and Dynamic
  995. States}.
  996. @end deftypefn
  997. @deftypefn Instruction {} pop-dynamic-state x24:@var{_}
  998. Restore a saved set of fluid bindings from the dynamic stack.
  999. @code{push-dynamic-state} should always be balanced with
  1000. @code{pop-dynamic-state}.
  1001. @end deftypefn
  1002. @node Miscellaneous Instructions
  1003. @subsubsection Miscellaneous Instructions
  1004. @deftypefn Instruction {} halt x24:@var{_}
  1005. Bring the VM to a halt, returning all the values from the stack. Used
  1006. in the ``boot continuation'', which is used when entering the VM from C.
  1007. @end deftypefn
  1008. @deftypefn Instruction {} push s24:@var{src}
  1009. Bump the stack pointer by one word, and fill it with the value from slot
  1010. @var{src}. The offset to @var{src} is calculated before the stack
  1011. pointer is adjusted.
  1012. @end deftypefn
  1013. The @code{push} instruction is used when another instruction is unable
  1014. to address an operand because the operand is encoded with fewer than 24
  1015. bits. In that case, Guile's assembler will transparently emit code that
  1016. temporarily pushes any needed operands onto the stack, emits the
  1017. original instruction to address those now-near variables, then shuffles
  1018. the result (if any) back into place.
  1019. @deftypefn Instruction {} pop s24:@var{dst}
  1020. Pop the stack pointer, storing the value that was there in slot
  1021. @var{dst}. The offset to @var{dst} is calculated after the stack
  1022. pointer is adjusted.
  1023. @end deftypefn
  1024. @deftypefn Instruction {} drop c24:@var{count}
  1025. Pop the stack pointer by @var{count} words, discarding any values that
  1026. were stored there.
  1027. @end deftypefn
  1028. @deftypefn Instruction {} handle-interrupts x24:@var{_}
  1029. Handle pending asynchronous interrupts (asyncs). @xref{Asyncs}. The
  1030. compiler inserts @code{handle-interrupts} instructions before any call,
  1031. return, or loop back-edge.
  1032. @end deftypefn
  1033. @deftypefn Instruction {} return-from-interrupt x24:@var{_}
  1034. A special instruction to return from a call and also pop off the stack
  1035. frame from the call. Used when returning from asynchronous interrupts.
  1036. @end deftypefn
  1037. @node Inlined Scheme Instructions
  1038. @subsubsection Inlined Scheme Instructions
  1039. The Scheme compiler can recognize the application of standard Scheme
  1040. procedures. It tries to inline these small operations to avoid the
  1041. overhead of creating new stack frames. This allows the compiler to
  1042. optimize better.
  1043. @deftypefn Instruction {} make-vector s8:@var{dst} s8:@var{length} s8:@var{init}
  1044. Make a vector and write it to @var{dst}. The vector will have space for
  1045. @var{length} slots. They will be filled with the value in slot
  1046. @var{init}.
  1047. @end deftypefn
  1048. @deftypefn Instruction {} make-vector/immediate s8:@var{dst} s8:@var{length} c8:@var{init}
  1049. Make a short vector of known size and write it to @var{dst}. The vector
  1050. will have space for @var{length} slots, an immediate value. They will
  1051. be filled with the value in slot @var{init}.
  1052. @end deftypefn
  1053. @deftypefn Instruction {} vector-length s12:@var{dst} s12:@var{src}
  1054. Store the length of the vector in @var{src} in @var{dst}, as an unboxed
  1055. unsigned 64-bit integer.
  1056. @end deftypefn
  1057. @deftypefn Instruction {} vector-ref s8:@var{dst} s8:@var{src} s8:@var{idx}
  1058. Fetch the item at position @var{idx} in the vector in @var{src}, and
  1059. store it in @var{dst}. The @var{idx} value should be an unboxed
  1060. unsigned 64-bit integer.
  1061. @end deftypefn
  1062. @deftypefn Instruction {} vector-ref/immediate s8:@var{dst} s8:@var{src} c8:@var{idx}
  1063. Fill @var{dst} with the item @var{idx} elements into the vector at
  1064. @var{src}. Useful for building data types using vectors.
  1065. @end deftypefn
  1066. @deftypefn Instruction {} vector-set! s8:@var{dst} s8:@var{idx} s8:@var{src}
  1067. Store @var{src} into the vector @var{dst} at index @var{idx}. The
  1068. @var{idx} value should be an unboxed unsigned 64-bit integer.
  1069. @end deftypefn
  1070. @deftypefn Instruction {} vector-set!/immediate s8:@var{dst} c8:@var{idx} s8:@var{src}
  1071. Store @var{src} into the vector @var{dst} at index @var{idx}. Here
  1072. @var{idx} is an immediate value.
  1073. @end deftypefn
  1074. @deftypefn Instruction {} struct-vtable s12:@var{dst} s12:@var{src}
  1075. Store the vtable of @var{src} into @var{dst}.
  1076. @end deftypefn
  1077. @deftypefn Instruction {} allocate-struct s8:@var{dst} s8:@var{vtable} s8:@var{nfields}
  1078. Allocate a new struct with @var{vtable}, and place it in @var{dst}. The
  1079. struct will be constructed with space for @var{nfields} fields, which
  1080. should correspond to the field count of the @var{vtable}. The @var{idx}
  1081. value should be an unboxed unsigned 64-bit integer.
  1082. @end deftypefn
  1083. @deftypefn Instruction {} struct-ref s8:@var{dst} s8:@var{src} s8:@var{idx}
  1084. Fetch the item at slot @var{idx} in the struct in @var{src}, and store
  1085. it in @var{dst}. The @var{idx} value should be an unboxed unsigned
  1086. 64-bit integer.
  1087. @end deftypefn
  1088. @deftypefn Instruction {} struct-set! s8:@var{dst} s8:@var{idx} s8:@var{src}
  1089. Store @var{src} into the struct @var{dst} at slot @var{idx}. The
  1090. @var{idx} value should be an unboxed unsigned 64-bit integer.
  1091. @end deftypefn
  1092. @deftypefn Instruction {} allocate-struct/immediate s8:@var{dst} s8:@var{vtable} c8:@var{nfields}
  1093. @deftypefnx Instruction {} struct-ref/immediate s8:@var{dst} s8:@var{src} c8:@var{idx}
  1094. @deftypefnx Instruction {} struct-set!/immediate s8:@var{dst} c8:@var{idx} s8:@var{src}
  1095. Variants of the struct instructions, but in which the @var{nfields} or
  1096. @var{idx} fields are immediate values.
  1097. @end deftypefn
  1098. @deftypefn Instruction {} class-of s12:@var{dst} s12:@var{type}
  1099. Store the vtable of @var{src} into @var{dst}.
  1100. @end deftypefn
  1101. @deftypefn Instruction {} make-array s24:@var{dst} x8:@var{_} s24:@var{type} x8:@var{_} s24:@var{fill} x8:@var{_} s24:@var{bounds}
  1102. Make a new array with @var{type}, @var{fill}, and @var{bounds}, storing it in @var{dst}.
  1103. @end deftypefn
  1104. @deftypefn Instruction {} string-length s12:@var{dst} s12:@var{src}
  1105. Store the length of the string in @var{src} in @var{dst}, as an unboxed
  1106. unsigned 64-bit integer.
  1107. @end deftypefn
  1108. @deftypefn Instruction {} string-ref s8:@var{dst} s8:@var{src} s8:@var{idx}
  1109. Fetch the character at position @var{idx} in the string in @var{src},
  1110. and store it in @var{dst}. The @var{idx} value should be an unboxed
  1111. unsigned 64-bit integer.
  1112. @end deftypefn
  1113. @deftypefn Instruction {} string-set! s8:@var{dst} s8:@var{idx} s8:@var{src}
  1114. Store the character @var{src} into the string @var{dst} at index
  1115. @var{idx}. The @var{idx} value should be an unboxed unsigned 64-bit
  1116. integer.
  1117. @end deftypefn
  1118. @deftypefn Instruction {} cons s8:@var{dst} s8:@var{car} s8:@var{cdr}
  1119. Cons @var{car} and @var{cdr}, and store the result in @var{dst}.
  1120. @end deftypefn
  1121. @deftypefn Instruction {} car s12:@var{dst} s12:@var{src}
  1122. Place the car of @var{src} in @var{dst}.
  1123. @end deftypefn
  1124. @deftypefn Instruction {} cdr s12:@var{dst} s12:@var{src}
  1125. Place the cdr of @var{src} in @var{dst}.
  1126. @end deftypefn
  1127. @deftypefn Instruction {} set-car! s12:@var{pair} s12:@var{car}
  1128. Set the car of @var{dst} to @var{src}.
  1129. @end deftypefn
  1130. @deftypefn Instruction {} set-cdr! s12:@var{pair} s12:@var{cdr}
  1131. Set the cdr of @var{dst} to @var{src}.
  1132. @end deftypefn
  1133. Note that @code{caddr} and friends compile to a series of @code{car}
  1134. and @code{cdr} instructions.
  1135. @deftypefn Instruction {} integer->char s12:@var{dst} s12:@var{src}
  1136. Convert the @code{u64} value in @var{src} to a Scheme character, and
  1137. place it in @var{dst}.
  1138. @end deftypefn
  1139. @deftypefn Instruction {} char->integer s12:@var{dst} s12:@var{src}
  1140. Convert the Scheme character in @var{src} to an integer, and place it in
  1141. @var{dst} as an unboxed @code{u64} value.
  1142. @end deftypefn
  1143. @node Inlined Atomic Instructions
  1144. @subsubsection Inlined Atomic Instructions
  1145. @xref{Atomics}, for more on atomic operations in Guile.
  1146. @deftypefn Instruction {} make-atomic-box s12:@var{dst} s12:@var{src}
  1147. Create a new atomic box initialized to @var{src}, and place it in
  1148. @var{dst}.
  1149. @end deftypefn
  1150. @deftypefn Instruction {} atomic-box-ref s12:@var{dst} s12:@var{box}
  1151. Fetch the value of the atomic box at @var{box} into @var{dst}.
  1152. @end deftypefn
  1153. @deftypefn Instruction {} atomic-box-set! s12:@var{box} s12:@var{val}
  1154. Set the contents of the atomic box at @var{box} to @var{val}.
  1155. @end deftypefn
  1156. @deftypefn Instruction {} atomic-box-swap! s12:@var{dst} s12:@var{box} x8:@var{_} s24:@var{val}
  1157. Replace the contents of the atomic box at @var{box} to @var{val} and
  1158. store the previous value at @var{dst}.
  1159. @end deftypefn
  1160. @deftypefn Instruction {} atomic-box-compare-and-swap! s12:@var{dst} s12:@var{box} x8:@var{_} s24:@var{expected} x8:@var{_} s24:@var{desired}
  1161. If the value of the atomic box at @var{box} is the same as the SCM value
  1162. at @var{expected} (in the sense of @code{eq?}), replace the contents of
  1163. the box with the SCM value at @var{desired}. Otherwise does not update
  1164. the box. Set @var{dst} to the previous value of the box in either case.
  1165. @end deftypefn
  1166. @node Inlined Mathematical Instructions
  1167. @subsubsection Inlined Mathematical Instructions
  1168. Inlining mathematical operations has the obvious advantage of handling
  1169. fixnums without function calls or allocations. The trick, of course,
  1170. is knowing when the result of an operation will be a fixnum, and there
  1171. might be a couple bugs here.
  1172. More instructions could be added here over time.
  1173. All of these operations place their result in their first operand,
  1174. @var{dst}.
  1175. @deftypefn Instruction {} add s8:@var{dst} s8:@var{a} s8:@var{b}
  1176. Add @var{a} to @var{b}.
  1177. @end deftypefn
  1178. @deftypefn Instruction {} add/immediate s8:@var{dst} s8:@var{src} c8:@var{imm}
  1179. Add the unsigned integer @var{imm} to the value in @var{src}.
  1180. @end deftypefn
  1181. @deftypefn Instruction {} sub s8:@var{dst} s8:@var{a} s8:@var{b}
  1182. Subtract @var{b} from @var{a}.
  1183. @end deftypefn
  1184. @deftypefn Instruction {} sub/immediate s8:@var{dst} s8:@var{src} s8:@var{imm}
  1185. Subtract the unsigned integer @var{imm} from the value in @var{src}.
  1186. @end deftypefn
  1187. @deftypefn Instruction {} mul s8:@var{dst} s8:@var{a} s8:@var{b}
  1188. Multiply @var{a} and @var{b}.
  1189. @end deftypefn
  1190. @deftypefn Instruction {} div s8:@var{dst} s8:@var{a} s8:@var{b}
  1191. Divide @var{a} by @var{b}.
  1192. @end deftypefn
  1193. @deftypefn Instruction {} quo s8:@var{dst} s8:@var{a} s8:@var{b}
  1194. Divide @var{a} by @var{b}.
  1195. @end deftypefn
  1196. @deftypefn Instruction {} rem s8:@var{dst} s8:@var{a} s8:@var{b}
  1197. Divide @var{a} by @var{b}.
  1198. @end deftypefn
  1199. @deftypefn Instruction {} mod s8:@var{dst} s8:@var{a} s8:@var{b}
  1200. Compute the modulo of @var{a} by @var{b}.
  1201. @end deftypefn
  1202. @deftypefn Instruction {} ash s8:@var{dst} s8:@var{a} s8:@var{b}
  1203. Shift @var{a} arithmetically by @var{b} bits.
  1204. @end deftypefn
  1205. @deftypefn Instruction {} logand s8:@var{dst} s8:@var{a} s8:@var{b}
  1206. Compute the bitwise @code{and} of @var{a} and @var{b}.
  1207. @end deftypefn
  1208. @deftypefn Instruction {} logior s8:@var{dst} s8:@var{a} s8:@var{b}
  1209. Compute the bitwise inclusive @code{or} of @var{a} with @var{b}.
  1210. @end deftypefn
  1211. @deftypefn Instruction {} logxor s8:@var{dst} s8:@var{a} s8:@var{b}
  1212. Compute the bitwise exclusive @code{or} of @var{a} with @var{b}.
  1213. @end deftypefn
  1214. @deftypefn Instruction {} logsub s8:@var{dst} s8:@var{a} s8:@var{b}
  1215. Place the bitwise @code{and} of @var{a} and the bitwise @code{not} of
  1216. @var{b} into @var{dst}.
  1217. @end deftypefn
  1218. @node Inlined Bytevector Instructions
  1219. @subsubsection Inlined Bytevector Instructions
  1220. Bytevector operations correspond closely to what the current hardware
  1221. can do, so it makes sense to inline them to VM instructions, providing
  1222. a clear path for eventual native compilation. Without this, Scheme
  1223. programs would need other primitives for accessing raw bytes -- but
  1224. these primitives are as good as any.
  1225. @deftypefn Instruction {} bv-length s12:@var{dst} s12:@var{src}
  1226. Store the length of the bytevector in @var{src} in @var{dst}, as an
  1227. unboxed unsigned 64-bit integer.
  1228. @end deftypefn
  1229. @deftypefn Instruction {} bv-u8-ref s8:@var{dst} s8:@var{src} s8:@var{idx}
  1230. @deftypefnx Instruction {} bv-s8-ref s8:@var{dst} s8:@var{src} s8:@var{idx}
  1231. @deftypefnx Instruction {} bv-u16-ref s8:@var{dst} s8:@var{src} s8:@var{idx}
  1232. @deftypefnx Instruction {} bv-s16-ref s8:@var{dst} s8:@var{src} s8:@var{idx}
  1233. @deftypefnx Instruction {} bv-u32-ref s8:@var{dst} s8:@var{src} s8:@var{idx}
  1234. @deftypefnx Instruction {} bv-s32-ref s8:@var{dst} s8:@var{src} s8:@var{idx}
  1235. @deftypefnx Instruction {} bv-u64-ref s8:@var{dst} s8:@var{src} s8:@var{idx}
  1236. @deftypefnx Instruction {} bv-s64-ref s8:@var{dst} s8:@var{src} s8:@var{idx}
  1237. @deftypefnx Instruction {} bv-f32-ref s8:@var{dst} s8:@var{src} s8:@var{idx}
  1238. @deftypefnx Instruction {} bv-f64-ref s8:@var{dst} s8:@var{src} s8:@var{idx}
  1239. Fetch the item at byte offset @var{idx} in the bytevector @var{src}, and
  1240. store it in @var{dst}. All accesses use native endianness.
  1241. The @var{idx} value should be an unboxed unsigned 64-bit integer.
  1242. The results are all written to the stack as unboxed values, either as
  1243. signed 64-bit integers, unsigned 64-bit integers, or IEEE double
  1244. floating point numbers.
  1245. @end deftypefn
  1246. @deftypefn Instruction {} bv-u8-set! s8:@var{dst} s8:@var{idx} s8:@var{src}
  1247. @deftypefnx Instruction {} bv-s8-set! s8:@var{dst} s8:@var{idx} s8:@var{src}
  1248. @deftypefnx Instruction {} bv-u16-set! s8:@var{dst} s8:@var{idx} s8:@var{src}
  1249. @deftypefnx Instruction {} bv-s16-set! s8:@var{dst} s8:@var{idx} s8:@var{src}
  1250. @deftypefnx Instruction {} bv-u32-set! s8:@var{dst} s8:@var{idx} s8:@var{src}
  1251. @deftypefnx Instruction {} bv-s32-set! s8:@var{dst} s8:@var{idx} s8:@var{src}
  1252. @deftypefnx Instruction {} bv-u64-set! s8:@var{dst} s8:@var{idx} s8:@var{src}
  1253. @deftypefnx Instruction {} bv-s64-set! s8:@var{dst} s8:@var{idx} s8:@var{src}
  1254. @deftypefnx Instruction {} bv-f32-set! s8:@var{dst} s8:@var{idx} s8:@var{src}
  1255. @deftypefnx Instruction {} bv-f64-set! s8:@var{dst} s8:@var{idx} s8:@var{src}
  1256. Store @var{src} into the bytevector @var{dst} at byte offset @var{idx}.
  1257. Multibyte values are written using native endianness.
  1258. The @var{idx} value should be an unboxed unsigned 64-bit integer.
  1259. The @var{src} values are all unboxed, either as signed 64-bit integers,
  1260. unsigned 64-bit integers, or IEEE double floating point numbers.
  1261. @end deftypefn
  1262. @node Unboxed Integer Arithmetic
  1263. @subsubsection Unboxed Integer Arithmetic
  1264. Guile supports two kinds of unboxed integers: unsigned 64-bit integers,
  1265. and signed 64-bit integers. Guile prefers unsigned integers, in the
  1266. sense that Guile's compiler supports them better and the virtual machine
  1267. has more operations that work on them. Still, signed integers are
  1268. supported at least to allow @code{bv-s64-ref} and related instructions
  1269. to avoid boxing their values.
  1270. @deftypefn Instruction {} scm->u64 s12:@var{dst} s12:@var{src}
  1271. Unbox the SCM value at @var{src} to a unsigned 64-bit integer, placing
  1272. the result in @var{dst}. If the @var{src} value is not an exact integer
  1273. in the unsigned 64-bit range, signal an error.
  1274. @end deftypefn
  1275. @deftypefn Instruction {} u64->scm s12:@var{dst} s12:@var{src}
  1276. Box the unsigned 64-bit integer at @var{src} to a SCM value and place
  1277. the result in @var{dst}. The result will be a fixnum or a bignum.
  1278. @end deftypefn
  1279. @deftypefn Instruction {} load-u64 s24:@var{dst} au32:@var{high-bits} au32:@var{low-bits}
  1280. Load a 64-bit value formed by joining @var{high-bits} and
  1281. @var{low-bits}, and write it to @var{dst}.
  1282. @end deftypefn
  1283. @deftypefn Instruction {} scm->s64 s12:@var{dst} s12:@var{src}
  1284. @deftypefnx Instruction {} s64->scm s12:@var{dst} s12:@var{src}
  1285. @deftypefnx Instruction {} load-s64 s24:@var{dst} as32:@var{high-bits} as32:@var{low-bits}
  1286. Like @code{scm->u64}, @code{u64->scm}, and @code{load-u64}, but for
  1287. signed 64-bit integers.
  1288. @end deftypefn
  1289. Sometimes the compiler can know that we will only need a subset of the
  1290. bits in an integer. In that case we can sometimes unbox an integer even
  1291. if it might be out of range.
  1292. @deftypefn Instruction {} scm->u64/truncate s12:@var{dst} s12:@var{src}
  1293. Take the SCM value in @var{dst} and @code{logand} it with @code{(1- (ash
  1294. 1 64))}. Place the unboxed result in @var{dst}.
  1295. @end deftypefn
  1296. @deftypefn Instruction {} br-if-u64-= s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  1297. @deftypefnx Instruction {} br-if-u64-< s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  1298. @deftypefnx Instruction {} br-if-u64-<= s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  1299. If the unboxed unsigned 64-bit integer value in @var{a} is @code{=},
  1300. @code{<}, or @code{<=} to the unboxed unsigned 64-bit integer value in
  1301. @var{b}, respectively, add @var{offset} to the current instruction
  1302. pointer.
  1303. @end deftypefn
  1304. @deftypefn Instruction {} br-if-u64-=-scm s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  1305. @deftypefnx Instruction {} br-if-u64-<-scm s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  1306. @deftypefnx Instruction {} br-if-u64-<=-scm s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  1307. If the unboxed unsigned 64-bit integer value in @var{a} is @code{=},
  1308. @code{<}, or @code{<=} to the SCM value in @var{b}, respectively, add
  1309. @var{offset} to the current instruction pointer.
  1310. @end deftypefn
  1311. @deftypefn Instruction {} uadd s8:@var{dst} s8:@var{a} s8:@var{b}
  1312. @deftypefnx Instruction {} usub s8:@var{dst} s8:@var{a} s8:@var{b}
  1313. @deftypefnx Instruction {} umul s8:@var{dst} s8:@var{a} s8:@var{b}
  1314. Like @code{add}, @code{sub}, and @code{mul}, except taking
  1315. the operands as unboxed unsigned 64-bit integers, and producing the
  1316. same. The result will be silently truncated to 64 bits.
  1317. @end deftypefn
  1318. @deftypefn Instruction {} uadd/immediate s8:@var{dst} s8:@var{a} c8:@var{b}
  1319. @deftypefnx Instruction {} usub/immediate s8:@var{dst} s8:@var{a} c8:@var{b}
  1320. @deftypefnx Instruction {} umul/immediate s8:@var{dst} s8:@var{a} c8:@var{b}
  1321. Like @code{uadd}, @code{usub}, and @code{umul}, except the second
  1322. operand is an immediate unsigned 8-bit integer.
  1323. @end deftypefn
  1324. @deftypefn Instruction {} ulogand s8:@var{dst} s8:@var{a} s8:@var{b}
  1325. @deftypefnx Instruction {} ulogior s8:@var{dst} s8:@var{a} s8:@var{b}
  1326. @deftypefnx Instruction {} ulogxor s8:@var{dst} s8:@var{a} s8:@var{b}
  1327. @deftypefnx Instruction {} ulogsub s8:@var{dst} s8:@var{a} s8:@var{b}
  1328. Like @code{logand}, @code{logior}, @code{logxor}, and @code{logsub}, but
  1329. operating on unboxed unsigned 64-bit integers.
  1330. @end deftypefn
  1331. @deftypefn Instruction {} ulsh s8:@var{dst} s8:@var{a} s8:@var{b}
  1332. Shift the unboxed unsigned 64-bit integer in @var{a} left by @var{b}
  1333. bits, also an unboxed unsigned 64-bit integer. Truncate to 64 bits and
  1334. write to @var{dst} as an unboxed value. Only the lower 6 bits of
  1335. @var{b} are used.
  1336. @end deftypefn
  1337. @deftypefn Instruction {} ursh s8:@var{dst} s8:@var{a} s8:@var{b}
  1338. Like @code{ulsh}, but shifting right.
  1339. @end deftypefn
  1340. @deftypefn Instruction {} ulsh/immediate s8:@var{dst} s8:@var{a} c8:@var{b}
  1341. @deftypefnx Instruction {} ursh/immediate s8:@var{dst} s8:@var{a} c8:@var{b}
  1342. Like @code{ulsh} and @code{ursh}, but encoding @code{b} as an immediate
  1343. 8-bit unsigned integer.
  1344. @end deftypefn
  1345. @node Unboxed Floating-Point Arithmetic
  1346. @subsubsection Unboxed Floating-Point Arithmetic
  1347. @deftypefn Instruction {} scm->f64 s12:@var{dst} s12:@var{src}
  1348. Unbox the SCM value at @var{src} to an IEEE double, placing the result
  1349. in @var{dst}. If the @var{src} value is not a real number, signal an
  1350. error.
  1351. @end deftypefn
  1352. @deftypefn Instruction {} f64->scm s12:@var{dst} s12:@var{src}
  1353. Box the IEEE double at @var{src} to a SCM value and place the result in
  1354. @var{dst}.
  1355. @end deftypefn
  1356. @deftypefn Instruction {} load-f64 s24:@var{dst} au32:@var{high-bits} au32:@var{low-bits}
  1357. Load a 64-bit value formed by joining @var{high-bits} and
  1358. @var{low-bits}, and write it to @var{dst}.
  1359. @end deftypefn
  1360. @deftypefn Instruction {} fadd s8:@var{dst} s8:@var{a} s8:@var{b}
  1361. @deftypefnx Instruction {} fsub s8:@var{dst} s8:@var{a} s8:@var{b}
  1362. @deftypefnx Instruction {} fmul s8:@var{dst} s8:@var{a} s8:@var{b}
  1363. @deftypefnx Instruction {} fdiv s8:@var{dst} s8:@var{a} s8:@var{b}
  1364. Like @code{add}, @code{sub}, @code{div}, and @code{mul}, except taking
  1365. the operands as unboxed IEEE double floating-point numbers, and producing
  1366. the same.
  1367. @end deftypefn
  1368. @deftypefn Instruction {} br-if-f64-= s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  1369. @deftypefnx Instruction {} br-if-f64-< s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  1370. @deftypefnx Instruction {} br-if-f64-<= s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  1371. @deftypefnx Instruction {} br-if-f64-> s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  1372. @deftypefnx Instruction {} br-if-f64->= s24:@var{a} x8:@var{_} s24:@var{b} b1:@var{invert} x7:@var{_} l24:@var{offset}
  1373. If the unboxed IEEE double value in @var{a} is @code{=}, @code{<},
  1374. @code{<=}, @code{>}, or @code{>=} to the unboxed IEEE double value in
  1375. @var{b}, respectively, add @var{offset} to the current instruction
  1376. pointer.
  1377. @end deftypefn