// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
// TODO: This module is only a draft implementation that covers most of the clkmgr
// functionality but is incomplete


# CLKMGR register template
#
{
  name:               "clkmgr",
  human_name:         "Clock Manager",
  one_line_desc:      "Derives and monitors on-chip clock signals, handles clock gating requests from power manager and software",
  one_paragraph_desc: '''
  Clock Manager derives on-chip clocks from root clock signals provided by Analog Sensor Top (AST).
  Input and output clocks may be asynchronous to each other.
  During clock derivation, Clock Manager can divide clocks to lower frequencies and gate clocks based on control signals from the power manager and to a limited extent from software.
  For example, the idle status of relevant hardware blocks is tracked and clock gating requests from software are ignored as long as these blocks are active.
  Further security features include switchable clock jitter, continuous monitoring of clock frequencies, and various countermeasures to deter fault injection (FI) attacks.
  '''
  design_spec:        "../doc",
  dv_doc:             "../doc/dv",
  hw_checklist:       "../doc/checklist",
  sw_checklist:       "/sw/device/lib/dif/dif_clkmgr",
  revisions: [
    {
      version:            "1.0",
      life_stage:         "L1",
      design_stage:       "D1",
      verification_stage: "V1",
      dif_stage:          "S2",
    }
  ]
  clocking: [{clock: "clk_i", reset: "rst_ni"}],
  bus_interfaces: [
    { protocol: "tlul", direction: "device" }
  ],
  regwidth: "32",
  param_list: [
    { name: "NumGroups",
      desc: "Number of clock groups",
      type: "int",
      default: "7",
      local: "true"
    },
  ],

  countermeasures: [
    { name: "BUS.INTEGRITY",
      desc: "End-to-end bus integrity scheme."
    },
    { name: "TIMEOUT.CLK.BKGN_CHK",
      desc: "Background check for clock timeout."
    },
    { name: "MEAS.CLK.BKGN_CHK",
      desc: "Background check for clock frequency."
    },
    { name: "IDLE.INTERSIG.MUBI",
      desc: "Idle inputs are multibit encoded."
    }
    { name: "LC_CTRL.INTERSIG.MUBI",
      desc: "The life cycle control signals are multibit encoded."
    }
    { name: "LC_CTRL_CLK_HANDSHAKE.INTERSIG.MUBI",
      desc: "The life cycle clock req/ack signals are multibit encoded."
    }
    { name: "CLK_HANDSHAKE.INTERSIG.MUBI",
      desc: "The external clock req/ack signals are multibit encoded."
    }
    { name: "DIV.INTERSIG.MUBI",
      desc: "Divider step down request is multibit encoded."
    }
    { name: "JITTER.CONFIG.MUBI",
      desc: "The jitter enable configuration is multibit encoded."
    }
    { name: "IDLE.CTR.REDUN",
      desc: "Idle counter is duplicated."
    }
    { name: "MEAS.CONFIG.REGWEN",
      desc: "The measurement controls protected with regwen."
    }
    { name: "CLK_CTRL.CONFIG.REGWEN",
      desc: "Software controlled clock requests are proteced with regwen."
    }
  ]

  // Define rstmgr struct package
  inter_signal_list: [
    { struct:  "clkmgr_out",
      type:    "uni",
      name:    "clocks",
      act:     "req",
      package: "clkmgr_pkg",
    },

    { struct:  "pwr_clk",
      type:    "req_rsp",
      name:    "pwr",
      act:     "rsp",
    },

    { struct:  "clk_dft",
      type:    "uni",
      name:    "dft",
      act:     "rcv",
      package: "clkmgr_pkg", // This should be moved elsewhere later
    },

    { struct:  "clk_hint_status",
      type:    "uni",
      name:    "status",
      act:     "rcv",
      package: "clkmgr_pkg",
    },
  ],


  registers: [
    { name: "CLK_ENABLES",
      desc: '''
        Clock enable for software gateable clocks.
        These clocks are direclty controlled by software.
      ''',
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        {
          bits: "0",
          name: "CLK_FIXED_PERI_EN",
          resval: 1,
          desc: '''
            0 CLK_FIXED_PERI is disabled.
            1 CLK_FIXED_PERI is enabled.
          '''
        }
        {
          bits: "1",
          name: "CLK_USB_48MHZ_PERI_EN",
          resval: 1,
          desc: '''
            0 CLK_USB_48MHZ_PERI is disabled.
            1 CLK_USB_48MHZ_PERI is enabled.
          '''
        }
      ]
    },

    { name: "CLK_HINTS",
      desc: '''
        Clock hint for software gateable clocks.
        These clocks are not fully controlled by software.

        For disable, software only provides a hint, and hardware determines the final clock state based on the
        hint and whether the block in question is idle.

      ''',
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        {
          bits: "0",
          name: "CLK_MAIN_AES_HINT",
          resval: 1,
          desc: '''
            0 CLK_MAIN_AES can be disabled.
            1 CLK_MAIN_AES is enabled.
          '''
        }
        {
          bits: "1",
          name: "CLK_MAIN_HMAC_HINT",
          resval: 1,
          desc: '''
            0 CLK_MAIN_HMAC can be disabled.
            1 CLK_MAIN_HMAC is enabled.
          '''
        }
      ]
    },

    { name: "CLK_HINTS_STATUS",
      desc: '''
        Since the final state of !!CLK_HINTS is not always determined by software,
        this register provides read feedback for the current clock state.

      ''',
      swaccess: "ro",
      hwaccess: "hwo",
      fields: [
        {
          bits: "0",
          name: "CLK_MAIN_AES_VAL",
          resval: 1,
          desc: '''
            0 CLK_MAIN_AES is disabled.
            1 CLK_MAIN_AES is enabled.
          '''
        }
        {
          bits: "1",
          name: "CLK_MAIN_HMAC_VAL",
          resval: 1,
          desc: '''
            0 CLK_MAIN_HMAC is disabled.
            1 CLK_MAIN_HMAC is enabled.
          '''
        }
      ]
    },
  ]
}