doc updates

README.rst

@@ -3,7 +3,7 @@ Ravi Programming Language
 
 Ravi is an experimental derivative/dialect of `Lua 5.3 <http://www.lua.org/>`_, with limited optional static typing and an LLVM based JIT compiler. Ravi is a Sanskrit word that means the Sun.
 
-Lua is perfect as a small embeddable dynamic language. So why a derivative? The reason is primarily to extend Lua with static typing for greater performance. However, at the same time maintain full compatibility with standard Lua.
+Lua is perfect as a small embeddable dynamic language. So why a derivative? The reason is primarily to extend Lua with static typing for greater performance under JIT compilation. However, at the same time maintain full compatibility with standard Lua.
 
 There are other attempts to add static typing to Lua (e.g. `Typed Lua <https://github.com/andremm/typedlua>`_ but these efforts are mostly about adding static type checks in the language while leaving the VM unmodified. So the static typing is to aid programming in the large - the code is eventually translated to standard Lua and executed in the unmodified Lua VM.
 
@@ -15,12 +15,15 @@ Goals
 * Type specific bytecodes to improve performance
 * Compatibility with Lua 5.3 (see Compatibility section below)
 * LLVM based JIT compiler
+* Additionally a libgccjit alternative JIT compiler (work in progress)
 
 Status
 ------
 The project was kicked off in January 2015. 
 
-Right now (as of May 2015) I am working on the JIT implementation. Please see `Ravi Documentation <http://the-ravi-programming-language.readthedocs.org/en/latest/index.html>`_ for details of this effort. The Lua and Ravi bytecodes currently implemented are described in `JIT Status <http://the-ravi-programming-language.readthedocs.org/en/latest/ravi-jit-status.html>`_ page.
+Right now (as of June 2015) I am working on the ``libgccjit`` based JIT implementation. 
+
+The LLVM JIT compiler is mostly functional - please see `Ravi Documentation <http://the-ravi-programming-language.readthedocs.org/en/latest/index.html>`_ for details of this effort. The Lua and Ravi bytecodes currently implemented in LLVM are described in `JIT Status <http://the-ravi-programming-language.readthedocs.org/en/latest/ravi-jit-status.html>`_ page.
 
 As of end Jan 2015, the Ravi interpreter allows you to declare local variables as ``integer`` or ``number``. This triggers following behaviour:
 
@@ -71,7 +74,7 @@ An example with arrays::
 
 JIT Compilation
 ---------------
-I am currently working on JIT compilation of Ravi using LLVM. As of now all bytecodes other than bit-wise operators can be compiled, but there are restrictions as described in compatibility section below.
+I am currently working on JIT compilation of Ravi using LLVM (an alternative ``libgccjit`` implementation is also in progress). As of now all bytecodes other than bit-wise operators can be compiled when using LLVM, but there are restrictions as described in compatibility section below. Everything described below relates to using LLVM as the JIT compiler.
 
 There are two modes of JIT compilation.
 

readthedocs/ravi-jit-libgccjit.rst

@@ -55,7 +55,6 @@ Above assumes that gccjit is installed under ``~/local`` as described in Buildin
 
 A helloworld test program is built. To run it though you need to ensure that your ``PATH`` and ``LD_LIBRARY_PATH`` variables include ``~/local/bin`` and ``~/local/lib`` respectively.
 
-
 Initial Observations 
 --------------------
 In terms of packaging ``libgccjit`` consists of a C header file, a C++ header file and one shared library. That is pretty neat as it simplifies the usage.
@@ -63,6 +62,216 @@ In terms of packaging ``libgccjit`` consists of a C header file, a C++ header fi
 Setting up of the Lua types is proving easier in ``libgccjit`` due to the fact that Lua uses unions extensively and ``libgccjit`` supports defining union types. This means that most of the Lua types can be translated more naturally. LLVM on the other hand does not support unions so I had to carefully define structs that would match the size of the union, and in the JIT compilation use casts where needed.
 
 
+JIT Status of Lua/Ravi Bytecodes
+---------------------------------
+Following is the status as of 15 June 2015.
+
++-------------------------+----------+--------------------------------------------------+
+| name                    | JITed?   | description                                      |
++=========================+==========+==================================================+
+| OP_MOVE                 | NO       | R(A) := R(B)                                     |
++-------------------------+----------+--------------------------------------------------+
+| OP_LOADK                | YES      | R(A) := Kst(Bx)                                  |
++-------------------------+----------+--------------------------------------------------+
+| OP_LOADKX               | NO       | R(A) := Kst(extra arg)                           |
++-------------------------+----------+--------------------------------------------------+
+| OP_LOADBOOL             | NO       | R(A) := (Bool)B; if (C) pc++                     |
++-------------------------+----------+--------------------------------------------------+
+| OP_LOADNIL              | NO       | R(A), R(A+1), ..., R(A+B) := nil                 |
++-------------------------+----------+--------------------------------------------------+
+| OP_GETUPVAL             | NO       | R(A) := UpValue[B]                               |
++-------------------------+----------+--------------------------------------------------+
+| OP_GETTABUP             | NO       | R(A) := UpValue[B][RK(C)]                        |
++-------------------------+----------+--------------------------------------------------+
+| OP_GETTABLE             | NO       | R(A) := R(B)[RK(C)]                              |
++-------------------------+----------+--------------------------------------------------+
+| OP_SETTABUP             | NO       | UpValue[A][RK(B)] := RK(C)                       |
++-------------------------+----------+--------------------------------------------------+
+| OP_SETUPVAL             | NO       | UpValue[B] := R(A)                               |
++-------------------------+----------+--------------------------------------------------+
+| OP_SETTABLE             | NO       | R(A)[RK(B)] := RK(C)                             |
++-------------------------+----------+--------------------------------------------------+
+| OP_NEWTABLE             | NO       | R(A) := {} (size = B,C)                          |
++-------------------------+----------+--------------------------------------------------+
+| OP_SELF                 | NO       | R(A+1) := R(B); R(A) := R(B)[RK(C)]              |
++-------------------------+----------+--------------------------------------------------+
+| OP_ADD                  | NO       | R(A) := RK(B) + RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_SUB                  | NO       | R(A) := RK(B) - RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_MUL                  | NO       | R(A) := RK(B) * RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_MOD                  | NO       | R(A) := RK(B) % RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_POW                  | NO       | R(A) := RK(B) ^ RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_DIV                  | NO       | R(A) := RK(B) / RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_IDIV                 | NO       | R(A) := RK(B) // RK(C)                           |
++-------------------------+----------+--------------------------------------------------+
+| OP_BAND                 | NO       | R(A) := RK(B) & RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_BOR                  | NO       | R(A) := RK(B) | RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_BXOR                 | NO       | R(A) := RK(B) ~ RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_SHL                  | NO       | R(A) := RK(B) << RK(C)                           |
++-------------------------+----------+--------------------------------------------------+
+| OP_SHR                  | NO       | R(A) := RK(B) >> RK(C)                           |
++-------------------------+----------+--------------------------------------------------+
+| OP_UNM                  | NO       | R(A) := -R(B)                                    |
++-------------------------+----------+--------------------------------------------------+
+| OP_BNOT                 | NO       | R(A) := ~R(B)                                    |
++-------------------------+----------+--------------------------------------------------+
+| OP_NOT                  | NO       | R(A) := not R(B)                                 |
++-------------------------+----------+--------------------------------------------------+
+| OP_LEN                  | NO       | R(A) := length of R(B)                           |
++-------------------------+----------+--------------------------------------------------+
+| OP_CONCAT               | NO       | R(A) := R(B).. ... ..R(C)                        |
++-------------------------+----------+--------------------------------------------------+
+| OP_JMP                  | NO       | c+=sBx; if (A) close all upvalues >= R(A - 1)    |
++-------------------------+----------+--------------------------------------------------+
+| OP_EQ                   | NO       | if ((RK(B) == RK(C)) ~= A) then pc++             |
++-------------------------+----------+--------------------------------------------------+
+| OP_LT                   | NO       | if ((RK(B) <  RK(C)) ~= A) then pc++             |
++-------------------------+----------+--------------------------------------------------+
+| OP_LE                   | NO       | if ((RK(B) <= RK(C)) ~= A) then pc++             |
++-------------------------+----------+--------------------------------------------------+
+| OP_TEST                 | NO       | if not (R(A) <=> C) then pc++                    |
++-------------------------+----------+--------------------------------------------------+
+| OP_TESTSET              | NO       | if (R(B) <=> C) then R(A) := R(B) else pc++      |
++-------------------------+----------+--------------------------------------------------+
+| OP_CALL                 | NO       | R(A), .. ,R(A+C-2) := R(A)(R(A+1), .. ,R(A+B-1)) |
++-------------------------+----------+--------------------------------------------------+
+| OP_TAILCALL             | NO       | return R(A)(R(A+1), ... ,R(A+B-1))               |
+|                         |          | Compiled as OP_CALL so no tail call optimization |
++-------------------------+----------+--------------------------------------------------+
+| OP_RETURN               | YES      | return R(A), ... ,R(A+B-2) (see note)            |
++-------------------------+----------+--------------------------------------------------+
+| OP_FORLOOP              | NO       | R(A)+=R(A+2);                                    |
+|                         |          | if R(A) <?= R(A+1) then { pc+=sBx; R(A+3)=R(A) } |
++-------------------------+----------+--------------------------------------------------+
+| OP_FORPREP              | NO       | R(A)-=R(A+2); pc+=sBx                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_TFORCALL             | NO       | R(A+3), ... ,R(A+2+C) := R(A)(R(A+1), R(A+2));   |
++-------------------------+----------+--------------------------------------------------+
+| OP_TFORLOOP             | NO       | if R(A+1) ~= nil then { R(A)=R(A+1); pc += sBx } |
++-------------------------+----------+--------------------------------------------------+
+| OP_SETLIST              | NO       | R(A)[(C-1)*FPF+i] := R(A+i), 1 <= i <= B	        |
++-------------------------+----------+--------------------------------------------------+
+| OP_CLOSURE              | NO       | R(A) := closure(KPROTO[Bx])                      |
++-------------------------+----------+--------------------------------------------------+
+| OP_VARARG               | NO       | R(A), R(A+1), ..., R(A+B-2) = vararg             |
++-------------------------+----------+--------------------------------------------------+
+| OP_EXTRAARG             | N/A      | extra (larger) argument for previous opcode      |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_NEWARRAYI       | NO       | R(A) := array of int                             |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_NEWARRAYF       | NO       | R(A) := array of float                           |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_LOADIZ          | NO       | R(A) := tointeger(0)                             |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_LOADFZ          | NO       | R(A) := tonumber(0)                              |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_UNMF            | NO       | R(A) := -R(B) floating point                     |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_UNMI            | NO       | R(A) := -R(B) integer                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_ADDFF           | NO       | R(A) := RK(B) + RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_ADDFI           | NO       | R(A) := RK(B) + RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_ADDII           | NO       | R(A) := RK(B) + RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_ADDFN           | NO       | R(A) := RK(B) + C                                |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_ADDIN           | NO       | R(A) := RK(B) + C                                |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_SUBFF           | NO       | R(A) := RK(B) - RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_SUBFI           | NO       | R(A) := RK(B) - RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_SUBIF           | NO       | R(A) := RK(B) - RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_SUBII           | NO       | R(A) := RK(B) - RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_SUBFN           | NO       | R(A) := RK(B) - C                                |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_SUBNF           | NO       | R(A) := B - RK(C)                                |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_SUBIN           | NO       | R(A) := RK(B) - C                                |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_SUBNI           | NO       | R(A) := B - RK(C)                                |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_MULFF           | NO       | R(A) := RK(B) * RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_MULFI           | NO       | R(A) := RK(B) * RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_MULII           | NO       | R(A) := RK(B) * RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_MULFN           | NO       | R(A) := RK(B) * C                                |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_MULIN           | NO       | R(A) := RK(B) * C                                |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_DIVFF           | NO       | R(A) := RK(B) / RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_DIVFI           | NO       | R(A) := RK(B) / RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_DIVIF           | NO       | R(A) := RK(B) / RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_DIVII           | NO       | R(A) := RK(B) / RK(C)                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_TOINT           | NO       | R(A) := toint(R(A))                              |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_TOFLT           | NO       | R(A) := tofloat(R(A))                            |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_TOARRAYI        | NO       | R(A) := to_arrayi(R(A))                          |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_TOARRAYF        | NO       | R(A) := to_arrayf(R(A))                          |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_MOVEI           | NO       | R(A) := R(B), check R(B) is integer              |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_MOVEF           | NO       | R(A) := R(B), check R(B) is number               |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_MOVEAI          | NO       | R(A) := R(B), check R(B) is array of integer     |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_MOVEAF          | NO       | R(A) := R(B), check R(B) is array of numbers     |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_GETTABLE_AI     | NO       | R(A) := R(B)[RK(C)] where R(B) is array of       |
+|                         |          | integers and RK(C) is integer                    |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_GETTABLE_AF     | NO       | R(A) := R(B)[RK(C)] where R(B) is array of       |
+|                         |          | numbers and RK(C) is integer                     |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_SETTABLE_AI     | NO       | R(A)[RK(B)] := RK(C) where RK(B) is an integer   |
+|                         |          | R(A) is array of integers, and RK(C) is an int   |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_SETTABLE_AF     | NO       | R(A)[RK(B)] := RK(C) where RK(B) is an integer   |
+|                         |          | R(A) is array of numbers, and RK(C) is a number  |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_FORLOOP_IP      | NO       | R(A)+=R(A+2);                                    |
+|                         |          | if R(A) <?= R(A+1) then { pc+=sBx; R(A+3)=R(A) } |
+|                         |          | Specialization for integer step > 1              |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_FORPREP_IP      | NO       | R(A)-=R(A+2); pc+=sBx                            |
+|                         |          | Specialization for integer step > 1              |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_FORLOOP_I1      | NO       | R(A)+=R(A+2);                                    |
+|                         |          | if R(A) <?= R(A+1) then { pc+=sBx; R(A+3)=R(A) } |
+|                         |          | Specialization for integer step == 1             |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_FORPREP_I1      | NO       | R(A)-=R(A+2); pc+=sBx                            |
+|                         |          | Specialization for integer step == 1             |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_SETUPVALI       | NO       | UpValue[B] := tointeger(R(A))                    |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_SETUPVALF       | NO       | UpValue[B] := tonumber(R(A))                     |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_SETUPVALAI      | NO       | UpValue[B] := toarrayint(R(A))                   |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_SETUPVALAF      | NO       | UpValue[B] := toarrayflt(R(A))                   |
++-------------------------+----------+--------------------------------------------------+
+
 
 
 

readthedocs/ravi-overview.rst

@@ -3,7 +3,7 @@ Ravi Programming Language
 
 Ravi is an experimental derivative/dialect of `Lua 5.3 <http://www.lua.org/>`_, with limited optional static typing and an LLVM based JIT compiler. Ravi is a Sanskrit word that means the Sun.
 
-Lua is perfect as a small embeddable dynamic language. So why a derivative? The reason is primarily to extend Lua with static typing for greater performance. However, at the same time maintain full compatibility with standard Lua.
+Lua is perfect as a small embeddable dynamic language. So why a derivative? The reason is primarily to extend Lua with static typing for greater performance under JIT compilation. However, at the same time maintain full compatibility with standard Lua.
 
 There are other attempts to add static typing to Lua (e.g. `Typed Lua <https://github.com/andremm/typedlua>`_ but these efforts are mostly about adding static type checks in the language while leaving the VM unmodified. So the static typing is to aid programming in the large - the code is eventually translated to standard Lua and executed in the unmodified Lua VM.
 
@@ -15,12 +15,15 @@ Goals
 * Type specific bytecodes to improve performance
 * Compatibility with Lua 5.3 (see Compatibility section below)
 * LLVM based JIT compiler
+* Additionally a libgccjit alternative JIT compiler (work in progress)
 
 Status
 ------
 The project was kicked off in January 2015. 
 
-Right now (as of May 2015) I am working on the JIT implementation. Please see `Ravi Documentation <http://the-ravi-programming-language.readthedocs.org/en/latest/index.html>`_ for details of this effort. The Lua and Ravi bytecodes currently implemented are described in `JIT Status <http://the-ravi-programming-language.readthedocs.org/en/latest/ravi-jit-status.html>`_ page.
+Right now (as of June 2015) I am working on the ``libgccjit`` based JIT implementation. 
+
+The LLVM JIT compiler is mostly functional - please see `Ravi Documentation <http://the-ravi-programming-language.readthedocs.org/en/latest/index.html>`_ for details of this effort. The Lua and Ravi bytecodes currently implemented in LLVM are described in `JIT Status <http://the-ravi-programming-language.readthedocs.org/en/latest/ravi-jit-status.html>`_ page.
 
 As of end Jan 2015, the Ravi interpreter allows you to declare local variables as ``integer`` or ``number``. This triggers following behaviour:
 
@@ -71,7 +74,7 @@ An example with arrays::
 
 JIT Compilation
 ---------------
-I am currently working on JIT compilation of Ravi using LLVM. As of now all bytecodes other than bit-wise operators can be compiled, but there are restrictions as described in compatibility section below.
+I am currently working on JIT compilation of Ravi using LLVM (an alternative ``libgccjit`` implementation is also in progress). As of now all bytecodes other than bit-wise operators can be compiled when using LLVM, but there are restrictions as described in compatibility section below. Everything described below relates to using LLVM as the JIT compiler.
 
 There are two modes of JIT compilation.