Greetings Guilers, I've been looking at the VM, and as far as I can tell, what's needed before it can be merged into master is just documentation. All the rest of it can be improved while it's in master, but it offers no significant regression.
The biggest regression that I know of is that the traps interface won't work with compiled code. I think this is fixable though -- although probably we'll have to hack on traps. I have some thoughts this, for a later time. Anyway. I think the place for VM docs is in the Guile manual, and so I just read through the whole manual, and what exists of the VM manual, trying to figure out a plan. The general plan that I've come up with is that we should interleave notes about compilation through the manual in all places that we talk about evaluation or memoization, and then at the end of the manual, we should add a separate toplevel section: "History and Implemention Details". We would fold in the "Data representation" into this section, and use it to talk about where Guile has come from (something I've always thought is lacking, in our public narrative), how it is implemented today, and where it's going (generally speaking). So we can talk about the memoizer/evaluator and its strengths, its principles of a highly dynamic development environment, its origins in "low-latency programming", in which we reduce to the minimum the delay between writing code and having it active. At that point we can talk about the data representation used in Guile, as coming from SCM and being one of the fastest hand-coded interpreters out there. But then we can talk about the compiler, and how it is a new feature, retrofitted on top of a large existing body of code, both C and Scheme, and on top of a large body of deployed users. Hence we can justify many of the design decisions: use of the VM and all. At that point we talk about the VM and its model: its registers, its memory model, its execution model, the representation of programs in memory, the representation of compiled code on disk, heap, stack, and toplevel variables, etc. Then we can describe the interface of the compiler: `compile' and `compile-file', `guile-tools compile', and the disassembler. Perhaps this section could actually go in the main reference, along with documentation for `load', `eval', et al. Then we can talk about the implementation of the compiler, its multilingual translation system, GHIL, GLIL, and all the rest. (It would be good to add GHIL and GLIL language definitions, so you can type them in directly at the REPL.) Also what optimizations the compiler implements, notes on performance, and some suggestions for future directions (JIT, etc). We can also devote a section to the VM instruction set around here, including a section on how to add new instructions, issues of compiled code compatibility, and when it is appropriate to add a new instruction. So that's the plan. Thoughts on the new section, or otherwise? Andy -- http://wingolog.org/