| # 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="4">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">AIX</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <tr> |
| <td colspan="3"> |
| </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> |
| |
| <tr> |
| <td rowspan="2">loongarch64</td> |
| <td rowspan="2">*</td> |
| <td>Yes</td> |
| <td>Locally</td> |
| <td>Unknown</td> |
| </tr> |
| <tr> |
| <td colspan="3"> |
| |
| The assembly code for loongarch64 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 |
| https://www.apache.org/licenses/LICENSE-2.0) |
| * MIT license ([LICENSE-MIT](LICENSE-MIT) or |
| https://opensource.org/licenses/MIT) |
| |
| at your option. |
