aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/changes.html297
-rw-r--r--doc/contact.html2
-rw-r--r--doc/ext_c_api.html2
-rw-r--r--doc/ext_ffi.html2
-rw-r--r--doc/ext_ffi_api.html8
-rw-r--r--doc/ext_ffi_semantics.html26
-rw-r--r--doc/ext_ffi_tutorial.html2
-rw-r--r--doc/ext_jit.html4
-rw-r--r--doc/ext_profiler.html365
-rw-r--r--doc/extensions.html80
-rw-r--r--doc/faq.html2
-rw-r--r--doc/install.html148
-rw-r--r--doc/luajit.html8
-rw-r--r--doc/running.html3
-rw-r--r--doc/status.html13
15 files changed, 657 insertions, 305 deletions
diff --git a/doc/changes.html b/doc/changes.html
index 8811efc5..426b18f7 100644
--- a/doc/changes.html
+++ b/doc/changes.html
@@ -44,6 +44,8 @@ div.major { max-width: 600px; padding: 1em; margin: 1em 0 1em 0; }
44<a href="ext_jit.html">jit.* Library</a> 44<a href="ext_jit.html">jit.* Library</a>
45</li><li> 45</li><li>
46<a href="ext_c_api.html">Lua/C API</a> 46<a href="ext_c_api.html">Lua/C API</a>
47</li><li>
48<a href="ext_profiler.html">Profiler</a>
47</li></ul> 49</li></ul>
48</li><li> 50</li><li>
49<a href="status.html">Status</a> 51<a href="status.html">Status</a>
@@ -72,6 +74,72 @@ to see whether newer versions are available.
72</p> 74</p>
73 75
74<div class="major" style="background: #d0d0ff;"> 76<div class="major" style="background: #d0d0ff;">
77<h2 id="LuaJIT-2.1.0-beta2">LuaJIT 2.1.0-beta2 &mdash; 2016-03-03</h2>
78<ul>
79<li>Enable trace stitching.</li>
80<li>Use internal implementation for converting FP numbers to strings.</li>
81<li>Parse Unicode escape <tt>'\u{XX...}'</tt> in string literals.</li>
82<li>Add MIPS soft-float support.</li>
83<li>Switch MIPS port to dual-number mode.</li>
84<li>x86/x64: Add support for AES-NI, AVX and AVX2 to DynASM.</li>
85<li>FFI: Add <tt>ssize_t</tt> declaration.</li>
86<li>FFI: Parse <tt>#line NN</tt> and <tt>#NN</tt>.</li>
87<li>Various minor fixes.</li>
88</ul>
89
90<h2 id="LuaJIT-2.1.0-beta1">LuaJIT 2.1.0-beta1 &mdash; 2015-08-25</h2>
91<p>
92This is a brief summary of the major changes in LuaJIT 2.1 compared to 2.0.
93Please take a look at the commit history for more details.
94</p>
95<ul>
96<li>Changes to the VM core:
97<ul>
98<li>Add low-overhead profiler (<tt>-jp</tt>).</li>
99<li>Add <tt>LJ_GC64</tt> mode: 64 bit GC object references (really: 47 bit). Interpreter-only for now.</li>
100<li>Add <tt>LJ_FR2</tt> mode: Two-slot frame info. Required by <tt>LJ_GC64</tt> mode.</li>
101<li>Add <tt>table.new()</tt> and <tt>table.clear()</tt>.</li>
102<li>Parse binary number literals (<tt>0bxxx</tt>).</li>
103</ul></li>
104<li>Improvements to the JIT compiler:
105<ul>
106<li>Add trace stitching (disabled for now).</li>
107<li>Compile various builtins: <tt>string.char()</tt>, <tt>string.reverse()</tt>, <tt>string.lower()</tt>, <tt>string.upper()</tt>, <tt>string.rep()</tt>, <tt>string.format()</tt>, <tt>table.concat()</tt>, <tt>bit.tohex()</tt>, <tt>getfenv(0)</tt>, <tt>debug.getmetatable()</tt>.</li>
108<li>Compile <tt>string.find()</tt> for fixed string searches (no patterns).</li>
109<li>Compile <tt>BC_TSETM</tt>, e.g. <tt>{1,2,3,f()}</tt>.</li>
110<li>Compile string concatenations (<tt>BC_CAT</tt>).</li>
111<li>Compile <tt>__concat</tt> metamethod.</li>
112<li>Various minor optimizations.</li>
113</ul></li>
114<li>Internal Changes:
115<ul>
116<li>Add support for embedding LuaJIT bytecode for builtins.</li>
117<li>Replace various builtins with embedded bytecode.</li>
118<li>Refactor string buffers and string formatting.</li>
119<li>Remove obsolete non-truncating number to integer conversions.</li>
120</ul></li>
121<li>Ports:
122<ul>
123<li>Add Xbox One port (<tt>LJ_GC64</tt> mode).</li>
124<li>ARM64: Add port of the interpreter (<tt>LJ_GC64</tt> mode).</li>
125<li>x64: Add separate port of the interpreter to <tt>LJ_GC64</tt> mode.</li>
126<li>x86/x64: Drop internal x87 math functions. Use libm functions.</li>
127<li>x86: Remove x87 support from interpreter. SSE2 is mandatory now.</li>
128<li>PPC/e500: Drop support for this architecture.</li>
129</ul></li>
130<li>FFI library:
131<ul>
132<li>FFI: Add 64 bit bitwise operations.</li>
133<li>FFI: Compile VLA/VLS and large cdata allocations with default initialization.</li>
134<li>FFI: Compile conversions from functions to function pointers.</li>
135<li>FFI: Compile lightuserdata to <tt>void *</tt> conversion.</li>
136<li>FFI: Compile <tt>ffi.gc(cdata, nil)</tt>, too.</li>
137<li>FFI: Add <tt>ffi.typeinfo()</tt>.</li>
138</ul></li>
139</ul>
140</div>
141
142<div class="major" style="background: #ffffd0;">
75<h2 id="LuaJIT-2.0.4">LuaJIT 2.0.4 &mdash; 2015-05-14</h2> 143<h2 id="LuaJIT-2.0.4">LuaJIT 2.0.4 &mdash; 2015-05-14</h2>
76<ul> 144<ul>
77<li>Fix stack check in narrowing optimization.</li> 145<li>Fix stack check in narrowing optimization.</li>
@@ -735,235 +803,6 @@ This matches the behavior of Lua 5.1, but not the specification.</li>
735no point in listing differences over earlier versions.</li> 803no point in listing differences over earlier versions.</li>
736</ul> 804</ul>
737</div> 805</div>
738
739<div class="major" style="background: #ffff80;">
740<h2 id="LuaJIT-1.1.8">LuaJIT 1.1.8 &mdash; 2012-04-16</h2>
741<ul>
742<li>Merged with Lua 5.1.5. Also integrated fixes for all
743<a href="http://www.lua.org/bugs.html#5.1.5"><span class="ext">&raquo;</span>&nbsp;<span class="ext">&raquo;</span>&nbsp;currently known bugs in Lua 5.1.5</a>.</li>
744</ul>
745
746<h2 id="LuaJIT-1.1.7">LuaJIT 1.1.7 &mdash; 2011-05-05</h2>
747<ul>
748<li>Added fixes for the
749<a href="http://www.lua.org/bugs.html#5.1.4"><span class="ext">&raquo;</span>&nbsp;currently known bugs in Lua 5.1.4</a>.</li>
750</ul>
751
752<h2 id="LuaJIT-1.1.6">LuaJIT 1.1.6 &mdash; 2010-03-28</h2>
753<ul>
754<li>Added fixes for the
755<a href="http://www.lua.org/bugs.html#5.1.4"><span class="ext">&raquo;</span>&nbsp;currently known bugs in Lua 5.1.4</a>.</li>
756<li>Removed wrong GC check in <tt>jit_createstate()</tt>.
757Thanks to Tim Mensch.</li>
758<li>Fixed bad assertions while compiling <tt>table.insert()</tt> and
759<tt>table.remove()</tt>.</li>
760</ul>
761
762<h2 id="LuaJIT-1.1.5">LuaJIT 1.1.5 &mdash; 2008-10-25</h2>
763<ul>
764<li>Merged with Lua 5.1.4. Fixes all
765<a href="http://www.lua.org/bugs.html#5.1.3"><span class="ext">&raquo;</span>&nbsp;known bugs in Lua 5.1.3</a>.</li>
766</ul>
767
768<h2 id="LuaJIT-1.1.4">LuaJIT 1.1.4 &mdash; 2008-02-05</h2>
769<ul>
770<li>Merged with Lua 5.1.3. Fixes all
771<a href="http://www.lua.org/bugs.html#5.1.2"><span class="ext">&raquo;</span>&nbsp;known bugs in Lua 5.1.2</a>.</li>
772<li>Fixed possible (but unlikely) stack corruption while compiling
773<tt>k^x</tt> expressions.</li>
774<li>Fixed DynASM template for cmpss instruction.</li>
775</ul>
776
777<h2 id="LuaJIT-1.1.3">LuaJIT 1.1.3 &mdash; 2007-05-24</h2>
778<ul>
779<li>Merged with Lua 5.1.2. Fixes all
780<a href="http://www.lua.org/bugs.html#5.1.1"><span class="ext">&raquo;</span>&nbsp;known bugs in Lua 5.1.1</a>.</li>
781<li>Merged pending Lua 5.1.x fixes: "return -nil" bug, spurious count hook call.</li>
782<li>Remove a (sometimes) wrong assertion in <tt>luaJIT_findpc()</tt>.</li>
783<li>DynASM now allows labels for displacements and <tt>.aword</tt>.</li>
784<li>Fix some compiler warnings for DynASM glue (internal API change).</li>
785<li>Correct naming for SSSE3 (temporarily known as SSE4) in DynASM and x86 disassembler.</li>
786<li>The loadable debug modules now handle redirection to stdout
787(e.g. <tt>-j&nbsp;trace=-</tt>).</li>
788</ul>
789
790<h2 id="LuaJIT-1.1.2">LuaJIT 1.1.2 &mdash; 2006-06-24</h2>
791<ul>
792<li>Fix MSVC inline assembly: use only local variables with
793<tt>lua_number2int()</tt>.</li>
794<li>Fix "attempt to call a thread value" bug on Mac OS X:
795make values of consts used as lightuserdata keys unique
796to avoid joining by the compiler/linker.</li>
797</ul>
798
799<h2 id="LuaJIT-1.1.1">LuaJIT 1.1.1 &mdash; 2006-06-20</h2>
800<ul>
801<li>Merged with Lua 5.1.1. Fixes all
802<a href="http://www.lua.org/bugs.html#5.1"><span class="ext">&raquo;</span>&nbsp;known bugs in Lua 5.1</a>.</li>
803<li>Enforce (dynamic) linker error for EXE/DLL version mismatches.</li>
804<li>Minor changes to DynASM: faster pre-processing, smaller encoding
805for some immediates.</li>
806</ul>
807<p>
808This release is in sync with Coco 1.1.1 (see the
809<a href="http://coco.luajit.org/changes.html"><span class="ext">&raquo;</span>&nbsp;Coco Change History</a>).
810</p>
811
812<h2 id="LuaJIT-1.1.0">LuaJIT 1.1.0 &mdash; 2006-03-13</h2>
813<ul>
814<li>Merged with Lua 5.1 (final).</li>
815
816<li>New JIT call frame setup:
817<ul>
818<li>The C stack is kept 16 byte aligned (faster).
819Mandatory for Mac OS X on Intel, too.</li>
820<li>Faster calling conventions for internal C helper functions.</li>
821<li>Better instruction scheduling for function prologue, OP_CALL and
822OP_RETURN.</li>
823</ul></li>
824
825<li>Miscellaneous optimizations:
826<ul>
827<li>Faster loads of FP constants. Remove narrow-to-wide store-to-load
828forwarding stalls.</li>
829<li>Use (scalar) SSE2 ops (if the CPU supports it) to speed up slot moves
830and FP to integer conversions.</li>
831<li>Optimized the two-argument form of <tt>OP_CONCAT</tt> (<tt>a..b</tt>).</li>
832<li>Inlined <tt>OP_MOD</tt> (<tt>a%b</tt>).
833With better accuracy than the C variant, too.</li>
834<li>Inlined <tt>OP_POW</tt> (<tt>a^b</tt>). Unroll <tt>x^k</tt> or
835use <tt>k^x = 2^(log2(k)*x)</tt> or call <tt>pow()</tt>.</li>
836</ul></li>
837
838<li>Changes in the optimizer:
839<ul>
840<li>Improved hinting for table keys derived from table values
841(<tt>t1[t2[x]]</tt>).</li>
842<li>Lookup hinting now works with arbitrary object types and
843supports index chains, too.</li>
844<li>Generate type hints for arithmetic and comparison operators,
845OP_LEN, OP_CONCAT and OP_FORPREP.</li>
846<li>Remove several hint definitions in favour of a generic COMBINE hint.</li>
847<li>Complete rewrite of <tt>jit.opt_inline</tt> module
848(ex <tt>jit.opt_lib</tt>).</li>
849</ul></li>
850
851<li>Use adaptive deoptimization:
852<ul>
853<li>If runtime verification of a contract fails, the affected
854instruction is recompiled and patched on-the-fly.
855Regular programs will trigger deoptimization only occasionally.</li>
856<li>This avoids generating code for uncommon fallback cases
857most of the time. Generated code is up to 30% smaller compared to
858LuaJIT&nbsp;1.0.3.</li>
859<li>Deoptimization is used for many opcodes and contracts:
860<ul>
861<li>OP_CALL, OP_TAILCALL: type mismatch for callable.</li>
862<li>Inlined calls: closure mismatch, parameter number and type mismatches.</li>
863<li>OP_GETTABLE, OP_SETTABLE: table or key type and range mismatches.</li>
864<li>All arithmetic and comparison operators, OP_LEN, OP_CONCAT,
865OP_FORPREP: operand type and range mismatches.</li>
866</ul></li>
867<li>Complete redesign of the debug and traceback info
868(bytecode &harr; mcode) to support deoptimization.
869Much more flexible and needs only 50% of the space.</li>
870<li>The modules <tt>jit.trace</tt>, <tt>jit.dumphints</tt> and
871<tt>jit.dump</tt> handle deoptimization.</li>
872</ul></li>
873
874<li>Inlined many popular library functions
875(for commonly used arguments only):
876<ul>
877<li>Most <tt>math.*</tt> functions (the 18 most used ones)
878[2x-10x faster].</li>
879<li><tt>string.len</tt>, <tt>string.sub</tt> and <tt>string.char</tt>
880[2x-10x faster].</li>
881<li><tt>table.insert</tt>, <tt>table.remove</tt> and <tt>table.getn</tt>
882[3x-5x faster].</li>
883<li><tt>coroutine.yield</tt> and <tt>coroutine.resume</tt>
884[3x-5x faster].</li>
885<li><tt>pairs</tt>, <tt>ipairs</tt> and the corresponding iterators
886[8x-15x faster].</li>
887</ul></li>
888
889<li>Changes in the core and loadable modules and the stand-alone executable:
890<ul>
891<li>Added <tt>jit.version</tt>, <tt>jit.version_num</tt>
892and <tt>jit.arch</tt>.</li>
893<li>Reorganized some internal API functions (<tt>jit.util.*mcode*</tt>).</li>
894<li>The <tt>-j dump</tt> output now shows JSUB names, too.</li>
895<li>New x86 disassembler module written in pure Lua. No dependency
896on ndisasm anymore. Flexible API, very compact (500 lines)
897and complete (x87, MMX, SSE, SSE2, SSE3, SSSE3, privileged instructions).</li>
898<li><tt>luajit -v</tt> prints the LuaJIT version and copyright
899on a separate line.</li>
900</ul></li>
901
902<li>Added SSE, SSE2, SSE3 and SSSE3 support to DynASM.</li>
903<li>Miscellaneous doc changes. Added a section about
904<a href="install.html#embedding">embedding LuaJIT</a>.</li>
905</ul>
906<p>
907This release is in sync with Coco 1.1.0 (see the
908<a href="http://coco.luajit.org/changes.html"><span class="ext">&raquo;</span>&nbsp;Coco Change History</a>).
909</p>
910</div>
911
912<div class="major" style="background: #ffffd0;">
913<h2 id="LuaJIT-1.0.3">LuaJIT 1.0.3 &mdash; 2005-09-08</h2>
914<ul>
915<li>Even more docs.</li>
916<li>Unified closure checks in <tt>jit.*</tt>.</li>
917<li>Fixed some range checks in <tt>jit.util.*</tt>.</li>
918<li>Fixed __newindex call originating from <tt>jit_settable_str()</tt>.</li>
919<li>Merged with Lua 5.1 alpha (including early bug fixes).</li>
920</ul>
921<p>
922This is the first public release of LuaJIT.
923</p>
924
925<h2 id="LuaJIT-1.0.2">LuaJIT 1.0.2 &mdash; 2005-09-02</h2>
926<ul>
927<li>Add support for flushing the Valgrind translation cache <br>
928(<tt>MYCFLAGS= -DUSE_VALGRIND</tt>).</li>
929<li>Add support for freeing executable mcode memory to the <tt>mmap()</tt>-based
930variant for POSIX systems.</li>
931<li>Reorganized the C&nbsp;function signature handling in
932<tt>jit.opt_lib</tt>.</li>
933<li>Changed to index-based hints for inlining C&nbsp;functions.
934Still no support in the backend for inlining.</li>
935<li>Hardcode <tt>HEAP_CREATE_ENABLE_EXECUTE</tt> value if undefined.</li>
936<li>Misc. changes to the <tt>jit.*</tt> modules.</li>
937<li>Misc. changes to the Makefiles.</li>
938<li>Lots of new docs.</li>
939<li>Complete doc reorg.</li>
940</ul>
941<p>
942Not released because Lua 5.1 alpha came out today.
943</p>
944
945<h2 id="LuaJIT-1.0.1">LuaJIT 1.0.1 &mdash; 2005-08-31</h2>
946<ul>
947<li>Missing GC step in <tt>OP_CONCAT</tt>.</li>
948<li>Fix result handling for C &ndash;> JIT calls.</li>
949<li>Detect CPU feature bits.</li>
950<li>Encode conditional moves (<tt>fucomip</tt>) only when supported.</li>
951<li>Add fallback instructions for FP compares.</li>
952<li>Add support for <tt>LUA_COMPAT_VARARG</tt>. Still disabled by default.</li>
953<li>MSVC needs a specific place for the <tt>CALLBACK</tt> attribute
954(David Burgess).</li>
955<li>Misc. doc updates.</li>
956</ul>
957<p>
958Interim non-public release.
959Special thanks to Adam D. Moss for reporting most of the bugs.
960</p>
961
962<h2 id="LuaJIT-1.0.0">LuaJIT 1.0.0 &mdash; 2005-08-29</h2>
963<p>
964This is the initial non-public release of LuaJIT.
965</p>
966</div>
967<br class="flush"> 806<br class="flush">
968</div> 807</div>
969<div id="foot"> 808<div id="foot">
diff --git a/doc/contact.html b/doc/contact.html
index 5e07bded..fe4751c0 100644
--- a/doc/contact.html
+++ b/doc/contact.html
@@ -41,6 +41,8 @@
41<a href="ext_jit.html">jit.* Library</a> 41<a href="ext_jit.html">jit.* Library</a>
42</li><li> 42</li><li>
43<a href="ext_c_api.html">Lua/C API</a> 43<a href="ext_c_api.html">Lua/C API</a>
44</li><li>
45<a href="ext_profiler.html">Profiler</a>
44</li></ul> 46</li></ul>
45</li><li> 47</li><li>
46<a href="status.html">Status</a> 48<a href="status.html">Status</a>
diff --git a/doc/ext_c_api.html b/doc/ext_c_api.html
index 041a7220..ad462c63 100644
--- a/doc/ext_c_api.html
+++ b/doc/ext_c_api.html
@@ -41,6 +41,8 @@
41<a href="ext_jit.html">jit.* Library</a> 41<a href="ext_jit.html">jit.* Library</a>
42</li><li> 42</li><li>
43<a class="current" href="ext_c_api.html">Lua/C API</a> 43<a class="current" href="ext_c_api.html">Lua/C API</a>
44</li><li>
45<a href="ext_profiler.html">Profiler</a>
44</li></ul> 46</li></ul>
45</li><li> 47</li><li>
46<a href="status.html">Status</a> 48<a href="status.html">Status</a>
diff --git a/doc/ext_ffi.html b/doc/ext_ffi.html
index d48d77fa..5e1daaf5 100644
--- a/doc/ext_ffi.html
+++ b/doc/ext_ffi.html
@@ -41,6 +41,8 @@
41<a href="ext_jit.html">jit.* Library</a> 41<a href="ext_jit.html">jit.* Library</a>
42</li><li> 42</li><li>
43<a href="ext_c_api.html">Lua/C API</a> 43<a href="ext_c_api.html">Lua/C API</a>
44</li><li>
45<a href="ext_profiler.html">Profiler</a>
44</li></ul> 46</li></ul>
45</li><li> 47</li><li>
46<a href="status.html">Status</a> 48<a href="status.html">Status</a>
diff --git a/doc/ext_ffi_api.html b/doc/ext_ffi_api.html
index 566897c8..91af2e1d 100644
--- a/doc/ext_ffi_api.html
+++ b/doc/ext_ffi_api.html
@@ -46,6 +46,8 @@ td.abiparam { font-weight: bold; width: 6em; }
46<a href="ext_jit.html">jit.* Library</a> 46<a href="ext_jit.html">jit.* Library</a>
47</li><li> 47</li><li>
48<a href="ext_c_api.html">Lua/C API</a> 48<a href="ext_c_api.html">Lua/C API</a>
49</li><li>
50<a href="ext_profiler.html">Profiler</a>
49</li></ul> 51</li></ul>
50</li><li> 52</li><li>
51<a href="status.html">Status</a> 53<a href="status.html">Status</a>
@@ -466,6 +468,8 @@ otherwise. The following parameters are currently defined:
466<td class="abiparam">eabi</td><td class="abidesc">EABI variant of the standard ABI</td></tr> 468<td class="abiparam">eabi</td><td class="abidesc">EABI variant of the standard ABI</td></tr>
467<tr class="odd"> 469<tr class="odd">
468<td class="abiparam">win</td><td class="abidesc">Windows variant of the standard ABI</td></tr> 470<td class="abiparam">win</td><td class="abidesc">Windows variant of the standard ABI</td></tr>
471<tr class="even">
472<td class="abiparam">gc64</td><td class="abidesc">64 bit GC references</td></tr>
469</table> 473</table>
470 474
471<h3 id="ffi_os"><tt>ffi.os</tt></h3> 475<h3 id="ffi_os"><tt>ffi.os</tt></h3>
@@ -542,8 +546,8 @@ corresponding ctype.
542The parser for Lua source code treats numeric literals with the 546The parser for Lua source code treats numeric literals with the
543suffixes <tt>LL</tt> or <tt>ULL</tt> as signed or unsigned 64&nbsp;bit 547suffixes <tt>LL</tt> or <tt>ULL</tt> as signed or unsigned 64&nbsp;bit
544integers. Case doesn't matter, but uppercase is recommended for 548integers. Case doesn't matter, but uppercase is recommended for
545readability. It handles both decimal (<tt>42LL</tt>) and hexadecimal 549readability. It handles decimal (<tt>42LL</tt>), hexadecimal
546(<tt>0x2aLL</tt>) literals. 550(<tt>0x2aLL</tt>) and binary (<tt>0b101010LL</tt>) literals.
547</p> 551</p>
548<p> 552<p>
549The imaginary part of complex numbers can be specified by suffixing 553The imaginary part of complex numbers can be specified by suffixing
diff --git a/doc/ext_ffi_semantics.html b/doc/ext_ffi_semantics.html
index 899640ce..bba03b7b 100644
--- a/doc/ext_ffi_semantics.html
+++ b/doc/ext_ffi_semantics.html
@@ -46,6 +46,8 @@ td.convop { font-style: italic; width: 40%; }
46<a href="ext_jit.html">jit.* Library</a> 46<a href="ext_jit.html">jit.* Library</a>
47</li><li> 47</li><li>
48<a href="ext_c_api.html">Lua/C API</a> 48<a href="ext_c_api.html">Lua/C API</a>
49</li><li>
50<a href="ext_profiler.html">Profiler</a>
49</li></ul> 51</li></ul>
50</li><li> 52</li><li>
51<a href="status.html">Status</a> 53<a href="status.html">Status</a>
@@ -183,6 +185,8 @@ a <tt>typedef</tt>, except re-declarations will be ignored):
183<tt>uint16_t</tt>, <tt>uint32_t</tt>, <tt>uint64_t</tt>, 185<tt>uint16_t</tt>, <tt>uint32_t</tt>, <tt>uint64_t</tt>,
184<tt>intptr_t</tt>, <tt>uintptr_t</tt>.</li> 186<tt>intptr_t</tt>, <tt>uintptr_t</tt>.</li>
185 187
188<li>From <tt>&lt;unistd.h&gt;</tt> (POSIX): <tt>ssize_t</tt>.</li>
189
186</ul> 190</ul>
187<p> 191<p>
188You're encouraged to use these types in preference to 192You're encouraged to use these types in preference to
@@ -730,6 +734,22 @@ You'll have to explicitly convert a 64&nbsp;bit integer to a Lua
730number (e.g. for regular floating-point calculations) with 734number (e.g. for regular floating-point calculations) with
731<tt>tonumber()</tt>. But note this may incur a precision loss.</li> 735<tt>tonumber()</tt>. But note this may incur a precision loss.</li>
732 736
737<li><b>64&nbsp;bit bitwise operations</b>: the rules for 64&nbsp;bit
738arithmetic operators apply analogously.<br>
739
740Unlike the other <tt>bit.*</tt> operations, <tt>bit.tobit()</tt>
741converts a cdata number via <tt>int64_t</tt> to <tt>int32_t</tt> and
742returns a Lua number.<br>
743
744For <tt>bit.band()</tt>, <tt>bit.bor()</tt> and <tt>bit.bxor()</tt>, the
745conversion to <tt>int64_t</tt> or <tt>uint64_t</tt> applies to
746<em>all</em> arguments, if <em>any</em> argument is a cdata number.<br>
747
748For all other operations, only the first argument is used to determine
749the output type. This implies that a cdata number as a shift count for
750shifts and rotates is accepted, but that alone does <em>not</em> cause
751a cdata number output.
752
733</ul> 753</ul>
734 754
735<h3 id="cdata_comp">Comparisons of cdata objects</h3> 755<h3 id="cdata_comp">Comparisons of cdata objects</h3>
@@ -1205,9 +1225,8 @@ suboptimal performance, especially when used in inner loops:
1205<li>Vector operations.</li> 1225<li>Vector operations.</li>
1206<li>Table initializers.</li> 1226<li>Table initializers.</li>
1207<li>Initialization of nested <tt>struct</tt>/<tt>union</tt> types.</li> 1227<li>Initialization of nested <tt>struct</tt>/<tt>union</tt> types.</li>
1208<li>Allocations of variable-length arrays or structs.</li> 1228<li>Non-default initialization of VLA/VLS or large C&nbsp;types
1209<li>Allocations of C&nbsp;types with a size &gt; 128&nbsp;bytes or an 1229(&gt; 128&nbsp;bytes or &gt; 16 array elements.</li>
1210alignment &gt; 8&nbsp;bytes.</li>
1211<li>Conversions from lightuserdata to <tt>void&nbsp;*</tt>.</li> 1230<li>Conversions from lightuserdata to <tt>void&nbsp;*</tt>.</li>
1212<li>Pointer differences for element sizes that are not a power of 1231<li>Pointer differences for element sizes that are not a power of
1213two.</li> 1232two.</li>
@@ -1224,7 +1243,6 @@ value.</li>
1224Other missing features: 1243Other missing features:
1225</p> 1244</p>
1226<ul> 1245<ul>
1227<li>Bit operations for 64&nbsp;bit types.</li>
1228<li>Arithmetic for <tt>complex</tt> numbers.</li> 1246<li>Arithmetic for <tt>complex</tt> numbers.</li>
1229<li>Passing structs by value to vararg C&nbsp;functions.</li> 1247<li>Passing structs by value to vararg C&nbsp;functions.</li>
1230<li><a href="extensions.html#exceptions">C++ exception interoperability</a> 1248<li><a href="extensions.html#exceptions">C++ exception interoperability</a>
diff --git a/doc/ext_ffi_tutorial.html b/doc/ext_ffi_tutorial.html
index 29cf549e..36500664 100644
--- a/doc/ext_ffi_tutorial.html
+++ b/doc/ext_ffi_tutorial.html
@@ -48,6 +48,8 @@ td.idiomlua b { font-weight: normal; color: #2142bf; }
48<a href="ext_jit.html">jit.* Library</a> 48<a href="ext_jit.html">jit.* Library</a>
49</li><li> 49</li><li>
50<a href="ext_c_api.html">Lua/C API</a> 50<a href="ext_c_api.html">Lua/C API</a>
51</li><li>
52<a href="ext_profiler.html">Profiler</a>
51</li></ul> 53</li></ul>
52</li><li> 54</li><li>
53<a href="status.html">Status</a> 55<a href="status.html">Status</a>
diff --git a/doc/ext_jit.html b/doc/ext_jit.html
index 5017e3cd..e4088bcb 100644
--- a/doc/ext_jit.html
+++ b/doc/ext_jit.html
@@ -41,6 +41,8 @@
41<a class="current" href="ext_jit.html">jit.* Library</a> 41<a class="current" href="ext_jit.html">jit.* Library</a>
42</li><li> 42</li><li>
43<a href="ext_c_api.html">Lua/C API</a> 43<a href="ext_c_api.html">Lua/C API</a>
44</li><li>
45<a href="ext_profiler.html">Profiler</a>
44</li></ul> 46</li></ul>
45</li><li> 47</li><li>
46<a href="status.html">Status</a> 48<a href="status.html">Status</a>
@@ -151,7 +153,7 @@ Contains the target OS name:
151<h3 id="jit_arch"><tt>jit.arch</tt></h3> 153<h3 id="jit_arch"><tt>jit.arch</tt></h3>
152<p> 154<p>
153Contains the target architecture name: 155Contains the target architecture name:
154"x86", "x64", "arm", "ppc", "ppcspe", or "mips". 156"x86", "x64", "arm", "arm64", "ppc", "mips" or "mips64".
155</p> 157</p>
156 158
157<h2 id="jit_opt"><tt>jit.opt.*</tt> &mdash; JIT compiler optimization control</h2> 159<h2 id="jit_opt"><tt>jit.opt.*</tt> &mdash; JIT compiler optimization control</h2>
diff --git a/doc/ext_profiler.html b/doc/ext_profiler.html
new file mode 100644
index 00000000..71b8c033
--- /dev/null
+++ b/doc/ext_profiler.html
@@ -0,0 +1,365 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>Profiler</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6<meta name="Author" content="Mike Pall">
7<meta name="Copyright" content="Copyright (C) 2005-2017, Mike Pall">
8<meta name="Language" content="en">
9<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
10<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
11</head>
12<body>
13<div id="site">
14<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
15</div>
16<div id="head">
17<h1>Profiler</h1>
18</div>
19<div id="nav">
20<ul><li>
21<a href="luajit.html">LuaJIT</a>
22<ul><li>
23<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
24</li><li>
25<a href="install.html">Installation</a>
26</li><li>
27<a href="running.html">Running</a>
28</li></ul>
29</li><li>
30<a href="extensions.html">Extensions</a>
31<ul><li>
32<a href="ext_ffi.html">FFI Library</a>
33<ul><li>
34<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
35</li><li>
36<a href="ext_ffi_api.html">ffi.* API</a>
37</li><li>
38<a href="ext_ffi_semantics.html">FFI Semantics</a>
39</li></ul>
40</li><li>
41<a href="ext_jit.html">jit.* Library</a>
42</li><li>
43<a href="ext_c_api.html">Lua/C API</a>
44</li><li>
45<a class="current" href="ext_profiler.html">Profiler</a>
46</li></ul>
47</li><li>
48<a href="status.html">Status</a>
49<ul><li>
50<a href="changes.html">Changes</a>
51</li></ul>
52</li><li>
53<a href="faq.html">FAQ</a>
54</li><li>
55<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
56</li><li>
57<a href="http://wiki.luajit.org/">Wiki <span class="ext">&raquo;</span></a>
58</li><li>
59<a href="http://luajit.org/list.html">Mailing List <span class="ext">&raquo;</span></a>
60</li></ul>
61</div>
62<div id="main">
63<p>
64LuaJIT has an integrated statistical profiler with very low overhead. It
65allows sampling the currently executing stack and other parameters in
66regular intervals.
67</p>
68<p>
69The integrated profiler can be accessed from three levels:
70</p>
71<ul>
72<li>The <a href="#hl_profiler">bundled high-level profiler</a>, invoked by the
73<a href="#j_p"><tt>-jp</tt></a> command line option.</li>
74<li>A <a href="#ll_lua_api">low-level Lua API</a> to control the profiler.</li>
75<li>A <a href="#ll_c_api">low-level C API</a> to control the profiler.</li>
76</ul>
77
78<h2 id="hl_profiler">High-Level Profiler</h2>
79<p>
80The bundled high-level profiler offers basic profiling functionality. It
81generates simple textual summaries or source code annotations. It can be
82accessed with the <a href="#j_p"><tt>-jp</tt></a> command line option
83or from Lua code by loading the underlying <tt>jit.p</tt> module.
84</p>
85<p>
86To cut to the chase &mdash; run this to get a CPU usage profile by
87function name:
88</p>
89<pre class="code">
90luajit -jp myapp.lua
91</pre>
92<p>
93It's <em>not</em> a stated goal of the bundled profiler to add every
94possible option or to cater for special profiling needs. The low-level
95profiler APIs are documented below. They may be used by third-party
96authors to implement advanced functionality, e.g. IDE integration or
97graphical profilers.
98</p>
99<p>
100Note: Sampling works for both interpreted and JIT-compiled code. The
101results for JIT-compiled code may sometimes be surprising. LuaJIT
102heavily optimizes and inlines Lua code &mdash; there's no simple
103one-to-one correspondence between source code lines and the sampled
104machine code.
105</p>
106
107<h3 id="j_p"><tt>-jp=[options[,output]]</tt></h3>
108<p>
109The <tt>-jp</tt> command line option starts the high-level profiler.
110When the application run by the command line terminates, the profiler
111stops and writes the results to <tt>stdout</tt> or to the specified
112<tt>output</tt> file.
113</p>
114<p>
115The <tt>options</tt> argument specifies how the profiling is to be
116performed:
117</p>
118<ul>
119<li><tt>f</tt> &mdash; Stack dump: function name, otherwise module:line.
120This is the default mode.</li>
121<li><tt>F</tt> &mdash; Stack dump: ditto, but dump module:name.</li>
122<li><tt>l</tt> &mdash; Stack dump: module:line.</li>
123<li><tt>&lt;number&gt;</tt> &mdash; stack dump depth (callee &larr;
124caller). Default: 1.</li>
125<li><tt>-&lt;number&gt;</tt> &mdash; Inverse stack dump depth (caller
126&rarr; callee).</li>
127<li><tt>s</tt> &mdash; Split stack dump after first stack level. Implies
128depth&nbsp;&ge;&nbsp;2 or depth&nbsp;&le;&nbsp;-2.</li>
129<li><tt>p</tt> &mdash; Show full path for module names.</li>
130<li><tt>v</tt> &mdash; Show VM states.</li>
131<li><tt>z</tt> &mdash; Show <a href="#jit_zone">zones</a>.</li>
132<li><tt>r</tt> &mdash; Show raw sample counts. Default: show percentages.</li>
133<li><tt>a</tt> &mdash; Annotate excerpts from source code files.</li>
134<li><tt>A</tt> &mdash; Annotate complete source code files.</li>
135<li><tt>G</tt> &mdash; Produce raw output suitable for graphical tools.</li>
136<li><tt>m&lt;number&gt;</tt> &mdash; Minimum sample percentage to be shown.
137Default: 3%.</li>
138<li><tt>i&lt;number&gt;</tt> &mdash; Sampling interval in milliseconds.
139Default: 10ms.<br>
140Note: The actual sampling precision is OS-dependent.</li>
141</ul>
142<p>
143The default output for <tt>-jp</tt> is a list of the most CPU consuming
144spots in the application. Increasing the stack dump depth with (say)
145<tt>-jp=2</tt> may help to point out the main callers or callees of
146hotspots. But sample aggregation is still flat per unique stack dump.
147</p>
148<p>
149To get a two-level view (split view) of callers/callees, use
150<tt>-jp=s</tt> or <tt>-jp=-s</tt>. The percentages shown for the second
151level are relative to the first level.
152</p>
153<p>
154To see how much time is spent in each line relative to a function, use
155<tt>-jp=fl</tt>.
156</p>
157<p>
158To see how much time is spent in different VM states or
159<a href="#jit_zone">zones</a>, use <tt>-jp=v</tt> or <tt>-jp=z</tt>.
160</p>
161<p>
162Combinations of <tt>v/z</tt> with <tt>f/F/l</tt> produce two-level
163views, e.g. <tt>-jp=vf</tt> or <tt>-jp=fv</tt>. This shows the time
164spent in a VM state or zone vs. hotspots. This can be used to answer
165questions like "Which time consuming functions are only interpreted?" or
166"What's the garbage collector overhead for a specific function?".
167</p>
168<p>
169Multiple options can be combined &mdash; but not all combinations make
170sense, see above. E.g. <tt>-jp=3si4m1</tt> samples three stack levels
171deep in 4ms intervals and shows a split view of the CPU consuming
172functions and their callers with a 1% threshold.
173</p>
174<p>
175Source code annotations produced by <tt>-jp=a</tt> or <tt>-jp=A</tt> are
176always flat and at the line level. Obviously, the source code files need
177to be readable by the profiler script.
178</p>
179<p>
180The high-level profiler can also be started and stopped from Lua code with:
181</p>
182<pre class="code">
183require("jit.p").start(options, output)
184...
185require("jit.p").stop()
186</pre>
187
188<h3 id="jit_zone"><tt>jit.zone</tt> &mdash; Zones</h3>
189<p>
190Zones can be used to provide information about different parts of an
191application to the high-level profiler. E.g. a game could make use of an
192<tt>"AI"</tt> zone, a <tt>"PHYS"</tt> zone, etc. Zones are hierarchical,
193organized as a stack.
194</p>
195<p>
196The <tt>jit.zone</tt> module needs to be loaded explicitly:
197</p>
198<pre class="code">
199local zone = require("jit.zone")
200</pre>
201<ul>
202<li><tt>zone("name")</tt> pushes a named zone to the zone stack.</li>
203<li><tt>zone()</tt> pops the current zone from the zone stack and
204returns its name.</li>
205<li><tt>zone:get()</tt> returns the current zone name or <tt>nil</tt>.</li>
206<li><tt>zone:flush()</tt> flushes the zone stack.</li>
207</ul>
208<p>
209To show the time spent in each zone use <tt>-jp=z</tt>. To show the time
210spent relative to hotspots use e.g. <tt>-jp=zf</tt> or <tt>-jp=fz</tt>.
211</p>
212
213<h2 id="ll_lua_api">Low-level Lua API</h2>
214<p>
215The <tt>jit.profile</tt> module gives access to the low-level API of the
216profiler from Lua code. This module needs to be loaded explicitly:
217<pre class="code">
218local profile = require("jit.profile")
219</pre>
220<p>
221This module can be used to implement your own higher-level profiler.
222A typical profiling run starts the profiler, captures stack dumps in
223the profiler callback, adds them to a hash table to aggregate the number
224of samples, stops the profiler and then analyzes all of the captured
225stack dumps. Other parameters can be sampled in the profiler callback,
226too. But it's important not to spend too much time in the callback,
227since this may skew the statistics.
228</p>
229
230<h3 id="profile_start"><tt>profile.start(mode, cb)</tt>
231&mdash; Start profiler</h3>
232<p>
233This function starts the profiler. The <tt>mode</tt> argument is a
234string holding options:
235</p>
236<ul>
237<li><tt>f</tt> &mdash; Profile with precision down to the function level.</li>
238<li><tt>l</tt> &mdash; Profile with precision down to the line level.</li>
239<li><tt>i&lt;number&gt;</tt> &mdash; Sampling interval in milliseconds (default
24010ms).</br>
241Note: The actual sampling precision is OS-dependent.
242</li>
243</ul>
244<p>
245The <tt>cb</tt> argument is a callback function which is called with
246three arguments: <tt>(thread, samples, vmstate)</tt>. The callback is
247called on a separate coroutine, the <tt>thread</tt> argument is the
248state that holds the stack to sample for profiling. Note: do
249<em>not</em> modify the stack of that state or call functions on it.
250</p>
251<p>
252<tt>samples</tt> gives the number of accumulated samples since the last
253callback (usually 1).
254</p>
255<p>
256<tt>vmstate</tt> holds the VM state at the time the profiling timer
257triggered. This may or may not correspond to the state of the VM when
258the profiling callback is called. The state is either <tt>'N'</tt>
259native (compiled) code, <tt>'I'</tt> interpreted code, <tt>'C'</tt>
260C&nbsp;code, <tt>'G'</tt> the garbage collector, or <tt>'J'</tt> the JIT
261compiler.
262</p>
263
264<h3 id="profile_stop"><tt>profile.stop()</tt>
265&mdash; Stop profiler</h3>
266<p>
267This function stops the profiler.
268</p>
269
270<h3 id="profile_dump"><tt>dump = profile.dumpstack([thread,] fmt, depth)</tt>
271&mdash; Dump stack </h3>
272<p>
273This function allows taking stack dumps in an efficient manner. It
274returns a string with a stack dump for the <tt>thread</tt> (coroutine),
275formatted according to the <tt>fmt</tt> argument:
276</p>
277<ul>
278<li><tt>p</tt> &mdash; Preserve the full path for module names. Otherwise
279only the file name is used.</li>
280<li><tt>f</tt> &mdash; Dump the function name if it can be derived. Otherwise
281use module:line.</li>
282<li><tt>F</tt> &mdash; Ditto, but dump module:name.</li>
283<li><tt>l</tt> &mdash; Dump module:line.</li>
284<li><tt>Z</tt> &mdash; Zap the following characters for the last dumped
285frame.</li>
286<li>All other characters are added verbatim to the output string.</li>
287</ul>
288<p>
289The <tt>depth</tt> argument gives the number of frames to dump, starting
290at the topmost frame of the thread. A negative number dumps the frames in
291inverse order.
292</p>
293<p>
294The first example prints a list of the current module names and line
295numbers of up to 10 frames in separate lines. The second example prints
296semicolon-separated function names for all frames (up to 100) in inverse
297order:
298</p>
299<pre class="code">
300print(profile.dumpstack(thread, "l\n", 10))
301print(profile.dumpstack(thread, "lZ;", -100))
302</pre>
303
304<h2 id="ll_c_api">Low-level C API</h2>
305<p>
306The profiler can be controlled directly from C&nbsp;code, e.g. for
307use by IDEs. The declarations are in <tt>"luajit.h"</tt> (see
308<a href="ext_c_api.html">Lua/C API</a> extensions).
309</p>
310
311<h3 id="luaJIT_profile_start"><tt>luaJIT_profile_start(L, mode, cb, data)</tt>
312&mdash; Start profiler</h3>
313<p>
314This function starts the profiler. <a href="#profile_start">See
315above</a> for a description of the <tt>mode</tt> argument.
316</p>
317<p>
318The <tt>cb</tt> argument is a callback function with the following
319declaration:
320</p>
321<pre class="code">
322typedef void (*luaJIT_profile_callback)(void *data, lua_State *L,
323 int samples, int vmstate);
324</pre>
325<p>
326<tt>data</tt> is available for use by the callback. <tt>L</tt> is the
327state that holds the stack to sample for profiling. Note: do
328<em>not</em> modify this stack or call functions on this stack &mdash;
329use a separate coroutine for this purpose. <a href="#profile_start">See
330above</a> for a description of <tt>samples</tt> and <tt>vmstate</tt>.
331</p>
332
333<h3 id="luaJIT_profile_stop"><tt>luaJIT_profile_stop(L)</tt>
334&mdash; Stop profiler</h3>
335<p>
336This function stops the profiler.
337</p>
338
339<h3 id="luaJIT_profile_dumpstack"><tt>p = luaJIT_profile_dumpstack(L, fmt, depth, len)</tt>
340&mdash; Dump stack </h3>
341<p>
342This function allows taking stack dumps in an efficient manner.
343<a href="#profile_dump">See above</a> for a description of <tt>fmt</tt>
344and <tt>depth</tt>.
345</p>
346<p>
347This function returns a <tt>const&nbsp;char&nbsp;*</tt> pointing to a
348private string buffer of the profiler. The <tt>int&nbsp;*len</tt>
349argument returns the length of the output string. The buffer is
350overwritten on the next call and deallocated when the profiler stops.
351You either need to consume the content immediately or copy it for later
352use.
353</p>
354<br class="flush">
355</div>
356<div id="foot">
357<hr class="hide">
358Copyright &copy; 2005-2017 Mike Pall
359<span class="noprint">
360&middot;
361<a href="contact.html">Contact</a>
362</span>
363</div>
364</body>
365</html>
diff --git a/doc/extensions.html b/doc/extensions.html
index 3d9e82ba..87d4da24 100644
--- a/doc/extensions.html
+++ b/doc/extensions.html
@@ -58,6 +58,8 @@ td.excinterop {
58<a href="ext_jit.html">jit.* Library</a> 58<a href="ext_jit.html">jit.* Library</a>
59</li><li> 59</li><li>
60<a href="ext_c_api.html">Lua/C API</a> 60<a href="ext_c_api.html">Lua/C API</a>
61</li><li>
62<a href="ext_profiler.html">Profiler</a>
61</li></ul> 63</li></ul>
62</li><li> 64</li><li>
63<a href="status.html">Status</a> 65<a href="status.html">Status</a>
@@ -113,6 +115,9 @@ bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap
113This module is a LuaJIT built-in &mdash; you don't need to download or 115This module is a LuaJIT built-in &mdash; you don't need to download or
114install Lua BitOp. The Lua BitOp site has full documentation for all 116install Lua BitOp. The Lua BitOp site has full documentation for all
115<a href="http://bitop.luajit.org/api.html"><span class="ext">&raquo;</span>&nbsp;Lua BitOp API functions</a>. 117<a href="http://bitop.luajit.org/api.html"><span class="ext">&raquo;</span>&nbsp;Lua BitOp API functions</a>.
118The FFI adds support for
119<a href="ext_ffi_semantics.html#cdata_arith">64&nbsp;bit bitwise operations</a>,
120using the same API functions.
116</p> 121</p>
117<p> 122<p>
118Please make sure to <tt>require</tt> the module before using any of 123Please make sure to <tt>require</tt> the module before using any of
@@ -146,6 +151,11 @@ LuaJIT adds some
146<a href="ext_c_api.html">extra functions to the Lua/C API</a>. 151<a href="ext_c_api.html">extra functions to the Lua/C API</a>.
147</p> 152</p>
148 153
154<h3 id="profiler">Profiler</h3>
155<p>
156LuaJIT has an <a href="ext_profiler.html">integrated profiler</a>.
157</p>
158
149<h2 id="library">Enhanced Standard Library Functions</h2> 159<h2 id="library">Enhanced Standard Library Functions</h2>
150 160
151<h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3> 161<h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3>
@@ -173,7 +183,7 @@ in <tt>"-inf"</tt>.
173<h3 id="tonumber"><tt>tonumber()</tt> etc. use builtin string to number conversion</h3> 183<h3 id="tonumber"><tt>tonumber()</tt> etc. use builtin string to number conversion</h3>
174<p> 184<p>
175All string-to-number conversions consistently convert integer and 185All string-to-number conversions consistently convert integer and
176floating-point inputs in decimal and hexadecimal on all platforms. 186floating-point inputs in decimal, hexadecimal and binary on all platforms.
177<tt>strtod()</tt> is <em>not</em> used anymore, which avoids numerous 187<tt>strtod()</tt> is <em>not</em> used anymore, which avoids numerous
178problems with poor C library implementations. The builtin conversion 188problems with poor C library implementations. The builtin conversion
179function provides full precision according to the IEEE-754 standard, it 189function provides full precision according to the IEEE-754 standard, it
@@ -197,6 +207,37 @@ for dot releases (x.y.0 &rarr; x.y.1), but may change with major or
197minor releases (2.0 &rarr; 2.1) or between any beta release. Foreign 207minor releases (2.0 &rarr; 2.1) or between any beta release. Foreign
198bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded. 208bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded.
199</p> 209</p>
210<p>
211Note: <tt>LJ_GC64</tt> mode requires a different frame layout, which implies
212a different, incompatible bytecode format for ports that use this mode (e.g.
213ARM64 or MIPS64) or when explicitly enabled for x64. This may be rectified
214in the future.
215</p>
216
217<h3 id="table_new"><tt>table.new(narray, nhash)</tt> allocates a pre-sized table</h3>
218<p>
219An extra library function <tt>table.new()</tt> can be made available via
220<tt>require("table.new")</tt>. This creates a pre-sized table, just like
221the C API equivalent <tt>lua_createtable()</tt>. This is useful for big
222tables if the final table size is known and automatic table resizing is
223too expensive.
224</p>
225
226<h3 id="table_clear"><tt>table.clear(tab)</tt> clears a table</h3>
227<p>
228An extra library function <tt>table.clear()</tt> can be made available
229via <tt>require("table.clear")</tt>. This clears all keys and values
230from a table, but preserves the allocated array/hash sizes. This is
231useful when a table, which is linked from multiple places, needs to be
232cleared and/or when recycling a table for use by the same context. This
233avoids managing backlinks, saves an allocation and the overhead of
234incremental array/hash part growth.
235</p>
236<p>
237Please note this function is meant for very specific situations. In most
238cases it's better to replace the (usually single) link with a new table
239and let the GC do its work.
240</p>
200 241
201<h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3> 242<h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3>
202<p> 243<p>
@@ -296,6 +337,7 @@ exit status.</li>
296<li><tt>debug.setmetatable()</tt> returns object.</li> 337<li><tt>debug.setmetatable()</tt> returns object.</li>
297<li><tt>debug.getuservalue()</tt> and <tt>debug.setuservalue()</tt>.</li> 338<li><tt>debug.getuservalue()</tt> and <tt>debug.setuservalue()</tt>.</li>
298<li>Remove <tt>math.mod()</tt>, <tt>string.gfind()</tt>.</li> 339<li>Remove <tt>math.mod()</tt>, <tt>string.gfind()</tt>.</li>
340<li><tt>package.searchers</tt>.</li>
299</ul> 341</ul>
300<p> 342<p>
301Note: this provides only partial compatibility with Lua 5.2 at the 343Note: this provides only partial compatibility with Lua 5.2 at the
@@ -304,6 +346,17 @@ Lua&nbsp;5.1, which prevents implementing features that would otherwise
304break the Lua/C API and ABI (e.g. <tt>_ENV</tt>). 346break the Lua/C API and ABI (e.g. <tt>_ENV</tt>).
305</p> 347</p>
306 348
349<h2 id="lua53">Extensions from Lua 5.3</h2>
350<p>
351LuaJIT supports some extensions from Lua&nbsp;5.3:
352<ul>
353<li>Unicode escape <tt>'\u{XX...}'</tt> embeds the UTF-8 encoding in string literals.</li>
354<li>The argument table <tt>arg</tt> can be read (and modified) by <tt>LUA_INIT</tt> and <tt>-e</tt> chunks.</li>
355<li><tt>io.read()</tt> and <tt>file:read()</tt> accept formats with or without a leading <tt>*</tt>.</li>
356<li><tt>table.move(a1, f, e, t [,a2])</tt>.</li>
357<li><tt>coroutine.isyieldable()</tt>.</li>
358</ul>
359
307<h2 id="exceptions">C++ Exception Interoperability</h2> 360<h2 id="exceptions">C++ Exception Interoperability</h2>
308<p> 361<p>
309LuaJIT has built-in support for interoperating with C++&nbsp;exceptions. 362LuaJIT has built-in support for interoperating with C++&nbsp;exceptions.
@@ -318,25 +371,30 @@ the toolchain used to compile LuaJIT:
318</tr> 371</tr>
319<tr class="odd separate"> 372<tr class="odd separate">
320<td class="excplatform">POSIX/x64, DWARF2 unwinding</td> 373<td class="excplatform">POSIX/x64, DWARF2 unwinding</td>
321<td class="exccompiler">GCC 4.3+</td> 374<td class="exccompiler">GCC 4.3+, Clang</td>
322<td class="excinterop"><b style="color: #00a000;">Full</b></td> 375<td class="excinterop"><b style="color: #00a000;">Full</b></td>
323</tr> 376</tr>
324<tr class="even"> 377<tr class="even">
378<td class="excplatform">ARM <tt>-DLUAJIT_UNWIND_EXTERNAL</tt></td>
379<td class="exccompiler">GCC, Clang</td>
380<td class="excinterop"><b style="color: #00a000;">Full</b></td>
381</tr>
382<tr class="odd">
325<td class="excplatform">Other platforms, DWARF2 unwinding</td> 383<td class="excplatform">Other platforms, DWARF2 unwinding</td>
326<td class="exccompiler">GCC</td> 384<td class="exccompiler">GCC, Clang</td>
327<td class="excinterop"><b style="color: #c06000;">Limited</b></td> 385<td class="excinterop"><b style="color: #c06000;">Limited</b></td>
328</tr> 386</tr>
329<tr class="odd"> 387<tr class="even">
330<td class="excplatform">Windows/x64</td> 388<td class="excplatform">Windows/x64</td>
331<td class="exccompiler">MSVC or WinSDK</td> 389<td class="exccompiler">MSVC or WinSDK</td>
332<td class="excinterop"><b style="color: #00a000;">Full</b></td> 390<td class="excinterop"><b style="color: #00a000;">Full</b></td>
333</tr> 391</tr>
334<tr class="even"> 392<tr class="odd">
335<td class="excplatform">Windows/x86</td> 393<td class="excplatform">Windows/x86</td>
336<td class="exccompiler">Any</td> 394<td class="exccompiler">Any</td>
337<td class="excinterop"><b style="color: #a00000;">No</b></td> 395<td class="excinterop"><b style="color: #00a000;">Full</b></td>
338</tr> 396</tr>
339<tr class="odd"> 397<tr class="even">
340<td class="excplatform">Other platforms</td> 398<td class="excplatform">Other platforms</td>
341<td class="exccompiler">Other compilers</td> 399<td class="exccompiler">Other compilers</td>
342<td class="excinterop"><b style="color: #a00000;">No</b></td> 400<td class="excinterop"><b style="color: #a00000;">No</b></td>
@@ -385,14 +443,6 @@ C++ destructors.</li>
385<li>Lua errors <b>cannot</b> be caught on the C++ side.</li> 443<li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
386<li>Throwing Lua errors across C++ frames will <b>not</b> call 444<li>Throwing Lua errors across C++ frames will <b>not</b> call
387C++ destructors.</li> 445C++ destructors.</li>
388<li>Additionally, on Windows/x86 with SEH-based C++&nbsp;exceptions:
389it's <b>not</b> safe to throw a Lua error across any frames containing
390a C++ function with any try/catch construct or using variables with
391(implicit) destructors. This also applies to any functions which may be
392inlined in such a function. It doesn't matter whether <tt>lua_error()</tt>
393is called inside or outside of a try/catch or whether any object actually
394needs to be destroyed: the SEH chain is corrupted and this will eventually
395lead to the termination of the process.</li>
396</ul> 446</ul>
397<br class="flush"> 447<br class="flush">
398</div> 448</div>
diff --git a/doc/faq.html b/doc/faq.html
index afeff940..2c930743 100644
--- a/doc/faq.html
+++ b/doc/faq.html
@@ -44,6 +44,8 @@ dd { margin-left: 1.5em; }
44<a href="ext_jit.html">jit.* Library</a> 44<a href="ext_jit.html">jit.* Library</a>
45</li><li> 45</li><li>
46<a href="ext_c_api.html">Lua/C API</a> 46<a href="ext_c_api.html">Lua/C API</a>
47</li><li>
48<a href="ext_profiler.html">Profiler</a>
47</li></ul> 49</li></ul>
48</li><li> 50</li><li>
49<a href="status.html">Status</a> 51<a href="status.html">Status</a>
diff --git a/doc/install.html b/doc/install.html
index f7a560f3..851f910a 100644
--- a/doc/install.html
+++ b/doc/install.html
@@ -69,6 +69,8 @@ td.compatno {
69<a href="ext_jit.html">jit.* Library</a> 69<a href="ext_jit.html">jit.* Library</a>
70</li><li> 70</li><li>
71<a href="ext_c_api.html">Lua/C API</a> 71<a href="ext_c_api.html">Lua/C API</a>
72</li><li>
73<a href="ext_profiler.html">Profiler</a>
72</li></ul> 74</li></ul>
73</li><li> 75</li><li>
74<a href="status.html">Status</a> 76<a href="status.html">Status</a>
@@ -112,17 +114,17 @@ operating systems, CPUs and compilers:
112</tr> 114</tr>
113<tr class="odd separate"> 115<tr class="odd separate">
114<td class="compatcpu">x86 (32 bit)</td> 116<td class="compatcpu">x86 (32 bit)</td>
115<td class="compatos">GCC 4.x+<br>GCC 3.4</td> 117<td class="compatos">GCC 4.2+</td>
116<td class="compatos">GCC 4.x+<br>GCC 3.4</td> 118<td class="compatos">GCC 4.2+</td>
117<td class="compatos">XCode 5.0+<br>Clang</td> 119<td class="compatos">XCode 5.0+<br>Clang</td>
118<td class="compatos">MSVC, MSVC/EE<br>WinSDK<br>MinGW, Cygwin</td> 120<td class="compatos">MSVC, MSVC/EE<br>WinSDK<br>MinGW, Cygwin</td>
119</tr> 121</tr>
120<tr class="even"> 122<tr class="even">
121<td class="compatcpu">x64 (64 bit)</td> 123<td class="compatcpu">x64 (64 bit)</td>
122<td class="compatos">GCC 4.x+</td> 124<td class="compatos">GCC 4.2+</td>
123<td class="compatos">ORBIS (<a href="#ps4">PS4</a>)</td> 125<td class="compatos">GCC 4.2+<br>ORBIS (<a href="#ps4">PS4</a>)</td>
124<td class="compatos">XCode 5.0+<br>Clang</td> 126<td class="compatos">XCode 5.0+<br>Clang</td>
125<td class="compatos">MSVC + SDK v7.0<br>WinSDK v7.0</td> 127<td class="compatos">MSVC + SDK v7.0<br>WinSDK v7.0<br>Durango (<a href="#xboxone">Xbox One</a>)</td>
126</tr> 128</tr>
127<tr class="odd"> 129<tr class="odd">
128<td class="compatcpu"><a href="#cross2">ARMv5+<br>ARM9E+</a></td> 130<td class="compatcpu"><a href="#cross2">ARMv5+<br>ARM9E+</a></td>
@@ -132,21 +134,21 @@ operating systems, CPUs and compilers:
132<td class="compatos compatno">&nbsp;</td> 134<td class="compatos compatno">&nbsp;</td>
133</tr> 135</tr>
134<tr class="even"> 136<tr class="even">
135<td class="compatcpu"><a href="#cross2">PPC</a></td> 137<td class="compatcpu"><a href="#cross2">ARM64</a></td>
136<td class="compatos">GCC 4.3+</td> 138<td class="compatos">GCC 4.8+</td>
137<td class="compatos">GCC 4.3+<br>GCC 4.1 (<a href="#ps3">PS3</a>)</td> 139<td class="compatos compatno">&nbsp;</td>
140<td class="compatos">XCode 6.0+<br>Clang 3.5+</td>
138<td class="compatos compatno">&nbsp;</td> 141<td class="compatos compatno">&nbsp;</td>
139<td class="compatos">XEDK (<a href="#xbox360">Xbox 360</a>)</td>
140</tr> 142</tr>
141<tr class="odd"> 143<tr class="odd">
142<td class="compatcpu"><a href="#cross2">PPC/e500v2</a></td> 144<td class="compatcpu"><a href="#cross2">PPC</a></td>
143<td class="compatos">GCC 4.3+</td>
144<td class="compatos">GCC 4.3+</td> 145<td class="compatos">GCC 4.3+</td>
146<td class="compatos">GCC 4.3+<br>GCC 4.1 (<a href="#ps3">PS3</a>)</td>
145<td class="compatos compatno">&nbsp;</td> 147<td class="compatos compatno">&nbsp;</td>
146<td class="compatos compatno">&nbsp;</td> 148<td class="compatos">XEDK (<a href="#xbox360">Xbox 360</a>)</td>
147</tr> 149</tr>
148<tr class="even"> 150<tr class="even">
149<td class="compatcpu"><a href="#cross2">MIPS</a></td> 151<td class="compatcpu"><a href="#cross2">MIPS32<br>MIPS64</a></td>
150<td class="compatos">GCC 4.3+</td> 152<td class="compatos">GCC 4.3+</td>
151<td class="compatos">GCC 4.3+</td> 153<td class="compatos">GCC 4.3+</td>
152<td class="compatos compatno">&nbsp;</td> 154<td class="compatos compatno">&nbsp;</td>
@@ -173,6 +175,14 @@ MSVC or WinSDK.</li>
173Please read the instructions given in these files, before changing 175Please read the instructions given in these files, before changing
174any settings. 176any settings.
175</p> 177</p>
178<p>
179LuaJIT on x64 currently uses 32 bit GC objects by default.
180<tt>LJ_GC64</tt> mode may be explicitly enabled:
181add <tt>XCFLAGS=-DLUAJIT_ENABLE_GC64</tt> to the make command or run
182<tt>msvcbuild gc64</tt> for MSVC/WinSDK. Please check the note
183about the <a href="extensions.html#string_dump">bytecode format</a>
184differences, too.
185</p>
176 186
177<h2 id="posix">POSIX Systems (Linux, OSX, *BSD etc.)</h2> 187<h2 id="posix">POSIX Systems (Linux, OSX, *BSD etc.)</h2>
178<h3>Prerequisites</h3> 188<h3>Prerequisites</h3>
@@ -200,7 +210,7 @@ which is probably the default on your system, anyway. Simply run:
200make 210make
201</pre> 211</pre>
202<p> 212<p>
203This always builds a native x86, x64 or PPC binary, depending on the host OS 213This always builds a native binary, depending on the host OS
204you're running this command on. Check the section on 214you're running this command on. Check the section on
205<a href="#cross">cross-compilation</a> for more options. 215<a href="#cross">cross-compilation</a> for more options.
206</p> 216</p>
@@ -331,25 +341,36 @@ directory where <tt>luajit.exe</tt> is installed
331 341
332<h2 id="cross">Cross-compiling LuaJIT</h2> 342<h2 id="cross">Cross-compiling LuaJIT</h2>
333<p> 343<p>
344First, let's clear up some terminology:
345</p>
346<ul>
347<li>Host: This is your development system, usually based on a x64 or x86 CPU.</li>
348<li>Target: This is the target system you want LuaJIT to run on, e.g. Android/ARM.</li>
349<li>Toolchain: This comprises a C compiler, linker, assembler and a matching C library.</li>
350<li>Host (or system) toolchain: This is the toolchain used to build native binaries for your host system.</li>
351<li>Cross-compile toolchain: This is the toolchain used to build binaries for the target system. They can only be run on the target system.</li>
352</ul>
353<p>
334The GNU Makefile-based build system allows cross-compiling on any host 354The GNU Makefile-based build system allows cross-compiling on any host
335for any supported target, as long as both architectures have the same 355for any supported target:
336pointer size. If you want to cross-compile to any 32 bit target on an
337x64 OS, you need to install the multilib development package (e.g.
338<tt>libc6-dev-i386</tt> on Debian/Ubuntu) and build a 32 bit host part
339(<tt>HOST_CC="gcc -m32"</tt>).
340</p> 356</p>
357<ul>
358<li>Yes, you need a toolchain for both your host <em>and</em> your target!</li>
359<li>Both host and target architectures must have the same pointer size.</li>
360<li>E.g. if you want to cross-compile to a 32 bit target on a 64 bit host, you need to install the multilib development package (e.g. <tt>libc6-dev-i386</tt> on Debian/Ubuntu) and build a 32 bit host part (<tt>HOST_CC="gcc -m32"</tt>).</li>
361<li>64 bit targets always require compilation on a 64 bit host.</li>
362</ul>
341<p> 363<p>
342You need to specify <tt>TARGET_SYS</tt> whenever the host OS and the 364You need to specify <tt>TARGET_SYS</tt> whenever the host OS and the
343target OS differ, or you'll get assembler or linker errors. E.g. if 365target OS differ, or you'll get assembler or linker errors:
344you're compiling on a Windows or OSX host for embedded Linux or Android,
345you need to add <tt>TARGET_SYS=Linux</tt> to the examples below. For a
346minimal target OS, you may need to disable the built-in allocator in
347<tt>src/Makefile</tt> and use <tt>TARGET_SYS=Other</tt>. Don't forget to
348specify the same <tt>TARGET_SYS</tt> for the install step, too.
349</p> 366</p>
367<ul>
368<li>E.g. if you're compiling on a Windows or OSX host for embedded Linux or Android, you need to add <tt>TARGET_SYS=Linux</tt> to the examples below.</li>
369<li>For a minimal target OS, you may need to disable the built-in allocator in <tt>src/Makefile</tt> and use <tt>TARGET_SYS=Other</tt>.</li>
370<li>Don't forget to specify the same <tt>TARGET_SYS</tt> for the install step, too.</li>
371</ul>
350<p> 372<p>
351The examples below only show some popular targets &mdash; please check 373Here are some examples where host and target have the same CPU:
352the comments in <tt>src/Makefile</tt> for more details.
353</p> 374</p>
354<pre class="code"> 375<pre class="code">
355# Cross-compile to a 32 bit binary on a multilib x64 OS 376# Cross-compile to a 32 bit binary on a multilib x64 OS
@@ -367,37 +388,47 @@ use the canonical toolchain triplets for Linux.
367</p> 388</p>
368<p> 389<p>
369Since there's often no easy way to detect CPU features at runtime, it's 390Since there's often no easy way to detect CPU features at runtime, it's
370important to compile with the proper CPU or architecture settings. You 391important to compile with the proper CPU or architecture settings:
371can specify these when building the toolchain yourself. Or add 392</o>
372<tt>-mcpu=...</tt> or <tt>-march=...</tt> to <tt>TARGET_CFLAGS</tt>. For 393<ul>
373ARM it's important to have the correct <tt>-mfloat-abi=...</tt> setting, 394<li>The best way to get consistent results is to specify the correct settings when building the toolchain yourself.</li>
374too. Otherwise LuaJIT may not run at the full performance of your target 395<li>For a pre-built, generic toolchain add <tt>-mcpu=...</tt> or <tt>-march=...</tt> and other necessary flags to <tt>TARGET_CFLAGS</tt>.</li>
375CPU. 396<li>For ARM it's important to have the correct <tt>-mfloat-abi=...</tt> setting, too. Otherwise LuaJIT may not run at the full performance of your target CPU.</li>
397<li>For MIPS it's important to select a supported ABI (o32 on MIPS32, n64 on MIPS64) and consistently compile your project either with hard-float or soft-float compiler settings.</li>
398</ul>
399<p>
400Here are some examples for targets with a different CPU than the host:
376</p> 401</p>
377<pre class="code"> 402<pre class="code">
378# ARM soft-float 403# ARM soft-float
379make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ 404make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \
380 TARGET_CFLAGS="-mfloat-abi=soft" 405 TARGET_CFLAGS="-mfloat-abi=soft"
381 406
382# ARM soft-float ABI with VFP (example for Cortex-A8) 407# ARM soft-float ABI with VFP (example for Cortex-A9)
383make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ 408make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \
384 TARGET_CFLAGS="-mcpu=cortex-a8 -mfloat-abi=softfp" 409 TARGET_CFLAGS="-mcpu=cortex-a9 -mfloat-abi=softfp"
385 410
386# ARM hard-float ABI with VFP (armhf, requires recent toolchain) 411# ARM hard-float ABI with VFP (armhf, most modern toolchains)
387make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabihf- 412make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabihf-
388 413
414# ARM64
415make CROSS=aarch64-linux-
416
389# PPC 417# PPC
390make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu- 418make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu-
391# PPC/e500v2 (fast interpreter only)
392make HOST_CC="gcc -m32" CROSS=powerpc-e500v2-linux-gnuspe-
393 419
394# MIPS big-endian 420# MIPS32 big-endian
395make HOST_CC="gcc -m32" CROSS=mips-linux- 421make HOST_CC="gcc -m32" CROSS=mips-linux-
396# MIPS little-endian 422# MIPS32 little-endian
397make HOST_CC="gcc -m32" CROSS=mipsel-linux- 423make HOST_CC="gcc -m32" CROSS=mipsel-linux-
424
425# MIPS64 big-endian
426make CROSS=mips-linux- TARGET_CFLAGS="-mips64r2 -mabi=64"
427# MIPS64 little-endian
428make CROSS=mipsel-linux- TARGET_CFLAGS="-mips64r2 -mabi=64"
398</pre> 429</pre>
399<p> 430<p>
400You can cross-compile for <b id="android">Android</b> using the <a href="http://developer.android.com/sdk/ndk/index.html"><span class="ext">&raquo;</span>&nbsp;Android NDK</a>. 431You can cross-compile for <b id="android">Android</b> using the <a href="https://developer.android.com/ndk/index.html">Android NDK</a>.
401The environment variables need to match the install locations and the 432The environment variables need to match the install locations and the
402desired target platform. E.g. Android&nbsp;4.0 corresponds to ABI level&nbsp;14. 433desired target platform. E.g. Android&nbsp;4.0 corresponds to ABI level&nbsp;14.
403For details check the folder <tt>docs</tt> in the NDK directory. 434For details check the folder <tt>docs</tt> in the NDK directory.
@@ -411,7 +442,7 @@ to build/deploy or which lowest common denominator you want to pick:
411# Android/ARM, armeabi (ARMv5TE soft-float), Android 2.2+ (Froyo) 442# Android/ARM, armeabi (ARMv5TE soft-float), Android 2.2+ (Froyo)
412NDK=/opt/android/ndk 443NDK=/opt/android/ndk
413NDKABI=8 444NDKABI=8
414NDKVER=$NDK/toolchains/arm-linux-androideabi-4.6 445NDKVER=$NDK/toolchains/arm-linux-androideabi-4.9
415NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi- 446NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi-
416NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm" 447NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm"
417make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF" 448make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF"
@@ -419,16 +450,16 @@ make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF"
419# Android/ARM, armeabi-v7a (ARMv7 VFP), Android 4.0+ (ICS) 450# Android/ARM, armeabi-v7a (ARMv7 VFP), Android 4.0+ (ICS)
420NDK=/opt/android/ndk 451NDK=/opt/android/ndk
421NDKABI=14 452NDKABI=14
422NDKVER=$NDK/toolchains/arm-linux-androideabi-4.6 453NDKVER=$NDK/toolchains/arm-linux-androideabi-4.9
423NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi- 454NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi-
424NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm" 455NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm"
425NDKARCH="-march=armv7-a -mfloat-abi=softfp -Wl,--fix-cortex-a8" 456NDKARCH="-march=armv7-a -mfloat-abi=softfp -Wl,--fix-cortex-a8"
426make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF $NDKARCH" 457make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF $NDKARCH"
427 458
428# Android/MIPS, mips (MIPS32R1 hard-float), Android 4.0+ (ICS) 459# Android/MIPS, mipsel (MIPS32R1 hard-float), Android 4.0+ (ICS)
429NDK=/opt/android/ndk 460NDK=/opt/android/ndk
430NDKABI=14 461NDKABI=14
431NDKVER=$NDK/toolchains/mipsel-linux-android-4.6 462NDKVER=$NDK/toolchains/mipsel-linux-android-4.9
432NDKP=$NDKVER/prebuilt/linux-x86/bin/mipsel-linux-android- 463NDKP=$NDKVER/prebuilt/linux-x86/bin/mipsel-linux-android-
433NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-mips" 464NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-mips"
434make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF" 465make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF"
@@ -436,7 +467,7 @@ make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF"
436# Android/x86, x86 (i686 SSE3), Android 4.0+ (ICS) 467# Android/x86, x86 (i686 SSE3), Android 4.0+ (ICS)
437NDK=/opt/android/ndk 468NDK=/opt/android/ndk
438NDKABI=14 469NDKABI=14
439NDKVER=$NDK/toolchains/x86-4.6 470NDKVER=$NDK/toolchains/x86-4.9
440NDKP=$NDKVER/prebuilt/linux-x86/bin/i686-linux-android- 471NDKP=$NDKVER/prebuilt/linux-x86/bin/i686-linux-android-
441NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-x86" 472NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-x86"
442make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF" 473make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF"
@@ -452,11 +483,19 @@ much slower than the JIT compiler. Please complain to Apple, not me.
452Or use Android. :-p 483Or use Android. :-p
453</p> 484</p>
454<pre class="code"> 485<pre class="code">
486# iOS/ARM (32 bit)
455ISDKP=$(xcrun --sdk iphoneos --show-sdk-path) 487ISDKP=$(xcrun --sdk iphoneos --show-sdk-path)
456ICC=$(xcrun --sdk iphoneos --find clang) 488ICC=$(xcrun --sdk iphoneos --find clang)
457ISDKF="-arch armv7 -isysroot $ISDKP" 489ISDKF="-arch armv7 -isysroot $ISDKP"
458make DEFAULT_CC=clang HOST_CC="clang -m32 -arch i386" \ 490make DEFAULT_CC=clang HOST_CC="clang -m32 -arch i386" \
459 CROSS="$(dirname $ICC)/" TARGET_FLAGS="$ISDKF" TARGET_SYS=iOS 491 CROSS="$(dirname $ICC)/" TARGET_FLAGS="$ISDKF" TARGET_SYS=iOS
492
493# iOS/ARM64
494ISDKP=$(xcrun --sdk iphoneos --show-sdk-path)
495ICC=$(xcrun --sdk iphoneos --find clang)
496ISDKF="-arch arm64 -isysroot $ISDKP"
497make DEFAULT_CC=clang CROSS="$(dirname $ICC)/" \
498 TARGET_FLAGS="$ISDKF" TARGET_SYS=iOS
460</pre> 499</pre>
461 500
462<h3 id="consoles">Cross-compiling for consoles</h3> 501<h3 id="consoles">Cross-compiling for consoles</h3>
@@ -513,6 +552,16 @@ the following commands:
513cd src 552cd src
514xedkbuild 553xedkbuild
515</pre> 554</pre>
555<p>
556To cross-compile for <b id="xboxone">Xbox One</b> from a Windows host,
557open a "Visual Studio .NET Command Prompt" (64&nbsp;bit host compiler),
558<tt>cd</tt> to the directory where you've unpacked the sources and run
559the following commands:
560</p>
561<pre class="code">
562cd src
563xb1build
564</pre>
516 565
517<h2 id="embed">Embedding LuaJIT</h2> 566<h2 id="embed">Embedding LuaJIT</h2>
518<p> 567<p>
@@ -543,14 +592,11 @@ intend to load Lua/C modules at runtime.
543</li> 592</li>
544<li> 593<li>
545If you're building a 64 bit application on OSX which links directly or 594If you're building a 64 bit application on OSX which links directly or
546indirectly against LuaJIT, you need to link your main executable 595indirectly against LuaJIT which is not built for <tt>LJ_GC64</tt> mode,
547with these flags: 596you need to link your main executable with these flags:
548<pre class="code"> 597<pre class="code">
549-pagezero_size 10000 -image_base 100000000 598-pagezero_size 10000 -image_base 100000000
550</pre> 599</pre>
551Also, it's recommended to <tt>rebase</tt> all (self-compiled) shared libraries
552which are loaded at runtime on OSX/x64 (e.g. C extension modules for Lua).
553See: <tt>man rebase</tt>
554</li> 600</li>
555</ul> 601</ul>
556<p>Additional hints for initializing LuaJIT using the C API functions:</p> 602<p>Additional hints for initializing LuaJIT using the C API functions:</p>
diff --git a/doc/luajit.html b/doc/luajit.html
index 00030081..ef5b824c 100644
--- a/doc/luajit.html
+++ b/doc/luajit.html
@@ -126,6 +126,8 @@ table.feature small {
126<a href="ext_jit.html">jit.* Library</a> 126<a href="ext_jit.html">jit.* Library</a>
127</li><li> 127</li><li>
128<a href="ext_c_api.html">Lua/C API</a> 128<a href="ext_c_api.html">Lua/C API</a>
129</li><li>
130<a href="ext_profiler.html">Profiler</a>
129</li></ul> 131</li></ul>
130</li><li> 132</li><li>
131<a href="status.html">Status</a> 133<a href="status.html">Status</a>
@@ -164,13 +166,13 @@ LuaJIT is Copyright &copy; 2005-2017 Mike Pall, released under the
164<tr><td><span style="font-size:90%;">Embedded</span></td><td>Android</td><td>iOS</td></tr> 166<tr><td><span style="font-size:90%;">Embedded</span></td><td>Android</td><td>iOS</td></tr>
165</table> 167</table>
166<table class="feature os os3"> 168<table class="feature os os3">
167<tr><td>PS3</td><td>PS4</td><td>PS Vita</td><td>Xbox 360</td></tr> 169<tr><td>PS3</td><td>PS4</td><td>PS Vita</td><td>Xbox 360</td><td>Xbox One</td></tr>
168</table> 170</table>
169<table class="feature compiler"> 171<table class="feature compiler">
170<tr><td>GCC</td><td>CLANG<br>LLVM</td><td>MSVC</td></tr> 172<tr><td>GCC</td><td>Clang<br>LLVM</td><td>MSVC</td></tr>
171</table> 173</table>
172<table class="feature cpu"> 174<table class="feature cpu">
173<tr><td>x86</td><td>x64</td><td>ARM</td><td>PPC</td><td>e500</td><td>MIPS</td></tr> 175<tr><td>x86<br>x64</td><td>ARM<br>ARM64</td><td>PPC</td><td>MIPS32<br>MIPS64</td></tr>
174</table> 176</table>
175<table class="feature fcompat"> 177<table class="feature fcompat">
176<tr><td>Lua&nbsp;5.1<br>API+ABI</td><td>+&nbsp;JIT</td><td>+&nbsp;BitOp</td><td>+&nbsp;FFI</td><td>Drop-in<br>DLL/.so</td></tr> 178<tr><td>Lua&nbsp;5.1<br>API+ABI</td><td>+&nbsp;JIT</td><td>+&nbsp;BitOp</td><td>+&nbsp;FFI</td><td>Drop-in<br>DLL/.so</td></tr>
diff --git a/doc/running.html b/doc/running.html
index 1232b84f..64f04916 100644
--- a/doc/running.html
+++ b/doc/running.html
@@ -63,6 +63,8 @@ td.param_default {
63<a href="ext_jit.html">jit.* Library</a> 63<a href="ext_jit.html">jit.* Library</a>
64</li><li> 64</li><li>
65<a href="ext_c_api.html">Lua/C API</a> 65<a href="ext_c_api.html">Lua/C API</a>
66</li><li>
67<a href="ext_profiler.html">Profiler</a>
66</li></ul> 68</li></ul>
67</li><li> 69</li><li>
68<a href="status.html">Status</a> 70<a href="status.html">Status</a>
@@ -178,6 +180,7 @@ Here are the available LuaJIT control commands:
178<li id="j_flush"><tt>-jflush</tt> &mdash; Flushes the whole cache of compiled code.</li> 180<li id="j_flush"><tt>-jflush</tt> &mdash; Flushes the whole cache of compiled code.</li>
179<li id="j_v"><tt>-jv</tt> &mdash; Shows verbose information about the progress of the JIT compiler.</li> 181<li id="j_v"><tt>-jv</tt> &mdash; Shows verbose information about the progress of the JIT compiler.</li>
180<li id="j_dump"><tt>-jdump</tt> &mdash; Dumps the code and structures used in various compiler stages.</li> 182<li id="j_dump"><tt>-jdump</tt> &mdash; Dumps the code and structures used in various compiler stages.</li>
183<li id="j_p"><tt>-jp</tt> &mdash; Start the <a href="ext_profiler.html">integrated profiler</a>.</li>
181</ul> 184</ul>
182<p> 185<p>
183The <tt>-jv</tt> and <tt>-jdump</tt> commands are extension modules 186The <tt>-jv</tt> and <tt>-jdump</tt> commands are extension modules
diff --git a/doc/status.html b/doc/status.html
index aa8df93e..cad6ca65 100644
--- a/doc/status.html
+++ b/doc/status.html
@@ -44,6 +44,8 @@ ul li { padding-bottom: 0.3em; }
44<a href="ext_jit.html">jit.* Library</a> 44<a href="ext_jit.html">jit.* Library</a>
45</li><li> 45</li><li>
46<a href="ext_c_api.html">Lua/C API</a> 46<a href="ext_c_api.html">Lua/C API</a>
47</li><li>
48<a href="ext_profiler.html">Profiler</a>
47</li></ul> 49</li></ul>
48</li><li> 50</li><li>
49<a class="current" href="status.html">Status</a> 51<a class="current" href="status.html">Status</a>
@@ -95,6 +97,17 @@ handled correctly. The error may fall through an on-trace
95<tt>lua_atpanic</tt> on x64. This issue will be fixed with the new 97<tt>lua_atpanic</tt> on x64. This issue will be fixed with the new
96garbage collector. 98garbage collector.
97</li> 99</li>
100<li>
101LuaJIT on 64 bit systems provides a <b>limited range</b> of 47 bits for the
102<b>legacy <tt>lightuserdata</tt></b> data type.
103This is only relevant on x64 systems which use the negative part of the
104virtual address space in user mode, e.g. Solaris/x64, and on ARM64 systems
105configured with a 48 bit or 52 bit VA.
106Avoid using <tt>lightuserdata</tt> to hold pointers that may point outside
107of that range, e.g. variables on the stack. In general, avoid this data
108type for new code and replace it with (much more performant) FFI bindings.
109FFI cdata pointers can address the full 64 bit range.
110</li>
98</ul> 111</ul>
99<br class="flush"> 112<br class="flush">
100</div> 113</div>