sha2: document available backends (#690)

Author: newpavlov

sha2/README.md

@@ -59,6 +59,29 @@ assert_eq!(hash512, hex!(
 
 Also, see the [examples section] in the RustCrypto/hashes readme.
 
+## Backends
+
+This crate supports the following backends:
+- `soft`: portable implementation with fully unrolled rounds
+- `soft-compact`: portable implementation which produces smaller binaries
+- `aarch64-sha2`: uses the AArch64 `sha2` extension, fallbacks to the `soft` backend
+  if the extension is not available
+- `loongarch64-asm`: `asm!`-based implementation for LoongArch64 targets
+- `riscv-zknh`: uses the RISC-V `Zknh` scalar crypto extension (experimental)
+- `riscv-zknh-compact`: same as `riscv_zknh` but does not unroll rounds (experimental)
+- `wasm32-simd`: uses the WASM `simd128` extension
+- `x86-shani`: uses the x86 SHA-NI extension, fallbacks to the `soft` backend
+  if the extension is not available (SHA-256 only)
+- `x86-avx2`: uses the x86 AVX2 extension, fallbacks to the `soft` backend
+  if the extension is not available (SHA-512 only)
+
+You can force backend selection using the `sha2_backend` configuration flag. It can be enabled
+using either environment variable (e.g. `RUSTFLAGS='--cfg sha2_backend="soft"' cargo build`), or
+by modifying your `.cargo/config.toml` file. Currently the flag supports the following values:
+`soft`, `soft-compact`, `riscv-zknh`, and `riscv-zknh-compact`.
+
+Note that the RISC-V backends are experimental and require Nightly compiler.
+
 ## License
 
 The crate is licensed under either of:

sha2/src/sha256.rs

@@ -25,14 +25,14 @@ cfg_if::cfg_if! {
         use riscv_zknh_compact::compress;
     } else if #[cfg(target_arch = "aarch64")] {
         mod soft;
-        mod aarch64;
-        use aarch64::compress;
+        mod aarch64_sha2;
+        use aarch64_sha2::compress;
     } else if #[cfg(target_arch = "loongarch64")] {
         mod loongarch64_asm;
         use loongarch64_asm::compress;
     } else if #[cfg(all(target_arch = "wasm32", target_feature = "simd128"))] {
-        mod wasm32;
-        use wasm32::compress;
+        mod wasm32_simd128;
+        use wasm32_simd128::compress;
     } else {
         mod soft;
         use soft::compress;

sha2/src/sha256/aarch64.rs sha2/src/sha256/aarch64_sha2.rssha2/src/sha256/aarch64.rs renamed to sha2/src/sha256/aarch64_sha2.rs

@@ -25,14 +25,14 @@ cfg_if::cfg_if! {
         use riscv_zknh_compact::compress;
     } else if #[cfg(target_arch = "aarch64")] {
         mod soft;
-        mod aarch64;
-        use aarch64::compress;
+        mod aarch64_sha2;
+        use aarch64_sha2::compress;
     } else if #[cfg(target_arch = "loongarch64")] {
         mod loongarch64_asm;
         use loongarch64_asm::compress;
     } else if #[cfg(all(target_arch = "wasm32", target_feature = "simd128"))] {
-        mod wasm32;
-        use wasm32::compress;
+        mod wasm32_simd128;
+        use wasm32_simd128::compress;
     } else {
         mod soft;
         use soft::compress;