util/docgen/examples/uartcfg.hjson

{
  name: "uart",
  clock_primary: "clk_fixed",
  bus_device: "tlul",
  bus_host: "none",
  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 programmed highwater mark."}
    { name: "rx_watermark",  desc: "raised if the receive FIFO is past the programmed 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."}
    { 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 inFIFO without being retrieved for the programmed time period."}
    { name: "rx_parity_err", desc: "raised if the receiver has detected a parity error."}
  ],

  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"
        }
        { bits: "2",
          name: "NF",
          desc: "RX noise filter enable"
        }
        { 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.
                '''
        }
        { 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.
                '''
        }
        { 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: "TXOVERFLOW"
          desc: "TX buffer overflow"
        }
        { bits: "3"
          name: "RXOVERFLOW"
          desc: "RX buffer overflow"
        }
        { bits: "4"
          name: "TXEMPTY"
          desc: "TX FIFO is empty"
        }
        { bits: "5"
          name: "TXIDLE"
          desc: "TX is idle"
        }
        { bits: "6"
          name: "RXIDLE"
          desc: "RX is idle"
        }
        { bits: "7"
          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: "4:0",
          name: "TXLVL",
          desc: "Current fill level of TX fifo"
        }
        { bits: "10:6",
          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: "Override the TX signal"
        }
        { bits: "1",
          name: "TXVAL",
          desc: "Value for TX Override"
        }
      ]
    }
    { 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.
                '''
        }
      ]
    }
    { 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"
        }
      ]
    }
  ]
}