compiler: Add `*-unknown-hermit` documentation

Signed-off-by: Martin Kröning <martin.kroening@eonerc.rwth-aachen.de>

3 files changed, 79 insertions, 2 deletions

diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md
index 96ee9a586de..e5af8526bfc 100644
--- a/src/doc/rustc/src/SUMMARY.md
+++ b/src/doc/rustc/src/SUMMARY.md
@@ -42,6 +42,7 @@
     - [sparc-unknown-none-elf](./platform-support/sparc-unknown-none-elf.md)
     - [*-pc-windows-gnullvm](platform-support/pc-windows-gnullvm.md)
     - [\*-nto-qnx-\*](platform-support/nto-qnx.md)
+    - [*-unknown-hermit](platform-support/hermit.md)
     - [\*-unknown-netbsd\*](platform-support/netbsd.md)
     - [*-unknown-openbsd](platform-support/openbsd.md)
     - [\*-unknown-uefi](platform-support/unknown-uefi.md)
diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md
index 351b03b9337..959f6174192 100644
--- a/src/doc/rustc/src/platform-support.md
+++ b/src/doc/rustc/src/platform-support.md
@@ -223,7 +223,7 @@ target | std | host | notes
 [`aarch64-unknown-linux-ohos`](platform-support/openharmony.md) | ✓ |  | ARM64 OpenHarmony |
 [`aarch64-unknown-nto-qnx710`](platform-support/nto-qnx.md) | ✓ |  | ARM64 QNX Neutrino 7.1 RTOS |
 `aarch64-unknown-freebsd` | ✓ | ✓ | ARM64 FreeBSD
-`aarch64-unknown-hermit` | ✓ |  | ARM64 HermitCore
+[`aarch64-unknown-hermit`](platform-support/hermit.md) | ✓ |  | ARM64 Hermit
 `aarch64-unknown-linux-gnu_ilp32` | ✓ | ✓ | ARM64 Linux (ILP32 ABI)
 [`aarch64-unknown-netbsd`](platform-support/netbsd.md) | ✓ | ✓ | ARM64 NetBSD
 [`aarch64-unknown-openbsd`](platform-support/openbsd.md) | ✓ | ✓ | ARM64 OpenBSD
@@ -303,6 +303,7 @@ target | std | host | notes
 [`riscv32imac-unknown-xous-elf`](platform-support/riscv32imac-unknown-xous-elf.md) | ? |  | RISC-V Xous (RV32IMAC ISA)
 [`riscv32imc-esp-espidf`](platform-support/esp-idf.md) | ✓ |  | RISC-V ESP-IDF
 [`riscv32imac-esp-espidf`](platform-support/esp-idf.md) | ✓ |  | RISC-V ESP-IDF
+[`riscv64gc-unknown-hermit`](platform-support/hermit.md) | ✓ |   | RISC-V Hermit
 `riscv64gc-unknown-freebsd` |   |   | RISC-V FreeBSD
 `riscv64gc-unknown-fuchsia` |   |   | RISC-V Fuchsia
 `riscv64gc-unknown-linux-musl` |   |   | RISC-V Linux (kernel 4.20, musl 1.2.0)
@@ -327,7 +328,7 @@ target | std | host | notes
 `x86_64-sun-solaris` | ? |  | Deprecated target for 64-bit Solaris 10/11, illumos
 `x86_64-unknown-dragonfly` | ✓ | ✓ | 64-bit DragonFlyBSD
 `x86_64-unknown-haiku` | ✓ | ✓ | 64-bit Haiku
-`x86_64-unknown-hermit` | ✓ |  | HermitCore
+[`x86_64-unknown-hermit`](platform-support/hermit.md) | ✓ |  | x86_64 Hermit
 `x86_64-unknown-l4re-uclibc` | ? |  |
 [`x86_64-unknown-linux-ohos`](platform-support/openharmony.md) | ✓ |  | x86_64 OpenHarmony |
 [`x86_64-unknown-openbsd`](platform-support/openbsd.md) | ✓ | ✓ | 64-bit OpenBSD
diff --git a/src/doc/rustc/src/platform-support/hermit.md b/src/doc/rustc/src/platform-support/hermit.md
new file mode 100644
index 00000000000..146079e36f4
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/hermit.md
@@ -0,0 +1,75 @@
+# `*-unknown-hermit`
+
+**Tier: 3**
+
+The [Hermit] unikernel target allows compiling your applications into self-contained, specialized unikernel images that can be run in small virtual machines.
+
+[Hermit]: https://github.com/hermitcore
+
+Target triplets available so far:
+
+- `x86_64-unknown-hermit`
+- `aarch64-unknown-hermit`
+- `riscv64gc-unknown-hermit`
+
+## Target maintainers
+
+- Stefan Lankes ([@stlankes](https://github.com/stlankes))
+- Martin Kröning ([@mkroening](https://github.com/mkroening))
+
+## Requirements
+
+These targets only support cross-compilation.
+The targets do support std.
+
+When building binaries for this target, the Hermit unikernel is built from scratch.
+The application developer themselves specializes the target and sets corresponding expectations.
+
+The Hermit targets follow Linux's `extern "C"` calling convention.
+
+Hermit binaries have the ELF format.
+
+## Building the target
+
+You can build Rust with support for the targets by adding it to the `target` list in `config.toml`.
+To run the Hermit build scripts, you also have to enable your host target.
+The build scripts rely on `llvm-tools` and binaries are linked using `rust-lld`, so those have to be enabled as well.
+
+```toml
+[build]
+build-stage = 1
+target = [
+    "<HOST_TARGET>",
+    "x86_64-unknown-hermit",
+    "aarch64-unknown-hermit",
+    "riscv64gc-unknown-hermit",
+]
+
+[rust]
+lld = true
+llvm-tools = true
+```
+
+## Building Rust programs
+
+Rust does not yet ship pre-compiled artifacts for these targets.
+To compile for these targets, you will either need to build Rust with the targets enabled
+(see “Building the targets” above), or build your own copy of `core` by using `build-std` or similar.
+
+Building Rust programs can be done by following the tutorial in our starter application [rusty-demo].
+
+[rusty-demo]: https://github.com/hermitcore/rusty-demo
+
+## Testing
+
+The targets support running binaries in the form of self-contained unikernel images.
+These images can be chainloaded by Hermit's [loader] or hypervisor ([Uhyve]).
+QEMU can be used to boot Hermit binaries using the loader on any architecture.
+The targets do not support running the Rust test suite.
+
+[loader]: https://github.com/hermitcore/rusty-loader
+[Uhyve]: https://github.com/hermitcore/uhyve
+
+## Cross-compilation toolchains and C code
+
+The targets do not yet support C code and Rust code at the same time.