docs: Add documentation for BPF targets

Author: vadorovsky

src/doc/rustc/src/platform-support.md

@@ -296,8 +296,8 @@ target | std | host | notes
 [`armv7s-apple-ios`](platform-support/apple-ios.md) | ✓ |  | Armv7-A Apple-A6 Apple iOS
 [`armv8r-none-eabihf`](platform-support/armv8r-none-eabihf.md) | * |  | Bare Armv8-R, hardfloat
 `avr-unknown-gnu-atmega328` | * |  | AVR. Requires `-Z build-std=core`
-`bpfeb-unknown-none` | * |  | BPF (big endian)
-`bpfel-unknown-none` | * |  | BPF (little endian)
+[`bpfeb-unknown-none`](platform-support/bpf-unknown-none.md) | * |  | BPF (big endian)
+[`bpfel-unknown-none`](platform-support/bpf-unknown-none.md) | * |  | BPF (little endian)
 `csky-unknown-linux-gnuabiv2` | ✓ |  | C-SKY abiv2 Linux (little endian)
 `csky-unknown-linux-gnuabiv2hf` | ✓ |  | C-SKY abiv2 Linux, hardfloat (little endian)
 [`hexagon-unknown-linux-musl`](platform-support/hexagon-unknown-linux-musl.md) | ✓ | | Hexagon Linux with musl 1.2.3

src/doc/rustc/src/platform-support/bpf-unknown-none.md

@@ -0,0 +1,123 @@
+# `bpf*-unknown-none`
+
+**Tier: 3**
+
+* `bpfeb-unknown-none` (big endian)
+* `bpfel-unknown-none` (little endian)
+
+Targets for the [eBPF virtual machine][ebpf].
+
+## Target maintainers
+
+- [@dave-tucker](https://github.com/dave-tucker)
+- [@vadorovsky](https://github.com/vadorovsky)
+
+## Requirements
+
+BPF targets require a Rust toolchain with `rust-src` component and
+[bpf-linker][bpf-linker].
+
+They don't support std and alloc and are meant for `no_std` environment.
+
+`extern "C"` uses the [BPF ABI calling convention][bpf-abi].
+
+Produced binaries use the ELF format.
+
+## Building the target
+
+You can build Rust with support for BPF targets by adding them to the `target`
+list in `config.toml`:
+
+```toml
+[build]
+target = ["bpfeb-unknown-none", "bpfel-unknown-none"]
+```
+
+## Building Rust programs
+
+Rust does not yet ship pre-compiled artifacts for this target. To compile for
+this target, you will either need to build Rust with the target enabled (see
+"Building the target" above), or build your own copy of `core` by using
+`build-std` or similar.
+
+Building the BPF target requires specifying it explicitly. Users can either
+add them to the `target` list in `config.toml`:
+
+```toml
+[build]
+target = ["bpfel-unknown-none"]
+```
+
+Or specify it directly in the `cargo build` invocation:
+
+```console
+cargo +nightly build -Z build-std=core --target bpfel-unknown-none
+```
+
+## Testing
+
+eBPF bytecode need to be executed on an eBPF virtual machine, like the one
+provided by the Linux kernel or one of user-space implementations like
+[rbpf][rbpf]. None of them supports running Rust testsuite.
+
+Currently the best way of unit testing the code used in BPF programs is
+extracting it to a separate crate, which can be built and ran on a host target,
+and using it as a dependency.
+
+## Cross-compilation toolchains
+
+Technically speaking, every build for BPF target is a cross build and is
+performed on a host target (e.g. `x86_64-unknown-linux-*`) for the BPF target
+(e.g. `bpfel-unknown-none`). The resulting BPF bytecode can be executed on a
+virtual machine, which can run on different host architectures (x86_64, aarch64,
+riscv64 etc.). The BPF bytecode format stays the same regardless of the host
+architecture hosting the virtual machine. When building BPF code, compiler does
+not care about the architecture hosting the VM.
+
+That said, in the context of BPF VM in the Linux kernel and BPF programs
+interacting with kernel types, the architecture which hosts the VM affects
+these types. For example, `char` in C translates to different Rust types
+on different architectures (`i8` on x86_64, `u8` on aarch64). Therefore, kernel
+types are different across architectures. Solving that problem is still not a
+concern of the Rust compiler itself. On the other hand, [Aya][aya] (the library
+for writing BPF programs and the main consumer of BPF targets in Rust) handles
+the C type differences by providing the [`aya-ebpf-cty`][aya-ebpf-cty] library,
+with type aliases similar to those provided by `core:ffi`. aya-ebpf-cty allows
+to specify the VM host target through the `CARGO_CFG_BPF_TARGET_ARCH`
+environment variable (e.g. `CARGO_CFG_BPF_TARGET_ARCH=aarch64`).
+
+## C code
+
+It's possible to link a Rust BPF project to bitcode or object files which are
+built from C code with [clang][clang]. It can be done using `rustc-link-lib`
+instruction in `build.rs`. Example:
+
+```rust
+let out_dir = std::env::var("OUT_DIR").unwrap();
+let c_module = "my_module.bpf.c"
+let s = Command::new("clang")
+    .arg("-I")
+    .arg("src/")
+    .arg("-O2")
+    .arg("-emit-llvm")
+    .arg("-target")
+    .arg("bpf")
+    .arg("-c")
+    .arg("-g")
+    .arg(c_module)
+    .arg("-o")
+    .arg(format!("{out_dir}/my_module.bpf.o"))
+    .status()
+    .unwrap();
+assert!(s.success());
+println!("cargo:rustc-link-search=native={out_dir}");
+println!("cargo:rustc-link-lib=link-arg={out_dir}/my_module.bpf.o");
+```
+
+[ebpf]: https://ebpf.io/
+[bpf-linker]: https://github.com/aya-rs/bpf-linker
+[bpf-abi]: https://www.kernel.org/doc/html/v6.13-rc5/bpf/standardization/abi.html
+[rbpf]: https://github.com/qmonnet/rbpf
+[aya]: https://aya-rs.dev
+[aya-ebpf-cty]: https://github.com/aya-rs/aya/tree/main/ebpf/aya-ebpf-cty
+[clang]: https://clang.llvm.org/