// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{
  name: "i2c"
  import_testplans: ["hw/dv/tools/testplans/csr_testplan.hjson",
                     "hw/dv/tools/testplans/intr_test_testplan.hjson",
                     "hw/dv/tools/testplans/tl_device_access_types_testplan.hjson"]
  entries: [
    {
      name: sanity
      desc: '''
            Basic I2C sanity test in which random (rd/wr) transactions are sent to the DUT 
            and received asynchronously with scoreboard checks.

            Stimulus:
              - Enable I2C host
              - Clear/Enable interrupt (if needed)
              - Program OVRD, FDATA register
              - Randomize I2C timing in TIMING 0-4 registers and other parameters such as TL agent delays
              - Randomize address and data for read/write transactions sent to the device

            Checking:
              - Check the timing behavior of START, STOP, ACK, NACK, and "repeated" START
              - Read and write transfer matching
            '''
      milestone: V1
      tests: ["i2c_sanity"]
    }
    {
      name: error
      desc: '''
            Test if the host receives interference and unstable scl and sda.

            Stimulus:
              - Within the clock pulse of the host scl, the device randomly asserts/deasserts its scl and sda

            Checking:
              - Ensure all intr_scl_interference, intr_sda_interference, and intr_sda_unstable interrupts are asserted
              - Ensure all intr_scl_interference, intr_sda_interference, and intr_sda_unstable interrupts stay asserted until cleared
            '''
      milestone: V2
      tests: ["i2c_error"]
    }
    {
      name: stress_all_with_reset
      desc: '''
            Pull reset at random times, ensure DUT are reset and recovered/ correctly and
            there is no residual data left in the registers.

            Stimulus:
              - Randomly reset DUT
              - Restart send/receive transaction

            Checking:
              - Ensure registers are properly reset
            '''
      milestone: V2
      tests: ["i2c_stress_all_with_rand_reset"]
    }
    {
      name: perf
      desc: '''
            Send/receive transactions at max bandwidth.

            Stimulus:
              - Reduce access latency for fmt_fifo and rx_fifo
              - Issue long read/write back-to-back transactions 
              - Read rx_fifo as soon as read data valid
              - Clear interrupt quickly
            Checking:
              - Ensure transactions are transceivered correctly
            '''
      milestone: V2
      tests: ["i2c_perf"]
    }
    {
      name: stress
      desc: '''
            Test multiple interrupts asserted.

            Stimulus:
              - Do combinations of multiple of above scenarios to get multiple interrupts asserted at the same time
              - Scoreboard should be robust enough to deal with all scenarios

            Checking:
              - Ensure multiple interrupts are asserted
            '''
      milestone: V2
      tests: ["i2c_stress"]
    }
    {
      name: override
      desc: '''
            Test SCL/SDA override.

            Stimulus:
              - Program OVRD register

            Checking:
              - Ensure scl_o, sda_o are overridden
            '''
      milestone: V2
      tests: ["i2c_override"]
    }
    {
      name: fifo_watermark
      desc: '''
            Test the watermark interrupt of fmt_fifo and rx_fifo.

            Stimulus:
              - Program random fmt_fifo and rx_fifo watermark level
              - Write data quickly to fmt_fifo and rx_fifo for triggering watermark interrupts

            Checking:
              - Ensure the fmt_fifo and rx_fifo watermark interrupts are asserted
              - Ensure the fmt_fifo and rx_fifo watermark interrupts stay asserted until cleared
              - Ensure receving correct number of fmt_fifo and rx_fifo watermark interrupts
            '''
      milestone: V2
      tests: ["i2c_fifo_watermark"]
    }
    {
      name: fifo_overflow
      desc: '''
            Test the overflow interrupt of fmt_fifo and rx_fifo.

            Stimulus:
              - Keep sending a number of format byte higher than fmt_fifo and rx_fifo depth

            Checking:
              - Ensure excess format bytes are dropped
              - Ensure fmt_overflow and rx_overflow interrupt are asserted
              - Ensure receving correct number of fmt_fifo and rx_fifo watermark interrupts
            '''
      milestone: V2
      tests: ["i2c_fifo_overflow"]
    }
    {
      name: fmt_reset
      desc: '''
            Test fmt_fifo reset.

            Stimulus:
              - Fill up the fmt fifo with data to be sent out
              - Reset the fmt_fifo randomly after a number of bytes shows up on fmt_fifo 

            Checking:
              - Ensure the remaining entries are not show up after fmt_fifo is reset
            '''
      milestone: V2
      tests: []
    }
    {
      name: rx_reset
      desc: '''
            Test rx_fifo reset.

            Stimulus:
              - Fill up the rx fifo by sending data bytes over rx
              - Reset the rx_fifo randomly after a random number of bytes shows up on rx_fifo

            Checking:
              - Ensure that reads to rdata register yield 0s after rx_fifo is reset
            '''
      milestone: V2
      tests: []
    }
    {
      name: fmt_rx_fifo_full
      desc: '''
            Test fmt_fifo and rx_fifo in full states.

            Stimulus:
              - Send enough read requests, not read data out,
                then stop until both fmt and rx fifo is full

            Checking:
              - Check fifo full states by reading status register
            '''
      milestone: V2
      tests: []
    }
    {
      name: rx_timeout
      desc: '''
            Test rx_timeout state.

            Stimulus:
              - Program timeout enable bit into timeout_ctrl register
              - Program timeout values (higher than host scl clock pulse) into timeout_ctrl register
              - Configure agent to pull down target(device) scl after the bit 9 (acknowledge bit) is transmitted

            Checking:
              - Ensure intr_stretch_timeout interrupt is asserted
            '''
      milestone: V2
      tests: []
    }
    {
      name: rx_oversample
      desc: '''
            Test rc oversampling.

            Stimulus:
              - Use input clock to sample the target sda (sample with baud rate equal to 1)
              - Drive scl_rx using input clock

            Checking:
              - Read rx data oversampled value and ensure it is same as driven value
            '''
      milestone: V2
      tests: []
    }
    {
      name: rw_loopback
      desc: '''
            Test write data, read loopback, then compare.

            Stimulus:
              - Drive i2c host to write data to the device then read loopback

            Checking:
              - Ensure read data is matched with write data
            '''
      milestone: V2
      tests: []
    }
  ]
}