spec: scalar - editorial issues.

Hat tip to Peter on the ISA dev mailing list for these. https://groups.google.com/a/groups.riscv.org/g/isa-dev/c/u3xzVkXhBx8/m/E1mFrjNsBAAJ On branch master Your branch is up-to-date with 'origin/master'. Changes to be committed: modified: insns/sha256sig0.adoc modified: insns/sha256sig1.adoc modified: insns/sha256sum0.adoc modified: insns/sha256sum1.adoc modified: insns/sha512sig0h.adoc modified: insns/sha512sig0l.adoc modified: insns/sha512sig1h.adoc modified: insns/sha512sig1l.adoc modified: insns/sm4ed.adoc modified: insns/sm4ks.adoc modified: riscv-crypto-scalar-audience.adoc modified: riscv-crypto-scalar-policies.adoc modified: riscv-crypto-scalar-sail-specifications.adoc modified: riscv-crypto-scalar-zbkb.adoc modified: riscv-crypto-scalar-zbkc.adoc modified: riscv-crypto-scalar-zbkx.adoc modified: riscv-crypto-scalar-zknd.adoc modified: riscv-crypto-scalar-zkne.adoc modified: riscv-crypto-spec-scalar.adoc Changes not staged for commit: modified: ../../extern/riscv-gnu-toolchain (modified content) modified: ../../extern/sail-riscv (untracked content)
riscv · Sep 8, 2021 · 9fae816 · 9fae816
1 parent c541916
commit 9fae816
Show file tree

Hide file tree

Showing 19 changed files with 36 additions and 23 deletions.
diff --git a/doc/scalar/insns/sha256sig0.adoc b/doc/scalar/insns/sha256sig0.adoc
@@ -25,7 +25,7 @@ Encoding::
 Description:: 
 This instruction is supported for both RV32 and RV64 base architectures.
 For RV32, the entire `XLEN` source register is operated on.
-For RV64, the low `32` bits of the source register is operated on, and the
+For RV64, the low `32` bits of the source register are operated on, and the
 result sign extended to `XLEN` bits.
 Though named for SHA2-256, the instruction works for both the
 SHA2-224 and SHA2-256 parameterisations as described in

diff --git a/doc/scalar/insns/sha256sig1.adoc b/doc/scalar/insns/sha256sig1.adoc
@@ -25,7 +25,7 @@ Encoding::
 Description:: 
 This instruction is supported for both RV32 and RV64 base architectures.
 For RV32, the entire `XLEN` source register is operated on.
-For RV64, the low `32` bits of the source register is operated on, and the
+For RV64, the low `32` bits of the source register are operated on, and the
 result sign extended to `XLEN` bits.
 Though named for SHA2-256, the instruction works for both the
 SHA2-224 and SHA2-256 parameterisations as described in

diff --git a/doc/scalar/insns/sha256sum0.adoc b/doc/scalar/insns/sha256sum0.adoc
@@ -25,7 +25,7 @@ Encoding::
 Description:: 
 This instruction is supported for both RV32 and RV64 base architectures.
 For RV32, the entire `XLEN` source register is operated on.
-For RV64, the low `32` bits of the source register is operated on, and the
+For RV64, the low `32` bits of the source register are operated on, and the
 result sign extended to `XLEN` bits.
 Though named for SHA2-256, the instruction works for both the
 SHA2-224 and SHA2-256 parameterisations as described in

diff --git a/doc/scalar/insns/sha256sum1.adoc b/doc/scalar/insns/sha256sum1.adoc
@@ -25,7 +25,7 @@ Encoding::
 Description:: 
 This instruction is supported for both RV32 and RV64 base architectures.
 For RV32, the entire `XLEN` source register is operated on.
-For RV64, the low `32` bits of the source register is operated on, and the
+For RV64, the low `32` bits of the source register are operated on, and the
 result sign extended to `XLEN` bits.
 Though named for SHA2-256, the instruction works for both the
 SHA2-224 and SHA2-256 parameterisations as described in

diff --git a/doc/scalar/insns/sha512sig0h.adoc b/doc/scalar/insns/sha512sig0h.adoc
@@ -27,7 +27,7 @@ This instruction is implemented on RV32 only.
 Used to compute the Sigma0 transform of the SHA2-512 hash function
 in conjunction with the <<insns-sha512sig0l,`sha512sig0l`>> instruction.
 The transform is a 64-bit to 64-bit function, so the input and output
-is represented by two 32-bit registers.
+are each represented by two 32-bit registers.
 This instruction must _always_ be implemented such that its execution
 latency does not depend on the data being operated on.
 

diff --git a/doc/scalar/insns/sha512sig0l.adoc b/doc/scalar/insns/sha512sig0l.adoc
@@ -27,7 +27,7 @@ This instruction is implemented on RV32 only.
 Used to compute the Sigma0 transform of the SHA2-512 hash function
 in conjunction with the <<insns-sha512sig0h,`sha512sig0h`>> instruction.
 The transform is a 64-bit to 64-bit function, so the input and output
-is represented by two 32-bit registers.
+are each represented by two 32-bit registers.
 This instruction must _always_ be implemented such that its execution
 latency does not depend on the data being operated on.
 

diff --git a/doc/scalar/insns/sha512sig1h.adoc b/doc/scalar/insns/sha512sig1h.adoc
@@ -27,7 +27,7 @@ This instruction is implemented on RV32 only.
 Used to compute the Sigma1 transform of the SHA2-512 hash function
 in conjunction with the <<insns-sha512sig1l,`sha512sig1l`>> instruction.
 The transform is a 64-bit to 64-bit function, so the input and output
-is represented by two 32-bit registers.
+are each represented by two 32-bit registers.
 This instruction must _always_ be implemented such that its execution
 latency does not depend on the data being operated on.
 

diff --git a/doc/scalar/insns/sha512sig1l.adoc b/doc/scalar/insns/sha512sig1l.adoc
@@ -27,7 +27,7 @@ This instruction is implemented on RV32 only.
 Used to compute the Sigma1 transform of the SHA2-512 hash function
 in conjunction with the <<insns-sha512sig1h,`sha512sig1h`>> instruction.
 The transform is a 64-bit to 64-bit function, so the input and output
-is represented by two 32-bit registers.
+are each represented by two 32-bit registers.
 This instruction must _always_ be implemented such that its execution
 latency does not depend on the data being operated on.
 

diff --git a/doc/scalar/insns/sm4ed.adoc b/doc/scalar/insns/sm4ed.adoc
@@ -29,7 +29,7 @@ A byte is extracted from `rs2` based on `bs`, to which the SBox and
 linear layer transforms are applied, before the result is XOR'd with
 `rs1` and written back to `rd`.
 This instruction exists on RV32 and RV64 base architectures.
-On RV64, the 32-bit result is sign extended up to XLEN bits.
+On RV64, the 32-bit result is sign extended to XLEN bits.
 This instruction must _always_ be implemented such that its execution
 latency does not depend on the data being operated on.
 

diff --git a/doc/scalar/insns/sm4ks.adoc b/doc/scalar/insns/sm4ks.adoc
@@ -29,7 +29,7 @@ A byte is extracted from `rs2` based on `bs`, to which the SBox and
 linear layer transforms are applied, before the result is XOR'd with
 `rs1` and written back to `rd`.
 This instruction exists on RV32 and RV64 base architectures.
-On RV64, the 32-bit result is sign extended up to XLEN bits.
+On RV64, the 32-bit result is sign extended to XLEN bits.
 This instruction must _always_ be implemented such that its execution
 latency does not depend on the data being operated on.
 

diff --git a/doc/scalar/riscv-crypto-scalar-audience.adoc b/doc/scalar/riscv-crypto-scalar-audience.adoc
@@ -1,7 +1,7 @@
 [[crypto_scalar_audience]]
 === Intended Audience
 
-Cryptography is a specialist subject, requiring people with many different
+Cryptography is a specialised subject, requiring people with many different
 backgrounds to cooperate in its secure and efficient implementation.
 Where possible, we have written this specification to be understandable by
 all, though we recognise that the motivations and references to
@@ -14,15 +14,15 @@ We have tried to capture these backgrounds
 here, with a brief explanation of what we expect them to know, and how
 it relates to the specification.
 We hope this aids people's understanding of which aspects of the specification
-are particularly relevant to them, which they may (safely!) ignore, and
+are particularly relevant to them, and which they may (safely!) ignore or
 pass to a colleague.
 
 Cryptographers and cryptographic software developers::
 These are the people we expect to write code using the instructions
 in this specification.
 They should understand fairly obviously the motivations for the
 instructions we include, and be familiar with most of the algorithms
-and outside standards which we refer to.
+and outside standards to which we refer.
 We expect the sections on constant time execution
 (<<crypto_scalar_zkt>>)
 and the entropy source
@@ -40,7 +40,7 @@ Digital design engineers & micro-architects::
 These are the people who will implement the specification inside a
 core. Again, no cryptography expertise is assumed, but we expect them to
 interpret the specification and anticipate any hardware implementation
-issues. E.g., where high-frequency design considerations apply, or where
+issues, e.g., where high-frequency design considerations apply, or where
 latency/area tradeoffs exist etc.
 In particular, they should be aware of the literature around efficiently
 implementing AES and SM4 SBoxes in hardware.
@@ -49,8 +49,8 @@ Verification engineers::
 Responsible for ensuring the correct implementation of the extension
 in hardware.
 No cryptography background is assumed.
-We hope they are able to identify interesting test cases from the
-specification, and knowing how the instructions are used in the real world.
+We expect them to identify interesting test cases from the
+specification. An understanding of their real-world usage will help with this.
 We do not expect verification engineers in this sense to be experts
 in entropy source design or certification, since this is a very
 specialised area.

diff --git a/doc/scalar/riscv-crypto-scalar-policies.adoc b/doc/scalar/riscv-crypto-scalar-policies.adoc
@@ -20,11 +20,11 @@ policies:
   cryptographic constructs well.
   It will not try to support proposed standards, or cryptographic
   constructs which exist only in academia.
-  Cryptographic standards which are settled upon concurrently with, or after
+  Cryptographic standards which are settled upon concurrently with or after
   the RISC-V cryptographic extension standardisation will be dealt with
   by future additions to, or versions of, the RISC-V cryptographic
   standard extension. It is anticipated that the NIST Lightweight
-  Cryptography contest, and the NIST Post-Quantum Cryptography contest
+  Cryptography contest and the NIST Post-Quantum Cryptography contest
   may be dealt with this way, depending on timescales.
 
 * Historically, there has been some discussion

diff --git a/doc/scalar/riscv-crypto-scalar-sail-specifications.adoc b/doc/scalar/riscv-crypto-scalar-sail-specifications.adoc
@@ -2,7 +2,7 @@
 === Sail Specifications
 
 RISC-V maintains a 
-link:https://github.com/rems-project/sail-riscv[formal model]
+link:https://github.com/riscv/sail-riscv[formal model]
 of the ISA specification,
 implemented in the Sail ISA specification language
 cite:[sail].
@@ -25,3 +25,8 @@ The
 link:https://github.com/rems-project/sail/blob/sail2/manual.pdf[Sail Manual]
 is recommended reading in order to best understand the code snippets.
 
+Note that this document contains only a subset of the formal model: refer to
+the formal model Github
+link:https://github.com/riscv/sail-riscv[repository]
+for the complete model.
+
diff --git a/doc/scalar/riscv-crypto-scalar-zbkb.adoc b/doc/scalar/riscv-crypto-scalar-zbkb.adoc
@@ -15,7 +15,7 @@ ratification package, and some are not (
 All of the instructions in <<zbkb>> have their complete specification included
 in this document, including those _not_ present in the initial
 Bitmanip ratification package.
-This is to make the specification complete as a standalone document.
+This is to make the present specification complete as a standalone document.
 Inevitably there might be small divergences between the Bitmanip and
 Scalar Cryptography specification documents as they move at different
 paces.

diff --git a/doc/scalar/riscv-crypto-scalar-zbkc.adoc b/doc/scalar/riscv-crypto-scalar-zbkc.adoc
@@ -11,7 +11,7 @@ ratification package for the `Zbc` extension.
 All of the instructions in <<zbkc>> have their complete specification included
 in this document, including those _not_ present in the initial
 Bitmanip ratification package.
-This is to make the specification complete as a standalone document.
+This is to make the present specification complete as a standalone document.
 Inevitably there might be small divergences between the Bitmanip and
 Scalar Cryptography specification documents as they move at different
 paces.

diff --git a/doc/scalar/riscv-crypto-scalar-zbkx.adoc b/doc/scalar/riscv-crypto-scalar-zbkx.adoc
@@ -11,7 +11,7 @@ NOTE: All of these instructions are missing from the first Bitmanip
 ratification package.
 Hence,  all of the instructions in <<zbkx>> have their complete specification
 included in this document.
-This is to make the specification complete as a standalone document.
+This is to make the present specification complete as a standalone document.
 Inevitably there might be small divergences between the Bitmanip and
 Scalar Cryptography specification documents as they move at different
 paces.

diff --git a/doc/scalar/riscv-crypto-scalar-zknd.adoc b/doc/scalar/riscv-crypto-scalar-zknd.adoc
@@ -20,3 +20,5 @@ the AES block cipher.
 |          | &#10003; | aes64ks2     | <<insns-aes64ks2>>
 |===
 
+NOTE: The <<insns-aes64ks1i>> and <<insns-aes64ks2>> instructions are
+present in both the <<zknd>> and <<zkne>> extensions.
diff --git a/doc/scalar/riscv-crypto-scalar-zkne.adoc b/doc/scalar/riscv-crypto-scalar-zkne.adoc
@@ -19,3 +19,9 @@ the AES block cipher.
 |          | &#10003; | aes64ks2     | <<insns-aes64ks2>>
 |===
 
+NOTE: The
+<<insns-aes64ks1i,`aes64ks1i`>>
+and
+<<insns-aes64ks2,`aes64ks2`>>
+instructions are present in both the <<zknd>> and <<zkne>> extensions.
+
diff --git a/doc/scalar/riscv-crypto-spec-scalar.adoc b/doc/scalar/riscv-crypto-spec-scalar.adoc
@@ -121,7 +121,7 @@ progress.
 ====
 Specialist encryption and decryption instructions are separated into different
 functional groups because some use cases (e.g., Galois/Counter
-Mode in TLS 1.3, among others) do not require decryption functionality.
+Mode in TLS 1.3) do not require decryption functionality.
 
 The NIST and ShangMi algorithms suites are separated because their
 usefulness is heavily dependent on the countries a device is expected to