hw/ip/i2s/data/i2s.hjson

// Copyright 2023 Google LLC
// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{ name: "i2s",
  clocking: [
    {clock: "clk_i", reset: "rst_ni", primary: true},
    {clock: "clk_audio_i"},
  ],
  bus_interfaces: [
    { protocol: "tlul", direction: "device" }
  ],
  available_input_list: [
    { name: "rx_sd", desc: "Serial receive bit" }
  ],
  available_output_list: [
    { name: "rx_sclk",    desc: "Serial data clock" }
    { name: "rx_ws",      desc: "Serial data word select" }
    { name: "tx_sclk",    desc: "Serial data clock" }
    { name: "tx_ws",      desc: "Serial data word select tx" }
    { name: "tx_sd",      desc: "Serial data tx bit" }
  ],
  interrupt_list: [
    { name: "tx_watermark"
      desc: "raised if the transmit FIFO is below the high-water mark. See TXILVL."}
    { name: "rx_watermark"
      desc: "raised if the receive FIFO is above the high-water mark. See RXILVL."}
    { name: "tx_empty"
      desc: "raised if the transmit FIFO has emptied."}
    { name: "rx_overflow"
      desc: "raised if the receive FIFO has overflowed."}
  ],
  regwidth: "32",
  registers: [
    { name: "CTRL",
      desc: "I2S control register",
      swaccess: "rw",
      hwaccess: "hro",
      fields: [
        { bits: "0",
          name: "TX",
          desc: "TX enable"
        }
        { bits: "1",
          name: "RX",
          desc: "RX enable"
        }
        { bits: "2",
          name: "SLPBK",
          desc: '''System loopback enable.

                If this bit is turned on, any outgoing bits to TX are received through RX.
                See Block Diagram.
                '''
        }
        { bits: "24:18",
          name: "NCO_RX",
          desc: "SCLK / BCLK Clock divide control TX. CLK_divided = clk_audio/(2*NCO_RX)."
          resval: "1"
        }
        { bits: "31:25",
          name: "NCO_TX",
          desc: "SCLK / BCLK Clock divide control RX. CLK_divided = clk_audio/(2*NCO_TX)."
          resval: "1"
        }
      ]
    },
    { name:     "STATUS"
      desc:     "I2S 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: "RXEMPTY"
          desc: "RX FIFO is empty"
          resval: "1"
        }
      ],
      tags: [// STATUS in read only
             "excl:CsrAllTests:CsrExclWrite"]
    }
    { name: "RDATA",
      desc: "I2S read data",
      swaccess: "ro",
      hwaccess: "hrw",
      hwext: "true",
      hwre: "true",
      fields: [
        { bits: "31:0" }
      ],
      tags: [// RDATA in read only
             "excl:CsrAllTests:CsrExclWrite"]
    }
    { name: "WDATA",
      desc: "I2S write data",
      swaccess: "wo",
      hwaccess: "hro",
      hwqe: "true",
      fields: [
        { bits: "31:0" }
      ]
      tags: [// don't write to wdata - it affects several other csrs
             "excl:CsrAllTests:CsrExclAll"]
    }
    { name: "FIFO_CTRL",
      desc: "I2S 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",
          tags: [
             "excl:CsrAllTests:CsrExclAll"]
        }
        { bits: "1",
          swaccess: "wo",
          hwaccess: "hro",
          name: "TXRST",
          desc: "TX fifo reset. Write 1 to the register resets TX_FIFO. Read returns 0",
          tags: [
             "excl:CsrAllTests:CsrExclAll"]
        }
        { 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.
                ''',
          resval: "2"
          enum: [
            { value: "0",
              name: "rxlvl1",
              desc: "1 word"
            },
            { value: "1",
              name: "rxlvl4",
              desc: "4 word"
            },
            { value: "2",
              name: "rxlvl8",
              desc: "8 word",
            },
            { value: "3",
              name: "rxlvl16",
              desc: "16 word"
            },
            { value: "4",
              name: "rxlvl30",
              desc: "30 word"
            },
          ]
        }
        { 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.
                ''',
          resval: "2"
          enum: [
            { value: "0",
              name: "txlvl1",
              desc: "2 word"
            },
            { value: "1",
              name: "txlvl4",
              desc: "4 word"
            },
            { value: "2",
              name: "txlvl8",
              desc: "8 word"
            },
            { value: "3",
              name: "txlvl16",
              desc: "16 word"
            }
          ]
        }
      ]
    }
    { name: "FIFO_STATUS",
      desc: "I2S 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"
        }
      ],
      tags: [// FIFO_STATUS in read only
             "excl:CsrAllTests:CsrExclWrite"]
    }
  ]
}