hw/ip/rv_dm/data/rv_dm.hjson

// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{
  name:               "rv_dm",
  human_name:         "RISC-V Debug Module",
  one_line_desc:      "Enables debug support for Ibex, access protected by life cycle",
  one_paragraph_desc: '''
  RISC-V Debug Module provides a JTAG test access port (TAP) to interface the Ibex RISC-V core as well as hardware blocks attached to the TileLink on-chip interconnect.
  The interface to Ibex is compliant with the RISC-V Debug Specification 0.13.2, which in turn is supported by debug software such as OpenOCD and GDB.
  For security reasons, RISC-V Debug Module is only active in life cycles that have hardware debug enabled.
  '''
  design_spec:        "../doc",
  dv_doc:             "../doc/dv",
  hw_checklist:       "../doc/checklist",
  sw_checklist:       "",
  version:            "1.0",
  life_stage:         "L1",
  design_stage:       "D2S",
  verification_stage: "V1",
  clocking: [
    {clock: "clk_i", reset: "rst_ni"}
  ]
  bus_interfaces: [
    { protocol: "tlul", direction: "host",   name: "sba" }
    { protocol: "tlul", direction: "device", name: "regs" }
    { protocol: "tlul", direction: "device", name: "mem" }
  ],
  scan: "true", // Enable `scanmode_i` port
  scan_reset: "true", // Enable `scan_rst_ni` port
  param_list: [
    { name:    "NrHarts",
      type:    "int",
      // TODO(b/271173103).
      default: "2",
      desc:    "Number of hardware threads in the system."
      local:   "true"
    },
    { name:    "IdcodeValue",
      type:    "logic [31:0]",
      default: "32'h 0000_0001",
      desc:    "RISC-V debug module JTAG ID code."
      local:   "false",
      expose:  "true"
    },
  ]
  interrupt_list: [
  ],
  alert_list: [
    { name: "fatal_fault",
      desc: '''
      This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected.
      '''
    }
  ],
  inter_signal_list: [
    { struct:  "jtag",
      type:    "req_rsp",
      name:    "jtag",
      act:     "rsp",
      package: "jtag_pkg",
      desc:    "JTAG signals for the RISC-V TAP."
    },
    { struct:  "lc_tx"
      type:    "uni"
      name:    "lc_hw_debug_en"
      act:     "rcv"
      default: "lc_ctrl_pkg::Off"
      package: "lc_ctrl_pkg"
      desc:    '''
               Multibit life cycle hardware debug enable signal coming from life cycle controller,
               asserted when the hardware debug mechanisms are enabled in the system.
               '''
    },
    { struct:  "lc_tx"
      type:    "uni"
      name:    "pinmux_hw_debug_en"
      act:     "rcv"
      default: "lc_ctrl_pkg::Off"
      package: "lc_ctrl_pkg"
      desc:    '''
               Multibit life cycle hardware debug enable signal coming from pinmux.
               This is a latched version of the lc_hw_debug_en signal and is only used to
               gate the JTAG / TAP side of the RV_DM. It is used to keep a debug session live
               while the rest of the system undergoes an NDM reset.
               '''
    },
    // TBD: should we connect this to the clock manager?
    { struct:  "logic"
      type:    "uni"
      name:    "unavailable"
      act:     "rcv"
      default: "2'b0"
      desc:    '''
               This signal indicates to the debug module that the main processor is not available
               for debug (e.g. due to a low-power state).
               '''
    },
    { struct:  "logic"
      type:    "uni"
      name:    "ndmreset_req"
      act:     "req"
      desc:    "Non-debug module reset request going to the system reset infrastructure."
    },
    { struct:  "logic"
      type:    "uni"
      name:    "dmactive"
      act:     "req"
      desc:    '''
               This signal indicates whether the debug module is active and can be used to prevent
               power down of the core and bus-attached peripherals.
               '''
    },
    { struct:  "logic"
      type:    "uni"
      name:    "debug_req"
      act:     "req"
      desc:    "This is the debug request interrupt going to the main processor."
      // TODO(b/271173103).
      width:   "2"
    },
  ]
  countermeasures: [
    { name: "BUS.INTEGRITY",
      desc: "End-to-end bus integrity scheme."
    }
    { name: "LC_HW_DEBUG_EN.INTERSIG.MUBI",
      desc: "The life cycle hardware debug enable signal is multibit encoded."
    }
    { name: "DM_EN.CTRL.LC_GATED",
      desc: '''
            The debug module is enabled with the LC_HW_DEBUG_EN signal.
            This enablement is implemented by gating / enabling critical
            blocks with separately buffered copies of the life cycle signal.
            This comprises the debug module interface (DMI) attached to the TAP,
            the reset request line, the system bus access module (SBA), the debug
            request output, the TL-UL adapter for the debug ROM, and the ifetch indicator
            being fed into the TL-UL adapter for the debug ROM.
            '''
    }
    { name: "SBA_TL_LC_GATE.FSM.SPARSE",
      desc: "The control FSM inside the TL-UL gating primitive is sparsely encoded."
    }
    { name: "MEM_TL_LC_GATE.FSM.SPARSE",
      desc: "The control FSM inside the TL-UL gating primitive is sparsely encoded."
    }
    { name: "EXEC.CTRL.MUBI",
      desc: '''
            The instruction fetch enable signal that is modulated with LC_HW_DEBUG_EN
            and that feeds into the TL-UL adapter is multibit encoded.
            '''
    }
  ]
  regwidth: "32",
  registers: {
    regs:[
    ]
    mem: [
      // Expansion of debug memory within rv_dm used for DV purposes. The generated reg_top is not
      // actually instantiated in RTL since the debug memory region is implemented inside the
      // vendored-in module from the PULP project.
      //
      // The debug memory region is specified in the PULP debug system documentation here:
      // https://github.com/pulp-platform/riscv-dbg/blob/master/doc/debug-system.md
      //
      // The debug module exposes a 16kB memory called debug memory. It has a ROM portion
      // (debug ROM), some memory mapped CSRs and a RAM portion (program buffer). This region is
      // accessible over the TL interface only if debug mode is active.
      { skipto: "0x100" }
      { name:  "HALTED"
        desc: "Write to this address to acknowledge that the core has halted.",
        swaccess: "wo",
        hwaccess: "hrw", // updated by write to RESUMING
        fields: [
          { bits: "0",
            resval: "0" // core ID value
          },
        ]
      },
      { skipto: "0x108" }
      { name: "GOING",
        desc: "Write to this address to acknowledge that the core is executing.",
        swaccess: "wo",
        hwaccess: "hro",
        fields: [
          { bits: "0",
            resval: "0"
          },
        ]
      },
      { skipto: "0x110" }
     {  name:  "RESUMING"
        desc: "Write to this address to acknowledge that the core is resuming non-debug operation.",
        swaccess: "wo",
        hwaccess: "hro",
        fields: [
          { bits: "0",
            resval: "0" // core ID value
          },
        ]
      },
      { skipto: "0x118" }
      { name: "EXCEPTION",
        desc: "An exception was triggered while the core was in debug mode.",
        swaccess: "wo",
        hwaccess: "hro",
        fields: [
          { bits: "0",
            resval: "0"
          },
        ]
      },
      { skipto: "0x300" }
      { name: "WHERETO",
        desc: "TODO: No description provided in the spec.",
        swaccess: "ro",
        hwaccess: "hrw",
        fields: [
          { bits: "31:0",
            resval: "0"
          },
        ]
      },
      { skipto: "0x338" }
      { multireg: {
          cname: "ABSTRACTCMD"
          name:  "ABSTRACTCMD"
          desc:  "TODO: No description provided in the spec."
          count: "10"
          swaccess: "ro"
          hwaccess: "hro"
          fields: [
            { bits: "31:0"
              resval: "0"
            }
          ]
          tags: [// TODO: It is unclear how to predict these values.
                 "excl:CsrAllTests:CsrExclCheck"]
        }
      },
      { multireg: {
          cname: "PROGRAM_BUFFER"
          name:  "PROGRAM_BUFFER"
          desc:  "TODO: No description provided in the spec."
          count: "8"
          swaccess: "ro"
          hwaccess: "hro"
          fields: [
            { bits: "31:0"
              resval: "0"
            }
          ]
        }
      },
      { multireg: {
          cname: "DATAADDR"
          name:  "DATAADDR"
          desc:  "TODO: No description provided in the spec."
          count: "2"
          swaccess: "rw"
          hwaccess: "hro"
          fields: [
            { bits: "31:0"
              resval: "0"
            }
          ]
          tags: [// TODO: Write-read-check will work after "activating" the debug module via JTAG.
                 "excl:CsrNonInitTests:CsrExclWriteCheck"]
        }
      },
      { skipto: "0x400" }
      { multireg: {
          cname: "FLAGS"
          name:  "FLAGS"
          desc:  "TODO: No description provided in the spec."
          count: "256"
          swaccess: "ro"
          hwaccess: "hro"
          fields: [
            { bits: "31:0"
              resval: "0"
            }
          ]
        }
      },
      // Note that this region starts at `0x800` and contains the HaltAddress,
      // ResumeAddress and ExceptionAddress locations.
      { window: {
          name: "ROM"
          // ROM size (given as `items` below) must be a power of two.
          // The 512 x 4 = 2 KiB are enough to hold the 20 x 8 = 0x98 bytes
          // currently allocated in the debug ROM.
          items: "512"
          swaccess: "ro",
          desc: '''Access window into the debug ROM.'''
        }
      },
    ]
  }
}