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