Repository navigation
Description
Problem
These descriptions state the wrong side, value, byte or name:
| location | text | correction |
|---|---|---|
| style_guide.md lines 231–236 | "x[23:16] refers to the 3rd byte … x[3 *: 8] refers to the 3rd byte of x. … the four different syntaxes are equivalent" |
x[3 *: 8] is bits 31:24; the equivalent element slice is x[2 *: 8] |
| Count_Trailing_Zero_Bits page | its only example is "Std::Bits::Count_Set_Bits(0b0010_0100) == 2" |
an example of Count_Trailing_Zero_Bits |
| Element slice page | "x[7 *: 8] extracts the 7th byte of x" | bits 63:56, the 8th byte (byte 7 counting from 0) |
| Zero_Extend page | "zero-extends value a to be source_size bits wide", with implicit target_size : {0..}, a : Bits(target_size), source_size : {0..}) -> Bits(source_size) |
the names are swapped: the input width is the source size and the result width the target size |
ISA_LRM, Align_Down (line 3978) |
"The smallest value that is an exact multiple of alignment and not greater than x" | "largest" |
ISA_LRM, Shift_Right_Arithmetic (line 4046) |
"padding the right hand side with copies of the sign bit" | the left (upper) side |
ISA_LRM, Shift_Right_Logical (line 4053) |
"padding the right hand side with zeros" | the left (upper) side |
ISA_LRM, Rotate_Right (line 4064) |
"padding the lower hand side with the lower bits of x" |
rotation moves the low bits to the high end |
ISA_LRM, Signed_Saturate (line 4078) |
"the result is either Bits(-2**(size-1)) or Bits(2**(size-1)-1)" |
Bits(…) is a type, not a value |
ISA_LRM, Count_Trailing_Zero_Bits (line 4094) |
"e.g.,. Count_Trailing_Zero_Bits(0b0011_0000) == r" | == 4; "e.g.,." is also on lines 4085, 4089 and 4090 |
| ISA_LRM, "Numeric literals" (lines 64–66) | "There is no syntax for writing bitvector literals whose length is not a multiple of 4." | binary literals have any length (0b101 is 3 bits); only hexadecimal literals are multiples of 4 |
| reading-specs.md lines 130–150 | isa_defn entries for Std::Bits::AlignDown, Std::Bits::AlignUp, Std::Bits::From_Integer, Std::Integer::AlignDown, Std::Integer::AlignUp |
no definitions have these names; the library uses Align_Down and Align_Up, and has no From_Integer |
Proposed fix
-- `x[3 *: 8]` refers to the 3rd byte of x.
+- `x[2 *: 8]` refers to the same 8 bits of x.-// The smallest value that is an exact multiple of alignment and not greater than x
+// The largest value that is an exact multiple of alignment and not greater than x
-// Shift a bitvector right by `amount` padding the right hand side with copies of the sign bit `x[size-1]`
+// Shift a bitvector right by `amount` padding the left hand side with copies of the sign bit `x[size-1]`
-// Shift a bitvector right by `amount` padding the right hand side with zeros.
+// Shift a bitvector right by `amount` padding the left hand side with zeros.
-// Rotate a bitvector right by `amount` padding the lower hand side with the lower bits of `x`
+// Rotate a bitvector right by `amount`, moving the bits shifted out
+// of the low end into the high end.
-// the result is either `Bits(-2**(size-1))` or `Bits(2**(size-1)-1)`
+// For size >= 1, the result is either
+// `0b1 ++ Zero(size-1)` or `0b0 ++ All_Ones(size-1)`.
-// e.g.,. Count_Trailing_Zero_Bits(0b0011_0000) == r
+// e.g., Count_Trailing_Zero_Bits(0b0011_0000) == 4
-There is no syntax for writing bitvector literals whose length is not a multiple of 4.
+Hexadecimal bitvector literals have widths divisible by four. Use a binary literal or a
+slice for other widths.Replace the trailing-zero page's example with
Std::Bits::Count_Trailing_Zero_Bits(0b0011_0000) == 4. Replace e.g.,. with e.g., at
LRM lines 4085, 4089 and 4090.
On the element-slice page, write "x[7 *: 8] extracts the 8th byte of x".
On the Zero_Extend page, rename the parameters and keep their domains:
function Std::Bits::Zero_Extend(
implicit source_size : {0..},
a : Bits(source_size),
target_size : {0..}
) -> Bits(target_size)
with the description "zero-extends value a to be target_size bits wide". In reading-specs.md, use the defined
names Align_Down and Align_Up, and remove the unresolved Std::Bits::From_Integer entry.
AI disclosure
Assisted-by: Claude
Claude assisted with source analysis, the proposed correction and drafting this report.
Reviewed with assistance from Codex.
Pinned source: definitions.xml.gz at revision 35eface1b7ee003a1cda95005ec5fd83de658a64.
Activity