[TechnoPorg]

Stabilization report

Summary

These intrinsics allow using instructions from the RISC-V ratified scalar crypto extensions and bit manipulation extensions. This includes:

• The AES block cipher extensions Zkne and Zknd
• The SHA-2 extension Zknh
• The bit manipulation extension Zbkb
• The carry-less multiply extension Zbkc
• The cross-bar permutation extension Zbkx
• The SM4 block cipher extension Zksed
• The SM3 hash function extension Zksh

These have the potential to significantly accelerate cryptographic operations on both RV32 and RV64 devices.

Tracking:

• Tracking Issue for RISC-V Ratified Extensions Intrinsics rust#114544

What isn't stabilized

Other RISC-V ratified extension intrinsics, such as the packed SIMD extension P.

Design

Answers to unresolved questions

From the tracking issue:

Use usize for riscv32 or riscv64 specific intrinsics or use u32 and u64 respectively?

The conclusion in rust-lang/rust#114544 from the libs team is that for this set of intrinsics, u32/u64 are preferable. This matches the way they are used by current nightly consumers and feels more appropriate given that these operate on data and not addresses.

Feedback

Nightly use

• The sha2 crate uses these intrinsics for a nightly-only Zknh backend.
• https://github.com/nazar-pc/abundance uses these intrinsics for bit manipulation operations.
• https://github.com/sayantn/aes uses these intrinsics for an AES implementation.

In all of these, u32/u64 are more ergonomic than usize.

Breaking changes

None.

History

• Implement RISC-V Zk intrinsics #1453 implemented the Zk intrinsics
• Implement RISC-V Zb intrinsics  #1461 implemented the Zb intrinsics

Acknowledgments

• @coastalwhite for the implementation

Open items

• Requires Make RISC-V bit manipulation intrinsics match C API #2247
• Requires Remove rustc_legacy_const_generics from unstable intrinsics #2254
• Requires fuzz testing for intrinsics
• Tracking Issue for RISC-V Ratified Extensions Intrinsics rust#114544 (comment): do we want to add intrinsics for patterns that can be expressed in normal Rust code? cc @Amanieu as someone who has previously opposed this idea

---

No LLMs were used to write this PR.

[rustbot]

Thanks for the pull request, and welcome! The Rust Project has assigned @sayantn (or someone else) to review your changes, you should hear from them (or someone else) within the next two weeks.

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: @Amanieu, @adamgemmell, @davidtwco, @folkertdev, @sayantn
• @Amanieu, @adamgemmell, @davidtwco, @folkertdev, @sayantn expanded to Amanieu, adamgemmell, davidtwco, folkertdev, sayantn
• Random selection from Amanieu, adamgemmell, davidtwco, folkertdev, sayantn

[rustbot]

Error: The feature shortcut is not enabled in this repository.
To enable it add its section in the triagebot.toml in the root of the repository.

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #triagebot on Zulip.

[sayantn]

#2255

@rustbot reroll

[tgross35]

@rustbot blocked

Based on rust-lang/rust#114544 (comment), we'd like to change to match the C API first. We should make sure there is fuzz testing against C intrinsics as mentioned in #2221 (comment).

[rustbot]

Error: The feature shortcut is not enabled in this repository.
To enable it add its section in the triagebot.toml in the root of the repository.

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #triagebot on Zulip.

[TechnoPorg]

Based on rust-lang/rust#114544 (comment), we'd like to change to match the C API first.

I've just updated #2247 to match the C API.

We should make sure there is fuzz testing against C intrinsics as mentioned in #2221 (comment).

That seems reasonable. I can start on a branch for it now, but I'd ideally like to wait until #2247 and #2254 are merged so as to not be stuck in an endless cycle of rebases.

Error: The feature shortcut is not enabled in this repository.

I tried the same thing 😂

[tgross35]

As of commit fadf8b8, the stabilized API here matches https://github.com/riscv-non-isa/riscv-c-api-doc/blob/b3df26527b2fa27d7219b6d6abe775f6bd13615b/src/c-api.adoc "Scalar Bit Manipulation Extension Intrinsics", "Scalar Cryptography Extension Intrinsics", with the following exceptions that are available as API on integers:

• clz / ctz
• cpop
• ror / rol
• rev8 / brev8

Our naming and signatures now also match, with one exception: some AES functions take a bs=[0..3] or rnum=[0..10] const parameter that is int in C but u8 in our version. In theory this range could be expanded with future extensions, but it seems unlikely to ever exceed 255 so this seems fine.

We're also including the "Emulated with ... on RV64" API that is sometimes two instructions but can be optimized, also seems fine.

That's my mini stabilization report, I'm not going to propose FCP since it's not yet in its final form because of rustc_legacy_const_generic. Needs #2254 to merge, or feel free to remove the attributes here.

[TechnoPorg]

with the following exceptions that are available as API on integers

Do we want to make these available via intrinsics? There was some dissent in rust-lang/rust#114544 about it.

That's my mini stabilization report, I'm not going to propose FCP since it's not yet in its final form because of rustc_legacy_const_generic. Needs #2254 to merge, or feel free to remove the attributes here.

I think I might as well wait for #2254. Afaik I also still need to open a PR with fuzz testing of the intrinsics against the C API before they can be stabilized.

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[tgross35]

Do we want to make these available via intrinsics? There was some dissent in rust-lang/rust#114544 about it.

Nope, not for now. Maybe we'd want to add them later but I don't think we need to.

Afaik I also still need to open a PR with fuzz testing of the intrinsics against C API before they can be stabilized.

Ah, this hasn't been done yet? Feel free to open a draft if you have something started but need help.

Until then,
@rustbot blocked

[rustbot]

Error: The feature shortcut is not enabled in this repository.
To enable it add its section in the triagebot.toml in the root of the repository.

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #triagebot on Zulip.

[TechnoPorg]

Ah, this hasn't been done yet? Feel free to open a draft if you have something started but need help.

I haven't found a great source for the intrinsic definitions to use in intrinsic-test. I started on an stdarch-gen-riscv crate with the C headers, but for anything with a const parameter, they use macros which forward to __builtin_* functions, and we can't get types out of those. I think the next best option is just to write a manual JSON spec and parse that.

[tgross35]

What exactly do you need? You could grab a list from https://github.com/llvm/llvm-project/blob/fa5e5fcfc594f86297d0f3bfd3f15c37cfcb87c4/clang/lib/Headers/riscv_bitmanip.h.

[TechnoPorg]

The bitmanip ones are fine, but I'd also like the crypto intrinsic signatures, and a lot of them look like this:

https://github.com/llvm/llvm-project/blob/fa5e5fcfc594f86297d0f3bfd3f15c37cfcb87c4/clang/lib/Headers/riscv_crypto.h#L169-L172

[tgross35]

If you can put up a PR with what you have, somebody more familiar with the tests can probably give you a hand. Or you might be able to figure something out from the loongarch tests, which I believe has similar signatures.