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">*</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">*</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">*</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">*</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">*</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">*</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">*</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">*</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">*</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">*</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">*</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">*</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