Add comments to i2c core

Author: lmbollen

clash-cores/src/Clash/Cores/I2C.hs

@@ -21,29 +21,60 @@ import Clash.Cores.I2C.ByteMaster
                    , PortName "write"
                    , PortName "ackIn"
                    , PortName "din"
-                   , PortName "i2cI"]
+                     , PortProduct "i2c"
+                        [ PortName "sda"
+                        , PortName "sdaEn"]
+                        ]
     , t_output   = PortProduct ""
                      [ PortName "dout"
                      , PortName "hostAck"
                      , PortName "busy"
                      , PortName "al"
                      , PortName "ackOut"
-                     , PortProduct "" [PortName "i2cO_clk"]
-                     ]
+                     , PortProduct "i2cO"
+                        [ PortName "scl"
+                        , PortName "sclOEn"
+                        , PortName "sda"
+                        , PortName "sdaOEn"
+                     ]]
     }) #-}
+-- | Core for I2C communication
 i2c ::
+  -- | Input Clock
   Clock System ->
+  -- | Low level reset
   Reset System ->
+  -- | Statemachine reset
   Signal System Bool ->
+  -- | BitMaster enable
   Signal System Bool ->
+  -- | Clock divider
   Signal System (Unsigned 16) ->
+  -- | Start signal
   Signal System Bool ->
+  -- | Stop signal
   Signal System Bool ->
+  -- | Read signal
   Signal System Bool ->
+  -- | Write signal
   Signal System Bool ->
+  -- | Ack signal
   Signal System Bool ->
+  -- | Input data
   Signal System (BitVector 8) ->
+  -- | I2C input signals (SCL, SDA)
   Signal System (Bit, Bit) ->
+  -- |
+  -- 1. Received data
+  -- 2. Command acknowledgement
+  -- 3. I2C bus busy
+  -- 4. Arbitration lost
+  -- 5. I2C slave acknowledgement
+  -- 6. Outgoing I2C signals
+  --    6.1 SCL
+  --    6.2 SCL Output enable`
+  --    6.3 SDA
+  --    6.4 SDA Output enable
   ( Signal System (BitVector 8)
   , Signal System Bool
   , Signal System Bool

clash-cores/src/Clash/Cores/I2C/BitMaster.hs

@@ -13,6 +13,16 @@ import Clash.Cores.I2C.BitMaster.BusCtrl
 import Clash.Cores.I2C.BitMaster.StateMachine
 import Clash.Cores.I2C.Types
 
+-- | Internal state of the I2C BitMaster.
+--
+-- It includes the bus status controller, bit-level state machine, and various control signals and counters.
+-- The '_busState' manages the overall status of the I2C bus.
+-- The '_stateMachine' handles the bit-level I2C operations.
+-- The '_dout' holds the data to be sent out on the I2C bus.
+-- The '_dsclOen' is a delayed version of the SCL output enable signal.
+-- The '_clkEn' enables the clock for the state machine.
+-- The '_slaveWait' indicates if the slave is pulling the SCL line low, causing the master to wait.
+-- The '_cnt' is a counter used for clock division.
 data BitMasterS
   = BitS
   { _busState       :: BusStatusCtrl
@@ -27,7 +37,19 @@ data BitMasterS
 
 makeLenses ''BitMasterS
 
+
+-- | 5-tuple containing the input interface for the BitMaster.
+--  1. Resets the internal state when asserted
+--  2. Enables or disables the BitMaster
+--  3. Used for clock division
+--  4. Carries command and data in signals
+--  5. Contains the SCL and SDA input signals
 type BitMasterI = (Bool,Bool,Unsigned 16,BitCtrlSig,I2CIn)
+
+-- | 3-tuple containing the output interface for the BitMaster.
+-- 1. Carries command acknowledgment and other flags
+-- 2. Indicates if the BitMaster is currently busy
+-- 3. Contains the SCL and SDA output signals
 type BitMasterO = (BitRespSig,Bool,I2COut)
 
 {-# ANN bitMaster
@@ -51,7 +73,11 @@ type BitMasterO = (BitRespSig,Bool,I2COut)
                         , PortName "al"
                         , PortName "dout" ]
                      , PortName "busy"
-                     , PortName "i2cO"
+                     , PortProduct "i2c"
+                        [ PortName "sda"
+                        , PortName "sdaEn"
+                        , PortName "scl"
+                        , PortName "sclEn" ]
                      ]
     }) #-}
 bitMaster

clash-cores/src/Clash/Cores/I2C/BitMaster/BusCtrl.hs

@@ -10,6 +10,7 @@ import Control.Monad.State
 import Clash.Cores.I2C.BitMaster.StateMachine
 import Clash.Cores.I2C.Types
 
+-- | Bus status control state.
 data BusStatusCtrl
   = BusStatusCtrl
   { _sI2C           :: I2CIn       -- synchronized SCL and SDA
@@ -44,6 +45,8 @@ busStartState
 
 -- See: https://github.com/clash-lang/clash-compiler/pull/2511
 {-# CLASH_OPAQUE busStatusCtrl #-}
+-- | Low level bus status controller that monitors the state of the bus and performs
+-- glitch filtering. It detects start conditions, stop conditions and arbitration loss.
 busStatusCtrl :: Bool
               -> Bool
               -> Unsigned 16

clash-cores/src/Clash/Cores/I2C/BitMaster/StateMachine.hs

@@ -9,38 +9,49 @@ import Control.Monad.State
 
 import Clash.Cores.I2C.Types
 
+-- | States for bit-level I2C operations.
 data BitStateMachine
-  = Idle
-  | Start (Index 5)
-  | Stop  (Index 4)
-  | Read  (Index 4)
-  | Write (Index 4)
+  = Idle          -- ^ Idle state
+  | Start (Index 5) -- ^ Start condition state
+  | Stop  (Index 4) -- ^ Stop condition state
+  | Read  (Index 4) -- ^ Read operation state
+  | Write (Index 4) -- ^ Write operation state
   deriving (Eq, Generic, NFDataX)
 
+-- | Defines the state machine with control and status registers.
 data StateMachine
   = StateMachine
-  { _sclOen    :: Bool            -- i2c clock output enable register
-  , _sdaOen    :: Bool            -- i2c data output enable register
-  , _sdaChk    :: Bool            -- check SDA status (multi-master arbiter)
-  , _cmdAck    :: Bool            -- command completed
-  , _bitStateM :: BitStateMachine -- State Machine
+  { _sclOen    :: Bool            -- ^ Enables SCL output
+  , _sdaOen    :: Bool            -- ^ Enables SDA output
+  , _sdaChk    :: Bool            -- ^ Checks SDA status
+  , _cmdAck    :: Bool            -- ^ Acknowledges command completion
+  , _bitStateM :: BitStateMachine -- ^ Current state of the bit-level state machine
   } deriving (Generic, NFDataX)
 
 makeLenses ''StateMachine
 
-{-# INLINE stateMachineStart #-}
+-- | Initial state of the state machine.
 stateMachineStart :: StateMachine
 stateMachineStart
   = StateMachine
-  { _sclOen    = True
-  , _sdaOen    = True
-  , _sdaChk    = False
-  , _cmdAck    = False
-  , _bitStateM = Idle
+  { _sclOen    = True  -- ^ SCL output enabled by default
+  , _sdaOen    = True  -- ^ SDA output enabled by default
+  , _sdaChk    = False -- ^ SDA status check disabled by default
+  , _cmdAck    = False -- ^ Command acknowledgment flag set to false
+  , _bitStateM = Idle  -- ^ Initial state set to Idle
   }
 
 -- See: https://github.com/clash-lang/clash-compiler/pull/2511
 {-# CLASH_OPAQUE bitStateMachine #-}
+-- | Bit level I2C state machine that manages transitions between various states from
+-- 'StateMachine' based on the input parameters and the current state.
+--
+-- * In the 'Start' state, the function initiates the start condition on the I2C bus.
+-- * In the 'Stop' state, it initiates the stop condition, releasing the bus.
+-- * In the 'Read' state, it reads a bit from the slave device.
+-- * In the 'Write' state, it writes a bit to the slave device.
+--
+-- The function ensures that the state transitions are compliant with the I2C protocol.
 bitStateMachine :: Bool
                 -> Bool
                 -> Bool

clash-cores/src/Clash/Cores/I2C/ByteMaster.hs

@@ -30,7 +30,22 @@ data ByteMasterS
 
 makeLenses ''ByteMasterS
 
+-- |
+-- 1. Statemachine reset
+-- 2. Start
+-- 3. Stop
+-- 4. Read
+-- 5. Write
+-- 6. Acknowledge
+-- 7. Data in
+-- 8. Bitmaster response
 type ByteMasterI = (Bool,Bool,Bool,Bool,Bool,Bool,BitVector 8,BitRespSig)
+
+-- |
+-- 1. Acknowledge for I2C controller
+-- 2. I2C acknowledgement
+-- 3. Data output
+-- 4  Bitmaster control signals
 type ByteMasterO = (Bool,Bool,BitVector 8,BitCtrlSig)
 
 {-# ANN byteMaster
@@ -56,6 +71,10 @@ type ByteMasterO = (Bool,Bool,BitVector 8,BitCtrlSig)
                      , PortName "bitCtrl"
                      ]
     }) #-}
+-- | Byte level controller, takes care of correctly executing i2c communication
+-- based on the supplied control signals. It should be instantiated alongside 'bitMaster'.
+-- The outgoing bitCtrl' controls the 'bitMaster' whose 'bitResp' should be supplied
+-- as last input.
 byteMaster
   :: Clock System
   -> Reset System

clash-cores/src/Clash/Cores/I2C/Types.hs

@@ -2,11 +2,18 @@ module Clash.Cores.I2C.Types where
 
 import Clash.Prelude
 
+-- | I2C commands: start, stop, read, write, and no-op.
 data I2CCommand = I2Cstart | I2Cstop | I2Cwrite | I2Cread | I2Cnop
   deriving (Eq, Ord, Generic, NFDataX)
 
-type BitCtrlSig = (I2CCommand,Bit)
-type BitRespSig = (Bool,Bool,Bit)
+-- | Bit-level I2C control signals (Command, Bit).
+type BitCtrlSig = (I2CCommand, Bit)
 
-type I2CIn      = (Bit,Bit)
-type I2COut     = (Bit,Bool,Bit,Bool)
+-- | Bit-level I2C response signals (Ack, Busy, Bit).
+type BitRespSig = (Bool, Bool, Bit)
+
+-- | I2C input signals (SCL, SDA).
+type I2CIn = (Bit, Bit)
+
+-- | I2C output signals (SCL, SCL enable, SDA, SDA enable).
+type I2COut = (Bit, Bool, Bit, Bool)