Specify bit validity and padding of some types

.github/workflows/main.yml

@@ -1,5 +1,7 @@
 name: CI
-on: [push, pull_request]
+on:
+  pull_request:
+  merge_group:
 
 jobs:
   test:

book.toml

@@ -6,9 +6,12 @@ author = "The Rust Project Developers"
 [output.html]
 additional-css = ["theme/reference.css"]
 git-repository-url = "https://github.com/rust-lang/reference/"
+edit-url-template = "https://github.com/rust-lang/reference/edit/master/{path}"
 
 [output.html.redirect]
 "/expressions/enum-variant-expr.html" = "struct-expr.html"
+"/unsafe-blocks.html" = "unsafe-keyword.html"
+"/unsafe-functions.html" = "unsafe-keyword.html"
 
 [rust]
 edition = "2021"

src/SUMMARY.md

@@ -44,6 +44,7 @@
     - [Code generation](attributes/codegen.md)
     - [Limits](attributes/limits.md)
     - [Type System](attributes/type_system.md)
+    - [Debugger](attributes/debugger.md)
 
 - [Statements and expressions](statements-and-expressions.md)
     - [Statements](statements.md)
@@ -118,8 +119,7 @@
 - [Inline assembly](inline-assembly.md)
 
 - [Unsafety](unsafety.md)
-    - [Unsafe functions](unsafe-functions.md)
-    - [Unsafe blocks](unsafe-blocks.md)
+    - [The `unsafe` keyword](unsafe-keyword.md)
     - [Behavior considered undefined](behavior-considered-undefined.md)
     - [Behavior not considered unsafe](behavior-not-considered-unsafe.md)
 

src/attributes.md

@@ -228,6 +228,8 @@ The following is an index of all built-in attributes.
   - [`link`] — Specifies a native library to link with an `extern` block.
   - [`link_name`] — Specifies the name of the symbol for functions or statics
     in an `extern` block.
+  - [`link_ordinal`] — Specifies the ordinal of the symbol for functions or
+    statics in an `extern` block.
   - [`no_link`] — Prevents linking an extern crate.
   - [`repr`] — Controls type layout.
   - [`crate_type`] — Specifies the type of crate (library, executable, etc.).
@@ -246,6 +248,7 @@ The following is an index of all built-in attributes.
   - [`no_builtins`] — Disables use of certain built-in functions.
   - [`target_feature`] — Configure platform-specific code generation.
   - [`track_caller`] - Pass the parent call location to `std::panic::Location::caller()`.
+  - [`instruction_set`] - Specify the instruction set used to generate a functions code
 - Documentation
   - `doc` — Specifies documentation. See [The Rustdoc Book] for more
     information. [Doc comments] are transformed into `doc` attributes.
@@ -268,6 +271,8 @@ The following is an index of all built-in attributes.
 - Type System
   - [`non_exhaustive`] — Indicate that a type will have more fields/variants
     added in future.
+- Debugger
+  - [`debugger_visualizer`] — Embeds a file that specifies debugger output for a type.
 
 [Doc comments]: comments.md#doc-comments
 [ECMA-334]: https://www.ecma-international.org/publications/standards/Ecma-334.htm
@@ -288,6 +293,7 @@ The following is an index of all built-in attributes.
 [`cold`]: attributes/codegen.md#the-cold-attribute
 [`crate_name`]: crates-and-source-files.md#the-crate_name-attribute
 [`crate_type`]: linkage.md
+[`debugger_visualizer`]: attributes/debugger.md#the-debugger_visualizer-attribute
 [`deny`]: attributes/diagnostics.md#lint-check-attributes
 [`deprecated`]: attributes/diagnostics.md#the-deprecated-attribute
 [`derive`]: attributes/derive.md
@@ -296,7 +302,9 @@ The following is an index of all built-in attributes.
 [`global_allocator`]: runtime.md#the-global_allocator-attribute
 [`ignore`]: attributes/testing.md#the-ignore-attribute
 [`inline`]: attributes/codegen.md#the-inline-attribute
+[`instruction_set`]: attributes/codegen.md#the-instruction_set-attribute
 [`link_name`]: items/external-blocks.md#the-link_name-attribute
+[`link_ordinal`]: items/external-blocks.md#the-link_ordinal-attribute
 [`link_section`]: abi.md#the-link_section-attribute
 [`link`]: items/external-blocks.md#the-link-attribute
 [`macro_export`]: macros-by-example.md#path-based-scope

src/attributes/codegen.md

@@ -63,7 +63,8 @@ error to specify a feature for a target architecture that the crate is not
 being compiled for.
 
 It is [undefined behavior] to call a function that is compiled with a feature
-that is not supported on the current platform the code is running on.
+that is not supported on the current platform the code is running on, *except*
+if the platform explicitly documents this to be safe.
 
 Functions marked with `target_feature` are not inlined into a context that
 does not support the given features. The `#[inline(always)]` attribute may not
@@ -75,19 +76,24 @@ The following is a list of the available feature names.
 
 #### `x86` or `x86_64`
 
-This platform requires that `#[target_feature]` is only applied to [`unsafe`
+Executing code with unsupported features is undefined behavior on this platform.
+Hence this platform requires that `#[target_feature]` is only applied to [`unsafe`
 functions][unsafe function].
 
 Feature     | Implicitly Enables | Description
 ------------|--------------------|-------------------
+`adx`       |          | [ADX] — Multi-Precision Add-Carry Instruction Extensions
 `aes`       | `sse2`   | [AES] — Advanced Encryption Standard
 `avx`       | `sse4.2` | [AVX] — Advanced Vector Extensions
 `avx2`      | `avx`    | [AVX2] — Advanced Vector Extensions 2
 `bmi1`      |          | [BMI1] — Bit Manipulation Instruction Sets
 `bmi2`      |          | [BMI2] — Bit Manipulation Instruction Sets 2
+`cmpxchg16b`|          | [`cmpxchg16b`] - Compares and exchange 16 bytes (128 bits) of data atomically
+`f16c`      | `avx`    | [F16C] — 16-bit floating point conversion instructions
 `fma`       | `avx`    | [FMA3] — Three-operand fused multiply-add
 `fxsr`      |          | [`fxsave`] and [`fxrstor`] — Save and restore x87 FPU, MMX Technology, and SSE State
 `lzcnt`     |          | [`lzcnt`] — Leading zeros count
+`movbe`     |          | [`movbe`] - Move data after swapping bytes
 `pclmulqdq` | `sse2`   | [`pclmulqdq`] — Packed carry-less multiplication quadword
 `popcnt`    |          | [`popcnt`] — Count of bits set to 1
 `rdrand`    |          | [`rdrand`] — Read random number
@@ -106,15 +112,19 @@ Feature     | Implicitly Enables | Description
 
 <!-- Keep links near each table to make it easier to move and update. -->
 
+[ADX]: https://en.wikipedia.org/wiki/Intel_ADX
 [AES]: https://en.wikipedia.org/wiki/AES_instruction_set
 [AVX]: https://en.wikipedia.org/wiki/Advanced_Vector_Extensions
 [AVX2]: https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#AVX2
 [BMI1]: https://en.wikipedia.org/wiki/Bit_Manipulation_Instruction_Sets
 [BMI2]: https://en.wikipedia.org/wiki/Bit_Manipulation_Instruction_Sets#BMI2
+[`cmpxchg16b`]: https://www.felixcloutier.com/x86/cmpxchg8b:cmpxchg16b
+[F16C]: https://en.wikipedia.org/wiki/F16C
 [FMA3]: https://en.wikipedia.org/wiki/FMA_instruction_set
 [`fxsave`]: https://www.felixcloutier.com/x86/fxsave
 [`fxrstor`]: https://www.felixcloutier.com/x86/fxrstor
 [`lzcnt`]: https://www.felixcloutier.com/x86/lzcnt
+[`movbe`]: https://www.felixcloutier.com/x86/movbe
 [`pclmulqdq`]: https://www.felixcloutier.com/x86/pclmulqdq
 [`popcnt`]: https://www.felixcloutier.com/x86/popcnt
 [`rdrand`]: https://en.wikipedia.org/wiki/RdRand
@@ -131,10 +141,77 @@ Feature     | Implicitly Enables | Description
 [`xsaveopt`]: https://www.felixcloutier.com/x86/xsaveopt
 [`xsaves`]: https://www.felixcloutier.com/x86/xsaves
 
+#### `aarch64`
+
+This platform requires that `#[target_feature]` is only applied to [`unsafe`
+functions][unsafe function].
+
+Further documentation on these features can be found in the [ARM Architecture
+Reference Manual], or elsewhere on [developer.arm.com].
+
+[ARM Architecture Reference Manual]: https://developer.arm.com/documentation/ddi0487/latest
+[developer.arm.com]: https://developer.arm.com
+
+> ***Note***: The following pairs of features should both be marked as enabled
+> or disabled together if used:
+> - `paca` and `pacg`, which LLVM currently implements as one feature.
+
+
+Feature        | Implicitly Enables | Feature Name
+---------------|--------------------|-------------------
+`aes`          | `neon`         | FEAT_AES - Advanced <abbr title="Single Instruction Multiple Data">SIMD</abbr> AES instructions
+`bf16`         |                | FEAT_BF16 - BFloat16 instructions
+`bti`          |                | FEAT_BTI - Branch Target Identification
+`crc`          |                | FEAT_CRC - CRC32 checksum instructions
+`dit`          |                | FEAT_DIT - Data Independent Timing instructions
+`dotprod`      |                | FEAT_DotProd - Advanced SIMD Int8 dot product instructions
+`dpb`          |                | FEAT_DPB - Data cache clean to point of persistence
+`dpb2`         |                | FEAT_DPB2 - Data cache clean to point of deep persistence
+`f32mm`        | `sve`          | FEAT_F32MM - SVE single-precision FP matrix multiply instruction
+`f64mm`        | `sve`          | FEAT_F64MM - SVE double-precision FP matrix multiply instruction
+`fcma`         | `neon`         | FEAT_FCMA - Floating point complex number support
+`fhm`          | `fp16`         | FEAT_FHM - Half-precision FP FMLAL instructions
+`flagm`        |                | FEAT_FlagM - Conditional flag manipulation
+`fp16`         | `neon`         | FEAT_FP16 - Half-precision FP data processing
+`frintts`      |                | FEAT_FRINTTS - Floating-point to int helper instructions
+`i8mm`         |                | FEAT_I8MM - Int8 Matrix Multiplication
+`jsconv`       | `neon`         | FEAT_JSCVT - JavaScript conversion instruction
+`lse`          |                | FEAT_LSE - Large System Extension
+`lor`          |                | FEAT_LOR - Limited Ordering Regions extension
+`mte`          |                | FEAT_MTE - Memory Tagging Extension
+`neon`         |                | FEAT_FP & FEAT_AdvSIMD - Floating Point and Advanced SIMD extension
+`pan`          |                | FEAT_PAN - Privileged Access-Never extension
+`paca`         |                | FEAT_PAuth - Pointer Authentication (address authentication)
+`pacg`         |                | FEAT_PAuth - Pointer Authentication (generic authentication)
+`pmuv3`        |                | FEAT_PMUv3 - Performance Monitors extension (v3)
+`rand`         |                | FEAT_RNG - Random Number Generator
+`ras`          |                | FEAT_RAS - Reliability, Availability and Serviceability extension
+`rcpc`         |                | FEAT_LRCPC - Release consistent Processor Consistent
+`rcpc2`        | `rcpc`         | FEAT_LRCPC2 - RcPc with immediate offsets
+`rdm`          |                | FEAT_RDM - Rounding Double Multiply accumulate
+`sb`           |                | FEAT_SB - Speculation Barrier
+`sha2`         | `neon`         | FEAT_SHA1 & FEAT_SHA256 - Advanced SIMD SHA instructions
+`sha3`         | `sha2`         | FEAT_SHA512 & FEAT_SHA3 - Advanced SIMD SHA instructions
+`sm4`          | `neon`         | FEAT_SM3 & FEAT_SM4 - Advanced SIMD SM3/4 instructions
+`spe`          |                | FEAT_SPE - Statistical Profiling Extension
+`ssbs`         |                | FEAT_SSBS - Speculative Store Bypass Safe
+`sve`          | `fp16`         | FEAT_SVE - Scalable Vector Extension
+`sve2`         | `sve`          | FEAT_SVE2 - Scalable Vector Extension 2
+`sve2-aes`     | `sve2`, `aes`  | FEAT_SVE_AES - SVE AES instructions
+`sve2-sm4`     | `sve2`, `sm4`  | FEAT_SVE_SM4 - SVE SM4 instructions
+`sve2-sha3`    | `sve2`, `sha3` | FEAT_SVE_SHA3 - SVE SHA3 instructions
+`sve2-bitperm` | `sve2`         | FEAT_SVE_BitPerm - SVE Bit Permute
+`tme`          |                | FEAT_TME - Transactional Memory Extension
+`vh`           |                | FEAT_VHE - Virtualization Host Extensions
+
 #### `wasm32` or `wasm64`
 
-This platform allows `#[target_feature]` to be applied to both safe and
-[`unsafe` functions][unsafe function].
+`#[target_feature]` may be used with both safe and
+[`unsafe` functions][unsafe function] on Wasm platforms. It is impossible to
+cause undefined behavior via the `#[target_feature]` attribute because
+attempting to use instructions unsupported by the Wasm engine will fail at load
+time without the risk of being interpreted in a way different from what the
+compiler expected.
 
 Feature     | Description
 ------------|-------------------
@@ -149,8 +226,8 @@ enabling or disabling compilation of code based on compile-time settings. Note
 that this option is not affected by the `target_feature` attribute, and is
 only driven by the features enabled for the entire crate.
 
-See the [`is_x86_feature_detected`] macro in the standard library for runtime
-feature detection on the x86 platforms.
+See the [`is_x86_feature_detected`] or [`is_aarch64_feature_detected`] macros
+in the standard library for runtime feature detection on these platforms.
 
 > Note: `rustc` has a default set of features enabled for each target and CPU.
 > The CPU may be chosen with the [`-C target-cpu`] flag. Individual features
@@ -267,16 +344,48 @@ trait object whose methods are attributed.
 [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
 [`-C target-cpu`]: ../../rustc/codegen-options/index.html#target-cpu
 [`-C target-feature`]: ../../rustc/codegen-options/index.html#target-feature
-[`is_x86_feature_detected`]: ../../std/macro.is_x86_feature_detected.html
+[`is_x86_feature_detected`]: ../../std/arch/macro.is_x86_feature_detected.html
+[`is_aarch64_feature_detected`]: ../../std/arch/macro.is_aarch64_feature_detected.html
 [`target_feature` conditional compilation option]: ../conditional-compilation.md#target_feature
 [attribute]: ../attributes.md
 [attributes]: ../attributes.md
 [functions]: ../items/functions.md
 [target architecture]: ../conditional-compilation.md#target_arch
 [trait]: ../items/traits.md
 [undefined behavior]: ../behavior-considered-undefined.md
-[unsafe function]: ../unsafe-functions.md
+[unsafe function]: ../unsafe-keyword.md
 [rust-abi]: ../items/external-blocks.md#abi
 [`core::intrinsics::caller_location`]: ../../core/intrinsics/fn.caller_location.html
 [`core::panic::Location::caller`]: ../../core/panic/struct.Location.html#method.caller
 [`Location`]: ../../core/panic/struct.Location.html
+
+## The `instruction_set` attribute
+
+The *`instruction_set` [attribute]* may be applied to a function to control which instruction set the function will be generated for.
+This allows mixing more than one instruction set in a single program on CPU architectures that support it.
+It uses the [_MetaListPath_] syntax, and a path comprised of the architecture family name and instruction set name.
+
+[_MetaListPath_]: ../attributes.md#meta-item-attribute-syntax
+
+It is a compilation error to use the `instruction_set` attribute on a target that does not support it.
+
+### On ARM
+
+For the `ARMv4T` and `ARMv5te` architectures, the following are supported:
+
+* `arm::a32` - Generate the function as A32 "ARM" code.
+* `arm::t32` - Generate the function as T32 "Thumb" code.
+
+<!-- ignore: arm-only -->
+```rust,ignore
+#[instruction_set(arm::a32)]
+fn foo_arm_code() {}
+
+#[instruction_set(arm::t32)]
+fn bar_thumb_code() {}
+```
+
+Using the `instruction_set` attribute has the following effects:
+
+* If the address of the function is taken as a function pointer, the low bit of the address will be set to 0 (arm) or 1 (thumb) depending on the instruction set.
+* Any inline assembly in the function must use the specified instruction set instead of the target default.