// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{
  name: "clkmgr"
  // TODO: remove the common testplans if not applicable
  import_testplans: ["hw/dv/tools/dvsim/testplans/csr_testplan.hjson",
                     "hw/dv/tools/dvsim/testplans/intr_test_testplan.hjson",
                     "hw/dv/tools/dvsim/testplans/alert_test_testplan.hjson",
                     "hw/dv/tools/dvsim/testplans/tl_device_access_types_testplan.hjson",
                     "hw/dv/tools/dvsim/testplans/stress_all_with_reset_testplan.hjson"]
  testpoints: [
    {
      name: smoke
      desc: '''
            Smoke test disabling peripheral and transactional clocks.

            - Disables all peripheral clocks from their enabled reset state.
            - Transactional clocks gating depends on whether they are idle.
            - Initializes all units as busy (not idle).
            - Clears each unit's `clk_hints` bit, which has no effect until
              the unit becomes idle.
            - Sets the unit's `idle_i` bit, which should disable the clock.
            - Writes both values of the `jitter_enable` CSR.

            **Stimulus**:
            - CSR writes to `clk_enables` and `clk_hints`.
            - Setting `idle_i` clkmgr input.

            **Checks**:
            - SVA assertions for peripheral clocks enable and disable
              properties.
            - Transactional clocks check SVA properties as follows:
              - If the hint enables it, the clock becomes active.
              - If the hint disables it but the unit is busy, the clock remains
                active.
              - If the hint disables it and the unit is idle, the clock stops.
            - For transactional units the CSR `clk_hints_status` is checked
              to correspond to `clk_hints` once the units are idle.
            - Check in scoreboard the `jitter_en_o` output tracks updates of the
              `jitter_enable` CSR.
            '''
      milestone: V1
      tests: ["clkmgr_smoke"]
    }
    {
      name: peri_enables
      desc: '''
            Peripheral clocks are disabled if its `clk_enables` bit is off,
            or `pwr_i.ip_clk_en` is off, and `scanmode_i` is not
            `lc_ctrl_pkg::On`.

            This test runs multiple rounds, and on each one it randomizes
             `ip_clk_en` and `scanmode_i`, and the initial setting of
             `clk_enables`, it sends a CSR write to `csr_enables` with this
             initial value followed by a write that flips all bits. 

            **Checks**:
            - The scoreboard checks the gated clock activities against its
              model of the expected behavior.
            '''
      milestone: V2
      tests: ["clkmgr_peri"]
    }
    {
      name: trans_enables
      desc: '''
            Transactional unit clocks are disabled if they are not busy and
            their CSR `clk_hints` bit is off, or `pwr_i.ip_clk_en` is off,
            and `scanmode_i` is not `lc_ctrl_pkg::On`.
            This test randomizes `ip_clk_en`, the initial setting of `idle_i`
            and the desired value of `clk_hints`. Each round performs this
            sequence:
            - Writes the desired value to CSR `clk_hints` and checks that the
              CSR `clk_hints_status` reflects CSR `clk_hints` except for the
              units not-idle.
            - Marks all units as idle, and checks that `csr_hints_status`
              matches `clk_hints`.
            - Writes `clk_hints` to all ones and checks that `csr_hints_status`
              is all ones.
            - Writes `clk_hints` with its reset value.

            **Checks**:
            - SVA assertions for transactional unit clocks described in
              clkmgr_smoke.
            '''
      milestone: V2
      tests: ["clkmgr_trans"]
    }
    {
      name: extclk
      desc: '''
            Tests the functionality of enabling external clocks.

            - External clock is enabled if the `lc_clk_byp_req_i` input from
              `lc_ctrl` is `lc_ctrl_pkg::On`.
            - External clock is also be enabled when CSR `extclk_sel` is set to
              `lc_ctrl_pkg::On` and the `lc_dtl_en_i` input from `lc_ctrl` is
              `lc_ctrl_pkg::On`.
            - Notice writes to the `extclk_sel` register are ignored unless the
              CSR `extclk_sel_regwen` is 1.
            - A successful switch to external clocks will cause the clkmgr
              to undo a divide by 2 for io_div4 and io_div2 clocks except when
              `(scanmode_i == lc_ctrl_pkg::On)`.

            **Stimulus**:
            - CSR writes to `extclk_sel` and `extclk_sel_regwen`.
            - Setting `lc_dft_en_i`, `lc_clk_byp_req_i`, and the handshake to
              ast via `ast_clk_byp_req_o` and `ast_clk_byp_ack_i`.
            - Setting `scanmode_i`.

            **Checks**:
            Clock divider checks: since `scanmode_i` is asynchronous, the checks
            are performed in behavioral code in the scoreboard; SVA assertions
            will be added, conditioned on scanmode being off.
            - When the external clock is selected (and not defeated by
              `scanmode_i` for scoreboard checks):
              - The `clk_io_div2_powerup` output matches the `clk_io_powerup`
                 output.
              - The `clk_io_div4_powerup` output matches the `clk_io_powerup`
                 output at half its frequency.
            - When the external clock is not selected or division is defeated:
              - The `clk_io_div2_powerup` output matches the `clk_io_powerup`
                output at half its frequency.
              - The `clk_io_div4_powerup` output matches the `clk_io_powerup`
                 output at a quarter of its frequency.
            LC / AST handshake:
            - When the external clock functionality is triggered the
              `ast_clk_byp_req_o` output pin is set to `lc_ctrl_pkg::On`.
            - When `ast_clk_byp_ack_i` is set to `lc_ctrl_pkg::On` in response
              to a corresponding request:
              - The clock dividers are stepped down, unless defeated by
                 `scanmode_i` being `lc_ctrl_pkg::On`.
             - If the initial request was due to the assertion of the
               `lc_clk_byp_req_i`, the `lc_clk_byp_ack_o` output is set to
               `lc_ctrl_pkg::On`.
            '''
      milestone: V2
      tests: ["clkmgr_extclk"]
    }
    {
      name: clk_status
      desc: '''
            This tests the `pwr_o.clk_status` output port.

            The `pwr_o.clk_status` output must track the `pwr_i.ip_clk_en`
            input once the clock outputs are enabled when ip_clk_en is active,
            or disabled when ip_clk_en goes inactive.

            **Stimulus**:
            - Randomize the `pwr_i.ip_clk_en` setting.
            - Randomize the various pwrmgr clock controls per settings in
              the pwrmgr `control` CSR.
            - This will trigger cases where the usb clock is inactive with
              `ip_clk_en` enabled.

            **Check**:
            - The sequence checks that `pwr_o.clk_status` tracks
              `pwr_i.ip_clk_en`.
            '''
      milestone: V2
      tests: ["clkmgr_clk_status"]
    }
    {
      name: jitter
      desc: '''
            This tests the jitter functionality.

            The jitter functionality is implemented by the AST block, but
            controlled by the `jitter_enable` CSR in this block. This CSR
            directly drives the `jitter_en_o` output pin.

            **Stimulus**:
            - CSR write to `jitter_enable`.

            **Check**:
            - The `jitter_en_o` output pin reflects the `jitter_enable` CSR.
              Test is implemented in the scoreboard, and runs always.
            '''
      milestone: V2
      tests: ["clkmgr_smoke"]
    }
    {
      name: stress
      desc: '''Create standard stress tests.

            Stress with the following sequences:
            - clkmgr_extclk_vseq,
            - clkmgr_peri_vseq,
            - clkmgr_smoke_vseq,
            - clkmgr_trans_vseq
            '''
      milestone: V3
      tests: []
    }
  ]

  covergroups: [
    {
      name: peri_cg
      desc: '''
            Collects coverage for each peripheral clock.

            The peripheral clocks depend on a bit in the clk_enables CSR,
            the ip_clk_en input from pwrmgr, and the scanmode input.
            This collects the cross of them for each peripheral.

            FIXME This is collected in an array, one instance for each clock,
            but the dvsim coverage flow doesn't yet support arrays.
            '''
    }
    {
      name: trans_cg
      desc: '''
            Collects coverage for each transactional unit clock.

            The transactional unit clocks depend on a bit in the clk_hints CSR,
            the ip_clk_en input from pwrmgr, the respective idle input bit from
            the unit, and the scanmode input.
            This collects the cross of them for each transactional unit.

            FIXME This is collected in an array, one instance for each clock,
            but the dvsim coverage flow doesn't yet support arrays.
            '''
    }
    {
      name: extclk_cg
      desc: '''
            Collects coverage for the external clock selection.

            The external clock selection depends on the `extclk_sel` CSR,
            and the `lc_dft_en_i`, `lc_clk_byp_req_i`, and `scanmode_i`
            input pins. This covergroup collects their cross.
            '''
    }
    {
      name: jitter_cg
      desc: '''
            Collects coverage of the `jitter` CSR.
            '''
    }
  ]
}