You're reading an pre-release version of this documentation.
For the latest stable release version, please have a look at master.

UInt/SInt

The UInt/SInt types are vectors of bits interpreted as two’s complement unsigned/signed integers. They can do what Bits can do, with the addition of unsigned/signed integer arithmetic and comparisons.

Declaration

The syntax to declare an integer is as follows: (everything between [] is optional)

Syntax

Description

UInt[()]
SInt[()]

Create an unsigned/signed integer, bits count is inferred

UInt(x bits)
SInt(x bits)

Create an unsigned/signed integer with x bits

U(value: Int[,x bits])
U(value: BigInt[,x bits])
S(value: Int[,x bits])
S(value: BigInt[,x bits])

Create an unsigned/signed integer assigned with ‘value’

U”[[size’]base]value”
S”[[size’]base]value”
Create an unsigned/signed integer assigned with ‘value’
(base: ‘h’, ‘d’, ‘o’, ‘b’)
U([x bits,] elements: Element*)
S([x bits,] elements: Element*)

Create an unsigned integer assigned with the value specified by elements

val myUInt = UInt(8 bit)
myUInt := U(2, 8 bit)
myUInt := U(2)
myUInt := U"0000_0101"  // Base per default is binary => 5
myUInt := U"h1A"        // Base could be x (base 16)
                        //               h (base 16)
                        //               d (base 10)
                        //               o (base 8)
                        //               b (base 2)
myUInt := U"8'h1A"
myUInt := 2             // You can use a Scala Int as a literal value

val myBool = Bool()
myBool := myUInt === U(7 -> true, (6 downto 0) -> false)
myBool := myUInt === U(8 bit, 7 -> true, default -> false)
myBool := myUInt === U(myUInt.range -> true)

// For assignment purposes, you can omit the U/S
// which also allows the use of "default -> ???"
myUInt := (default -> true)                        // Assign myUInt with "11111111"
myUInt := (myUInt.range -> true)                   // Assign myUInt with "11111111"
myUInt := (7 -> true, default -> false)            // Assign myUInt with "10000000"
myUInt := ((4 downto 1) -> true, default -> false) // Assign myUInt with "00011110"

Operators

The following operators are available for the UInt and SInt types:

Logic

Operator

Description

Return type

~x

Bitwise NOT

T(w(x) bits)

x & y

Bitwise AND

T(max(w(x), w(y)) bits)

x | y

Bitwise OR

T(max(w(x), w(y)) bits)

x ^ y

Bitwise XOR

T(max(w(x), w(y)) bits)

x.xorR

XOR all bits of x (reduction operator)

Bool

x.orR

OR all bits of x (reduction operator)

Bool

x.andR

AND all bits of x (reduction operator)

Bool

x >> y

Arithmetic shift right, y : Int

T(w(x) - y bits)

x >> y

Arithmetic shift right, y : UInt

T(w(x) bits)

x << y

Arithmetic shift left, y : Int

T(w(x) + y bits)

x << y

Arithmetic shift left, y : UInt

T(w(x) + max(y) bits)

x |>> y

Logical shift right, y : Int/UInt

T(w(x) bits)

x |<< y

Logical shift left, y : Int/UInt

T(w(x) bits)

x.rotateLeft(y)

Logical left rotation, y : UInt/Int
The width of y is constrained to the width of log2Up(x) or less

T(w(x) bits)

x.rotateRight(y)

Logical right rotation, y : UInt/Int
The width of y is constrained to the width of log2Up(x) or less

T(w(x) bits)

x.clearAll[()]

Clear all bits

modifies x

x.setAll[()]

Set all bits

modifies x

x.setAllTo(value : Boolean)

Set all bits to the given Boolean value

modifies x

x.setAllTo(value : Bool)

Set all bits to the given Bool value

modifies x

Note

Notice the difference in behavior between x >> 2 (result 2 bit narrower than x) and x >> U(2) (keeping width) due to the Scala type of y.

In the first case “2” is an Int (which can be seen as an “elaboration integer constant”), and in the second case it is a hardware signal (type UInt) that may or may not be a constant.

val a, b, c = SInt(32 bits)
a := S(5)
b := S(10)

// Bitwise operators
c := ~(a & b)     // Inverse(a AND b)
assert(c.getWidth == 32)

// Shift
val arithShift = UInt(8 bits) << 2      // shift left (resulting in 10 bits)
val logicShift = UInt(8 bits) |<< 2     // shift left (resulting in 8 bits)
assert(arithShift.getWidth == 10)
assert(logicShift.getWidth == 8)

// Rotation
val rotated = UInt(8 bits) rotateLeft 3 // left bit rotation
assert(rotated.getWidth == 8)

// Set all bits of b to True when all bits of a are True
when(a.andR) { b.setAll() }

Arithmetic

Operator

Description

Return

x + y

Addition

T(max(w(x), w(y)) bits)

x +^ y

Addition with carry

T(max(w(x), w(y)) + 1 bits)

x +| y

Addition of addend with saturation (see also T.maxValue and T.minValue)

T(max(w(x), w(y)) bits)

x - y

Subtraction

T(max(w(x), w(y)) bits)

x -^ y

Subtraction with carry

T(max(w(x), w(y)) + 1 bits)

x -| y

Subtraction of subtrahend with saturation (see also T.minValue and T.maxValue)

T(max(w(x), w(y)) bits)

x * y

Multiplication

T(w(x) + w(y)) bits)

x / y

Division

T(w(x) bits)

x % y

Modulo

T(min(w(x), w(y)) bits)

~x

Unary One’s compliment, Bitwise NOT

T(w(x) bits)

-x

Unary Two’s compliment of SInt type. Not available for UInt.

SInt(w(x) bits)

val a, b, c = UInt(8 bits)
a := U"xf0"
b := U"x0f"

c := a + b
assert(c === U"8'xff")

val d = a +^ b
assert(d === U"9'x0ff")

// 0xf0 + 0x20 would overflow, the result therefore saturates
val e = a +| U"8'x20"
assert(e === U"8'xff")

Note

Notice how simulation assertions are made here (with ===), as opposed to elaboration assertions in the previous example (with ==).

Comparison

Operator

Description

Return type

x === y

Equality

Bool

x =/= y

Inequality

Bool

x > y

Greater than

Bool

x >= y

Greater than or equal

Bool

x < y

Less than

Bool

x <= y

Less than or equal

Bool

val a = U(5, 8 bits)
val b = U(10, 8 bits)
val c = UInt(2 bits)

when (a > b) {
  c := U"10"
} elsewhen (a =/= b) {
  c := U"01"
} elsewhen (a === U(0)) {
  c.setAll()
} otherwise {
  c.clearAll()
}

Note

When comparing UInt values in a way that allows for “wraparound” behavior, meaning that the values will “wrap around” to the minimum value when they exceed the maximum value. The wrap method of UInt can be used as x.wrap < y for UInt variables x, y, the result will be true if x is less than y in the wraparound sense.

Type cast

Operator

Description

Return

x.asBits

Binary cast to Bits

Bits(w(x) bits)

x.asUInt

Binary cast to UInt

UInt(w(x) bits)

x.asSInt

Binary cast to SInt

SInt(w(x) bits)

x.asBools

Cast into a array of Bool

Vec(Bool(), w(x))

x.asBool

Extract LSB of x

Bool(x.lsb)

S(x: T)

Cast a Data into a SInt

SInt(w(x) bits)

U(x: T)

Cast a Data into an UInt

UInt(w(x) bits)

x.intoSInt

Convert to SInt expanding sign bit

SInt(w(x) + 1 bits)

myUInt.twoComplement(en: Bool)

Generate two’s complement of number if en is True, unchanged otherwise. (en makes result negative)

SInt(w(myUInt) + 1, bits)

mySInt.abs

Return the absolute value as a UInt value

UInt(w(mySInt) bits)

mySInt.abs(en: Bool)

Return the absolute value as a UInt value when en is True, otherwise just reinterpret bits as unsigned

UInt(w(mySInt) bits)

mySInt.absWithSym

Return the absolute value of the UInt value with symmetric, shrink 1 bit

UInt(w(mySInt) - 1 bits)

To cast a Bool, a Bits, or an SInt into a UInt, you can use U(something). To cast things into an SInt, you can use S(something).

// Cast an SInt to Bits
val myBits = mySInt.asBits

// Create a Vector of Bool
val myVec = myUInt.asBools

// Cast a Bits to SInt
val mySInt = S(myBits)

// UInt to SInt conversion
val UInt_30 = U(30, 8 bit)

val SInt_30 = UInt_30.intoSInt
assert(SInt_30 === S(30, 9 bit))

mySInt := UInt_30.twoComplement(booleanDoInvert)
    // if booleanDoInvert is True then we get S(-30, 9 bit)
    // otherwise we get S(30, 9 bit)

// absolute values
val SInt_n_4 = S(-3, 3 bit)
val abs_en = SInt_n_3.abs(booleanDoAbs)
    // if booleanDoAbs is True we get U(3, 3 bit)
    // otherwise we get U"3'b101" or U(5, 3 bit) (raw bit pattern of -3)

val SInt_n_128 = S(-128, 8 bit)
val abs = SInt_n_128.abs
assert(abs === U(128, 8 bit))
val sym_abs = SInt_n_128.absWithSym
assert(sym_abs === U(127, 7 bit))

Bit extraction

All of the bit extraction operations can be used to read a bit / group of bits. Like in other HDLs the extraction operators can also be used to assign a part of a UInt / SInt .

Operator

Description

Return

x(y: Int)

Static bit access of y-th bit

Bool

x(y: UInt)

Variable bit access of y-th bit

Bool

x(offset: Int, width bits)

Fixed part select of fixed width, offset is LSB index

Bits(width bits)

x(offset: UInt, width bits)

Variable part-select of fixed width, offset is LSB index

Bits(width bits)

x(range: Range)

Access a range of bits. Ex : myBits(4 downto 2)

Bits(range.size bits)

x.subdivideIn(y slices, [strict: Boolean])

Subdivide x into y slices, y: Int

Vec(Bits(…), y)

x.subdivideIn(y bits, [strict: Boolean])

Subdivide x in multiple slices of y bits, y: Int

Vec(Bits(y bit), …)

x.msb

Access most significant bit of x (highest index, sign bit for SInt)

Bool

x.lsb

Access lowest significant bit of x (index 0)

Bool

mySInt.sign

Access most sign bit, only SInt

Bool

Some basic examples:

// get the element at the index 4
val myBool = myUInt(4)
// assign element 1
myUInt(1) := True

// index dynamically
val index = UInt(2 bit)
val indexed = myUInt(index, 2 bit)

// range index
val myUInt_8bit = myUInt_16bit(7 downto 0)
val myUInt_7bit = myUInt_16bit(0 to 6)
val myUInt_6bit = myUInt_16bit(0 until 6)
// assign to myUInt_16bit(3 downto 0)
myUInt_8bit(3 downto 0) := myUInt_4bit

// equivalent slices, no reversing occurs
val a = myUInt_16bit(8 downto 4)
val b = myUInt_16bit(4 to 8)

// read / assign the msb / leftmost bit / x.high bit
val isNegative = mySInt_16bit.sign
myUInt_16bit.msb := False

Subdivide details

Both overloads of subdivideIn have an optional parameter strict (i.e. subdivideIn(slices: SlicesCount, strict: Boolean = true)). If strict is true an error will be raised if the input could not be divided into equal parts. If set to false the last element may be smaller than the other (equal sized) elements.

// Subdivide
val sel = UInt(2 bits)
val myUIntWord = myUInt_128bits.subdivideIn(32 bits)(sel)
    // sel = 3 => myUIntWord = myUInt_128bits(127 downto 96)
    // sel = 2 => myUIntWord = myUInt_128bits( 95 downto 64)
    // sel = 1 => myUIntWord = myUInt_128bits( 63 downto 32)
    // sel = 0 => myUIntWord = myUInt_128bits( 31 downto  0)

 // If you want to access in reverse order you can do:
 val myVector   = myUInt_128bits.subdivideIn(32 bits).reverse
 val myRevUIntWord = myVector(sel)

 // We can also assign through subdivides
 val output8 = UInt(8 bit)
 val pieces = output8.subdivideIn(2 slices)
 // assign to output8
 pieces(0) := 0xf
 pieces(1) := 0x5

Misc

In contrast to the bit extraction operations listed above it’s not possible to use the return values to assign to the original signal.

Operator

Description

Return

x.getWidth

Return bitcount

Int

x.high

Return the index of the MSB (highest allowed index for Int)

Int

x.bitsRange

Return the range (0 to x.high)

Range

x.minValue

Lowest possible value of x (e.g. 0 for UInt)

BigInt

x.maxValue

Highest possible value of x

BigInt

x.valueRange

Return the range from minimum to maximum possible value of x (x.minValue to x.maxValue).

Range

x ## y

Concatenate, x->high, y->low

Bits(w(x) + w(y) bits)

x #* n

Repeat x n-times

Bits(w(x) * n bits)

x @@ y

Concatenate x:T with y:Bool/SInt/UInt

T(w(x) + w(y) bits)

x.resize(y)

Return a resized copy of x, if enlarged, it is filled with zero
for UInt or filled with the sign for SInt, y: Int

T(y bits)

x.resized

Return a version of x which is allowed to be automatically
resized where needed

T(w(x) bits)

x.expand

Return x with 1 bit expand

T(w(x)+1 bits)

x.getZero

Return a new instance of type T that is assigned a constant value of zeros the same width as x.

T(0, w(x) bits).clearAll()

x.getAllTrue

Return a new instance of type T that is assigned a constant value of ones the same width as x.

T(w(x) bits).setAll()

Note

validRange can only be used for types where the minimum and maximum values fit into a signed 32-bit integer. (This is a limitation given by the Scala scala.collection.immutable.Range type which uses Int)

myBool := mySInt.lsb  // equivalent to mySInt(0)

// Concatenation
val mySInt = mySInt_1 @@ mySInt_1 @@ myBool
val myBits = mySInt_1 ## mySInt_1 ## myBool

// Resize
myUInt_32bits := U"32'x112233344"
myUInt_8bits  := myUInt_32bits.resized      // automatic resize (myUInt_8bits = 0x44)
val lowest_8bits = myUInt_32bits.resize(8)  // resize to 8 bits (myUInt_8bits = 0x44)

FixPoint operations

For fixpoint, we can divide it into two parts:

  • Lower bit operations (rounding methods)

  • High bit operations (saturation operations)

Lower bit operations

../../_images/lowerBitOperation.png

About Rounding: https://en.wikipedia.org/wiki/Rounding

SpinalHDL-Name

Wikipedia-Name

API

Mathematic Algorithm

return(align=false)

Supported

FLOOR

RoundDown

floor

floor(x)

w(x)-n bits

Yes

FLOORTOZERO

RoundToZero

floorToZero

sign*floor(abs(x))

w(x)-n bits

Yes

CEIL

RoundUp

ceil

ceil(x)

w(x)-n+1 bits

Yes

CEILTOINF

RoundToInf

ceilToInf

sign*ceil(abs(x))

w(x)-n+1 bits

Yes

ROUNDUP

RoundHalfUp

roundUp

floor(x+0.5)

w(x)-n+1 bits

Yes

ROUNDDOWN

RoundHalfDown

roundDown

ceil(x-0.5)

w(x)-n+1 bits

Yes

ROUNDTOZERO

RoundHalfToZero

roundToZero

sign*ceil(abs(x)-0.5)

w(x)-n+1 bits

Yes

ROUNDTOINF

RoundHalfToInf

roundToInf

sign*floor(abs(x)+0.5)

w(x)-n+1 bits

Yes

ROUNDTOEVEN

RoundHalfToEven

roundToEven

No

ROUNDTOODD

RoundHalfToOdd

roundToOdd

No

Note

The RoundToEven and RoundToOdd modes are very special, and are used in some big data statistical fields with high accuracy concerns, SpinalHDL doesn’t support them yet.

You will find ROUNDUP, ROUNDDOWN, ROUNDTOZERO, ROUNDTOINF, ROUNDTOEVEN, ROUNTOODD are very close in behavior, ROUNDTOINF is the most common. The behavior of rounding in different programming languages may be different.

Programming language

default-RoundType

Example

comments

Matlab

ROUNDTOINF

round(1.5)=2,round(2.5)=3;round(-1.5)=-2,round(-2.5)=-3

round to ±Infinity

python2

ROUNDTOINF

round(1.5)=2,round(2.5)=3;round(-1.5)=-2,round(-2.5)=-3

round to ±Infinity

python3

ROUNDTOEVEN

round(1.5)=round(2.5)=2; round(-1.5)=round(-2.5)=-2

close to Even

Scala.math

ROUNDTOUP

round(1.5)=2,round(2.5)=3;round(-1.5)=-1,round(-2.5)=-2

always to +Infinity

SpinalHDL

ROUNDTOINF

round(1.5)=2,round(2.5)=3;round(-1.5)=-2,round(-2.5)=-3

round to ±Infinity

Note

In SpinalHDL ROUNDTOINF is the default RoundType (round = roundToInf)

val A  = SInt(16 bits)
val B  = A.roundToInf(6 bits)         // default 'align = false' with carry, got 11 bit
val B  = A.roundToInf(6 bits, align = true) // sat 1 carry bit, got 10 bit
val B  = A.floor(6 bits)              // return 10 bit
val B  = A.floorToZero(6 bits)        // return 10 bit
val B  = A.ceil(6 bits)               // ceil with carry so return 11 bit
val B  = A.ceil(6 bits, align = true) // ceil with carry then sat 1 bit return 10 bit
val B  = A.ceilToInf(6 bits)
val B  = A.roundUp(6 bits)
val B  = A.roundDown(6 bits)
val B  = A.roundToInf(6 bits)
val B  = A.roundToZero(6 bits)
val B  = A.round(6 bits)              // SpinalHDL uses roundToInf as the default rounding mode

val B0 = A.roundToInf(6 bits, align = true)         //  ---+
                                                    //     |--> equal
val B1 = A.roundToInf(6 bits, align = false).sat(1) //  ---+

Note

Only floor and floorToZero work without the align option; they do not need a carry bit. Other rounding operations default to using a carry bit.

round Api

API

UInt/SInt

description

Return(align=false)

Return(align=true)

floor

Both

w(x)-n bits

w(x)-n bits

floorToZero

SInt

equal to floor in UInt

w(x)-n bits

w(x)-n bits

ceil

Both

w(x)-n+1 bits

w(x)-n bits

ceilToInf

SInt

equal to ceil in UInt

w(x)-n+1 bits

w(x)-n bits

roundUp

Both

simple for HW

w(x)-n+1 bits

w(x)-n bits

roundDown

Both

w(x)-n+1 bits

w(x)-n bits

roundToInf

SInt

most Common

w(x)-n+1 bits

w(x)-n bits

roundToZero

SInt

equal to roundDown in UInt

w(x)-n+1 bits

w(x)-n bits

round

Both

SpinalHDL chose roundToInf

w(x)-n+1 bits

w(x)-n bits

Note

Although roundToInf is very common, roundUp has the least cost and good timing, with almost no performance loss. As a result, roundUp is strongly recommended for production use.

High bit operations

../../_images/highBitOperation.png

function

Operation

Positive-Op

Negative-Op

sat

Saturation

when(Top[w-1, w-n].orR) set maxValue

When(Top[w-1, w-n].andR) set minValue

trim

Discard

N/A

N/A

symmetry

Symmetric

N/A

minValue = -maxValue

Symmetric is only valid for SInt.

val A  = SInt(8 bits)
val B  = A.sat(3 bits)      // return 5 bits with saturated highest 3 bits
val B  = A.sat(3)           // equal to sat(3 bits)
val B  = A.trim(3 bits)     // return 5 bits with the highest 3 bits discarded
val B  = A.trim(3 bits)     // return 5 bits with the highest 3 bits discarded
val C  = A.symmetry         // return 8 bits and symmetry as (-128~127 to -127~127)
val C  = A.sat(3).symmetry  // return 5 bits and symmetry as (-16~15 to -15~15)

fixTo function

Two ways are provided in UInt/SInt to do fixpoint:

../../_images/fixPoint.png

fixTo is strongly recommended in your RTL work, you don’t need to handle carry bit alignment and bit width calculations manually like Way1 in the above diagram.

Factory Fix function with Auto Saturation:

Function

Description

Return

fixTo(section, roundType, symmetric)

Factory FixFunction

section.size bits

val A  = SInt(16 bits)
val B  = A.fixTo(10 downto 3) // default RoundType.ROUNDTOINF, sym = false
val B  = A.fixTo( 8 downto 0, RoundType.ROUNDUP)
val B  = A.fixTo( 9 downto 3, RoundType.CEIL,       sym = false)
val B  = A.fixTo(16 downto 1, RoundType.ROUNDTOINF, sym = true )
val B  = A.fixTo(10 downto 3, RoundType.FLOOR) // floor 3 bit, sat 5 bit @ highest
val B  = A.fixTo(20 downto 3, RoundType.FLOOR) // floor 3 bit, expand 2 bit @ highest