hw/ip/spi_device/doc/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: "main",
  bus_device: "tlul",
  available_input_list: [
    { name: "sck", desc: "SPI Clock" },
    { name: "csb", desc: "Chip Enable#" },
    { name: "mosi", desc: "SPI Input" },
  ],
  available_output_list: [
    { name: "miso", 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: "MOSI in FwMode has error" },
  ],
  scan: "true", // Enable `scanmode_i` 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 MISO. 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 MISO. 0 for MSB to LSB, 1 for LSB to MSB",
          resval: "0",
        },
        { bits: "3",
          name: "rx_order",
          desc: "RX bit order on MOSI. 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.
            '''
        },
        { 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: "FIFO 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" },
      ]
    },
    { 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",
        },
        { 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",
        }
      ]
    },
    { 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",
        }
      ],
    },
    { window: {
        name: "buffer",
        items: "512",
        validbits: "32",
        byte-write: "false",
        unusual: "false"
        swaccess: "rw",
        desc: '''
          SPI internal 2kB buffer.

          This buffer is shared by RX and TX circular buffer together.
          '''
      },
    },
  ]
}