// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{ name: "usbuart",
  clocking: [
    {clock: "clk_i", reset: "rst_ni", primary: true},
    {clock: "clk_usb_48mhz_i", reset: "rst_usb_48mhz_ni"}
  ]
  bus_interfaces: [
    { protocol: "tlul", direction: "device" }
  ],
  available_inout_list: [
    { name: "usb_dp", desc: "USB data D+" }
    { name: "usb_dm", desc: "USB data D-" }
  ],
  available_input_list: [
    {  name: "usb_sense", desc: "USB host VBUS sense" }
  ],
  available_output_list: [
    { name: "usb_pullup", desc: "USB FS pullup control" }
  ],
  interrupt_list: [
    { name: "tx_watermark"
      desc: "raised if the transmit FIFO is past the highwater mark."}
    { name: "rx_watermark"
      desc: "raised if the receive FIFO is past the highwater mark."}
    { name: "tx_overflow"
      desc: "raised if the transmit FIFO has overflowed."}
    { 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,
            which will never happen on the USB interface.
            '''}
    { name: "rx_break_err"
      desc: '''
            raised if break condition has been detected on receive.
            This is done if either the host is not providing VBUS or has not
            provided a Start of Frame indication in 2.048ms.
            '''}
    { 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,
            which will never happen on the USB interface.
            '''}
  ]
  alert_list: [
    { name: "fatal_fault",
      desc: '''
      This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected inside the USBUART unit.
      '''
    }
  ],
  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, if this bit is set (or the RX) the USB
                interface is enabled by asserting the usb_pullup.
                '''
        }
        { bits: "1",
          name: "RX",
          desc: '''
                RX enable, if this bit is set (or the TX) the USB
                interface is enabled by asserting the usb_pullup.
                '''
        }
        { bits: "2",
          name: "NF",
          desc: "Ignored (RX noise filter enable)"
        }
        { bits: "4",
          name: "SLPBK",
          desc: '''System loopback enable

                If this bit is turned on, bytes written to the tx fifo
                will loop back to the rx fifo. They will be syncronized
                through the USB 48MHz clock domain. When in loopback the
                USB interface will always see an empty TX fifo so will
                never send any data, and all data received on the USB
                interface is discarded.
                '''
        }
        { bits: "5",
          name: "LLPBK",
          desc: "Ignored (Line loopback enable)"
        }
        { bits: "6",
          name: "PARITY_EN",
          desc: "Ignored (Parity enable)"
        }
        { bits: "7",
          name: "PARITY_ODD",
          desc: "Ignored (1 for odd parity, 0 for even.)"
        }
        { bits: "9:8",
          name: "RXBLVL",
          desc: '''
                Trigger level for rx break detection.
                A break is detected whenever the USB Host VBUS is dropped
                or if the host stops sending Start of Frame packets (which
                should arrive every 1ms). If this field is 0 then the
                break is detected if no SOF is received for 2.048ms,
                if non-zero then when no SOF is received for 1s.
                '''
        }
        { bits: "31:16",
          name: "NCO",
          desc: '''
                BAUD clock rate control. This is only used to determine the
                bit time used as the basis for the RX timeout, so the
                software will see the same timeout time as if configuring
                the standard uart (see !!TIMEOUT_CTRL register).
                '''
        }
      ]
    },
    { name:     "STATUS"
      desc:     "UART live status register"
      swaccess: "ro"
      hwaccess: "hwo"
      hwext:    "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"
        }
        { bits: "3"
          name: "TXIDLE"
          desc: "TX is idle. At the moment this matches the TXEMPTY bit."
        }
        { bits: "4"
          name: "RXIDLE"
          desc: "RX is idle. At the moment this matches the RXEMPTY bit."
        }
        { bits: "5"
          name: "RXEMPTY"
          desc: "RX FIFO is empty"
        }
      ]
    }
    { name: "RDATA",
      desc: "UART read data",
      swaccess: "ro",
      hwaccess: "hrw",
      hwext: "true",
      hwre: "true",
      fields: [
        { bits: "7:0" }
      ]
    }
    { name: "WDATA",
      desc: "UART write data",
      swaccess: "wo",
      hwaccess: "hro",
      hwqe: "true",
      fields: [
        { bits: "7:0" }
      ]
    }
    { name: "FIFO_CTRL",
      desc: "UART FIFO control register",
      swaccess: "rw",
      hwaccess: "hrw",
      hwqe:     "true",
      fields: [
        { bits: "0",
          name: "RXRST",
          desc: "RX fifo reset"
        }
        { bits: "1",
          name: "TXRST",
          desc: "TX fifo reset"
        }
        { bits: "4:2",
          name: "RXILVL",
          desc: "Trigger level for RX interrupts",
          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"
            },
            // TODO expect generator to make others reserved
          ]
        }
        { bits: "6:5",
          name: "TXILVL",
          desc: "Trigger level for TX interrupts",
          enum: [
            { value: "0",
              name: "txlvl1",
              desc: "1 character"
            },
            { 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: "UART override control register",
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        { bits: "0",
          name: "TXEN",
          desc: "Ignored (Override the TX signal)"
        }
        { bits: "1",
          name: "TXVAL",
          desc: "Ignored (Value for TX Override)"
        }
      ]
    }
    { name: "VAL",
      desc: "UART oversampled values",
      swaccess: "ro",
      hwaccess: "hwo",
      hwext:    "true",
      fields: [
        { bits: "15:0",
          name: "RX",
          desc: '''
                Always zero (Last 16 oversampled values of RX.)
                '''
        }
      ]
    }
    { 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"
        }
      ]
    }
    { name: "USBSTAT",
      desc: "USB Status",
      swaccess: "ro",
      hwaccess: "hwo",
      hwext: "true",
      fields: [
        {
          bits: "10:0",
          name: "frame",
          desc: '''
                Frame index received from host. On an active link this
                will increment every milisecond.
                '''
        }
        {
          bits: "14",
          name: "host_timeout",
          desc: '''
                Start of frame not received from host for 1s.
                '''
        }
        {
          bits: "15",
          name: "host_lost",
          desc: '''
                Start of frame not received from host for 2.048ms.
                '''
        }
        {
          bits: "22:16",
          name: "device_address",
          desc: '''
                Device address set by host.
                '''
        }
      ]
    }
    { name: "USBPARAM",
      desc: "USB Parmeters",
      swaccess: "ro",
      hwaccess: "hwo",
      hwext: "true",
      fields: [
        {
          bits: "15:0",
          name: "baud_req",
          desc: '''
                Baud rate requested if the interface is bridged to a real uart.
                '''
        }
        {
          bits: "17:16",
          name: "parity_req",
          desc: '''
                Parity requested if the interface is bridged to a real uart.
                '''
          enum: [
            { value: "0",
              name: "none",
              desc: "No parity"
            },
            { value: "1",
              name: "odd",
              desc: "Odd parity"
            },
            { value: "2",
              name: "even",
              desc: "Even parity"
            }
          ]
        }
      ]
    }
  ]
}