// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{
  name:               "uart",
  human_name:         "UART",
  one_line_desc:      "Full duplex serial communication interface, supports bit rates of up to 1 Mbit/s",
  one_paragraph_desc: '''
  Universal Asynchronous Receiver/Transmitter (UART) provides industry standard serial communication with external devices via two wires at a programmable baud rate.
  Its full duplex design supports simultaneous transmission and reception, and flow control may be achieved using software handshaking if required.
  To reduce software load, UART includes hardware FIFOs and supports interrupt generation when the FIFO level reaches software-programmable thresholds.
  For compatibility with a variety of different targets and applications, the baud rate is software programmable and bit rates of up to 1 Mbit/s are supported.
  The data format is restricted to 8 bits, reducing the complexity and cost, with optional parity for robustness against transmission errors.
  '''
  design_spec:        "../doc",
  dv_doc:             "../doc/dv",
  hw_checklist:       "../doc/checklist",
  sw_checklist:       "/sw/device/lib/dif/dif_uart",
  revisions: [
  {
    version:            "1.0",
    life_stage:         "L2",
    design_stage:       "D3",
    verification_stage: "V3",
    commit_id:          "4166794b902cc72b4cfdfacca0869ffc56e6b42a",
    notes:              ""
  }
  {
    version:            "1.1",
    life_stage:         "L1",
    design_stage:       "D3",
    verification_stage: "V2",
    dif_stage:          "S2",
    commit_id:          "558942bb7869d9a5d8abd4bd0eb46dab820d3564"
    notes:              ""
  }
  ]
  clocking: [{clock: "clk_i", reset: "rst_ni"}],
  bus_interfaces: [
    { protocol: "tlul", direction: "device" }
  ],
  available_input_list: [
    { name: "rx", desc: "Serial receive bit" }
  ],
  available_output_list: [
    { name: "tx", desc: "Serial transmit bit" }
  ],
  interrupt_list: [
    { name: "tx_watermark"
      desc: "raised if the transmit FIFO is past the high-water mark."}
    { name: "rx_watermark"
      desc: "raised if the receive FIFO is past the high-water mark."}
    { name: "tx_empty"
      desc: "raised if the transmit FIFO has emptied and no transmit is ongoing."}
    { name: "rx_overflow"
      desc: "raised if the receive FIFO has overflowed."}
    { name: "rx_frame_err"
      desc: "raised if a framing error has been detected on receive."}
    { name: "rx_break_err"
      desc: "raised if break condition has been detected on receive."}
    { name: "rx_timeout"
      desc: '''
          raised if RX FIFO has characters remaining in the FIFO without being
          retrieved for the programmed time period.
          '''
    }
    { name: "rx_parity_err"
      desc: "raised if the receiver has detected a parity error."}
  ],
  alert_list: [
    { name: "fatal_fault",
      desc: '''
      This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected.
      '''
    }
  ],
  countermeasures: [
    { name: "BUS.INTEGRITY",
      desc: "End-to-end bus integrity scheme."
    }
  ]
  regwidth: "32",
  registers: [
    { name: "CTRL",
      desc: "UART control register",
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        { bits: "0",
          name: "TX",
          desc: "TX enable"
        }
        { bits: "1",
          name: "RX",
          desc: "RX enable"
          tags: [// enable RX in other tests only. In top-level, RX pin is driven by 0 when it's
                 // not selected at pinmux, which causes RX related status updated to non-default
                 // value
            "excl:CsrAllTests:CsrExclWrite"]
        }
        { bits: "2",
          name: "NF",
          desc: '''RX noise filter enable.
                If the noise filter is enabled, RX line goes through the 3-tap
                repetition code. It ignores single IP clock period noise.
          '''
        }
        { bits: "4",
          name: "SLPBK",
          desc: '''System loopback enable.

                If this bit is turned on, any outgoing bits to TX are received through RX.
                See Block Diagram. Note that the TX line goes 1 if System loopback is enabled.
                '''
        }
        { bits: "5",
          name: "LLPBK",
          desc: '''Line loopback enable.

                If this bit is turned on, incoming bits are forwarded to TX for testing purpose.
                See Block Diagram. Note that the internal design sees RX value as 1 always if line
                loopback is enabled.
                '''
        }
        { bits: "6",
          name: "PARITY_EN",
          desc: "If true, parity is enabled in both RX and TX directions."
        }
        { bits: "7",
          name: "PARITY_ODD",
          desc: "If PARITY_EN is true, this determines the type, 1 for odd parity, 0 for even."
        }
        { bits: "9:8",
          name: "RXBLVL",
          desc: '''
                Trigger level for RX break detection. Sets the number of character
                times the line must be low to detect a break.
                ''',
          enum: [
            { value: "0",
              name: "break2",
              desc: "2 characters"
            },
            { value: "1",
              name: "break4",
              desc: "4 characters"
            },
            { value: "2",
              name: "break8",
              desc: "8 characters"
            },
            { value: "3",
              name: "break16",
              desc: "16 characters"
            }
          ]
        }
        { bits: "31:16",
          name: "NCO",
          desc: "BAUD clock rate control."
        }
      ]
    },
    { name:     "STATUS"
      desc:     "UART live status register"
      swaccess: "ro"
      hwaccess: "hrw"
      hwext:    "true"
      hwre:     "true"
      fields: [
        { bits: "0"
          name: "TXFULL"
          desc: "TX buffer is full"
        }
        { bits: "1"
          name: "RXFULL"
          desc: "RX buffer is full"
        }
        { bits: "2"
          name: "TXEMPTY"
          desc: "TX FIFO is empty"
          resval: "1"
        }
        { bits: "3"
          name: "TXIDLE"
          desc: "TX FIFO is empty and all bits have been transmitted"
          resval: "1"
        }
        { bits: "4"
          name: "RXIDLE"
          desc: "RX is idle"
          resval: "1",
        }
        { bits: "5"
          name: "RXEMPTY"
          desc: "RX FIFO is empty"
          resval: "1"
        }
      ]
    }
    { name: "RDATA",
      desc: "UART read data",
      swaccess: "ro",
      hwaccess: "hrw",
      hwext: "true",
      hwre: "true",
      fields: [
        { bits: "7:0" }
      ]
      tags: [// read wdata when fifo is empty, dut may return unknown data
             "excl:CsrAllTests:CsrExclCheck"]
    }
    { name: "WDATA",
      desc: "UART write data",
      swaccess: "wo",
      hwaccess: "hro",
      hwqe: "true",
      fields: [
        { bits: "7:0" }
      ]
      tags: [// don't write to wdata - it affects several other csrs
             "excl:CsrNonInitTests:CsrExclWrite"]
    }
    { name: "FIFO_CTRL",
      desc: "UART FIFO control register",
      swaccess: "rw",
      hwaccess: "hrw",
      hwqe:     "true",
      fields: [
        { bits: "0",
          swaccess: "wo",
          hwaccess: "hro",
          name: "RXRST",
          desc: "RX fifo reset. Write 1 to the register resets RX_FIFO. Read returns 0"
        }
        { bits: "1",
          swaccess: "wo",
          hwaccess: "hro",
          name: "TXRST",
          desc: "TX fifo reset. Write 1 to the register resets TX_FIFO. Read returns 0"
        }
        { bits: "4:2",
          name: "RXILVL",
          desc: '''Trigger level for RX interrupts. If the FIFO depth is greater than or equal to
                the setting, it raises rx_watermark interrupt.
                ''',
          enum: [
            { value: "0",
              name: "rxlvl1",
              desc: "1 character"
            },
            { value: "1",
              name: "rxlvl4",
              desc: "4 characters"
            },
            { value: "2",
              name: "rxlvl8",
              desc: "8 characters"
            },
            { value: "3",
              name: "rxlvl16",
              desc: "16 characters"
            },
            { value: "4",
              name: "rxlvl30",
              desc: "30 characters"
            },
          ]
        }
        { bits: "6:5",
          name: "TXILVL",
          desc: '''Trigger level for TX interrupts. If the FIFO depth is less than the setting, it
                raises tx_watermark interrupt.
                ''',
          enum: [
            { value: "0",
              name: "txlvl1",
              desc: "2 characters"
            },
            { value: "1",
              name: "txlvl4",
              desc: "4 characters"
            },
            { value: "2",
              name: "txlvl8",
              desc: "8 characters"
            },
            { value: "3",
              name: "txlvl16",
              desc: "16 characters"
            }
          ]
        }
      ]
    }
    { name: "FIFO_STATUS",
      desc: "UART FIFO status register",
      swaccess: "ro",
      hwaccess: "hwo",
      hwext: "true",
      fields: [
        { bits: "5:0",
          name: "TXLVL",
          desc: "Current fill level of TX fifo"
        }
        { bits: "21:16",
          name: "RXLVL",
          desc: "Current fill level of RX fifo"
        }
      ]
    }
    { name: "OVRD",
      desc: "TX pin override control. Gives direct SW control over TX pin state",
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        { bits: "0",
          name: "TXEN",
          desc: "Enable TX pin override control",
          tags: [// writes to ovrd.txen causes tx output to be forced to ovrd.txval
                 // causing protocol violation
                 "excl:CsrAllTests:CsrExclWrite"]
        }
        { bits: "1",
          name: "TXVAL",
          desc: "Write to set the value of the TX pin"
        }
      ]
    }
    { name: "VAL",
      desc: "UART oversampled values",
      swaccess: "ro",
      hwaccess: "hwo",
      hwext:    "true",
      fields: [
        { bits: "15:0",
          name: "RX",
          desc: '''
                Last 16 oversampled values of RX. Most recent bit is bit 0, oldest 15.
                '''
          tags: [// UART oversampled values are updated by design according to setting and pin RX
                 "excl:CsrNonInitTests:CsrExclCheck"]
        }
      ]
    }
    { name: "TIMEOUT_CTRL",
      desc: "UART RX timeout control",
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        { bits: "23:0",
          name: "VAL",
          desc: "RX timeout value in UART bit times"
        }
        { bits: "31",
          name: "EN",
          desc: "Enable RX timeout feature"
        }
      ]
    }
  ]
}