Skip to content

[General]: Comments and examples in the manual, style guide and library pages state the wrong side, value or byte #111

Open

Description

@shuklaayush

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions