summaryrefslogtreecommitdiffstats
path: root/vendor/psm/README.mkd
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 12:02:58 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 12:02:58 +0000
commit698f8c2f01ea549d77d7dc3338a12e04c11057b9 (patch)
tree173a775858bd501c378080a10dca74132f05bc50 /vendor/psm/README.mkd
parentInitial commit. (diff)
downloadrustc-698f8c2f01ea549d77d7dc3338a12e04c11057b9.tar.xz
rustc-698f8c2f01ea549d77d7dc3338a12e04c11057b9.zip
Adding upstream version 1.64.0+dfsg1.upstream/1.64.0+dfsg1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'vendor/psm/README.mkd')
-rw-r--r--vendor/psm/README.mkd495
1 files changed, 495 insertions, 0 deletions
diff --git a/vendor/psm/README.mkd b/vendor/psm/README.mkd
new file mode 100644
index 000000000..441763873
--- /dev/null
+++ b/vendor/psm/README.mkd
@@ -0,0 +1,495 @@
+# 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">&#42;</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">&#42;</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">&#42;</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">&#42;</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">&#42;</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">&#42;</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">&#42;</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">&#42;</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">&#42;</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">&#42;</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">&#42;</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">&#42;</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.