doc updates

README.rst

@@ -93,11 +93,14 @@ Compatibility with Lua
 ----------------------
 Ravi should be able to run all Lua 5.3 programs in interpreted mode. When JIT compilation is enabled some things will not work:
 
-* You cannot yield from a compiled function, so if you use coroutines then it is better to use the interpreter, as compiled code does not support coroutines 
-* The debugger doesn't work when JIT compilation is turned on as information it requires is not available; the debugger also does not support Ravi's extended opcodes
-* Functions using bit-wise operations cannot be JIT compiled as yet (to be implemented)
+* You cannot yield from a compiled function, so if you use coroutines then it is better to use the interpreter, as compiled code does not support coroutines (issue 14)
+* The debugger doesn't work when JIT compilation is turned on as information it requires is not available; the debugger also does not support Ravi's extended opcodes (issue 15)
+* Functions using bit-wise operations cannot be JIT compiled as yet (issue 27)
 * Ravi supports optional typing and enhanced types such as arrays (described later). Programs using these features cannot be run by standard Lua. However all types in Ravi can be passed to Lua functions - there are some restrictions on arrays that are described in a later section. Values crossing from Lua to Ravi may be subjected to typechecks.
-* In JITed code tailcalls are implemented as regular calls so unlike Lua VM which supports infinite tail recursion JIT compiled code only supports tail recursion to a depth of about 110.
+* In JITed code tailcalls are implemented as regular calls so unlike Lua VM which supports infinite tail recursion JIT compiled code only supports tail recursion to a depth of about 110 (issue 17)
+* pairs() and ipairs() do not work on ravi arrays yet (issues 24 and 25)
+* Upvalues can subvert the static typing of local variables (issue 26)
+* Lua C API doesn't work correctly for Ravi arrays (issue 9)
 
 Documentation
 --------------

readthedocs/ravi-internals.rst

@@ -766,6 +766,95 @@ The Lua fornum statements create special variables. In order to allows the loop
     forbody(ls, base, line, 1, 1);
   }
 
+
+Handling of Upvalues
+====================
+Upvalues can be used to update local variables that have static typing specified. So this means that upvalues need to be annotated with types as well and any operation that updates an upvalue must be type checked. To support this the Lua parser has been enhanced to record the type of an upvalue in ``Upvaldesc``::
+
+  /*
+  ** Description of an upvalue for function prototypes
+  */
+  typedef struct Upvaldesc {
+    TString *name;  /* upvalue name (for debug information) */
+    ravitype_t type; /* RAVI type of upvalue */
+    lu_byte instack;  /* whether it is in stack */
+    lu_byte idx;  /* index of upvalue (in stack or in outer function's list) */
+  } Upvaldesc;
+
+
+Whenever a new upvalue is referenced, we assign the type of the the upvalue to the expression in function ``singlevaraux()`` - relevant code is shown below::
+
+  static int singlevaraux (FuncState *fs, TString *n, expdesc *var, int base) {
+    /* ... omitted code ... */  
+      int idx = searchupvalue(fs, n);  /* try existing upvalues */
+      if (idx < 0) {  /* not found? */
+        if (singlevaraux(fs->prev, n, var, 0) == VVOID) /* try upper levels */
+          return VVOID;  /* not found; is a global */
+        /* else was LOCAL or UPVAL */
+        idx  = newupvalue(fs, n, var);  /* will be a new upvalue */
+      }
+      init_exp(var, VUPVAL, idx, fs->f->upvalues[idx].type); /* RAVI : set upvalue type */
+      return VUPVAL;
+      /* ... omitted code ... */
+  }
+
+The function ``newupvalue()`` sets the type of a new upvalue.
+
+  /* create a new upvalue */
+  static int newupvalue (FuncState *fs, TString *name, expdesc *v) {
+    Proto *f = fs->f;
+    int oldsize = f->sizeupvalues;
+    checklimit(fs, fs->nups + 1, MAXUPVAL, "upvalues");
+    luaM_growvector(fs->ls->L, f->upvalues, fs->nups, f->sizeupvalues,
+                  Upvaldesc, MAXUPVAL, "upvalues");
+    while (oldsize < f->sizeupvalues) f->upvalues[oldsize++].name = NULL;
+
+    f->upvalues[fs->nups].instack = (v->k == VLOCAL);
+    f->upvalues[fs->nups].idx = cast_byte(v->u.info);
+    f->upvalues[fs->nups].name = name;
+    f->upvalues[fs->nups].type = v->ravi_type;
+    luaC_objbarrier(fs->ls->L, f, name);
+    return fs->nups++;
+  }
+
+When we need to generate assignments to an upvalue (OP_SETUPVAL) we need to use more specialized opcodes that do the necessary conversion at runtime. This is handled in ``luaK_storevar()`` in ``lcode.c``::
+
+
+  /* Emit store for LHS expression. */
+  void luaK_storevar (FuncState *fs, expdesc *var, expdesc *ex) {
+    switch (var->k) {
+      /* ... omitted code .. */
+      case VUPVAL: {
+        OpCode op = check_valid_setupval(fs, var, ex);
+        int e = luaK_exp2anyreg(fs, ex);
+        luaK_codeABC(fs, op, e, var->u.info, 0);
+        break;
+      }
+      /* ... omitted code ... */
+    }
+  }
+
+  static OpCode check_valid_setupval(FuncState *fs, expdesc *var, expdesc *ex) {
+    OpCode op = OP_SETUPVAL;
+    if (var->ravi_type != RAVI_TANY && var->ravi_type != ex->ravi_type) {
+      if (var->ravi_type == RAVI_TNUMINT)
+        op = OP_RAVI_SETUPVALI;
+      else if (var->ravi_type == RAVI_TNUMFLT)
+        op = OP_RAVI_SETUPVALF;
+      else if (var->ravi_type == RAVI_TARRAYINT)
+        op = OP_RAVI_SETUPVALAI;
+      else if (var->ravi_type == RAVI_TARRAYFLT)
+        op = OP_RAVI_SETUPVALAF;
+      else
+        luaX_syntaxerror(fs->ls,
+                      luaO_pushfstring(fs->ls->L, "Invalid assignment of "
+                                                   "upvalue: upvalue type "
+                                                   "%d, expression type %d",
+                                        var->ravi_type, ex->ravi_type));
+    }
+    return op;
+  }
+
 VM Enhancements
 ===============
 A number of new opcodes are introduced to allow type specific operations.

readthedocs/ravi-jit-status.rst

@@ -242,6 +242,30 @@ Note that if a Lua functions contains a bytecode that cannot be be JITed then th
 | OP_RAVI_SETTABLE_AF     | YES      | 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      | YES      | 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      | YES      | R(A)-=R(A+2); pc+=sBx                            |
+|                         |          | Specialization for integer step > 1              |
++-------------------------+----------+--------------------------------------------------+
+| OP_RAVI_FORLOOP_I1      | YES      | 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      | YES      | 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))                   |
++-------------------------+----------+--------------------------------------------------+
+
+
 
 Ravi's JIT compiler source
 --------------------------

readthedocs/ravi-overview.rst

@@ -99,7 +99,7 @@ Ravi should be able to run all Lua 5.3 programs in interpreted mode. When JIT co
 * Ravi supports optional typing and enhanced types such as arrays (described later). Programs using these features cannot be run by standard Lua. However all types in Ravi can be passed to Lua functions - there are some restrictions on arrays that are described in a later section. Values crossing from Lua to Ravi may be subjected to typechecks.
 * In JITed code tailcalls are implemented as regular calls so unlike Lua VM which supports infinite tail recursion JIT compiled code only supports tail recursion to a depth of about 110 (issue 17)
 * pairs() and ipairs() do not work on ravi arrays yet (issues 24 and 25)
-* Up-values can subvert the static typing of local variables (issue 26)
+* Upvalues can subvert the static typing of local variables (issue 26)
 * Lua C API doesn't work correctly for Ravi arrays (issue 9)
 
 Documentation