search

rust-lang / stdarch

Rust's standard library vendor-specific APIs and run-time feature detection
https://doc.rust-lang.org/stable/core/arch/
Apache License 2.0
600 stars 265 forks source link

Make sure intrinsics for all architectures appear in rustdoc #1055

Open Amanieu opened 3 years ago

Amanieu commented 3 years ago

Conceptually this is quite simple, wherever there is a cfg that checks for a particular target_arch, we also need to enable it if doc is true. We then need to tell rustdoc that the intrinsic is only available on a particular architecture with #[cfg(doc(target_arch = "..."))].

Basically we turn this:

#[cfg(target_arch = "arm")]

Into this:

#[cfg(any(target_arch = "arm", doc))]
#[doc(cfg(target_arch = "arm"))]

A quick search shows the following uses of target_arch that need to be fixed:

crates/core_arch/src/acle/hints.rs:
   12: #[cfg(any(target_feature = "v6", target_arch = "aarch64"))]
   25: #[cfg(any(target_feature = "v6", target_arch = "aarch64"))]
   37: #[cfg(any(target_feature = "v6", target_arch = "aarch64"))]
   65: #[cfg(any(target_feature = "v6", target_arch = "aarch64"))]

crates/core_arch/src/acle/mod.rs:
  94: #[cfg(all(not(target_arch = "aarch64"), target_feature = "v6",))]
  97: #[cfg(all(not(target_arch = "aarch64"), target_feature = "v6",))]

crates/core_arch/src/acle/barrier/mod.rs:
  59: #[cfg(any(target_arch = "aarch64", target_feature = "v7",))]
  62: #[cfg(any(target_arch = "aarch64", target_feature = "v7",))]
  65: #[cfg(target_arch = "aarch64")]
  68: #[cfg(target_arch = "aarch64")]

crates/core_arch/src/acle/registers/mod.rs:
   61: #[cfg(not(target_arch = "aarch64"))]
   64: #[cfg(not(target_arch = "aarch64"))]
   77: #[cfg(target_arch = "aarch64")]
  105: #[cfg(target_arch = "aarch64")]

crates/core_arch/src/arm/mod.rs:
  17: #[cfg(any(target_arch = "aarch64", target_feature = "v7"))]
  19: #[cfg(any(target_arch = "aarch64", target_feature = "v7"))]
  22: #[cfg(any(target_arch = "aarch64", target_feature = "v7", doc))]
  24: #[cfg(any(target_arch = "aarch64", target_feature = "v7", doc))]
  27: #[cfg(any(target_arch = "aarch64", target_feature = "v7"))]
  29: #[cfg(any(target_arch = "aarch64", target_feature = "v7"))]
  32: #[cfg(any(target_arch = "aarch64", target_feature = "v7"))]
  34: #[cfg(any(target_arch = "aarch64", target_feature = "v7"))]
  43: #[cfg(target_arch = "arm")]
  51: #[cfg(any(target_arch = "aarch64", target_feature = "v7"))]

crates/core_arch/src/arm/neon/load_tests.rs:
    7: #[cfg(target_arch = "arm")]
   10: #[cfg(target_arch = "aarch64")]
  192: #[cfg(target_arch = "aarch64")]
  201: #[cfg(target_arch = "aarch64")]

crates/core_arch/src/arm/neon/mod.rs:
     8: #[cfg(target_arch = "arm")]
   297: #[cfg(target_arch = "arm")]
   392: #[cfg(target_arch = "arm")]
   401: #[cfg(target_arch = "arm")]
   410: #[cfg(target_arch = "arm")]
   419: #[cfg(target_arch = "arm")]
   428: #[cfg(target_arch = "arm")]
   437: #[cfg(target_arch = "arm")]
   446: #[cfg(target_arch = "arm")]
   455: #[cfg(target_arch = "arm")]
   464: #[cfg(target_arch = "arm")]
   473: #[cfg(target_arch = "arm")]
   482: #[cfg(target_arch = "arm")]
   491: #[cfg(target_arch = "arm")]
   500: #[cfg(target_arch = "arm")]
   509: #[cfg(target_arch = "arm")]
   518: #[cfg(target_arch = "arm")]
   527: #[cfg(target_arch = "arm")]
   536: #[cfg(target_arch = "arm")]
   545: #[cfg(target_arch = "arm")]
   554: #[cfg(target_arch = "arm")]
   563: #[cfg(target_arch = "arm")]
   572: #[cfg(target_arch = "arm")]
   581: #[cfg(target_arch = "arm")]
  3039: #[cfg(target_arch = "arm")]
  3049: #[cfg(target_arch = "arm")]
  3059: #[cfg(target_arch = "arm")]
  3069: #[cfg(target_arch = "arm")]
  3079: #[cfg(target_arch = "arm")]
  3089: #[cfg(target_arch = "arm")]
  3099: #[cfg(target_arch = "arm")]
  3109: #[cfg(target_arch = "arm")]
  3124: #[cfg(target_arch = "arm")]
  3139: #[cfg(target_arch = "arm")]
  3149: #[cfg(target_arch = "arm")]
  3165: #[cfg(target_arch = "arm")]
  3181: #[cfg(target_arch = "arm")]
  3191: #[cfg(target_arch = "arm")]
  3201: #[cfg(target_arch = "arm")]
  3211: #[cfg(target_arch = "arm")]
  3221: #[cfg(target_arch = "arm")]
  3236: #[cfg(target_arch = "arm")]
  3251: #[cfg(target_arch = "arm")]
  3261: #[cfg(target_arch = "arm")]
  3277: #[cfg(target_arch = "arm")]
  3293: #[cfg(target_arch = "arm")]
  3303: #[cfg(target_arch = "arm")]
  3320: #[cfg(target_arch = "arm")]
  3783: #[cfg(target_arch = "arm")]
  3793: #[cfg(target_arch = "arm")]
  3858: #[cfg(target_arch = "arm")]
  3869: #[cfg(target_arch = "arm")]
  3884: #[cfg(target_arch = "arm")]
  3895: #[cfg(target_arch = "arm")]
  3906: #[cfg(target_arch = "arm")]
  3916: #[cfg(target_arch = "arm")]
  3926: #[cfg(target_arch = "arm")]
  3936: #[cfg(target_arch = "arm")]
  3946: #[cfg(target_arch = "arm")]
  3961: #[cfg(target_arch = "arm")]
  3976: #[cfg(target_arch = "arm")]
  3991: #[cfg(target_arch = "arm")]
  4006: #[cfg(target_arch = "arm")]
  4016: #[cfg(target_arch = "arm")]
  4030: #[cfg(target_arch = "arm")]
  4044: #[cfg(target_arch = "arm")]
  4058: #[cfg(target_arch = "arm")]
  4073: #[cfg(target_arch = "arm")]
  4088: #[cfg(target_arch = "arm")]
  4103: #[cfg(target_arch = "arm")]
  4119: #[cfg(target_arch = "arm")]
  4130: #[cfg(target_arch = "arm")]
  4145: #[cfg(target_arch = "arm")]
  4156: #[cfg(target_arch = "arm")]
  4167: #[cfg(target_arch = "arm")]
  4177: #[cfg(target_arch = "arm")]
  4187: #[cfg(target_arch = "arm")]
  4197: #[cfg(target_arch = "arm")]
  4207: #[cfg(target_arch = "arm")]
  4222: #[cfg(target_arch = "arm")]
  4237: #[cfg(target_arch = "arm")]
  4252: #[cfg(target_arch = "arm")]
  4267: #[cfg(target_arch = "arm")]
  4281: #[cfg(target_arch = "arm")]
  4295: #[cfg(target_arch = "arm")]
  4309: #[cfg(target_arch = "arm")]
  4323: #[cfg(target_arch = "arm")]
  4338: #[cfg(target_arch = "arm")]
  4353: #[cfg(target_arch = "arm")]
  4368: #[cfg(target_arch = "arm")]

crates/core_arch/src/x86/tbm.rs:
   84: #[cfg(not(target_arch = "x86"))] // generates lots of instructions
  107: #[cfg(not(target_arch = "x86"))] // generates lots of instructions
  130: #[cfg(not(target_arch = "x86"))] // generates lots of instructions
  155: #[cfg(not(target_arch = "x86"))] // generates lots of instructions
  178: #[cfg(not(target_arch = "x86"))] // generates lots of instructions
  201: #[cfg(not(target_arch = "x86"))] // generates lots of instructions
  224: #[cfg(not(target_arch = "x86"))] // generates lots of instructions
  249: #[cfg(not(target_arch = "x86"))] // generates lots of instructions
  274: #[cfg(not(target_arch = "x86"))] // generates lots of instructions

crates/core_arch/src/x86_64/bmi.rs:
  22: #[cfg(not(target_arch = "x86"))]
  38: #[cfg(not(target_arch = "x86"))]
  61: #[cfg(not(target_arch = "x86"))] // generates lots of instructions
  73: #[cfg(not(target_arch = "x86"))] // generates lots of instructions
  87: #[cfg(not(target_arch = "x86"))] // generates lots of instructions

crates/core_arch/src/x86_64/bmi2.rs:
  25: #[cfg(not(target_arch = "x86"))] // calls an intrinsic
  39: #[cfg(not(target_arch = "x86"))]
  52: #[cfg(not(target_arch = "x86"))]
  65: #[cfg(not(target_arch = "x86"))]
Byron commented 3 years ago

Do I understand correctly that a side effect of this issue is the disappearance of ARMv8 cryptography extensions which would help fixing an issue with Sha1/2 asm builds on Apple Silicon (and maybe others)?

If so and the fix truly is what’s described here then I could try to submit a PR as it prevents gitoxide from outperforming git on my machine 😅.

Amanieu commented 3 years ago

I haven't looked at the cryptographic extensions in detail, but it should be fairly easy to resolve. In the longer term we need better code organization in the ARM code to separate:

Byron commented 3 years ago

I think I should be able to produce a simple PR based on the suggestion here as TARGET=aarch64-apple-darwin cargo test already runs all tests successfully on nightly in the core_arch crate. That should be all that's needed to be reasonably sure the change isn't entirely broken.