mirror of
https://git.proxmox.com/git/rustc
synced 2025-08-19 15:43:26 +00:00
496 lines
9.3 KiB
Markdown
496 lines
9.3 KiB
Markdown
# Portable Stack Manipulation
|
||
|
||
This crate provides very portable functions to control the stack pointer and inspect the properties
|
||
of the stack. This crate does not attempt to provide safe abstractions to any operations, the
|
||
only goals are correctness, portability and efficiency (in that exact order). As a consequence most
|
||
functions you’ll see in this crate are unsafe.
|
||
|
||
Unless you’re writing a safe abstraction over stack manipulation, this is not the crate you
|
||
want. Instead consider one of the safe abstractions over this crate. A good place to look at is
|
||
the crates.io’s reverse dependency list.
|
||
|
||
# Platform support
|
||
|
||
The following table lists supported targets and architectures with notes on the level of current
|
||
support and knowledge about the target. The three columns “Available”, “Tested” and “Callstack”
|
||
imply an increasingly high level of support.
|
||
|
||
* “Available” basically means that the code builds and the assembly files have been written for the
|
||
target;
|
||
* “Tested” means that the assembly code has been tested or otherwise verified to be correct. For
|
||
most targets it also means that continuous integration is set up;
|
||
* “Callstack” means that the assembly code has been written with due care to support unwinding the
|
||
stack and displaying the call frames (i.e. `gdb backtrace` works as expected).
|
||
|
||
<table>
|
||
<tr>
|
||
<th rowspan="1" colspan="2">Target</th>
|
||
<th colspan="3">Support</th>
|
||
</tr>
|
||
<tr>
|
||
<th rowspan="2">Architecture</th>
|
||
<th rowspan="2">OS</th>
|
||
<th>Available</th>
|
||
<th>Tested</th>
|
||
<th>Callstack</th>
|
||
</tr>
|
||
<tr>
|
||
<th colspan="3">Notes</th>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="6">x86_64</td>
|
||
<td rowspan="2">apple-ios</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
Target has been tested locally.
|
||
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td rowspan="2">windows</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
<td>Yes, but disabled</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
Stacks allocated the usual way are not valid to be used on Windows and the functions to allocate a
|
||
stack in a proper way is a Windows implementation detail. As a (unnecessarily slow and inflexible)
|
||
alternative use [Fibers][fibers].
|
||
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td rowspan="2">*</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td></td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="8">i686<br>i586<br>i386</td>
|
||
<td rowspan="2">apple-ios</td>
|
||
<td>Yes</td>
|
||
<td>Unknown</td>
|
||
<td>Unknown</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td rowspan="2">linux-android</td>
|
||
<td>Unknown</td>
|
||
<td>Unknown</td>
|
||
<td>Unknown</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
The assembly files are available, but the target hasn’t been verified to build
|
||
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td rowspan="2">windows</td>
|
||
<td>No</td>
|
||
<td>No</td>
|
||
<td>No</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
The code technically works on my local machine, but exception handling does not correctly work on
|
||
appveyor, which makes me unwilling to mark this as working yet.
|
||
|
||
Stacks allocated the usual way are not valid to be used on Windows and the functions to allocate a
|
||
stack in a proper way is a Windows implementation detail. As a (unnecessarily slow and inflexible)
|
||
alternative use [Fibers][fibers].
|
||
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td rowspan="2">*</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="8">aarch64</td>
|
||
<td rowspan="2">apple-ios</td>
|
||
<td>Yes</td>
|
||
<td>Unknown</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
aarch64-apple-ios has not been tested. iOS hardware is necessary to run these tests.
|
||
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td rowspan="2">fuchsia<br>unknown-cloudabi</td>
|
||
<td>Unknown</td>
|
||
<td>Unknown</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td rowspan="2">windows</td>
|
||
<td>No</td>
|
||
<td>No</td>
|
||
<td>No</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
Stacks allocated the usual way are not valid to be used on Windows and the functions to allocate a
|
||
stack in a proper way is a Windows implementation detail. As a (unnecessarily slow and inflexible)
|
||
alternative use [Fibers][fibers].
|
||
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td rowspan="2">*</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
</td>
|
||
</tr>
|
||
|
||
|
||
<tr>
|
||
<td rowspan="6">arm<br>armv7</td>
|
||
<td rowspan="2">apple-ios</td>
|
||
<td>Yes</td>
|
||
<td>Unknown</td>
|
||
<td>Unknown</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
armv7-apple-ios has not been tested. iOS hardware is necessary to run these tests.
|
||
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td rowspan="2">windows</td>
|
||
<td>No</td>
|
||
<td>No</td>
|
||
<td>No</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
Stacks allocated the usual way are not valid to be used on Windows and the functions to allocate a
|
||
stack in a proper way is a Windows implementation detail. As a (unnecessarily slow and inflexible)
|
||
alternative use [Fibers][fibers].
|
||
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td rowspan="2">*</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">armv5te</td>
|
||
<td rowspan="2">*</td>
|
||
<td>Unknown</td>
|
||
<td>Unknown</td>
|
||
<td>Unknown</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">thumbv6<br>thumbv7</td>
|
||
<td rowspan="2">*</td>
|
||
<td>Unknown</td>
|
||
<td>Unknown</td>
|
||
<td>Unknown</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">mips<br>mipsel</td>
|
||
<td rowspan="2">linux</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
Only the o32 ABI is supported and will be used for all 32-bit MIPS targets.
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">mips64<br>mips64el</td>
|
||
<td rowspan="2">linux</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">powerpc</td>
|
||
<td rowspan="2">linux</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
Callstack generation may fail at certain well defined ranges of the program, although the usual
|
||
compiler-generated code fails at similar points itself.
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">powerpc64</td>
|
||
<td rowspan="2">linux</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
Callstack generation may fail at certain well defined ranges of the program, although the usual
|
||
compiler-generated code fails at similar points itself.
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">powerpc64le</td>
|
||
<td rowspan="2">linux</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
Callstack generation may fail at certain well defined ranges of the program, although the usual
|
||
compiler-generated code fails at similar points itself.
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">s390x</td>
|
||
<td rowspan="2">linux</td>
|
||
<td>Yes</td>
|
||
<td>Locally</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
Test runner on CI hangs, local verification has been done on a qemu-system-s390x VM. It may be
|
||
possible to add CI testing in the future via qemu’s full-system emulation.
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">sparc</td>
|
||
<td rowspan="2">linux</td>
|
||
<td>Unknown</td>
|
||
<td>Unknown</td>
|
||
<td>Unknown</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
A Rust target for 32-bit SPARC exists, but no Linux distributions actually have a 32-bit SPARC
|
||
distribution, so verification is infeasible.
|
||
|
||
The actual assembly code has been written conservatively, modelled after the 64-bit SPARC code.
|
||
and so has a non-zero chance of working.
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">sparc64</td>
|
||
<td rowspan="2">linux</td>
|
||
<td>Yes</td>
|
||
<td>Locally</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
Has been manually verified to work on the [GCC Farm Project] machines. It may be possible to
|
||
add CI testing in the future via qemu’s full-system emulation.
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">sparc9</td>
|
||
<td rowspan="2">solaris</td>
|
||
<td>Yes</td>
|
||
<td>Unknown</td>
|
||
<td>Unknown</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
Uses the same assembly as the sparc64-linux-gnu target. This target has no rustc builds and
|
||
therefore the correct operation of this target could not be verified at the moment.
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">wasm</td>
|
||
<td rowspan="2">*</td>
|
||
<td>No</td>
|
||
<td>No</td>
|
||
<td>No</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
This library is not applicable to the target. WASM hasn’t a specified C ABI, the callstack is
|
||
not even in an address space and does not appear to be manipulatable.
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">asmjs</td>
|
||
<td rowspan="2">*</td>
|
||
<td>No</td>
|
||
<td>No</td>
|
||
<td>No</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
Feasibility/necessity hasn’t been acertained.
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">nvptx</td>
|
||
<td rowspan="2">*</td>
|
||
<td>No</td>
|
||
<td>No</td>
|
||
<td>No</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
Feasibility/necessity hasn’t been acertained.
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">msp430</td>
|
||
<td rowspan="2">*</td>
|
||
<td>No</td>
|
||
<td>No</td>
|
||
<td>No</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
Haven’t gotten to it yet...
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">riscv32</td>
|
||
<td rowspan="2">*</td>
|
||
<td>Yes</td>
|
||
<td>No</td>
|
||
<td>Unknown</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
Although the assembly code has not been tested, it is a straightforward copy of the 64-bit version.
|
||
Unless there is a non-obvious mistake, this should work fine.
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td rowspan="2">riscv64</td>
|
||
<td rowspan="2">*</td>
|
||
<td>Yes</td>
|
||
<td>Locally</td>
|
||
<td>Unknown</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="3">
|
||
|
||
The assembly code for riscv64 has been tested locally with a C caller.
|
||
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
[GCC Farm Project]: https://cfarm.tetaneutral.net/
|
||
[fibers]: https://docs.microsoft.com/en-gb/windows/desktop/ProcThread/fibers
|
||
|
||
# License
|
||
|
||
PSM is licensed under either of
|
||
|
||
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
|
||
http://www.apache.org/licenses/LICENSE-2.0)
|
||
* MIT license ([LICENSE-MIT](LICENSE-MIT) or
|
||
http://opensource.org/licenses/MIT)
|
||
|
||
at your option.
|