Clash.Class.Counter

Utilities for wrapping counters consisting of multiple individual counters

Documentation

class Counter a

Counter is a class that composes multiple counters into a single one. It is similar to odometers found in olds cars, once all counters reach their maximum they reset to zero - i.e. odometer rollover. See countSucc and countPred for API usage examples.

Example use case: when driving a monitor through VGA you would like to keep track at least two counters: one counting a horizontal position, and one vertical. Perhaps a fancy VGA driver would also like to keep track of the number of drawn frames. To do so, the three counters are setup with different types. On each round of the horizontal counter the vertical counter should be increased. On each round of the vertical counter the frame counter should be increased. With this class you could simply use the type:

(FrameCount, VerticalCount, HorizontalCount)

and have countSucc work as described.

NB: This class exposes four functions countMin, countMax, countSuccOverflow, and countPredOverflow. These functions are considered an internal API. Users are encouraged to use countSucc and countPred.

Instances

KnownNat n => Counter (BitVector n)

Defined in Clash.Class.Counter.Internal

Methods

countMin :: BitVector n

countMax :: BitVector n

countSuccOverflow :: BitVector n -> (Bool, BitVector n)

countPredOverflow :: BitVector n -> (Bool, BitVector n)

(1 <= n, KnownNat n) => Counter (Index n)

Defined in Clash.Class.Counter.Internal

Methods

countMin :: Index n

countMax :: Index n

countSuccOverflow :: Index n -> (Bool, Index n)

countPredOverflow :: Index n -> (Bool, Index n)

KnownNat n => Counter (Unsigned n)

Defined in Clash.Class.Counter.Internal

Methods

countMin :: Unsigned n

countMax :: Unsigned n

countSuccOverflow :: Unsigned n -> (Bool, Unsigned n)

countPredOverflow :: Unsigned n -> (Bool, Unsigned n)

KnownNat n => Counter (Signed n)

Defined in Clash.Class.Counter.Internal

Methods

countMin :: Signed n

countMax :: Signed n

countSuccOverflow :: Signed n -> (Bool, Signed n)

countPredOverflow :: Signed n -> (Bool, Signed n)

(Counter a, Counter b) => Counter (Either a b)

Counter instance that flip-flops between Left and Right. Examples:

>>> type T = Either (Index 2) (Unsigned 2)
>>> countSucc @T (Left 0)
Left 1
>>> countSucc @T (Left 1)
Right 0
>>> countSucc @T (Right 0)
Right 1

Defined in Clash.Class.Counter.Internal

Methods

countMin :: Either a b

countMax :: Either a b

countSuccOverflow :: Either a b -> (Bool, Either a b)

countPredOverflow :: Either a b -> (Bool, Either a b)

(Counter a0, Counter a1) => Counter (a0, a1)

Counters on tuples increment from right-to-left. This makes sense from the perspective of LSB/MSB; MSB is on the left-hand-side and LSB is on the right-hand-side in other Clash types.

>>> type T = (Unsigned 2, Index 2, Index 2)
>>> countSucc @T (0, 0, 0)
(0,0,1)
>>> countSucc @T (0, 0, 1)
(0,1,0)
>>> countSucc @T (0, 1, 0)
(0,1,1)
>>> countSucc @T (0, 1, 1)
(1,0,0)

NB: The documentation only shows the instances up to 3-tuples. By default, instances up to and including 12-tuples will exist. If the flag large-tuples is set instances up to the GHC imposed limit will exist. The GHC imposed limit is either 62 or 64 depending on the GHC version.

Defined in Clash.Class.Counter.Internal

Methods

countMin :: (a0, a1)

countMax :: (a0, a1)

countSuccOverflow :: (a0, a1) -> (Bool, (a0, a1))

countPredOverflow :: (a0, a1) -> (Bool, (a0, a1))

(Counter a0, Counter a1, Counter a2) => Counter (a0, a1, a2)

Defined in Clash.Class.Counter.Internal

Methods

countMin :: (a0, a1, a2)

countMax :: (a0, a1, a2)

countSuccOverflow :: (a0, a1, a2) -> (Bool, (a0, a1, a2))

countPredOverflow :: (a0, a1, a2) -> (Bool, (a0, a1, a2))

countSucc :: Counter a => a -> a

Successor of a counter.

Examples:

>>> type T = (Unsigned 2, Unsigned 2)
>>> countSucc @T (1, 1)
(1,2)
>>> countSucc @T (1, 2)
(1,3)
>>> countSucc @T (1, 3)
(2,0)
>>> countSucc @T (3, 3)
(0,0)
>>> countSucc @(Index 9, Index 2) (0, 1)
(1,0)
>>> countSucc @(Either (Index 9) (Index 9)) (Left 8)
Right 0

countPred :: Counter a => a -> a

Predecessor of a counter

Examples:

>>> type T = (Unsigned 2, Unsigned 2)
>>> countPred @T (1, 2)
(1,1)
>>> countPred @T (1, 3)
(1,2)
>>> countPred @T (2, 0)
(1,3)
>>> countPred @T (0, 0)
(3,3)
>>> countPred @(Index 9, Index 2) (1, 0)
(0,1)
>>> countPred @(Either (Index 9) (Index 9)) (Right 0)
Left 8