hw/ip/spi_device/data/spi_device.hjson

// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{ name: "SPI_DEVICE",
  clock_primary: "clk_i",
  bus_device: "tlul",
  available_input_list: [
    { name: "sck", desc: "SPI Clock" },
    { name: "csb", desc: "Chip Enable#" },
    { name: "sdi", desc: "SPI Input" },
  ],
  available_output_list: [
    { name: "sdo", desc: "SPI Output" },
  ],
  interrupt_list: [
    { name: "rxf",         desc: "RX SRAM FIFO Full" },
    { name: "rxlvl",       desc: "RX SRAM FIFO is above the level" },
    { name: "txlvl",       desc: "TX SRAM FIFO is under the level" },
    { name: "rxerr",       desc: "SDI in FwMode has error" },
    { name: "rxoverflow",  desc: "RX Async FIFO overflow" },
    { name: "txunderflow", desc: "TX Async FIFO underflow" },
  ],
  scan: "true",       // Enable `scanmode_i` port
  scan_reset: "true", // Enable `scan_rst_ni` port
  regwidth: "32",
  registers: [
    { name: "CONTROL",
      desc: "Control register",
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        { bits: "0",
          name: "ABORT",
          desc: '''
            Abort pending jobs. If TX_FIFO (async) is full,
            this command can let TXF Control logic back to Idle state
            '''
          resval: "0"
        },
        { bits: "5:4",
          name: "MODE",
          desc: "SPI Device operation mode. Currently only FwMode is supported.",
          enum: [
            { value: "0",
              name: "fwmode",
              desc: '''
                FW operation mode.

                HW just dumps incoming data to SRAM and reads from SRAM and
                sends to SDO. This mode doesn't support Dual or Quad mode
                '''
            },
          ]
        },
        { bits: "16",
          name: "rst_txfifo",
          desc: '''
            Reset Async TX_FIFO.

            This only resets asynchronous fifo. If firmware wants to reset SRAM
            FIFO, it should write 0 into read/write pointers.

            _Note_: This value should be controlled only when SPI interface is
            in Idle state as this reset signal doesn't have reset synchronizer.
            '''
          resval: "0",
        },
        { bits: "17",
          name: "rst_rxfifo",
          desc: '''
            Reset Async RX_FIFO.

            This only resets asynchronous fifo. If firmware wants to reset SRAM
            FIFO, it should write 0 into read pointer and write pointer.

            _Note_: This value should be controlled only when SPI interface is
            in Idle state as this reset signal doesn't have reset synchronizer.
            '''
          resval: "0",
        },
      ]
    },
    { name: "CFG",
      desc: "Configuration Register",
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        { bits: "0",
          name: "CPOL",
          desc: "Clock polarity. 0 for normal SPI, 1 for negative edge latch",
          resval: "0",
        },
        { bits: "1",
          name: "CPHA",
          desc: "Data phase. 0 for negative edge change, 1 for positive edge change",
          resval: "0",
        },
        { bits: "2",
          name: "tx_order",
          desc: "TX bit order on SDO. 0 for MSB to LSB, 1 for LSB to MSB",
          resval: "0",
        },
        { bits: "3",
          name: "rx_order",
          desc: "RX bit order on SDI. Module stores bitstream from MSB to LSB if value is 0.",
          resval: "0",
        },
        { bits: "15:8",
          name: "timer_v",
          desc: '''
            number of clocks for RXF to wait.

            To reduce traffic to SRAM, RXF control module waits given clock cycle
            if it doesn't fill SRAM data width even if Async RX FIFO is empty.
            '''
          resval: "0x7F",
        },
      ]
    },
    { name: "FIFO_LEVEL",
      desc: "RX/ TX FIFO levels.",
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        { bits: "15:0",
          name: "rxlvl",
          resval: "0x80",
          desc: '''
            RX FIFO level.

            If RX SRAM FIFO level exceeds this value, it triggers interrupt.
            '''
        },
        { bits: "31:16",
          name: "txlvl",
          resval: "0x0",
          desc: '''
            TX FIFO level.

            If TX SRAM FIFO level drops below this value, it triggers interrupt.
            '''
        },
      ],
    },
    { name: "ASYNC_FIFO_LEVEL",
      desc: "RX/ TX Async FIFO levels between main clk and spi clock",
      swaccess: "ro",
      hwaccess: "hwo",
      hwext: "true",
      fields: [
        { bits:  "23:16",
          name: "txlvl",
          desc: '''
            TX Async FIFO level.

            This value shows the number of available entry in TX Async FIFO.
            If the software writes message into SRAM FIFO and update FIFO write pointer
            but no clock from the host is given, the data stuck at this async fifo waiting
            host toggles SCK. This value represents the number of bytes.
            '''
          tags: [// HW modifies async_fifo_level.txlvl when txf_ptr.wptr is updated.
                 "excl:CsrNonInitTests:CsrExclWriteCheck"]
        },
        { bits: "7:0",
          name: "rxlvl",
          desc: '''
            RX Async FIFO level.

            This value shows the number of available entry in RX Async FIFO.
            '''
        }
      ]
    },
    { name: "STATUS",
      desc: "SPI Device status register",
      swaccess: "ro",
      hwaccess: "hwo",
      hwext: "true",
      fields: [
        { bits: "0", name: "rxf_full",   desc: "RX FIFO full" },
        { bits: "1", name: "rxf_empty",  desc: "RX FIFO empty", resval: "1"},
        { bits: "2", name: "txf_full",   desc: "TX FIFO full"},
        { bits: "3", name: "txf_empty",  desc: "TX FIFO empty", resval: "1"},
        { bits: "4", name: "abort_done", desc: "Abort process is completed", resval: "1" },
        { bits: "5", name: "csb",        desc: "Direct input of CSb signal", resval: "1" },
      ]
      tags: [// Status reads back unexpected values due to writes to other CSRs.
             "excl:CsrNonInitTests:CsrExclWriteCheck"]
    },
    { name: "RXF_PTR",
      desc: "Receiver FIFO (SRAM) pointers",
      swaccess: "rw",
      hwaccess: "hrw",
      fields: [
        { bits: "15:0",
          name: "RPTR",
          desc: "Read pointer. bit x is for phase bit. check circular fifo description",
          swaccess: "rw",
          hwaccess: "hro",
          resval: "0",
          tags: [// Updating rptr will cause unexpected interrupts. These interrupts may take a
                 // while to generate and cip_base_vseq::clear_all_interrupts may not be able to
                 // clear them in time. Leftover interrupts will cause sim error
                 "excl:CsrNonInitTests:CsrExclWrite"]
        },
        { bits: "31:16",
          name: "WPTR",
          desc: "Write pointer. Bit x is phase bit.",
          swaccess: "ro",
          hwaccess: "hwo",
          resval: "0",
        }
      ]
    },
    { name: "TXF_PTR",
      desc: "Transmitter FIFO (SRAM) pointers",
      swaccess: "rw",
      hwaccess: "hrw",
      fields: [
        { bits: "15:0",
          name: "RPTR",
          desc: "Read pointer. bit x is for phase bit. check circular fifo description",
          swaccess: "ro",
          hwaccess: "hwo",
          resval: "0",
        },
        { bits: "31:16",
          name: "WPTR",
          desc: "Write pointer. Bit x is phase bit.",
          swaccess: "rw",
          hwaccess: "hro",
          resval: "0",
          tags: [// Updating rptr will cause unexpected interrupts. These interrupts may take a
                 // while to generate and cip_base_vseq::clear_all_interrupts may not be able to
                 // clear them in time. Leftover interrupts will cause sim error
                 "excl:CsrNonInitTests:CsrExclWrite"]
        }
      ]
    },
    { name: "RXF_ADDR",
      desc: "Receiver FIFO (SRAM) Addresses",
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        { bits: "15:0",
          name: "base",
          desc: "Base offset in bytes in the SRAM. Lower 2 bits are ignored.",
          resval: "0",
        },
        { bits: "31:16",
          name: "limit",
          desc: "Limit offset in bytes in the SRAM. Lower 2 bits are ignored.",
          resval: "0x1FC",
        }
      ],
    },
    { name: "TXF_ADDR",
      desc: "Transmitter FIFO (SRAM) Addresses",
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        { bits: "15:0",
          name: "base",
          desc: "Base offset in bytes in the SRAM. Lower 2 bits are ignored.",
          resval: "0x200",
        },
        { bits: "31:16",
          name: "limit",
          desc: "Limit offset in bytes in the SRAM. Lower 2 bits are ignored.",
          resval: "0x3FC",
        }
      ],
    },
    { skipto: "0x1000" }
    { window: {
        name: "buffer",
        items: "1024",
        validbits: "32",
        byte-write: "false",
        unusual: "false"
        swaccess: "rw",
        desc: '''
          SPI internal buffer.

          In Generic mode, this buffer is used for RX/TX buffer.  In Flash &
          Passthrough mode, lower 2kB is for Read content emulating eFlash.
          next 1kB is for Mailbox read/write buffer. The rest is 64B of
          CmdFIFO, 64B of AddrFIFO, and 256B of payload FIFO.
          '''
      },
    },
  ]
}