diff --git a/compiler/rustc_metadata/src/rmeta/decoder.rs b/compiler/rustc_metadata/src/rmeta/decoder.rs index 8fa703a776075..6b0b5ac7da9a1 100644 --- a/compiler/rustc_metadata/src/rmeta/decoder.rs +++ b/compiler/rustc_metadata/src/rmeta/decoder.rs @@ -83,7 +83,7 @@ pub(crate) struct CrateMetadata { // --- Some data pre-decoded from the metadata blob, usually for performance --- /// NOTE(eddyb) we pass `'static` to a `'tcx` parameter because this - /// lifetime is only used behind `Lazy`, and therefore acts like a + /// lifetime is only used behind `LazyValue`, `LazyArray`, or `LazyTable`, and therefore acts like a /// universal (`for<'tcx>`), that is paired up with whichever `TyCtxt` /// is being used to decode those values. root: CrateRoot, diff --git a/compiler/rustc_metadata/src/rmeta/mod.rs b/compiler/rustc_metadata/src/rmeta/mod.rs index 0f291f9264777..23198a8536933 100644 --- a/compiler/rustc_metadata/src/rmeta/mod.rs +++ b/compiler/rustc_metadata/src/rmeta/mod.rs @@ -66,13 +66,13 @@ pub const METADATA_HEADER: &[u8] = &[b'r', b'u', b's', b't', 0, 0, 0, METADATA_V /// /// Metadata is effective a tree, encoded in post-order, /// and with the root's position written next to the header. -/// That means every single `Lazy` points to some previous +/// That means every single `LazyValue` points to some previous /// location in the metadata and is part of a larger node. /// -/// The first `Lazy` in a node is encoded as the backwards +/// The first `LazyValue` in a node is encoded as the backwards /// distance from the position where the containing node -/// starts and where the `Lazy` points to, while the rest -/// use the forward distance from the previous `Lazy`. +/// starts and where the `LazyValue` points to, while the rest +/// use the forward distance from the previous `LazyValue`. /// Distances start at 1, as 0-byte nodes are invalid. /// Also invalid are nodes being referred in a different /// order than they were encoded in. @@ -94,12 +94,12 @@ impl LazyValue { /// A list of lazily-decoded values. /// -/// Unlike `Lazy>`, the length is encoded next to the +/// Unlike `LazyValue>`, the length is encoded next to the /// position, not at the position, which means that the length /// doesn't need to be known before encoding all the elements. /// /// If the length is 0, no position is encoded, but otherwise, -/// the encoding is that of `Lazy`, with the distinction that +/// the encoding is that of `LazyArray`, with the distinction that /// the minimal distance the length of the sequence, i.e. /// it's assumed there's no 0-byte element in the sequence. struct LazyArray { @@ -167,17 +167,17 @@ impl Clone for LazyTable { } } -/// Encoding / decoding state for `Lazy`. +/// Encoding / decoding state for `Lazy`s (`LazyValue`, `LazyArray`, and `LazyTable`). #[derive(Copy, Clone, PartialEq, Eq, Debug)] enum LazyState { /// Outside of a metadata node. NoNode, - /// Inside a metadata node, and before any `Lazy`. + /// Inside a metadata node, and before any `Lazy`s. /// The position is that of the node itself. NodeStart(NonZeroUsize), - /// Inside a metadata node, with a previous `Lazy`. + /// Inside a metadata node, with a previous `Lazy`s. /// The position is where that previous `Lazy` would start. Previous(NonZeroUsize), } diff --git a/compiler/rustc_metadata/src/rmeta/table.rs b/compiler/rustc_metadata/src/rmeta/table.rs index 42759f0a652b3..21841ae2532a7 100644 --- a/compiler/rustc_metadata/src/rmeta/table.rs +++ b/compiler/rustc_metadata/src/rmeta/table.rs @@ -141,7 +141,7 @@ fixed_size_enum! { } } -// We directly encode `DefPathHash` because a `Lazy` would encur a 25% cost. +// We directly encode `DefPathHash` because a `LazyValue` would incur a 25% cost. impl FixedSizeEncoding for Option { type ByteArray = [u8; 16]; @@ -159,7 +159,7 @@ impl FixedSizeEncoding for Option { } } -// We directly encode RawDefId because using a `Lazy` would incur a 50% overhead in the worst case. +// We directly encode RawDefId because using a `LazyValue` would incur a 50% overhead in the worst case. impl FixedSizeEncoding for Option { type ByteArray = [u8; 8]; diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md index f6348b2bddc88..736c30694cddb 100644 --- a/src/doc/rustc/src/SUMMARY.md +++ b/src/doc/rustc/src/SUMMARY.md @@ -28,6 +28,7 @@ - [riscv32imac-unknown-xous-elf](platform-support/riscv32imac-unknown-xous-elf.md) - [*-pc-windows-gnullvm](platform-support/pc-windows-gnullvm.md) - [*-unknown-openbsd](platform-support/openbsd.md) + - [\*-unknown-uefi](platform-support/unknown-uefi.md) - [wasm64-unknown-unknown](platform-support/wasm64-unknown-unknown.md) - [x86_64-unknown-none](platform-support/x86_64-unknown-none.md) - [Targets](targets/index.md) diff --git a/src/doc/rustc/src/platform-support/unknown-uefi.md b/src/doc/rustc/src/platform-support/unknown-uefi.md new file mode 100644 index 0000000000000..8f90d9c7453d0 --- /dev/null +++ b/src/doc/rustc/src/platform-support/unknown-uefi.md @@ -0,0 +1,254 @@ +# `*-unknown-uefi` + +**Tier: 3** + +Unified Extensible Firmware Interface (UEFI) targets for application, driver, +and core UEFI binaries. + +Available targets: + +- `aarch64-unknown-uefi` +- `i686-unknown-uefi` +- `x86_64-unknown-uefi` + +## Target maintainers + +- David Rheinsberg ([@dvdhrm](https://github.com/dvdhrm)) +- Nicholas Bishop ([@nicholasbishop](https://github.com/nicholasbishop)) + +## Requirements + +All UEFI targets can be used as `no-std` environments via cross-compilation. +Support for `std` is missing, but actively worked on. `alloc` is supported if +an allocator is provided by the user. No host tools are supported. + +The UEFI environment resembles the environment for Microsoft Windows, with some +minor differences. Therefore, cross-compiling for UEFI works with the same +tools as cross-compiling for Windows. The target binaries are PE32+ encoded, +the calling convention is different for each architecture, but matches what +Windows uses (if the architecture is supported by Windows). The special +`efiapi` Rust calling-convention chooses the right ABI for the target platform +(`extern "C"` is incorrect on Intel targets at least). The specification has an +elaborate section on the different supported calling-conventions, if more +details are desired. + +MMX, SSE, and other FP-units are disabled by default, to allow for compilation +of core UEFI code that runs before they are set up. This can be overridden for +individual compilations via rustc command-line flags. Not all firmwares +correctly configure those units, though, so careful inspection is required. + +As native to PE32+, binaries are position-dependent, but can be relocated at +runtime if their desired location is unavailable. The code must be statically +linked. Dynamic linking is not supported. Code is shared via UEFI interfaces, +rather than dynamic linking. Additionally, UEFI forbids running code on +anything but the boot CPU/thread, nor is interrupt-usage allowed (apart from +the timer interrupt). Device drivers are required to use polling methods. + +UEFI uses a single address-space to run all code in. Multiple applications can +be loaded simultaneously and are dispatched via cooperative multitasking on a +single stack. + +By default, the UEFI targets use the `link`-flavor of the LLVM linker `lld` to +link binaries into the final PE32+ file suffixed with `*.efi`. The PE subsystem +is set to `EFI_APPLICATION`, but can be modified by passing `/subsystem:<...>` +to the linker. Similarly, the entry-point is to to `efi_main` but can be +changed via `/entry:<...>`. The panic-strategy is set to `abort`, + +The UEFI specification is available online for free: +[UEFI Specification Directory](https://uefi.org/specifications) + +## Building rust for UEFI targets + +Rust can be built for the UEFI targets by enabling them in the `rustc` build +configuration. Note that you can only build the standard libraries. The +compiler and host tools currently cannot be compiled for UEFI targets. A sample +configuration would be: + +```toml +[build] +build-stage = 1 +target = ["x86_64-unknown-uefi"] +``` + +## 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 rust for UEFI targets" above), or build your own copy of `core` by +using `build-std`, `cargo-buildx`, or similar. + +A native build with the unstable `build-std`-feature can be achieved via: + +```sh +cargo +nightly build \ + -Zbuild-std=core,compiler_builtins \ + -Zbuild-std-features=compiler-builtins-mem \ + --target x86_64-unknown-uefi +``` + +Alternatively, you can install `cargo-xbuild` via +`cargo install --force cargo-xbuild` and build for the UEFI targets via: + +```sh +cargo \ + +nightly \ + xbuild \ + --target x86_64-unknown-uefi +``` + +## Testing + +UEFI applications can be copied into the ESP on any UEFI system and executed +via the firmware boot menu. The qemu suite allows emulating UEFI systems and +executing UEFI applications as well. See its documentation for details. + +The [uefi-run](https://github.com/Richard-W/uefi-run) rust tool is a simple +wrapper around `qemu` that can spawn UEFI applications in qemu. You can install +it via `cargo install uefi-run` and execute qemu applications as +`uefi-run ./application.efi`. + +## Cross-compilation toolchains and C code + +There are 3 common ways to compile native C code for UEFI targets: + +- Use the official SDK by Intel: + [Tianocore/EDK2](https://github.com/tianocore/edk2). This supports a + multitude of platforms, comes with the full specification transposed into C, + lots of examples and build-system integrations. This is also the only + officially supported platform by Intel, and is used by many major firmware + implementations. Any code compiled via the SDK is compatible to rust binaries + compiled for the UEFI targets. You can link them directly into your rust + binaries, or call into each other via UEFI protocols. +- Use the **GNU-EFI** suite. This approach is used by many UEFI applications + in the Linux/OSS ecosystem. The GCC compiler is used to compile ELF binaries, + and linked with a pre-loader that converts the ELF binary to PE32+ + **at runtime**. You can combine such binaries with the rust UEFI targets only + via UEFI protocols. Linking both into the same executable will fail, since + one is an ELF executable, and one a PE32+. If linking to **GNU-EFI** + executables is desired, you must compile your rust code natively for the same + GNU target as **GNU-EFI** and use their pre-loader. This requires careful + consideration about which calling-convention to use when calling into native + UEFI protocols, or calling into linked **GNU-EFI** code (similar to how these + differences need to be accounted for when writing **GNU-EFI** C code). +- Use native Windows targets. This means compiling your C code for the Windows + platform as if it was the UEFI platform. This works for static libraries, but + needs adjustments when linking into an UEFI executable. You can, however, + link such static libraries seemlessly into rust code compiled for UEFI + targets. Be wary of any includes that are not specifically suitable for UEFI + targets (especially the C standard library includes are not always + compatible). Freestanding compilations are recommended to avoid + incompatibilites. + +## Ecosystem + +The rust language has a long history of supporting UEFI targets. Many crates +have been developed to provide access to UEFI protocols and make UEFI +programming more ergonomic in rust. The following list is a short overview (in +alphabetical ordering): + +- **efi**: *Ergonomic Rust bindings for writing UEFI applications*. Provides + _rustified_ access to UEFI protocols, implements allocators and a safe + environment to write UEFI applications. +- **r-efi**: *UEFI Reference Specification Protocol Constants and Definitions*. + A pure transpose of the UEFI specification into rust. This provides the raw + definitions from the specification, without any extended helpers or + _rustification_. It serves as baseline to implement any more elaborate rust + UEFI layers. +- **uefi-rs**: *Safe and easy-to-use wrapper for building UEFI apps*. An + elaborate library providing safe abstractions for UEFI protocols and + features. It implements allocators and provides an execution environment to + UEFI applications written in rust. +- **uefi-run**: *Run UEFI applications*. A small wrapper around _qemu_ to spawn + UEFI applications in an emulated `x86_64` machine. + +## Example: Freestanding + +The following code is a valid UEFI application returning immediately upon +execution with an exit code of 0. A panic handler is provided. This is executed +by rust on panic. For simplicity, we simply end up in an infinite loop. + +Note that as of rust-1.31.0, all features used here are stabilized. No unstable +features are required, nor do we rely on nightly compilers. However, if you do +not compile rustc for the UEFI targets, you need a nightly compiler to support +the `-Z build-std` flag. + +This example can be compiled as binary crate via `cargo`: + +```sh +cargo +nightly build \ + -Zbuild-std=core,compiler_builtins \ + -Zbuild-std-features=compiler-builtins-mem \ + --target x86_64-unknown-uefi +``` + +```rust,ignore (platform-specific,eh-personality-is-unstable) +#![no_main] +#![no_std] + +#[panic_handler] +fn panic_handler(_info: &core::panic::PanicInfo) -> ! { + loop {} +} + +#[export_name = "efi_main"] +pub extern "C" fn main(_h: *mut core::ffi::c_void, _st: *mut core::ffi::c_void) -> usize { + 0 +} +``` + +## Example: Hello World + +This is an example UEFI application that prints "Hello World!", then waits for +key input before it exits. It serves as base example how to write UEFI +applications without any helper modules other than the standalone UEFI protocol +definitions provided by the `r-efi` crate. + +This extends the "Freestanding" example and builds upon its setup. See there +for instruction how to compile this as binary crate. + +Note that UEFI uses UTF-16 strings. Since rust literals are UTF-8, we have to +use an open-coded, zero-terminated, UTF-16 array as argument to +`output_string()`. Similarly to the panic handler, real applications should +rather use UTF-16 modules. + +```rust,ignore (platform-specific,eh-personality-is-unstable) +#![no_main] +#![no_std] + +use r_efi::efi; + +#[panic_handler] +fn panic_handler(_info: &core::panic::PanicInfo) -> ! { + loop {} +} + +#[export_name = "efi_main"] +pub extern "C" fn main(_h: efi::Handle, st: *mut efi::SystemTable) -> efi::Status { + let s = [ + 0x0048u16, 0x0065u16, 0x006cu16, 0x006cu16, 0x006fu16, // "Hello" + 0x0020u16, // " " + 0x0057u16, 0x006fu16, 0x0072u16, 0x006cu16, 0x0064u16, // "World" + 0x0021u16, // "!" + 0x000au16, // "\n" + 0x0000u16, // NUL + ]; + + // Print "Hello World!". + let r = + unsafe { ((*(*st).con_out).output_string)((*st).con_out, s.as_ptr() as *mut efi::Char16) }; + if r.is_error() { + return r; + } + + // Wait for key input, by waiting on the `wait_for_key` event hook. + let r = unsafe { + let mut x: usize = 0; + ((*(*st).boot_services).wait_for_event)(1, &mut (*(*st).con_in).wait_for_key, &mut x) + }; + if r.is_error() { + return r; + } + + efi::Status::SUCCESS +} +``` diff --git a/src/librustdoc/clean/mod.rs b/src/librustdoc/clean/mod.rs index 2f3ca41723d85..2f2fbc9d4ba8d 100644 --- a/src/librustdoc/clean/mod.rs +++ b/src/librustdoc/clean/mod.rs @@ -398,23 +398,19 @@ fn clean_type_outlives_predicate<'tcx>( }) } -impl<'tcx> Clean<'tcx, Term> for ty::Term<'tcx> { - fn clean(&self, cx: &mut DocContext<'tcx>) -> Term { - match self { - ty::Term::Ty(ty) => Term::Type(clean_middle_ty(*ty, cx, None)), - ty::Term::Const(c) => Term::Constant(clean_middle_const(*c, cx)), - } +fn clean_middle_term<'tcx>(term: ty::Term<'tcx>, cx: &mut DocContext<'tcx>) -> Term { + match term { + ty::Term::Ty(ty) => Term::Type(clean_middle_ty(ty, cx, None)), + ty::Term::Const(c) => Term::Constant(clean_middle_const(c, cx)), } } -impl<'tcx> Clean<'tcx, Term> for hir::Term<'tcx> { - fn clean(&self, cx: &mut DocContext<'tcx>) -> Term { - match self { - hir::Term::Ty(ty) => Term::Type(clean_ty(ty, cx)), - hir::Term::Const(c) => { - let def_id = cx.tcx.hir().local_def_id(c.hir_id); - Term::Constant(clean_middle_const(ty::Const::from_anon_const(cx.tcx, def_id), cx)) - } +fn clean_hir_term<'tcx>(term: &hir::Term<'tcx>, cx: &mut DocContext<'tcx>) -> Term { + match term { + hir::Term::Ty(ty) => Term::Type(clean_ty(ty, cx)), + hir::Term::Const(c) => { + let def_id = cx.tcx.hir().local_def_id(c.hir_id); + Term::Constant(clean_middle_const(ty::Const::from_anon_const(cx.tcx, def_id), cx)) } } } @@ -426,7 +422,7 @@ fn clean_projection_predicate<'tcx>( let ty::ProjectionPredicate { projection_ty, term } = pred; WherePredicate::EqPredicate { lhs: clean_projection(projection_ty, cx, None), - rhs: term.clean(cx), + rhs: clean_middle_term(term, cx), } } @@ -474,47 +470,44 @@ fn projection_to_path_segment<'tcx>( } } -impl<'tcx> Clean<'tcx, GenericParamDef> for ty::GenericParamDef { - fn clean(&self, cx: &mut DocContext<'tcx>) -> GenericParamDef { - let (name, kind) = match self.kind { - ty::GenericParamDefKind::Lifetime => { - (self.name, GenericParamDefKind::Lifetime { outlives: vec![] }) - } - ty::GenericParamDefKind::Type { has_default, synthetic, .. } => { - let default = if has_default { - Some(clean_middle_ty(cx.tcx.type_of(self.def_id), cx, Some(self.def_id))) - } else { - None - }; - ( - self.name, - GenericParamDefKind::Type { - did: self.def_id, - bounds: vec![], // These are filled in from the where-clauses. - default: default.map(Box::new), - synthetic, - }, - ) - } - ty::GenericParamDefKind::Const { has_default } => ( - self.name, - GenericParamDefKind::Const { - did: self.def_id, - ty: Box::new(clean_middle_ty( - cx.tcx.type_of(self.def_id), - cx, - Some(self.def_id), - )), - default: match has_default { - true => Some(Box::new(cx.tcx.const_param_default(self.def_id).to_string())), - false => None, - }, +fn clean_generic_param_def<'tcx>( + def: &ty::GenericParamDef, + cx: &mut DocContext<'tcx>, +) -> GenericParamDef { + let (name, kind) = match def.kind { + ty::GenericParamDefKind::Lifetime => { + (def.name, GenericParamDefKind::Lifetime { outlives: vec![] }) + } + ty::GenericParamDefKind::Type { has_default, synthetic, .. } => { + let default = if has_default { + Some(clean_middle_ty(cx.tcx.type_of(def.def_id), cx, Some(def.def_id))) + } else { + None + }; + ( + def.name, + GenericParamDefKind::Type { + did: def.def_id, + bounds: vec![], // These are filled in from the where-clauses. + default: default.map(Box::new), + synthetic, }, - ), - }; + ) + } + ty::GenericParamDefKind::Const { has_default } => ( + def.name, + GenericParamDefKind::Const { + did: def.def_id, + ty: Box::new(clean_middle_ty(cx.tcx.type_of(def.def_id), cx, Some(def.def_id))), + default: match has_default { + true => Some(Box::new(cx.tcx.const_param_default(def.def_id).to_string())), + false => None, + }, + }, + ), + }; - GenericParamDef { name, kind } - } + GenericParamDef { name, kind } } fn clean_generic_param<'tcx>( @@ -672,7 +665,7 @@ fn clean_ty_generics<'tcx>( .iter() .filter_map(|param| match param.kind { ty::GenericParamDefKind::Lifetime if param.name == kw::UnderscoreLifetime => None, - ty::GenericParamDefKind::Lifetime => Some(param.clean(cx)), + ty::GenericParamDefKind::Lifetime => Some(clean_generic_param_def(param, cx)), ty::GenericParamDefKind::Type { synthetic, .. } => { if param.name == kw::SelfUpper { assert_eq!(param.index, 0); @@ -682,9 +675,9 @@ fn clean_ty_generics<'tcx>( impl_trait.insert(param.index.into(), vec![]); return None; } - Some(param.clean(cx)) + Some(clean_generic_param_def(param, cx)) } - ty::GenericParamDefKind::Const { .. } => Some(param.clean(cx)), + ty::GenericParamDefKind::Const { .. } => Some(clean_generic_param_def(param, cx)), }) .collect::>(); @@ -1682,7 +1675,9 @@ pub(crate) fn clean_middle_ty<'tcx>( .projection_ty, cx, ), - kind: TypeBindingKind::Equality { term: pb.skip_binder().term.clean(cx) }, + kind: TypeBindingKind::Equality { + term: clean_middle_term(pb.skip_binder().term, cx), + }, }); } @@ -1746,7 +1741,7 @@ pub(crate) fn clean_middle_ty<'tcx>( Some(TypeBinding { assoc: projection_to_path_segment(proj.projection_ty, cx), kind: TypeBindingKind::Equality { - term: proj.term.clean(cx), + term: clean_middle_term(proj.term, cx), }, }) } else { @@ -2283,7 +2278,7 @@ impl<'tcx> Clean<'tcx, TypeBindingKind> for hir::TypeBindingKind<'tcx> { fn clean(&self, cx: &mut DocContext<'tcx>) -> TypeBindingKind { match *self { hir::TypeBindingKind::Equality { ref term } => { - TypeBindingKind::Equality { term: term.clean(cx) } + TypeBindingKind::Equality { term: clean_hir_term(term, cx) } } hir::TypeBindingKind::Constraint { bounds } => TypeBindingKind::Constraint { bounds: bounds.iter().filter_map(|b| b.clean(cx)).collect(), diff --git a/src/librustdoc/html/static/css/settings.css b/src/librustdoc/html/static/css/settings.css index e531e6ce6bbde..e82ec04263718 100644 --- a/src/librustdoc/html/static/css/settings.css +++ b/src/librustdoc/html/static/css/settings.css @@ -41,9 +41,7 @@ .toggle { position: relative; - display: inline-block; width: 100%; - height: 27px; margin-right: 20px; display: flex; align-items: center; @@ -58,6 +56,7 @@ .slider { position: relative; width: 45px; + min-width: 45px; display: block; height: 28px; margin-right: 20px; diff --git a/src/test/rustdoc-gui/settings.goml b/src/test/rustdoc-gui/settings.goml index 8a3365d3cc25e..d9cf5ee66140f 100644 --- a/src/test/rustdoc-gui/settings.goml +++ b/src/test/rustdoc-gui/settings.goml @@ -147,3 +147,12 @@ assert-false: "noscript section" javascript: false reload: assert-css: ("noscript section", {"display": "block"}) +javascript: true + +// Check for the display on small screen +show-text: true +reload: +size: (300, 1000) +click: "#settings-menu" +wait-for: "#settings" +assert-css: ("#settings .slider", {"width": "45px"}, ALL)