clash-prelude-1.6.4: Clash: a functional hardware description language - Prelude library

Clash.Sized.Index

Description

Synopsis

# Documentation

data Index (n :: Nat) Source #

Arbitrarily-bounded unsigned integer represented by ceil(log_2(n)) bits

Given an upper bound n, an Index n number has a range of: [0 .. n-1]

>>> maxBound :: Index 8
7
>>> minBound :: Index 8
0
>>> read (show (maxBound :: Index 8)) :: Index 8
7
>>> 1 + 2 :: Index 8
3
>>> 2 + 6 :: Index 8
*** Exception: X: Clash.Sized.Index: result 8 is out of bounds: [0..7]
...
>>> 1 - 3 :: Index 8
*** Exception: X: Clash.Sized.Index: result -2 is out of bounds: [0..7]
...
>>> 2 * 3 :: Index 8
6
>>> 2 * 4 :: Index 8
*** Exception: X: Clash.Sized.Index: result 8 is out of bounds: [0..7]
...


NB: The usual Haskell method of converting an integral numeric type to another, fromIntegral, is not well suited for Clash as it will go through Integer which is arbitrarily bounded in HDL. Instead use bitCoerce and the Resize class.

Index has the type role

>>> :i Index
type role Index nominal
...


as it is not safe to coerce between Indexes with different ranges. To change the size, use the functions in the Resize class.

#### Instances

Instances details
 Source # Instance detailsDefined in Clash.Sized.Internal.Index Methodsresize :: forall (a :: Nat) (b :: Nat). (KnownNat a, KnownNat b) => Index a -> Index b Source #extend :: forall (a :: Nat) (b :: Nat). (KnownNat a, KnownNat b) => Index a -> Index (b + a) Source #zeroExtend :: forall (a :: Nat) (b :: Nat). (KnownNat a, KnownNat b) => Index a -> Index (b + a) Source #signExtend :: forall (a :: Nat) (b :: Nat). (KnownNat a, KnownNat b) => Index a -> Index (b + a) Source #truncateB :: forall (a :: Nat) (b :: Nat). KnownNat a => Index (a + b) -> Index a Source # KnownNat n => Lift (Index n :: Type) Source # Instance detailsDefined in Clash.Sized.Internal.Index Methodslift :: Index n -> Q Exp #liftTyped :: Index n -> Q (TExp (Index n)) # KnownNat n => Bounded (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index Methods KnownNat n => Enum (Index n) Source # The functions: enumFrom, enumFromThen, enumFromTo, and enumFromThenTo, are not synthesizable. Instance detailsDefined in Clash.Sized.Internal.Index Methodssucc :: Index n -> Index n #pred :: Index n -> Index n #toEnum :: Int -> Index n #fromEnum :: Index n -> Int #enumFrom :: Index n -> [Index n] #enumFromThen :: Index n -> Index n -> [Index n] #enumFromTo :: Index n -> Index n -> [Index n] #enumFromThenTo :: Index n -> Index n -> Index n -> [Index n] # Eq (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index Methods(==) :: Index n -> Index n -> Bool #(/=) :: Index n -> Index n -> Bool # KnownNat n => Integral (Index n) Source # NB: toInteger/fromIntegral can cause unexpected truncation, as Integer is arbitrarily bounded during synthesis. Prefer bitCoerce and the Resize class. Instance detailsDefined in Clash.Sized.Internal.Index Methodsquot :: Index n -> Index n -> Index n #rem :: Index n -> Index n -> Index n #div :: Index n -> Index n -> Index n #mod :: Index n -> Index n -> Index n #quotRem :: Index n -> Index n -> (Index n, Index n) #divMod :: Index n -> Index n -> (Index n, Index n) #toInteger :: Index n -> Integer # KnownNat n => Data (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index Methodsgfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Index n -> c (Index n) #gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Index n) #toConstr :: Index n -> Constr #dataTypeOf :: Index n -> DataType #dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Index n)) #dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Index n)) #gmapT :: (forall b. Data b => b -> b) -> Index n -> Index n #gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Index n -> r #gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Index n -> r #gmapQ :: (forall d. Data d => d -> u) -> Index n -> [u] #gmapQi :: Int -> (forall d. Data d => d -> u) -> Index n -> u #gmapM :: Monad m => (forall d. Data d => d -> m d) -> Index n -> m (Index n) #gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Index n -> m (Index n) #gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Index n -> m (Index n) # KnownNat n => Num (Index n) Source # Operators report an error on overflow and underflowNB: fromInteger/fromIntegral can cause unexpected truncation, as Integer is arbitrarily bounded during synthesis. Prefer bitCoerce and the Resize class. Instance detailsDefined in Clash.Sized.Internal.Index Methods(+) :: Index n -> Index n -> Index n #(-) :: Index n -> Index n -> Index n #(*) :: Index n -> Index n -> Index n #negate :: Index n -> Index n #abs :: Index n -> Index n #signum :: Index n -> Index n # Ord (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index Methodscompare :: Index n -> Index n -> Ordering #(<) :: Index n -> Index n -> Bool #(<=) :: Index n -> Index n -> Bool #(>) :: Index n -> Index n -> Bool #(>=) :: Index n -> Index n -> Bool #max :: Index n -> Index n -> Index n #min :: Index n -> Index n -> Index n # KnownNat n => Read (Index n) Source # None of the Read class' methods are synthesizable. Instance detailsDefined in Clash.Sized.Internal.Index MethodsreadsPrec :: Int -> ReadS (Index n) #readList :: ReadS [Index n] # KnownNat n => Real (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index MethodstoRational :: Index n -> Rational # Show (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index MethodsshowsPrec :: Int -> Index n -> ShowS #show :: Index n -> String #showList :: [Index n] -> ShowS # KnownNat n => Ix (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index Methodsrange :: (Index n, Index n) -> [Index n] #index :: (Index n, Index n) -> Index n -> Int #unsafeIndex :: (Index n, Index n) -> Index n -> Int #inRange :: (Index n, Index n) -> Index n -> Bool #rangeSize :: (Index n, Index n) -> Int #unsafeRangeSize :: (Index n, Index n) -> Int # Generic (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index Associated Typestype Rep (Index n) :: Type -> Type # Methodsfrom :: Index n -> Rep (Index n) x #to :: Rep (Index n) x -> Index n # KnownNat n => Arbitrary (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index Methodsarbitrary :: Gen (Index n) #shrink :: Index n -> [Index n] # KnownNat n => CoArbitrary (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index Methodscoarbitrary :: Index n -> Gen b -> Gen b # KnownNat n => PrintfArg (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index Methods (KnownNat n, 1 <= n) => Bits (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index Methods(.&.) :: Index n -> Index n -> Index n #(.|.) :: Index n -> Index n -> Index n #xor :: Index n -> Index n -> Index n #complement :: Index n -> Index n #shift :: Index n -> Int -> Index n #rotate :: Index n -> Int -> Index n #bit :: Int -> Index n #setBit :: Index n -> Int -> Index n #clearBit :: Index n -> Int -> Index n #complementBit :: Index n -> Int -> Index n #testBit :: Index n -> Int -> Bool #bitSize :: Index n -> Int #isSigned :: Index n -> Bool #shiftL :: Index n -> Int -> Index n #unsafeShiftL :: Index n -> Int -> Index n #shiftR :: Index n -> Int -> Index n #unsafeShiftR :: Index n -> Int -> Index n #rotateL :: Index n -> Int -> Index n #rotateR :: Index n -> Int -> Index n #popCount :: Index n -> Int # (KnownNat n, 1 <= n) => FiniteBits (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index MethodsfiniteBitSize :: Index n -> Int # KnownNat n => Default (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index Methodsdef :: Index n # NFData (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index Methodsrnf :: Index n -> () # (KnownNat n, 1 <= n) => SaturatingNum (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index MethodssatAdd :: SaturationMode -> Index n -> Index n -> Index n Source #satSub :: SaturationMode -> Index n -> Index n -> Index n Source #satMul :: SaturationMode -> Index n -> Index n -> Index n Source # NFDataX (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index MethodsensureSpine :: Index n -> Index n Source #rnfX :: Index n -> () Source # ShowX (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index MethodsshowsPrecX :: Int -> Index n -> ShowS Source #showX :: Index n -> String Source #showListX :: [Index n] -> ShowS Source # (KnownNat n, 1 <= n) => BitPack (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index Associated Typestype BitSize (Index n) :: Nat Source # Methodspack :: Index n -> BitVector (BitSize (Index n)) Source #unpack :: BitVector (BitSize (Index n)) -> Index n Source # (KnownNat n, 1 <= n) => Parity (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index Methodseven :: Index n -> Bool Source #odd :: Index n -> Bool Source # Bundle (Index n) Source # Instance detailsDefined in Clash.Signal.Bundle Associated Typestype Unbundled dom (Index n) = (res :: Type) Source # Methodsbundle :: forall (dom :: Domain). Unbundled dom (Index n) -> Signal dom (Index n) Source #unbundle :: forall (dom :: Domain). Signal dom (Index n) -> Unbundled dom (Index n) Source # Bundle (Index n) Source # Instance detailsDefined in Clash.Signal.Delayed.Bundle Associated Typestype Unbundled dom d (Index n) = (res :: Type) Source # Methodsbundle :: forall (dom :: Domain) (d :: Nat). Unbundled dom d (Index n) -> DSignal dom d (Index n) Source #unbundle :: forall (dom :: Domain) (d :: Nat). DSignal dom d (Index n) -> Unbundled dom d (Index n) Source # (1 <= n, KnownNat n) => Counter (Index n) Source # Instance detailsDefined in Clash.Class.Counter.Internal MethodscountSuccOverflow :: Index n -> (Bool, Index n) Source #countPredOverflow :: Index n -> (Bool, Index n) Source # AutoReg (Index n) Source # Instance detailsDefined in Clash.Class.AutoReg.Internal MethodsautoReg :: forall (dom :: Domain). (HasCallStack, KnownDomain dom) => Clock dom -> Reset dom -> Enable dom -> Index n -> Signal dom (Index n) -> Signal dom (Index n) Source # KnownNat m => Exp (Index m) Source # Instance detailsDefined in Clash.Class.Exp Associated Typestype ExpResult (Index m) n Source # Methods(^) :: forall (n :: Nat). Index m -> SNat n -> ExpResult (Index m) n Source # ExtendingNum (Index m) (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index Associated Typestype AResult (Index m) (Index n) Source #type MResult (Index m) (Index n) Source # Methodsadd :: Index m -> Index n -> AResult (Index m) (Index n) Source #sub :: Index m -> Index n -> AResult (Index m) (Index n) Source #mul :: Index m -> Index n -> MResult (Index m) (Index n) Source # type Unbundled dom d (Index n) Source # Instance detailsDefined in Clash.Signal.Delayed.Bundle type Unbundled dom d (Index n) = DSignal dom d (Index n) type Unbundled dom (Index n) Source # Instance detailsDefined in Clash.Signal.Bundle type Unbundled dom (Index n) = Signal dom (Index n) type TryDomain t (Index n) Source # Instance detailsDefined in Clash.Class.HasDomain.HasSingleDomain type TryDomain t (Index n) = 'NotFound type Rep (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index type Rep (Index n) = D1 ('MetaData "Index" "Clash.Sized.Internal.Index" "clash-prelude-1.6.4-inplace" 'True) (C1 ('MetaCons "I" 'PrefixI 'True) (S1 ('MetaSel ('Just "unsafeToInteger") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Integer))) type BitSize (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index type BitSize (Index n) = CLog 2 n type ExpResult (Index m) n Source # Instance detailsDefined in Clash.Class.Exp type ExpResult (Index m) n = Index (Max 2 (m ^ n)) type AResult (Index m) (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index type AResult (Index m) (Index n) = Index ((m + n) - 1) type MResult (Index m) (Index n) Source # Instance detailsDefined in Clash.Sized.Internal.Index type MResult (Index m) (Index n) = Index (((m - 1) * (n - 1)) + 1)

bv2i :: KnownNat n => BitVector n -> Index (2 ^ n) Source #

An alternative implementation of unpack for the Index data type; for when you know the size of the BitVector and want to determine the size of the Index.

That is, the type of unpack is:

unpack :: BitVector (CLog 2 n) -> Index n


And is useful when you know the size of the Index, and want to get a value from a BitVector that is large enough (CLog 2 n) enough to hold an Index. Note that unpack can fail at run-time when the value inside the BitVector is higher than 'n-1'.

bv2i on the other hand will never fail at run-time, because the BitVector argument determines the size.

fromSNat :: (KnownNat m, (n + 1) <= m) => SNat n -> Index m Source #

Safely convert an SNat value to an Index