summaryrefslogtreecommitdiffstats
path: root/src/doc/unstable-book
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 12:19:43 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 12:19:43 +0000
commit3e3e70d529d8c7d7c4d7bc4fefc9f109393b9245 (patch)
treedaf049b282ab10e8c3d03e409b3cd84ff3f7690c /src/doc/unstable-book
parentAdding debian version 1.68.2+dfsg1-1. (diff)
downloadrustc-3e3e70d529d8c7d7c4d7bc4fefc9f109393b9245.tar.xz
rustc-3e3e70d529d8c7d7c4d7bc4fefc9f109393b9245.zip
Merging upstream version 1.69.0+dfsg1.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'src/doc/unstable-book')
-rw-r--r--src/doc/unstable-book/src/compiler-flags/export-executable-symbols.md43
-rw-r--r--src/doc/unstable-book/src/compiler-flags/instrument-xray.md39
-rw-r--r--src/doc/unstable-book/src/compiler-flags/sanitizer.md20
-rw-r--r--src/doc/unstable-book/src/compiler-flags/tiny-const-eval-limit.md6
-rw-r--r--src/doc/unstable-book/src/library-features/char-error-internals.md5
-rw-r--r--src/doc/unstable-book/src/library-features/int-error-internals.md5
6 files changed, 108 insertions, 10 deletions
diff --git a/src/doc/unstable-book/src/compiler-flags/export-executable-symbols.md b/src/doc/unstable-book/src/compiler-flags/export-executable-symbols.md
new file mode 100644
index 000000000..c7f10afac
--- /dev/null
+++ b/src/doc/unstable-book/src/compiler-flags/export-executable-symbols.md
@@ -0,0 +1,43 @@
+# `export-executable-symbols`
+
+The tracking issue for this feature is: [#84161](https://github.com/rust-lang/rust/issues/84161).
+
+------------------------
+
+The `-Zexport-executable-symbols` compiler flag makes `rustc` export symbols from executables. The resulting binary is runnable, but can also be used as a dynamic library. This is useful for interoperating with programs written in other languages, in particular languages with a runtime like Java or Lua.
+
+For example on windows:
+```rust
+#[no_mangle]
+fn my_function() -> usize {
+ return 42;
+}
+
+fn main() {
+ println!("Hello, world!");
+}
+```
+
+A standard `cargo build` will produce a `.exe` without an export directory. When the `export-executable-symbols` flag is added
+
+```Bash
+export RUSTFLAGS="-Zexport-executable-symbols"
+cargo build
+```
+
+the binary has an export directory with the functions:
+
+```plain
+The Export Tables (interpreted .edata section contents)
+
+...
+
+[Ordinal/Name Pointer] Table
+ [ 0] my_function
+ [ 1] main
+```
+(the output of `objdump -x` on the binary)
+
+Please note that the `#[no_mangle]` attribute is required. Without it, the symbol is not exported.
+
+The equivalent of this flag in C and C++ compilers is the `__declspec(dllexport)` annotation or the `-rdynamic` linker flag.
diff --git a/src/doc/unstable-book/src/compiler-flags/instrument-xray.md b/src/doc/unstable-book/src/compiler-flags/instrument-xray.md
new file mode 100644
index 000000000..7fb33cd68
--- /dev/null
+++ b/src/doc/unstable-book/src/compiler-flags/instrument-xray.md
@@ -0,0 +1,39 @@
+# `instrument-xray`
+
+The tracking issue for this feature is: [#102921](https://github.com/rust-lang/rust/issues/102921).
+
+------------------------
+
+Enable generation of NOP sleds for XRay function tracing instrumentation.
+For more information on XRay,
+read [LLVM documentation](https://llvm.org/docs/XRay.html),
+and/or the [XRay whitepaper](http://research.google.com/pubs/pub45287.html).
+
+Set the `-Z instrument-xray` compiler flag in order to enable XRay instrumentation.
+
+ - `-Z instrument-xray` – use the default settings
+ - `-Z instrument-xray=skip-exit` – configure a custom setting
+ - `-Z instrument-xray=ignore-loops,instruction-threshold=300` –
+ multiple settings separated by commas
+
+Supported options:
+
+ - `always` – force instrumentation of all functions
+ - `never` – do no instrument any functions
+ - `ignore-loops` – ignore presence of loops,
+ instrument functions based only on instruction count
+ - `instruction-threshold=10` – set a different instruction threshold for instrumentation
+ - `skip-entry` – do no instrument function entry
+ - `skip-exit` – do no instrument function exit
+
+The default settings are:
+
+ - instrument both entry & exit from functions
+ - instrument functions with at least 200 instructions,
+ or containing a non-trivial loop
+
+Note that `-Z instrument-xray` only enables generation of NOP sleds
+which on their own don't do anything useful.
+In order to actually trace the functions,
+you will need to link a separate runtime library of your choice,
+such as Clang's [XRay Runtime Library](https://www.llvm.org/docs/XRay.html#xray-runtime-library).
diff --git a/src/doc/unstable-book/src/compiler-flags/sanitizer.md b/src/doc/unstable-book/src/compiler-flags/sanitizer.md
index 70c3a445b..262cef345 100644
--- a/src/doc/unstable-book/src/compiler-flags/sanitizer.md
+++ b/src/doc/unstable-book/src/compiler-flags/sanitizer.md
@@ -531,6 +531,24 @@ LLVM KCFI is supported on the following targets:
See the [Clang KernelControlFlowIntegrity documentation][clang-kcfi] for more
details.
+# KernelAddressSanitizer
+
+KernelAddressSanitizer (KASAN) is a freestanding version of AddressSanitizer
+which is suitable for detecting memory errors in programs which do not have a
+runtime environment, such as operating system kernels. KernelAddressSanitizer
+requires manual implementation of the underlying functions used for tracking
+KernelAddressSanitizer state.
+
+KernelAddressSanitizer is supported on the following targets:
+
+* `aarch64-unknown-none`
+* `riscv64gc-unknown-none-elf`
+* `riscv64imac-unknown-none-elf`
+* `x86_64-unknown-none`
+
+See the [Linux Kernel's KernelAddressSanitizer documentation][linux-kasan] for
+more details.
+
# LeakSanitizer
LeakSanitizer is run-time memory leak detector.
@@ -714,6 +732,7 @@ Sanitizers produce symbolized stacktraces when llvm-symbolizer binary is in `PAT
* [AddressSanitizer in Clang][clang-asan]
* [ControlFlowIntegrity in Clang][clang-cfi]
* [HWAddressSanitizer in Clang][clang-hwasan]
+* [Linux Kernel's KernelAddressSanitizer documentation][linux-kasan]
* [LeakSanitizer in Clang][clang-lsan]
* [MemorySanitizer in Clang][clang-msan]
* [MemTagSanitizer in LLVM][llvm-memtag]
@@ -727,4 +746,5 @@ Sanitizers produce symbolized stacktraces when llvm-symbolizer binary is in `PAT
[clang-msan]: https://clang.llvm.org/docs/MemorySanitizer.html
[clang-scs]: https://clang.llvm.org/docs/ShadowCallStack.html
[clang-tsan]: https://clang.llvm.org/docs/ThreadSanitizer.html
+[linux-kasan]: https://www.kernel.org/doc/html/latest/dev-tools/kasan.html
[llvm-memtag]: https://llvm.org/docs/MemTagSanitizer.html
diff --git a/src/doc/unstable-book/src/compiler-flags/tiny-const-eval-limit.md b/src/doc/unstable-book/src/compiler-flags/tiny-const-eval-limit.md
new file mode 100644
index 000000000..51c5fd69c
--- /dev/null
+++ b/src/doc/unstable-book/src/compiler-flags/tiny-const-eval-limit.md
@@ -0,0 +1,6 @@
+# `tiny-const-eval-limit`
+
+--------------------
+
+The `-Ztiny-const-eval-limit` compiler flag sets a tiny, non-configurable limit for const eval.
+This flag should only be used by const eval tests in the rustc test suite.
diff --git a/src/doc/unstable-book/src/library-features/char-error-internals.md b/src/doc/unstable-book/src/library-features/char-error-internals.md
deleted file mode 100644
index 8013b4988..000000000
--- a/src/doc/unstable-book/src/library-features/char-error-internals.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# `char_error_internals`
-
-This feature is internal to the Rust compiler and is not intended for general use.
-
-------------------------
diff --git a/src/doc/unstable-book/src/library-features/int-error-internals.md b/src/doc/unstable-book/src/library-features/int-error-internals.md
deleted file mode 100644
index 402e4fa5e..000000000
--- a/src/doc/unstable-book/src/library-features/int-error-internals.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# `int_error_internals`
-
-This feature is internal to the Rust compiler and is not intended for general use.
-
-------------------------