[Guile-commits] GNU Guile branch, master, updated. v2.1.0-523-g1f6f591

[Andy Wingo]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Guile".

http://git.savannah.gnu.org/cgit/guile.git/commit/?id=1f6f591d666a0332317374f32339cd4ec3e248e9

The branch, master has been updated
       via  1f6f591d666a0332317374f32339cd4ec3e248e9 (commit)
       via  9e9745b3550c1c0c6e4502e570c3b81a4bb1ebf4 (commit)
      from  69aecc6abb1a6579f5b1f9787d0fd000ae9ce26f (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 1f6f591d666a0332317374f32339cd4ec3e248e9
Author: Andy Wingo <address@hidden>
Date:   Sun Dec 1 12:35:12 2013 +0100

    Add section to vm.texi about Guile's use of ELF
    
    * doc/ref/vm.texi (Object File Format): New section.

commit 9e9745b3550c1c0c6e4502e570c3b81a4bb1ebf4
Author: Andy Wingo <address@hidden>
Date:   Sat Nov 30 20:59:14 2013 +0100

    vm.texi tweak
    
    * doc/ref/vm.texi (Why a VM?): Small tense tweak.

-----------------------------------------------------------------------

Summary of changes:
 doc/ref/vm.texi |  108 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 107 insertions(+), 1 deletions(-)

diff --git a/doc/ref/vm.texi b/doc/ref/vm.texi
index a4f47e2..468ac65 100644
--- a/doc/ref/vm.texi
+++ b/doc/ref/vm.texi
@@ -26,6 +26,7 @@ machine.
 * Stack Layout::                
 * Variables and the VM::                   
 * VM Programs::         
+* Object File Format::
 * Instruction Set::
 @end menu
 
@@ -38,7 +39,7 @@ operated directly on the S-expression representation of 
Scheme source
 code.
 
 But while the interpreter was highly optimized and hand-tuned, it still
-performs many needless computations during the course of evaluating an
+performed many needless computations during the course of evaluating an
 expression. For example, application of a function to arguments
 needlessly consed up the arguments in a list. Evaluation of an
 expression always had to figure out what the car of the expression is --
@@ -309,6 +310,111 @@ called -- into slot 4, then @code{ip} 11 conses it onto 
the list.
 Finally we cons local 2, containing the @code{foo} toplevel, onto the
 front of the list, and we return it.
 
+
address@hidden Object File Format
address@hidden Object File Format
+
+To compile a file to disk, we need a format in which to write the
+compiled code to disk, and later load it into Guile.  A good @dfn{object
+file format} has a number of characteristics:
+
address@hidden
address@hidden Above all else, it should be very cheap to load a compiled file.
address@hidden It should be possible to statically allocate constants in the
+file.  For example, a bytevector literal in source code can be emitted
+directly into the object file.
address@hidden The compiled file should enable maximum code and data sharing
+between different processes.
address@hidden The compiled file should contain debugging information, such as
+line numbers, but that information should be separated from the code
+itself.  It should be possible to strip debugging information if space
+is tight.
address@hidden itemize
+
+These characteristics are not specific to Scheme.  Indeed, mainstream
+languages like C and C++ have solved this issue many times in the past.
+Guile builds on their work by adopting ELF, the object file format of
+GNU and other Unix-like systems, as its object file format.  Although
+Guile uses ELF on all platforms, we do not use platform support for ELF.
+Guile implements its own linker and loader.  The advantage of using ELF
+is not sharing code, but sharing ideas.  ELF is simply a well-designed
+object file format.
+
+An ELF file has two meta-tables describing its contents.  The first
+meta-table is for the loader, and is called the @dfn{program table} or
+sometimes the @dfn{segment table}.  The program table divides the file
+into big chunks that should be treated differently by the loader.
+Mostly the difference between these @dfn{segments} is their
+permissions.
+
+Typically all segments of an ELF file are marked as read-only, except
+that part that represents modifiable static data or static data that
+needs load-time initialization.  Loading an ELF file is as simple as
+mmapping the thing into memory with read-only permissions, then using
+the segment table to mark a small sub-region of the file as writable.
+This writable section is typically added to the root set of the garbage
+collector as well.
+
+One ELF segment is marked as ``dynamic'', meaning that it has data of
+interest to the loader.  Guile uses this segment to record the Guile
+version corresponding to this file.  There is also an entry in the
+dynamic segment that points to the address of an initialization thunk
+that is run to perform any needed link-time initialization.  (This is
+like dynamic relocations for normal ELF shared objects, except that we
+compile the relocations as a procedure instead of having the loader
+interpret a table of relocations.)  Finally, the dynamic segment marks
+the location of the ``entry thunk'' of the object file.  This thunk is
+returned to the caller of @code{load-thunk-from-memory} or
address@hidden  When called, it will execute the ``body''
+of the compiled expression.
+
+The other meta-table in an ELF file is the @dfn{section table}.  Whereas
+the program table divides an ELF file into big chunks for the loader,
+the section table specifies small sections for use by introspective
+tools like debuggers or the like.  One segment (program table entry)
+typically contains many sections.  There may be sections outside of any
+segment, as well.
+
+Typical sections in a Guile @code{.go} file include:
+
address@hidden @code
address@hidden .rtl-text
+Bytecode.
address@hidden .data
+Data that needs initialization, or which may be modified at runtime.
address@hidden .rodata
+Statically allocated data that needs no run-time initialization, and
+which therefore can be shared between processes.
address@hidden .dynamic
+The dynamic section, discussed above.
address@hidden .symtab
address@hidden .strtab
+A table mapping addresses in the @code{.rtl-text} to procedure names.
address@hidden is used by @code{.symtab}.
address@hidden .guile.procprops
address@hidden .guile.arities
address@hidden .guile.arities.strtab
address@hidden .guile.docstrs
address@hidden .guile.docstrs.strtab
+Side tables of procedure properties, arities, and docstrings.
address@hidden .debug_info
address@hidden .debug_abbrev
address@hidden .debug_str
address@hidden .debug_loc
address@hidden .debug_line
+Debugging information, in DWARF format.  See the DWARF specification,
+for more information.
address@hidden .shstrtab
+Section name string table.
address@hidden table
+
+For more information, see @uref{http://linux.die.net/man/5/elf,,the
+elf(5) man page}.  See @uref{http://dwarfstd.org/,the DWARF
+specification} for more on the DWARF debugging format.  Or if you are an
+adventurous explorer, try running @code{readelf} or @code{objdump} on
+compiled @code{.go} files.  It's good times!
+
+
 @node Instruction Set
 @subsection Instruction Set
 


hooks/post-receive
-- 
GNU Guile