aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/LuaJIT-1.1.7/jitdoc/coco_portability.html
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/LuaJIT-1.1.7/jitdoc/coco_portability.html')
-rw-r--r--libraries/LuaJIT-1.1.7/jitdoc/coco_portability.html235
1 files changed, 235 insertions, 0 deletions
diff --git a/libraries/LuaJIT-1.1.7/jitdoc/coco_portability.html b/libraries/LuaJIT-1.1.7/jitdoc/coco_portability.html
new file mode 100644
index 0000000..e120ae9
--- /dev/null
+++ b/libraries/LuaJIT-1.1.7/jitdoc/coco_portability.html
@@ -0,0 +1,235 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>Portability Requirements for Coco</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-2011, 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<style type="text/css">
12table.support {
13 line-height: 1.2;
14 width: 25em;
15}
16tr.supporthead td {
17 font-weight: bold;
18}
19td.supportcpu {
20 width: 6em;
21}
22td.supportsys {
23 width: 8em;
24}
25</style>
26</head>
27<body>
28<div id="site">
29<a href="http://luajit.org/"><span>Lua<span id="logo">JIT</span></span></a>
30</div>
31<div id="head">
32<h1>Portability Requirements for Coco</h1>
33</div>
34<div id="nav">
35<ul><li>
36<a href="index.html">Index</a>
37</li><li>
38<a href="luajit.html">LuaJIT</a>
39<ul><li>
40<a href="luajit_features.html">Features</a>
41</li><li>
42<a href="luajit_install.html">Installation</a>
43</li><li>
44<a href="luajit_run.html">Running</a>
45</li><li>
46<a href="luajit_api.html">API Extensions</a>
47</li><li>
48<a href="luajit_intro.html">Introduction</a>
49</li><li>
50<a href="luajit_performance.html">Performance</a>
51</li><li>
52<a href="luajit_debug.html">Debugging</a>
53</li><li>
54<a href="luajit_changes.html">Changes</a>
55</li></ul>
56</li><li>
57<a href="coco.html">Coco</a>
58<ul><li>
59<a class="current" href="coco_portability.html">Portability</a>
60</li><li>
61<a href="coco_api.html">API Extensions</a>
62</li><li>
63<a href="coco_changes.html">Changes</a>
64</li></ul>
65</li><li>
66<a href="dynasm.html">DynASM</a>
67<ul><li>
68<a href="dynasm_features.html">Features</a>
69</li><li>
70<a href="dynasm_examples.html">Examples</a>
71</li></ul>
72</li><li>
73<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
74</li></ul>
75</div>
76<div id="main">
77<p>
78Coco needs some machine-specific features which are
79inherently non-portable. Although the coverage is pretty good,
80this means that Coco will probably never be a standard part
81of the Lua core (which is pure ANSI&nbsp;C).
82</p>
83
84<h2>Context Switching Methods</h2>
85<p>
86Coco relies on four different machine-specific methods
87for allocating a C&nbsp;stack and switching context.
88The appropriate method is automatically selected at compile time.
89</p>
90
91<h3>GCC Inline Assembler</h3>
92<p>
93This method is only available when GCC 3.x/4.x is used
94to compile the source.
95This is the fastest method for context switching, but only available
96for a few CPUs (see below).
97</p>
98
99<h3>Modified setjmp Buffer</h3>
100<p>
101This method changes a few fields in the setjmp buffer to
102redirect the next longjmp to a new function with a new stack
103frame. It needs a bit of guesswork and lots of #ifdef's to
104handle the supported CPU/OS combinations, but this is quite
105manageable.
106</p>
107<p>
108This is the fallback method if inline assembler is not available.
109It's pretty fast because it doesn't have to save or restore signals
110(which is slow and generally undesirable for Lua coroutines).
111</p>
112
113<h3>POSIX ucontext</h3>
114<p>
115The POSIX calls getcontext, makecontext and switchcontext
116are used to set up and switch between different C&nbsp;stacks.
117Although highly portable and even available for some
118esoteric platforms, it's slower than the setjmp method
119because it saves and restores signals, too (using at least one
120syscall for each context switch).
121</p>
122<p>
123You can force the use of ucontext (instead of setjmp) by enabling
124<tt>-DCOCO_USE_UCONTEXT</tt> in <tt>src/Makefile</tt>.
125</p>
126
127<h3>Windows Fibers</h3>
128<p>
129This is the standard method to set up and switch between
130different C&nbsp;stacks on Windows. It's available on Windows&nbsp;98
131and later.
132</p>
133<p>
134None of the other methods work for Windows because OS specific code
135is required to switch exception handling contexts.
136</p>
137
138<h2 class="pagebreak">Supported Platforms</h2>
139<p>
140Coco has support for the following platforms:
141</p>
142<table class="support">
143<tr class="supporthead">
144<td class="supportcpu">CPU</td>
145<td class="supportsys">System</td>
146<td>Method</td>
147</tr>
148<tr class="odd separate">
149<td class="supportcpu">x86</td><td class="supportsys">(any OS)</td><td>gccasm</td></tr>
150<tr class="even">
151<td class="supportcpu">x86</td><td class="supportsys">Linux</td><td>setjmp</td></tr>
152<tr class="odd">
153<td class="supportcpu">x86</td><td class="supportsys">FreeBSD</td><td>setjmp</td></tr>
154<tr class="even">
155<td class="supportcpu">x86</td><td class="supportsys">NetBSD</td><td>setjmp</td></tr>
156<tr class="odd">
157<td class="supportcpu">x86</td><td class="supportsys">OpenBSD</td><td>setjmp</td></tr>
158<tr class="even">
159<td class="supportcpu">x86</td><td class="supportsys">Solaris</td><td>setjmp</td></tr>
160<tr class="odd">
161<td class="supportcpu">x86</td><td class="supportsys">Mac OS X</td><td>setjmp</td></tr>
162<tr class="even separate">
163<td class="supportcpu">x64</td><td class="supportsys">(any OS)</td><td>gccasm</td></tr>
164<tr class="odd">
165<td class="supportcpu">x64</td><td class="supportsys">Solaris</td><td>setjmp</td></tr>
166<tr class="even separate">
167<td class="supportcpu">MIPS32</td><td class="supportsys">(any OS)</td><td>gccasm</td></tr>
168<tr class="odd">
169<td class="supportcpu">MIPS32</td><td class="supportsys">Linux</td><td>setjmp</td></tr>
170<tr class="even separate">
171<td class="supportcpu">ARM</td><td class="supportsys">Linux</td><td>setjmp</td></tr>
172<tr class="odd separate">
173<td class="supportcpu">PPC32</td><td class="supportsys">Mac OS X</td><td>setjmp</td></tr>
174<tr class="even separate">
175<td class="supportcpu">(any CPU)</td><td class="supportsys">POSIX</td><td>ucontext</td></tr>
176<tr class="odd separate">
177<td class="supportcpu">(any CPU)</td><td class="supportsys">Windows</td><td>fibers</td></tr>
178</table>
179<pre>
180</pre>
181<p>
182It should work pretty much anywhere where a <em>correct</em>
183POSIX ucontext implementation is available. It has been tested
184on every systems I could get hold of (e.g. Sparc, PPC32/PPC64,
185IA64, Alpha, HPPA with various operating systems).
186</p>
187
188<h2>Caveats</h2>
189<ul>
190<li>
191Some older operating systems may have defective ucontext
192implementations because this feature is not widely used. E.g. some
193implementations don't mix well with other C&nbsp;library functions
194like <tt>malloc()</tt> or with native threads.
195This is really not the fault of Coco &mdash; please upgrade your OS.
196</li>
197<li>
198Note for Windows: Please read the explanation for the default
199<a href="http://msdn.microsoft.com/library/en-us/dllproc/base/thread_stack_size.asp"><span class="ext">&raquo;</span>&nbsp;Thread Stack Size</a>
200in case you want to create large numbers of Fiber-based coroutines.
201</li>
202<li>
203Note for MinGW/Cygwin: Older releases of GCC (before 4.0) generate
204wrong unwind information when <tt>-fomit-frame-pointer</tt> is used
205with stdcalls. This may lead to crashes when exceptions are thrown.
206The workaround is to always use two flags:<br>
207<tt>-fomit-frame-pointer -maccumulate-outgoing-args</tt>.
208</li>
209<li>
210Note for MIPS CPUs without FPU: It's recommended to compile
211<em>all</em> sources with <tt>-msoft-float</tt>, even if you don't use
212any floating point ops anywhere. Otherwise context switching must
213save and restore FPU registers (which needs to go through
214the slow kernel emulation).
215</li>
216<li>
217To run Coco with <a href="http://valgrind.org/"><span class="ext">&raquo;</span>&nbsp;Valgrind</a>
218(a memory debugger) you <em>must</em> add <tt>-DUSE_VALGRIND</tt>
219to <tt>MYCFLAGS</tt> and recompile. You will get random errors
220if you don't! Valgrind 3.x or later is required. Earlier versions
221do not work well with newly allocated C stacks.
222</li>
223</ul>
224<br class="flush">
225</div>
226<div id="foot">
227<hr class="hide">
228Copyright &copy; 2005-2011 Mike Pall
229<span class="noprint">
230&middot;
231<a href="contact.html">Contact</a>
232</span>
233</div>
234</body>
235</html>
generated by cgit v1.1 at 2024-12-26 15:34:25 +0000