// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{
  name:               "gpio",
  human_name:         "General-Purpose I/O Controller",
  one_line_desc:      "General-purpose I/O pin control interface for software",
  one_paragraph_desc: '''
  General-Purpose Input/Output (GPIO) Controller allows software to communicate through general-purpose I/O pins in a flexible manner.
  It supports up to 32 GPIO ports and each of these ports can be written as peripheral outputs in two modes: either with direct access to each GPIO value using direct write, allowing software to control all GPIO ports simultaneously, or with masked writes to half of the bits at a time, allowing software to affect the output value of a subset of the bits without requiring a read-modify-write.
  In the input direction, software can read the contents of any of the GPIO peripheral inputs, and it can request the detection of an interrupt event for any of the 32 bits in a configurable manner for detecting rising edge, falling edge, or active low/high input.
  A noise filter is available through configuration for any of the inputs.
  '''
  design_spec:        "../doc",
  dv_doc:             "../doc/dv",
  hw_checklist:       "../doc/checklist",
  sw_checklist:       "/sw/device/lib/dif/dif_gpio",
  revisions: [
    {
      version:            "1.0",
      life_stage:         "L2",
      design_stage:       "D3",
      verification_stage: "V3",
      commit_id:          "c1be7eb2b7265cd5ba6ceb026c28acf8e371151a",
      notes:              "",
    }
    {
      version:            "1.1",
      life_stage:         "L1",
      design_stage:       "D3",
      verification_stage: "V2",
      dif_stage:          "S2",
      commit_id:          "9a2fd04f5e1f36128c858d6a1a7b06c34681337c"
      notes:              ""
    }
  ]
  clocking: [{clock: "clk_i", reset: "rst_ni"}],
  bus_interfaces: [
    { protocol: "tlul", direction: "device" }
  ],
  available_inout_list: [
    { name: "gpio",
      width: 32,
      desc: "GPIO inout to/from PAD"
    }
  ],
  interrupt_list: [
    { name: "gpio",
      width: 32,
      desc: "raised if any of GPIO pin detects configured interrupt mode"
      auto_split: "true"
    }
  ],
  alert_list: [
    { name: "fatal_fault",
      desc: '''
      This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected.
      '''
    }
  ],
  param_list: [
    { name:    "GpioAsyncOn",
      type:    "bit",
      default: "1'b1",
      desc:    '''
      Instantiates 2-flop synchronizers on all GPIO inputs if set to 1.
      '''
      local:   "false",
      expose:  "true"
    },
  ]
  countermeasures: [
    { name: "BUS.INTEGRITY",
      desc: "End-to-end bus integrity scheme."
    }
  ]

  regwidth: "32",
  registers: [
    { name: "DATA_IN",
      desc: "GPIO Input data read value",
      swaccess: "ro",
      hwaccess: "hwo",
      tags: [// data_in is ro register, so exclude its readback check
             "excl:CsrNonInitTests:CsrExclWriteCheck"],
      fields: [
        { bits: "31:0",
          resval: "x"
        }
      ],
    },
    { name: "DIRECT_OUT",
      desc: "GPIO direct output data write value",
      swaccess: "rw",
      hwaccess: "hrw",
      hwext: "true",
      hwqe: "true",
      fields: [
        { bits: "31:0" }
      ],
    },
    { name: "MASKED_OUT_LOWER",
      desc: '''GPIO write data lower with mask.

            Masked write for DATA_OUT[15:0].

            Upper 16 bits of this register are used as mask. Writing
            lower 16 bits of the register changes DATA_OUT[15:0] value
            if mask bits are set.

            Read-back of this register returns upper 16 bits as zero
            and lower 16 bits as DATA_OUT[15:0].
            '''
      swaccess: "rw",
      hwaccess: "hrw",
      hwext: "true",
      hwqe: "true",
      tags: [// read value of masked_* registers yield a different value than written
             // avoid writing to masked_out* registers as they affect direct_out value
             "excl:CsrNonInitTests:CsrExclAll"],
      fields: [
        { bits: "15:0",
          name: "data",
          desc: '''Write data value[15:0].

                Value to write into DATA_OUT[i], valid in the presence of mask[i]==1
                '''
        },
        { bits: "31:16",
          name: "mask",
          desc: '''Write data mask[15:0].

                A value of 1 in mask[i] allows the updating of DATA_OUT[i], 0 <= i <= 15
                '''
          swaccess: "wo"
        },
      ],
    },
    { name: "MASKED_OUT_UPPER",
      desc: '''GPIO write data upper with mask.

            Masked write for DATA_OUT[31:16].

            Upper 16 bits of this register are used as mask. Writing
            lower 16 bits of the register changes DATA_OUT[31:16] value
            if mask bits are set.

            Read-back of this register returns upper 16 bits as zero
            and lower 16 bits as DATA_OUT[31:16].
            '''
      swaccess: "rw",
      hwaccess: "hrw",
      hwext: "true",
      hwqe: "true",
      tags: [// read value of masked_* registers yield a different value than written
             // avoid writing to masked_out* registers as they affect direct_out value
             "excl:CsrNonInitTests:CsrExclAll"],
      fields: [
        { bits: "15:0",
          name: "data",
          desc: '''Write data value[31:16].

                   Value to write into DATA_OUT[i], valid in the presence of mask[i]==1
                '''
        },
        { bits: "31:16",
          name: "mask",
          desc: '''Write data mask[31:16].

                A value of 1 in mask[i] allows the updating of DATA_OUT[i], 16 <= i <= 31
                '''
          swaccess: "wo"
        },
      ],
    },
    { name: "DIRECT_OE",
      desc: '''GPIO Output Enable.

            Setting direct_oe[i] to 1 enables output mode for GPIO[i]
            ''',
      swaccess: "rw",
      hwaccess: "hrw",
      hwext: "true",
      hwqe: "true",
      fields: [
        { bits: "31:0",
          auto_split: "true"
        }
      ],
    },
    { name: "MASKED_OE_LOWER",
      desc: '''GPIO write Output Enable lower with mask.

            Masked write for DATA_OE[15:0], the register that controls
            output mode for GPIO pins [15:0].

            Upper 16 bits of this register are used as mask. Writing
            lower 16 bits of the register changes DATA_OE[15:0] value
            if mask bits are set.

            Read-back of this register returns upper 16 bits as zero
            and lower 16 bits as DATA_OE[15:0].
            ''',
      swaccess: "rw",
      hwaccess: "hrw",
      hwext: "true",
      hwqe: "true",
      tags: [// read value of masked_* registers yield a different value than written
             // avoid writing to masked_oe* registers as they affect direct_oe value
             "excl:CsrNonInitTests:CsrExclAll"],
      fields: [
        { bits: "15:0",
          name: "data",
          desc: '''Write OE value[15:0].

                Value to write into DATA_OE[i], valid in the presence of mask[i]==1
                ''',
        },
        { name: "mask",
          desc: '''Write OE mask[15:0].

                A value of 1 in mask[i] allows the updating of DATA_OE[i], 0 <= i <= 15
                ''',
          bits: "31:16"
        },
      ],
    },
    { name: "MASKED_OE_UPPER",
      desc: '''GPIO write Output Enable upper with mask.

            Masked write for DATA_OE[31:16], the register that controls
            output mode for GPIO pins [31:16].

            Upper 16 bits of this register are used as mask. Writing
            lower 16 bits of the register changes DATA_OE[31:16] value
            if mask bits are set.

            Read-back of this register returns upper 16 bits as zero
            and lower 16 bits as DATA_OE[31:16].
            ''',
      swaccess: "rw",
      hwaccess: "hrw",
      hwext: "true",
      hwqe: "true",
      tags: [// read value of masked_* registers yield a different value than written
             // avoid writing to masked_oe* registers as they affect direct_oe value
             "excl:CsrNonInitTests:CsrExclAll"],
      fields: [
        { bits: "15:0",
          name: "data",
          desc: '''Write OE value[31:16].

                Value to write into DATA_OE[i], valid in the presence of mask[i]==1
                ''',
        },
        { name: "mask",
          desc: '''Write OE mask[31:16].

                A value of 1 in mask[i] allows the updating of DATA_OE[i], 16 <= i <= 31
                ''',
          bits: "31:16"
        },
      ],
    },

    { name: "INTR_CTRL_EN_RISING",
      desc: '''GPIO interrupt enable for GPIO, rising edge.

            If !!INTR_ENABLE[i] is true, a value of 1 on !!INTR_CTRL_EN_RISING[i]
            enables rising-edge interrupt detection on GPIO[i].
            ''',
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        { bits: "31:0" }
      ],
    },
    { name: "INTR_CTRL_EN_FALLING",
      desc: '''GPIO interrupt enable for GPIO, falling edge.

            If !!INTR_ENABLE[i] is true, a value of 1 on !!INTR_CTRL_EN_FALLING[i]
            enables falling-edge interrupt detection on GPIO[i].
            ''',
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        { bits: "31:0" }
      ],
    },
    { name: "INTR_CTRL_EN_LVLHIGH",
      desc: '''GPIO interrupt enable for GPIO, level high.

            If !!INTR_ENABLE[i] is true, a value of 1 on !!INTR_CTRL_EN_LVLHIGH[i]
            enables level high interrupt detection on GPIO[i].
            ''',
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        { bits: "31:0" }
      ],
    },
    { name: "INTR_CTRL_EN_LVLLOW",
      desc: '''GPIO interrupt enable for GPIO, level low.

            If !!INTR_ENABLE[i] is true, a value of 1 on !!INTR_CTRL_EN_LVLLOW[i]
            enables level low interrupt detection on GPIO[i].
            ''',
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        { bits: "31:0" }
      ],
    },
    { name: "CTRL_EN_INPUT_FILTER",
      desc: '''filter enable for GPIO input bits.

            If !!CTRL_EN_INPUT_FILTER[i] is true, a value of input bit [i]
            must be stable for 16 cycles before transitioning.
            ''',
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        { bits: "31:0" }
      ],
    },
  ],
}