Signed Fixed-point number, with int integer bits (including sign-bit) and frac fractional bits.

• The range SFixed int frac numbers is: [-(2^(int -1)) .. 2^(int-1) - 2^-frac ]
• The resolution of SFixed int frac numbers is: 2^frac
• The Num operators for this type saturate on overflow, and use truncation as the rounding method.

>>> maxBound :: SFixed 3 4
3.9375
>>> minBound :: SFixed 3 4
-4.0
>>> read (show (maxBound :: SFixed 3 4)) :: SFixed 3 4
3.9375
>>> 1 + 2 :: SFixed 3 4
3.0
>>> 2 + 3 :: SFixed 3 4
3.9375
>>> (-2) + (-3) :: SFixed 3 4
-4.0
>>> 1.375 * (-0.8125) :: SFixed 3 4
-1.125
>>> (1.375 :: SFixed 3 4) `times` (-0.8125 :: SFixed 3 4) :: SFixed 6 8
-1.1171875
>>> (2 :: SFixed 3 4) `plus` (3 :: SFixed 3 4) :: SFixed 4 4
5.0
>>> (-2 :: SFixed 3 4) `plus` (-3 :: SFixed 3 4) :: SFixed 4 4
-5.0

Treat a Signed integer as a Signed Fixed-point integer

>>> sf d4 (-22 :: Signed 7)
-1.375

See the underlying representation of a Signed Fixed-point integer

Unsigned Fixed-point number, with int integer bits and frac fractional bits

• The range UFixed int frac numbers is: [0 .. 2^int - 2^-frac ]
• The resolution of UFixed int frac numbers is: 2^frac
• The Num operators for this type saturate on overflow, and use truncation as the rounding method.

>>> maxBound :: UFixed 3 4
7.9375
>>> minBound :: UFixed 3 4
0.0
>>> 1 + 2 :: UFixed 3 4
3.0
>>> 2 + 6 :: UFixed 3 4
7.9375
>>> 1 - 3 :: UFixed 3 4
0.0
>>> 1.375 * 0.8125 :: UFixed 3 4
1.0625
>>> (1.375 :: UFixed 3 4) `times` (0.8125 :: UFixed 3 4) :: UFixed 6 8
1.1171875
>>> (2 :: UFixed 3 4) `plus` (6 :: UFixed 3 4) :: UFixed 4 4
8.0

However, minus does not saturate to minBound on underflow:

>>> (1 :: UFixed 3 4) `minus` (3 :: UFixed 3 4) :: UFixed 4 4
14.0

Treat an Unsigned integer as a Unsigned Fixed-point number

>>> uf d4 (92 :: Unsigned 7)
5.75

See the underlying representation of an Unsigned Fixed-point integer

Fixed point division

When used in a polymorphic setting, use the following Constraint synonyms for less verbose type signatures:

• DivideC rep int1 frac1 int2 frac2 for: Fixed rep int1 frac1 -> Fixed rep int2 frac2 -> Fixed rep (int1 + frac2 + 1) (int2 + frac1)
• DivideSC rep int1 frac1 int2 frac2 for: SFixed int1 frac1 -> SFixed int2 frac2 -> SFixed (int1 + frac2 + 1) (int2 + frac1)
• DivideUC rep int1 frac1 int2 frac2 for: UFixed int1 frac1 -> UFixed int2 frac2 -> UFixed (int1 + frac2 + 1) (int2 + frac1)

Convert, at compile-time, a Double constant to a Fixed-point literal. The conversion saturates on overflow, and uses truncation as its rounding method.

So when you type:

n = $$(fLit pi) :: SFixed 4 4

The compiler sees:

n = Fixed (fromInteger 50) :: SFixed 4 4

Upon evaluation you see that the value is rounded / truncated in accordance to the fixed point representation:

>>> n
3.125

Further examples:

>>> sin 0.5 :: Double
0.479425538604203
>>> $$(fLit (sin 0.5)) :: SFixed 1 8
0.4765625
>>> atan 0.2 :: Double
0.19739555984988078
>>> $$(fLit (atan 0.2)) :: SFixed 1 8
0.1953125
>>> $$(fLit (atan 0.2)) :: SFixed 1 20
0.19739532470703125

Convert, at run-time, a Double to a Fixed-point.

NB: this functions is not synthesisable

Creating data-files

An example usage of this function is for example to convert a data file containing Doubles to a data file with ASCI-encoded binary numbers to be used by a synthesisable function like asyncRomFile. For example, given a file Data.txt containing:

1.2 2.0 3.0 4.0
-1.0 -2.0 -3.5 -4.0

which we want to put in a ROM, interpreting them as 8.8 signed fixed point numbers. What we do is that we first create a conversion utility, createRomFile, which uses fLitR:

createRomFile.hs:

module Main where

import Clash.Prelude
import System.Environment
import qualified Data.List as L

createRomFile :: KnownNat n => (Double -> BitVector n)
              -> FilePath -> FilePath -> IO ()
createRomFile convert fileR fileW = do
  f <- readFile fileR
  let ds :: [Double]
      ds = L.concat . (L.map . L.map) read . L.map words $ lines f
      bvs = L.map (filter (/= '_') . show . convert) ds
  writeFile fileW (unlines bvs)

toSFixed8_8 :: Double -> SFixed 8 8
toSFixed8_8 = fLitR

main :: IO ()
main = do
  [fileR,fileW] <- getArgs
  createRomFile (pack . toSFixed8_8) fileR fileW

We then compile this to an executable:

$ clash --make createRomFile.hs

We can then use this utility to convert our Data.txt file which contains Doubles to a Data.bin file which will containing the desired ASCI-encoded binary data:

$ ./createRomFile "Data.txt" "Data.bin"

Which results in a Data.bin file containing:

0000000100110011
0000001000000000
0000001100000000
0000010000000000
1111111100000000
1111111000000000
1111110010000000
1111110000000000

We can then use this Data.bin file in for our ROM:

romF :: Unsigned 3 -> Unsigned 3 -> SFixed 8 8
romF rowAddr colAddr = unpack
                     $ asyncRomFile d8 "Data.bin" ((rowAddr * 4) + colAddr)

And see that it works as expected:

>>> romF 1 2
-3.5
>>> romF 0 0
1.19921875

Using Template Haskell

For those of us who like to live on the edge, another option is to convert our Data.txt at compile-time using Template Haskell. For this we first create a module CreateRomFileTH.hs:

module CreateRomFileTH (romDataFromFile) where

import Clash.Prelude
import qualified Data.List        as L
import Language.Haskell.TH        (ExpQ, litE, stringL)
import Language.Haskell.TH.Syntax (qRunIO)

createRomFile :: KnownNat n => (Double -> BitVector n)
              -> FilePath -> FilePath -> IO ()
createRomFile convert fileR fileW = do
  f <- readFile fileR
  let ds :: [Double]
      ds = L.concat . (L.map . L.map) read . L.map words $ lines f
      bvs = L.map (filter (/= '_') . show . convert) ds
  writeFile fileW (unlines bvs)

romDataFromFile :: KnownNat n => (Double -> BitVector n) -> String -> ExpQ
romDataFromFile convert fileR = do
  let fileW = fileR L.++ ".bin"
  bvF <- qRunIO (createRomFile convert fileR fileW)
  litE (stringL fileW)

Instead of first converting Data.txt to Data.bin, we will now use the romDataFromFile function to convert Data.txt to a new file in the proper format at compile-time of our new romF' function:

import Clash.Prelude
import CreateRomFileTH

toSFixed8_8 :: Double -> SFixed 8 8
toSFixed8_8 = fLitR

romF' :: Unsigned 3 -> Unsigned 3 -> SFixed 8 8
romF' rowAddr colAddr = unpack $
  asyncRomFile d8
               $(romDataFromFile (pack . toSFixed8_8) "Data.txt") -- Template Haskell splice
               ((rowAddr * 4) + colAddr)

And see that it works just like the romF function from earlier:

>>> romF' 1 2
-3.5
>>> romF' 0 0
1.19921875

Fixed-point number

Where:

• rep is the underlying representation
• int is the number of bits used to represent the integer part
• frac is the number of bits used to represent the fractional part

The Num operators for this type saturate to maxBound on overflow and minBound on underflow, and use truncation as the rounding method.

Saturating resize operation, truncates for rounding

>>> 0.8125 :: SFixed 3 4
0.8125
>>> resizeF (0.8125 :: SFixed 3 4) :: SFixed 2 3
0.75
>>> 3.4 :: SFixed 3 4
3.375
>>> resizeF (3.4 :: SFixed 3 4) :: SFixed 2 3
1.875
>>> maxBound :: SFixed 2 3
1.875

When used in a polymorphic setting, use the following Constraint synonyms for less verbose type signatures:

• ResizeFC rep int1 frac1 int2 frac2 for: Fixed rep int1 frac1 -> Fixed rep int2 frac2
• ResizeSFC int1 frac1 int2 frac2 for: SFixed int1 frac1 -> SFixed int2 frac2
• ResizeUFC rep int1 frac1 int2 frac2 for: UFixed int1 frac1 -> UFixed int2 frac2

Get the position of the virtual point of a Fixed-point number

Constraint for the Num instance of SFixed

Constraint for the ExtendingNum instance of SFixed

Constraint for the Fractional instance of SFixed

Constraint for the resizeF function, specialized for SFixed

Constraint for the divide function, specialized for SFixed

Constraint for the Num instance of UFixed

Constraint for the ExtendingNum instance of UFixed

Constraint for the Fractional instance of UFixed

Constraint for the resizeF function, specialized for UFixed

Constraint for the divide function, specialized for UFixed

Constraint for the Num instance of Fixed

Constraint for the ExtendingNum instance of Fixed

Constraint for the Fractional instance of Fixed

Constraint for the resizeF function

Constraint for the divide function

Fixed as a Proxy for it's representation type rep

Fixed as a Proxy for the number of integer bits int