• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..03-May-2022-

examples/H03-May-2022-301252

src/H03-May-2022-1,9971,371

tests/H03-May-2022-3732

.cargo-checksum.jsonH A D03-May-202289 11

.cargo_vcs_info.jsonH A D06-May-202074 65

.gitignoreH A D06-Oct-201950 75

Cargo.lockH A D06-May-2020347 1513

Cargo.tomlH A D06-May-2020962 2825

Cargo.toml.orig-cargoH A D06-May-2020430 1714

LICENSE-APACHEH A D06-May-202010.5 KiB202169

LICENSE-MITH A D06-May-20201 KiB1713

README.mkdH A D06-May-20209.3 KiB496416

build.rsH A D06-May-20203.2 KiB7155

README.mkd

1# Portable Stack Manipulation
2
3This crate provides very portable functions to control the stack pointer and inspect the properties
4of the stack. This crate does not attempt to provide safe abstractions to any operations, the
5only goals are correctness, portability and efficiency (in that exact order). As a consequence most
6functions you’ll see in this crate are unsafe.
7
8Unless you’re writing a safe abstraction over stack manipulation, this is not the crate you
9want. Instead consider one of the safe abstractions over this crate. A good place to look at is
10the crates.io’s reverse dependency list.
11
12# Platform support
13
14The following table lists supported targets and architectures with notes on the level of current
15support and knowledge about the target. The three columns “Available”, “Tested” and “Callstack”
16imply an increasingly high level of support.
17
18* “Available” basically means that the code builds and the assembly files have been written for the
19  target;
20* “Tested” means that the assembly code has been tested or otherwise verified to be correct. For
21  most targets it also means that continuous integration is set up;
22* “Callstack” means that the assembly code has been written with due care to support unwinding the
23  stack and displaying the call frames (i.e. `gdb backtrace` works as expected).
24
25<table>
26<tr>
27<th rowspan="1" colspan="2">Target</th>
28<th colspan="3">Support</th>
29</tr>
30<tr>
31<th rowspan="2">Architecture</th>
32<th rowspan="2">OS</th>
33<th>Available</th>
34<th>Tested</th>
35<th>Callstack</th>
36</tr>
37<tr>
38<th colspan="3">Notes</th>
39</tr>
40
41<tr>
42<td rowspan="6">x86_64</td>
43<td rowspan="2">apple-ios</td>
44<td>Yes</td>
45<td>Yes</td>
46<td>Yes</td>
47</tr>
48<tr>
49<td colspan="3">
50
51Target has been tested locally.
52
53</td>
54</tr>
55<tr>
56<td rowspan="2">windows</td>
57<td>Yes</td>
58<td>Yes</td>
59<td>Yes, but disabled</td>
60</tr>
61<tr>
62<td colspan="3">
63
64Stacks allocated the usual way are not valid to be used on Windows and the functions to allocate a
65stack in a proper way is a Windows implementation detail. As a (unnecessarily slow and inflexible)
66alternative use [Fibers][fibers].
67
68</td>
69</tr>
70<tr>
71<td rowspan="2">&#42;</td>
72<td>Yes</td>
73<td>Yes</td>
74<td>Yes</td>
75</tr>
76<tr>
77<td></td>
78</tr>
79
80<tr>
81<td rowspan="8">i686<br>i586<br>i386</td>
82<td rowspan="2">apple-ios</td>
83<td>Yes</td>
84<td>Unknown</td>
85<td>Unknown</td>
86</tr>
87<tr>
88<td colspan="3">
89</td>
90</tr>
91<tr>
92<td rowspan="2">linux-android</td>
93<td>Unknown</td>
94<td>Unknown</td>
95<td>Unknown</td>
96</tr>
97<tr>
98<td colspan="3">
99
100The assembly files are available, but the target hasn’t been verified to build
101
102</td>
103</tr>
104<tr>
105<td rowspan="2">windows</td>
106<td>No</td>
107<td>No</td>
108<td>No</td>
109</tr>
110<tr>
111<td colspan="3">
112
113The code technically works on my local machine, but exception handling does not correctly work on
114appveyor, which makes me unwilling to mark this as working yet.
115
116Stacks allocated the usual way are not valid to be used on Windows and the functions to allocate a
117stack in a proper way is a Windows implementation detail. As a (unnecessarily slow and inflexible)
118alternative use [Fibers][fibers].
119
120</td>
121</tr>
122<tr>
123<td rowspan="2">&#42;</td>
124<td>Yes</td>
125<td>Yes</td>
126<td>Yes</td>
127</tr>
128<tr>
129<td colspan="3">
130</td>
131</tr>
132
133<tr>
134<td rowspan="8">aarch64</td>
135<td rowspan="2">apple-ios</td>
136<td>Yes</td>
137<td>Unknown</td>
138<td>Yes</td>
139</tr>
140<tr>
141<td colspan="3">
142
143aarch64-apple-ios has not been tested. iOS hardware is necessary to run these tests.
144
145</td>
146</tr>
147<tr>
148<td rowspan="2">fuchsia<br>unknown-cloudabi</td>
149<td>Unknown</td>
150<td>Unknown</td>
151<td>Yes</td>
152</tr>
153<tr>
154<td colspan="3">
155</td>
156</tr>
157<tr>
158<td rowspan="2">windows</td>
159<td>No</td>
160<td>No</td>
161<td>No</td>
162</tr>
163<tr>
164<td colspan="3">
165
166Stacks allocated the usual way are not valid to be used on Windows and the functions to allocate a
167stack in a proper way is a Windows implementation detail. As a (unnecessarily slow and inflexible)
168alternative use [Fibers][fibers].
169
170</td>
171</tr>
172<tr>
173<td rowspan="2">&#42;</td>
174<td>Yes</td>
175<td>Yes</td>
176<td>Yes</td>
177</tr>
178<tr>
179<td colspan="3">
180</td>
181</tr>
182
183
184<tr>
185<td rowspan="6">arm<br>armv7</td>
186<td rowspan="2">apple-ios</td>
187<td>Yes</td>
188<td>Unknown</td>
189<td>Unknown</td>
190</tr>
191<tr>
192<td colspan="3">
193
194armv7-apple-ios has not been tested. iOS hardware is necessary to run these tests.
195
196</td>
197</tr>
198<tr>
199<td rowspan="2">windows</td>
200<td>No</td>
201<td>No</td>
202<td>No</td>
203</tr>
204<tr>
205<td colspan="3">
206
207Stacks allocated the usual way are not valid to be used on Windows and the functions to allocate a
208stack in a proper way is a Windows implementation detail. As a (unnecessarily slow and inflexible)
209alternative use [Fibers][fibers].
210
211</td>
212</tr>
213<tr>
214<td rowspan="2">&#42;</td>
215<td>Yes</td>
216<td>Yes</td>
217<td>Yes</td>
218</tr>
219<tr>
220<td colspan="3">
221</td>
222</tr>
223
224<tr>
225<td rowspan="2">armv5te</td>
226<td rowspan="2">&#42;</td>
227<td>Unknown</td>
228<td>Unknown</td>
229<td>Unknown</td>
230</tr>
231<tr>
232<td colspan="3">
233</td>
234</tr>
235
236<tr>
237<td rowspan="2">thumbv6<br>thumbv7</td>
238<td rowspan="2">&#42;</td>
239<td>Unknown</td>
240<td>Unknown</td>
241<td>Unknown</td>
242</tr>
243<tr>
244<td colspan="3">
245</td>
246</tr>
247
248<tr>
249<td rowspan="2">mips<br>mipsel</td>
250<td rowspan="2">linux</td>
251<td>Yes</td>
252<td>Yes</td>
253<td>Yes</td>
254</tr>
255<tr>
256<td colspan="3">
257
258Only the o32 ABI is supported and will be used for all 32-bit MIPS targets.
259
260</td>
261</tr>
262
263<tr>
264<td rowspan="2">mips64<br>mips64el</td>
265<td rowspan="2">linux</td>
266<td>Yes</td>
267<td>Yes</td>
268<td>Yes</td>
269</tr>
270<tr>
271<td colspan="3">
272</td>
273</tr>
274
275<tr>
276<td rowspan="2">powerpc</td>
277<td rowspan="2">linux</td>
278<td>Yes</td>
279<td>Yes</td>
280<td>Yes</td>
281</tr>
282<tr>
283<td colspan="3">
284
285Callstack generation may fail at certain well defined ranges of the program, although the usual
286compiler-generated code fails at similar points itself.
287
288</td>
289</tr>
290
291<tr>
292<td rowspan="2">powerpc64</td>
293<td rowspan="2">linux</td>
294<td>Yes</td>
295<td>Yes</td>
296<td>Yes</td>
297</tr>
298<tr>
299<td colspan="3">
300
301Callstack generation may fail at certain well defined ranges of the program, although the usual
302compiler-generated code fails at similar points itself.
303
304</td>
305</tr>
306
307<tr>
308<td rowspan="2">powerpc64le</td>
309<td rowspan="2">linux</td>
310<td>Yes</td>
311<td>Yes</td>
312<td>Yes</td>
313</tr>
314<tr>
315<td colspan="3">
316
317Callstack generation may fail at certain well defined ranges of the program, although the usual
318compiler-generated code fails at similar points itself.
319
320</td>
321</tr>
322
323<tr>
324<td rowspan="2">s390x</td>
325<td rowspan="2">linux</td>
326<td>Yes</td>
327<td>Locally</td>
328<td>Yes</td>
329</tr>
330<tr>
331<td colspan="3">
332
333Test runner on CI hangs, local verification has been done on a qemu-system-s390x VM. It may be
334possible to add CI testing in the future via qemu’s full-system emulation.
335
336</td>
337</tr>
338
339<tr>
340<td rowspan="2">sparc</td>
341<td rowspan="2">linux</td>
342<td>Unknown</td>
343<td>Unknown</td>
344<td>Unknown</td>
345</tr>
346<tr>
347<td colspan="3">
348
349A Rust target for 32-bit SPARC exists, but no Linux distributions actually have a 32-bit SPARC
350distribution, so verification is infeasible.
351
352The actual assembly code has been written conservatively, modelled after the 64-bit SPARC code.
353and so has a non-zero chance of working.
354
355</td>
356</tr>
357
358<tr>
359<td rowspan="2">sparc64</td>
360<td rowspan="2">linux</td>
361<td>Yes</td>
362<td>Locally</td>
363<td>Yes</td>
364</tr>
365<tr>
366<td colspan="3">
367
368Has been manually verified to work on the [GCC Farm Project] machines. It may be possible to
369add CI testing in the future via qemu’s full-system emulation.
370
371</td>
372</tr>
373
374<tr>
375<td rowspan="2">sparc9</td>
376<td rowspan="2">solaris</td>
377<td>Yes</td>
378<td>Unknown</td>
379<td>Unknown</td>
380</tr>
381<tr>
382<td colspan="3">
383
384Uses the same assembly as the sparc64-linux-gnu target. This target has no rustc builds and
385therefore the correct operation of this target could not be verified at the moment.
386
387</td>
388</tr>
389
390<tr>
391<td rowspan="2">wasm</td>
392<td rowspan="2">&#42;</td>
393<td>No</td>
394<td>No</td>
395<td>No</td>
396</tr>
397<tr>
398<td colspan="3">
399
400This library is not applicable to the target. WASM hasn’t a specified C ABI, the callstack is
401not even in an address space and does not appear to be manipulatable.
402
403</td>
404</tr>
405
406<tr>
407<td rowspan="2">asmjs</td>
408<td rowspan="2">&#42;</td>
409<td>No</td>
410<td>No</td>
411<td>No</td>
412</tr>
413<tr>
414<td colspan="3">
415
416Feasibility/necessity hasn’t been acertained.
417
418</td>
419</tr>
420
421<tr>
422<td rowspan="2">nvptx</td>
423<td rowspan="2">&#42;</td>
424<td>No</td>
425<td>No</td>
426<td>No</td>
427</tr>
428<tr>
429<td colspan="3">
430
431Feasibility/necessity hasn’t been acertained.
432
433</td>
434</tr>
435
436<tr>
437<td rowspan="2">msp430</td>
438<td rowspan="2">&#42;</td>
439<td>No</td>
440<td>No</td>
441<td>No</td>
442</tr>
443<tr>
444<td colspan="3">
445
446Haven’t gotten to it yet...
447
448</td>
449</tr>
450
451<tr>
452<td rowspan="2">riscv32</td>
453<td rowspan="2">&#42;</td>
454<td>Yes</td>
455<td>No</td>
456<td>Unknown</td>
457</tr>
458<tr>
459<td colspan="3">
460
461Although the assembly code has not been tested, it is a straightforward copy of the 64-bit version.
462Unless there is a non-obvious mistake, this should work fine.
463
464</td>
465</tr>
466
467<tr>
468<td rowspan="2">riscv64</td>
469<td rowspan="2">&#42;</td>
470<td>Yes</td>
471<td>Locally</td>
472<td>Unknown</td>
473</tr>
474<tr>
475<td colspan="3">
476
477The assembly code for riscv64 has been tested locally with a C caller.
478
479</td>
480</tr>
481</table>
482
483[GCC Farm Project]: https://cfarm.tetaneutral.net/
484[fibers]: https://docs.microsoft.com/en-gb/windows/desktop/ProcThread/fibers
485
486# License
487
488PSM is licensed under either of
489
490 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
491   http://www.apache.org/licenses/LICENSE-2.0)
492 * ISC license ([LICENSE-ISC](LICENSE-ISC) or
493   http://opensource.org/licenses/ISC)
494
495at your option.
496