// 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",
                     // Disable alert and interrupt tests until RTL adds support.'
                     // "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"]
  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.

            **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.
            '''
      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 `clk_hints` bit is off, or `pwr_i.ip_clk_en` is off,
            and `scanmode_i` is not `lc_ctrl_pkg::On`.
            This test randomize `ip_clk_en`, the initial setting of `idle_i`
            and `clk_hints`, and flips any bit in `clk_hints`. If the
            corresponding unit is not idle it waits some cycles and clears its
            `idle_i` bit.

            **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 clocks can be enabled writing `lc_ctrl_pkg::On` to CSR
              `extclk_sel`.
            - Writes to CSR `extclk_sel` are ignored unless the value of CSR
              `extclk_sel_regwen` is 1.
            - Regardless of the `extclk_sel` contents, external clocks won't
              be enabled unless `lc_dtl_en_i == lc_ctrl_pkg::On`.
            - External clocks can also be enabled if the input
             `lc_clk_byp_req_i == lc_ctrl_pkg::On`.
            - A successful switch to external clocks will cause the clkmgr
              to undo a divide by 2 for io_div4 and io_div2 clocks unless in
              scan mode `(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`.

            **Checks**:
            - SVA assertions:
              - `lc_clk_byp_req_i == lc_ctrl_pkg::On` causes
                `ast_clk_byp_req_o == lc_ctrl_pkg::On`.
              - `extclk_sel == lc_ctrl_pkg::On` and
                `lc_dft_en_i == lc_ctrl_pkg::On` causes
                `ast_clk_byp_req_o == lc_ctrl_pkg::On`.
              - `ast_clk_byp_ack_i == lc_ctrl_pkg::On` causes the divided
                clocks to ramp up unless `scanmode_i == lc_ctrl_pkg::On`.
            '''
      milestone: V2
      tests: []
    }
  ]
  // The covergroups are arrays, which are yet to be supported by the tools.
  covergroups: [
    // peri_cg_wrap cover the dependencies of each peripheral clock.
    // trans_cg_wrap  cover the dependencies of each transactional unit clock.
  ]
}