From de5e28ccace6719dc260156136251b75bcc1ad07 Mon Sep 17 00:00:00 2001 From: Tomek Kurcz Date: Tue, 21 Nov 2017 11:46:04 +0100 Subject: [PATCH 1/3] Update status.org for the new documentation Some things that are actually written already weren't ticked in the TODO list. --- src/doc/new-doc/standards/objects.txi | 2 +- src/doc/status.org | 42 +++++++++++++-------------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/src/doc/new-doc/standards/objects.txi b/src/doc/new-doc/standards/objects.txi index 4df4ed9cb..7f5314181 100644 --- a/src/doc/new-doc/standards/objects.txi +++ b/src/doc/new-doc/standards/objects.txi @@ -7,7 +7,7 @@ @subsubsection ANSI Dictionary Common Lisp and C equivalence -@multitable @columnfractions .3 .7 +@multitable @columnfractions .35 .65 @headitem Lisp symbol @tab C function @item @clhs{f_fn_kwd.htm,function-keywords} @tab [Only in Common Lisp] @item @clhs{f_ensure.htm,ensure-generic-function} @tab cl_object cl_ensure_generic_function(cl_narg narg, cl_object function_name, ...) diff --git a/src/doc/status.org b/src/doc/status.org index ce9bde135..67ea428e2 100644 --- a/src/doc/status.org +++ b/src/doc/status.org @@ -2,10 +2,10 @@ - [X] Makefile * Introduction -- [ ] About ECL -- [ ] History -- [ ] Credits -- [ ] Copyrights +- [X] About ECL +- [X] History +- [X] Credits +- [X] Copyrights * User's guide - [-] Building ECL @@ -27,10 +27,10 @@ - Source documentation - [ ] Modules hierarchy - [ ] Testing and benchmarking -- [ ] Manipulating Lisp objects +- [X] Manipulating Lisp objects - [ ] Environment implementation - [ ] The interpreter -- [ ] The compiler +- [X] The compiler - [ ] Porting ECL - [ ] Experimental features - [ ] Current roadmap @@ -39,27 +39,27 @@ Many nodes, moderate amount of content (deviations from the standard) * Extensions -- [ ] System building (ASDF, builder) -- [ ] OS interface +- [X] System building (ASDF, builder) +- [X] OS interface - [X] FFI - [X] General info and examples - [X] SFFI :: Static FFI # - [ ] LFFI :: Library FFI :: (?) /dlopen etc./ # - [ ] DFFI :: Dynamic FFI - [X] UFFI - - [ ] Multithreading - - [X] Signals and Interrupts - - [ ] Networking - - [X] Memory managament - - [X] MOP - - [ ] Green threads - - [ ] Continuations - - [ ] Extensible Sequences - - [ ] Gray streams - - [ ] Series - - [ ] Tree walker - - [ ] Local package nicknames - - [ ] CDR Extensions +- [X] Multithreading +- [X] Signals and Interrupts +- [ ] Networking +- [X] Memory managament +- [-] MOP +- [ ] Green threads +- [ ] Continuations +- [ ] Extensible Sequences +- [ ] Gray streams +- [ ] Series +- [ ] Tree walker +- [X] Local package nicknames +- [ ] CDR Extensions * Not documented yet #+BEGIN_SRC lisp -- GitLab From 5116a13ebc2f14bb46c3ee99b103558b8f41b776 Mon Sep 17 00:00:00 2001 From: Tomek Kurcz Date: Sat, 25 Nov 2017 12:55:46 +0100 Subject: [PATCH 2/3] Port the interpreter section from the old doc --- src/doc/new-doc/developer-guide/index.txi | 3 +- .../new-doc/developer-guide/interpreter.txi | 141 ++++++++++++++++++ src/doc/status.org | 2 +- 3 files changed, 144 insertions(+), 2 deletions(-) create mode 100644 src/doc/new-doc/developer-guide/interpreter.txi diff --git a/src/doc/new-doc/developer-guide/index.txi b/src/doc/new-doc/developer-guide/index.txi index be7829c80..d63c36095 100644 --- a/src/doc/new-doc/developer-guide/index.txi +++ b/src/doc/new-doc/developer-guide/index.txi @@ -9,7 +9,7 @@ @c * Defun preprocessor:: Preprocessor for the Lisp constructs in C * Manipulating Lisp objects:: * Environment implementation:: -@c * The interpreter:: +* The interpreter:: * The compiler:: @c * Porting ECL:: * Removed features:: @@ -22,5 +22,6 @@ @c @include developer-guide/dpp.txi @include developer-guide/objects.txi @include developer-guide/environment.txi +@include developer-guide/interpreter.txi @include developer-guide/compiler.txi @include developer-guide/removed.txi diff --git a/src/doc/new-doc/developer-guide/interpreter.txi b/src/doc/new-doc/developer-guide/interpreter.txi new file mode 100644 index 000000000..b3ca32969 --- /dev/null +++ b/src/doc/new-doc/developer-guide/interpreter.txi @@ -0,0 +1,141 @@ +@node The interpreter +@section The interpreter + +@subsection ECL stacks +ECL uses the following stacks: +@multitable @columnfractions .3 .7 +@item Frame Stack +@tab consisting of catch, block, tagbody frames +@item Bind Stack +@tab for shallow binding of dynamic variables +@item Interpreter Stack +@tab acts as a Forth data stack, keeping intermediate arguments to interpreted functions, plus a history of called functions. +@item C Control Stack +@tab used for arguments/values passing, typed lexical variables, temporary values, and function invocation. +@end multitable + +@subsection Procedure Call Conventions +ECL employs standard C calling conventions to achieve efficiency and interoperability with other languages. Each Lisp function is implemented as a C function which takes as many argument as the Lisp original plus one additional integer argument which holds the number of actual arguments. The function sets @code{NValues} to the number of Lisp values produced, it returns the first one and the remaining ones are kept in a global (per thread) array (@code{VALUES}). + +To show the argument/value passing mechanism, here we list the actual code for the Common-Lisp function cons. + +@verbatim + cl_cons(int narg, object car, object cdr) + { object x; + check_arg(2); + x = alloc_object(t_cons); + CAR(x) = car; + CDR(x) = cdr; + NValues = 1; + return x; + } +@end verbatim + +ECL adopts the convention that the name of a function that implements a Common-Lisp function begins with a short package name (@code{cl} for @code{COMMON-LISP}, @code{si} for @code{SYSTEM}, etc), followed by @code{L}, and followed by the name of the Common-Lisp function. (Strictly speaking, `@code{-}' and `@code{*}' in the Common-Lisp function name are replaced by `@code{_}' and `@code{A}', respectively, to obey the syntax of C.) + +@code{check_arg(2)} in the code of @code{cl_cons} checks that exactly two arguments are supplied to @code{cons}. That is, it checks that @code{narg} is 2, and otherwise, it causes an error. @code{allocate_object(t_cons)} allocates a cons cell in the heap and returns the pointer to the cell. After the @code{CAR} and the @code{CDR} fields of the cell are set, the cell pointer is returned directly. The number assigned to @code{NValues} set by the function (1 in this case) represents the number of values of the function. + +In general, if one is to play with the C kernel of ECL there is no need to know about all these conventions. There is a preprocessor that takes care of the details, by using a lisp representation of the statements that output values, and of the function definitions. For instance, the actual source code for @code{cl_cons} in @code{src/c/lists.d} + +@verbatim + @(defun cons (car cdr) + @ + @(return CONS(car, cdr)) + @) +@end verbatim + +@subsection The lexical environment +The ECL interpreter uses two A-lists (Association lists) to represent lexical environments. + +@itemize +@item One for variable bindings +@item One for local function/macro/tag/block bindings +@end itemize + +When a function closure is created, the current two A-lists are saved in the closure along with the lambda expression. Later, when the closure is invoked, the saved A-lists are used to recover the lexical environment. + +@subsection The interpreter stack +The bytecodes interpreter uses a stack of its own to save and restore values from intermediate calculations. This Forth-like data stack is also used in other parts of the C kernel for various purposes, such as saving compiled code, keeping arguments to @code{FORMAT}, etc. + +However, one of the most important roles of the Interpreter Stack is to keep a log of the functions which are called during the execution of bytecodes. For each function invoked, the interpreter keeps three lisp objects on the stack: + +@verbatim + +----------+------------------------------------------------+ + | function | lexical environment | index to previous record | + +----------+---------------------+--------------------------+ +@end verbatim + +The first item is the object which is funcalled. It can be a bytecodes object, a compiled function or a generic function. In the last two cases the lexical environment is just @code{NIL}. In the first case, the second item on the stack is the lexical environment on which the code is executed. Each of these records are popped out of the stack after function invocation. + +Let us see how these invocation records are used for debugging. + +@verbatim + >(defun fact (x) ;;; Wrong definition of the + (if (= x 0) ;;; factorial function. + one ;;; one should be 1. + (* x (fact (1- x))))) + FACT + + >(fact 3) ;;; Tries 3! + Error: The variable ONE is unbound. + Error signalled by IF. + Broken at IF. + >>:b ;;; Backtrace. + Backtrace: eval > fact > if > fact > if > fact > if > fact > IF + ;;; Currently at the last IF. + >>:h ;;; Help. + + Break commands: + :q(uit) Return to some previous break level. + :pop Pop to previous break level. + :c(ontinue) Continue execution. + :b(acktrace) Print backtrace. + :f(unction) Show current function. + :p(revious) Go to previous function. + :n(ext) Go to next function. + :g(o) Go to next function. + :fs Search forward for function. + :bs Search backward for function. + :v(ariables) Show local variables, functions, blocks, and tags. + :l(ocal) Return the nth local value on the stack. + :hide Hide function. + :unhide Unhide function. + :hp Hide package. + :unhp Unhide package. + :unhide-all Unhide all variables and packages. + :bds Show binding stack. + :m(essage) Show error message. + :hs Help stack. + Top level commands: + :cf Compile file. + :exit or ^D Exit Lisp. + :ld Load file. + :step Single step form. + :tr(ace) Trace function. + :untr(ace) Untrace function. + + Help commands: + :apropos Apropos. + :doc(ument) Document. + :h(elp) or ? Help. Type ":help help" for more information. + + >>:p ;;; Move to the last call of FACT. + Broken at IF. + + >>:b + Backtrace: eval > fact > if > fact > if > fact > if > FACT > if + ;;; Now at the last FACT. + >>:v ;;; The environment at the last call + Local variables: ;;; to FACT is recovered. + X: 0 ;;; X is the only bound variable. + Block names: FACT. ;;; The block FACT is established. + + >>x + 0 ;;; The value of x is 0. + + >>(return-from fact 1) ;;; Return from the last call of + 6 ;;; FACT with the value of 0. + ;;; The execution is resumed and + > ;;; the value 6 is returned. + ;;; Again at the top-level loop. +@end verbatim diff --git a/src/doc/status.org b/src/doc/status.org index 67ea428e2..958e1ecd2 100644 --- a/src/doc/status.org +++ b/src/doc/status.org @@ -29,7 +29,7 @@ - [ ] Testing and benchmarking - [X] Manipulating Lisp objects - [ ] Environment implementation -- [ ] The interpreter +- [X] The interpreter - [X] The compiler - [ ] Porting ECL - [ ] Experimental features -- GitLab From f34938c5068050d6d2c398557ed572a793109151 Mon Sep 17 00:00:00 2001 From: Tomek Kurcz Date: Sat, 25 Nov 2017 13:00:47 +0100 Subject: [PATCH 3/3] Port the porting ECL section from the old doc --- src/doc/new-doc/developer-guide/index.txi | 3 ++- src/doc/new-doc/developer-guide/porting-ecl.txi | 13 +++++++++++++ src/doc/status.org | 2 +- 3 files changed, 16 insertions(+), 2 deletions(-) create mode 100644 src/doc/new-doc/developer-guide/porting-ecl.txi diff --git a/src/doc/new-doc/developer-guide/index.txi b/src/doc/new-doc/developer-guide/index.txi index d63c36095..efc772a11 100644 --- a/src/doc/new-doc/developer-guide/index.txi +++ b/src/doc/new-doc/developer-guide/index.txi @@ -11,7 +11,7 @@ * Environment implementation:: * The interpreter:: * The compiler:: -@c * Porting ECL:: +* Porting ECL:: * Removed features:: @c * Experimental features:: @c * Current roadmap:: @@ -24,4 +24,5 @@ @include developer-guide/environment.txi @include developer-guide/interpreter.txi @include developer-guide/compiler.txi +@include developer-guide/porting-ecl.txi @include developer-guide/removed.txi diff --git a/src/doc/new-doc/developer-guide/porting-ecl.txi b/src/doc/new-doc/developer-guide/porting-ecl.txi new file mode 100644 index 000000000..7b6a63b81 --- /dev/null +++ b/src/doc/new-doc/developer-guide/porting-ecl.txi @@ -0,0 +1,13 @@ +@node Porting ECL +@section Porting ECL + +To port ECL to a new architecture, the following steps are required: + +@enumerate +@item Ensure that the GNU Multiprecision library supports this machine. +@item Ensure that the Boehm-Weiser garbage collector is supported by that architecture. Alternatively, port ECL's own garbage collector @code{src/c/alloc.d} and @code{src/c/gbc.d} to that platform. +@item Fix @code{src/aclocal.in}, @code{src/h/config.h.in} and @code{src/h/ecl.h} so that they supply flags for the new host machine. +@item Fix the machine dependent code in @code{src/c/}. The most critical parts are in the @code{unix*.d} and @code{thread*.d} files. +@item Compile as in any other platform. +@item Run the tests and compare to the results of other platforms. +@end enumerate diff --git a/src/doc/status.org b/src/doc/status.org index 958e1ecd2..8596d0d69 100644 --- a/src/doc/status.org +++ b/src/doc/status.org @@ -31,7 +31,7 @@ - [ ] Environment implementation - [X] The interpreter - [X] The compiler -- [ ] Porting ECL +- [X] Porting ECL - [ ] Experimental features - [ ] Current roadmap -- GitLab