Actions

Difference between revisions of "Internal Documentation"

From Gambit wiki

Line 80: Line 80:
 
The closet document to describe Gambit Virtual Machine is probably [http://www.iro.umontreal.ca/~feeley/papers/pvm.ps.gz A Parallel Virtual Machine for Efficient Scheme Compilation].
 
The closet document to describe Gambit Virtual Machine is probably [http://www.iro.umontreal.ca/~feeley/papers/pvm.ps.gz A Parallel Virtual Machine for Efficient Scheme Compilation].
  
TODO: describe GVM.
+
==== Operands ====
 +
 
 +
There are 6 types of operands, described in _gvmadt.scm. All operands are encoded to a number. The following list is extracted from _gvmadt.scm:
 +
 
 +
  reg(n)      n*8 + 0
 +
  stk(n)      n*8 + 1
 +
  lbl(n)      n*8 + 2
 +
  glo(name)    index_in_operand_table*8 + 3
 +
  clo(opnd,n)  index_in_operand_table*8 + 4
 +
  obj(x)      index_in_operand_table*8 + 5
 +
 
 +
Global variables (glo), closed variables (clo) and objects are saved in *opnd-table*. Reg, stk, lbl are respectively abbreviations of register, stack and label. All these operands can be created by make-X, where X is the abbreviation.
 +
 
 +
==== Instructions ====
 +
 
 +
GVM instructions include apply, copy, close, ifjump, switch,  jump, comment and label, in _gvm.scm, "Virtual machine instruction representation" section.
 +
 
 +
==== Optimization ====
  
 
After GVM generation, dead code is removed by '''bbs-purify!'''.
 
After GVM generation, dead code is removed by '''bbs-purify!'''.

Revision as of 14:18, 27 October 2009

People who want to contribute to Gambit development will need to learn something about how the Gambit-C runtime and compiler are organized. While we intend that source code documentation be included in the source itself (currently there is very little documentation), we intend that descriptions of program design or algorithms used in the runtime and compiler could be included here.

Namespace handling

See Namespaces.

Runtime Library

Memory Management

General notes on internal object storage and memory consumption is on the Debugging page. Also see Notes on Memory Management.

Thread System

I/O System

Arithmetic implementation

Eval

Continuation manipulation

The manual lists continuation-graft, continuation-capture, and continuation-return but doesn't describe them. The REPL debugger, and possibly other things, use them. See Marc Feeley's paper A Better API for First-Class Continuations.

REPL

The REPL has some fairly interesting functions and variables, especially for hackers.

Variables

##repl-location-relative
Should the REPL give relative or absolute pathnames. Note: When using emacs with gambit, it is useful to set it to #f, especially if you change the current-directory.

Functions

##cmd-x
where x is a REPL command letter (typed after a comma from the REPL). Executes that command as if it was executed inside of the REPL. For instance ##cmd-b displays a backtrace.

Record system

That is, define-type. Based on SRFI-9, but extensions not documented. This email provides the best explanation [1]

Introspection

Symbol introspection

To get list of interned symbols:

(define (symbol-table->list st)

  (define (symbol-chain s syms)
    (let loop ((s s) (syms syms))
      (if (symbol? s)
          (loop (##vector-ref s 2) (cons s syms))
          syms)))

  (let loop ((lst (vector->list st)) (syms '()))
    (if (pair? lst)
        (loop (cdr lst) (symbol-chain (car lst) syms))
        (reverse syms))))

(define (interned-symbols)
  (symbol-table->list (##symbol-table)))

(pp (length (interned-symbols)))

(From Gambit ML 2009-03-22)

Compiler

Script igsc.scm inside gsc directory can be used to get REPL of compiler so you can inspect details.

Frontend

The frontend entry point is cf, main function to do compilation is compile-parsed-program, which generates GVM instructions. Some optimization is done by frontend via function normalize-program.

TODO: Optimizations, program tree representation.

Intermediate representation

The closet document to describe Gambit Virtual Machine is probably A Parallel Virtual Machine for Efficient Scheme Compilation.

Operands

There are 6 types of operands, described in _gvmadt.scm. All operands are encoded to a number. The following list is extracted from _gvmadt.scm:

 reg(n)       n*8 + 0
 stk(n)       n*8 + 1
 lbl(n)       n*8 + 2
 glo(name)    index_in_operand_table*8 + 3
 clo(opnd,n)  index_in_operand_table*8 + 4
 obj(x)       index_in_operand_table*8 + 5

Global variables (glo), closed variables (clo) and objects are saved in *opnd-table*. Reg, stk, lbl are respectively abbreviations of register, stack and label. All these operands can be created by make-X, where X is the abbreviation.

Instructions

GVM instructions include apply, copy, close, ifjump, switch, jump, comment and label, in _gvm.scm, "Virtual machine instruction representation" section.

Optimization

After GVM generation, dead code is removed by bbs-purify!.

Backend

Backend is selected by target-select!. All backend functions start with target.. The only supported backend is C, which explains the "C" part in "Gambit-C", reside in _t-c-[1-3].scm.

TODO: linking?