UInt/SInt

Description

The UInt/SInt type corresponds to a vector of bits that can be used for signed/unsigned integer arithmetic.

Declaration

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

Syntax

Description

Return

UInt[()]
SInt[()]

Create an unsigned/signed integer, bits count is inferred

UInt
SInt
UInt(x bits)
SInt(x bits)

Create an unsigned/signed integer with x bits

UInt
SInt
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’

UInt
SInt
U”[[size’]base]value”
S”[[size’]base]value”

Create an unsigned/signed integer assigned with ‘value’ (Base : ‘h’, ‘d’, ‘o’, ‘b’)

UInt
SInt
U([x bits,] element, …)
S([x bits,] element, …)

Create an unsigned integer assigned with the value specified by elements

UInt
SInt
val myUInt = UInt(8 bits)
myUInt := U(2,8 bits)
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 scala Int as literal value

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

// For assignement purposes, you can omit the U/S, which also alow the use of the [default -> ???] feature
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 type

Logic

Operator

Description

Return type

x ^ y

Logical XOR

Bool

~x

Bitwise NOT

T(w(x) bits)

x & y

Bitwise AND

T(max(w(xy) bits)

x | y

Bitwise OR

T(max(w(xy) bits)

x ^ y

Bitwise XOR

T(max(w(xy) bits)

x.xorR

XOR all bits of x

Bool

x.orR

OR all bits of x

Bool

x.andR

AND all bits of x

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

T(w(x) bits)

x.rotateRight(y)

Logical right rotation, y : UInt/Int

T(w(x) bits)

x.clearAll[()]

Clear all bits

x.setAll[()]

Set all bits

x.setAllTo(value : Boolean)

Set all bits to the given Boolean value

x.setAllTo(value : Bool)

Set all bits to the given Bool value

// Bitwise operator
val a, b, c = SInt(32 bits)
c := ~(a & b) //  Inverse(a AND b)

val all_1 = a.andR // Check that all bits are equal to 1

// Logical shift
val uint_10bits = uint_8bits << 2  // shift left (resulting in 10 bits)
val shift_8bits = uint_8bits |<< 2 // shift left (resulting in 8 bits)

// Logical rotation
val myBits = uint_8bits.rotateLeft(3) // left bit rotation

// Set/clear
val a = B"8'x42"
when(cond){
  a.setAll() // set all bits to True when cond is True
}

Arithmetic

Operator

Description

Return

x + y

Addition

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

x +^ y

Addition with carray

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

x +| y

addition by sat carray bit

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

x - y

Subtraction

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

x - y

Subtraction with carray

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

x -| y

Subtraction by sat carray bit

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(w(x),bits)

// Addition
val res = mySInt_1 + mySInt_2

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

// Comparaison between two SInt
myBool := mySInt_1 > mySInt_2

// Comparaison between a UInt and a literal
myBool := myUInt_8bits >= U(3, 8 bits)

when(myUInt_8bits === 3){

}

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))

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 expand signbit

SInt(w(x) + 1, bits)

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

// cast a 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)

Bit extraction

Operator

Description

Return

x(y)

Readbit, y : Int/UInt

Bool

x(offset, width)

Read bitfield, offset: UInt, width: Int

T(width bits)

x(range)

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

T(range bits)

x(y) := z

Assign bits, y : Int/UInt

Bool

x(offset, width) := z

Assign bitfield, offset: UInt, width: Int

T(width bits)

x(range) := z

Assign a range of bit. Ex : myBits(4 downto 2) := U”010”

T(range bits)

// get the bit at index 4
val myBool = myUInt(4)

// assign bit 1 to True
mySInt(1) := True

// Range
val myUInt_8bits = myUInt_16bits(7 downto 0)
val myUInt_7bits = myUInt_16bits(0 to 6)
val myUInt_6bits = myUInt_16Bits(0 until 6)

mySInt_8bits(3 downto 0) := mySInt_4bits

Misc

Operator

Description

Return

x.getWidth

Return bitcount

Int

x.msb

Return the most significant bit

Bool

x.lsb

Return the least significant bit

Bool

x.range

Return the range (x.high downto 0)

Range

x.high

Return the upper bound of the type x

Int

x ## y

Concatenate, x->high, y->low

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

x @@ y

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

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

x.subdivideIn(y slices)

Subdivide x into y slices, y: Int

Vec(T, y)

x.subdivideIn(y bits)

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

Vec(T, w(x)/y)

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)

myUInt.twoComplement(en: Bool)

Use the two’s complement to transform an UInt into an SInt

SInt(w(myUInt) + 1, bits)

mySInt.abs

Return the absolute value of the UInt value

UInt(w(mySInt), bits)

mySInt.abs(en: Bool)

Return the absolute value of the UInt value when en is True

UInt(w(mySInt), bits)

mySInt.sign

Return most significant bit

Bool

x.expand

Return x with 1 bit expand

T(w(x)+1 bit)

mySInt.absWithSym

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

UInt(w(mySInt) - 1, bits)

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

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

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

 // if you want to access in a reverse order you can do
 val myVector   = mySInt_128bits.subdivideIn(32 bits).reverse
 val mySIntWord = myVector(sel)

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

// Two's complement
mySInt := myUInt.twoComplement(myBool)

// Absolute value
mySInt_abs := mySInt.abs

fixPoint operation

For fixed-point, we can divide it into two parts.
  • LowerBit Operation(round methods)

  • HighBit Operation(saturation operations)

Lower Bit operation

../../_images/lowerBitOperation.png

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

SpinalHDL-Name

Wikipedia-Name

API

Matmatic-Alogrithm

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 RoundToOdd are very special ,Used in some big data statistical fields with high accuracy concern, SpinalHDL don’t support them yet.

You can find ROUNDUP, ROUNDDOWN, ROUNDTOZERO, ROUNDTOINF, ROUNDTOEVEN, ROUNTOODD are very close, ROUNDTOINF is most common. the api of round in different Programing-language may different.

Programing-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 bit)
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 use roundToInf as default round

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

Note

only floor and floorToZero without align option, they do not need carry bit. other round operation default with 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.
but roundUp with lowerest cost and good timing, almost no performance lost.
so roundUp is very recommended in your work.

High Bit operation

../../_images/highBitOperation.png

function

Operation

Postive-Op

Negtive-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 bit)
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 discard hightest 3 bits
val B  = A.trim(3 bits)     //return 5 bits with discard hightest 3 bits
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 way are provided in UInt/SInt do fixpoint:

../../_images/fixPoint.png

fixTo is strongly recommended in your RTL work, you don’t need handle carry bit align and bit width calculate manually like Way1.

Factory Fix function with Auto Saturation

fuction

description

Return

fixTo(section,roundType,symmetric)

Factory FixFunction

section.size bits

val A  = SInt(16 bit)
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