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