EF_UART.yaml

---
info:
  name: EF_UART
  description: |
    UART, or universal asynchronous receiver-transmitter, is one of the most used device-to-device communication protocols. A UART enables two devices to exchange data serially without sharing the clock in a frame oriented way. The frame consists of a start bit, a number of data bits (typically one byte), a parity bit (optional) and 1-2 stop bits.
    EF_UART is a Soft IP with the following features:
    - A configurable frame format
      - Data bits could vary from 5 to 9 bits
      - Even, odd, stick, or no-parity bit generation/detection
      - One or Two stop bit generation
    - Line-break detection
    - Configurable receiver timeout
    - Loopback capability for testing/debugging
    - Glitch Filter on RX enable
    - Matching received data detection
    - 16-byte TX and RX FIFOs with programmable thresholds
    - 16-bit prescaler (PR) for programmable baud rate generation
    - Ten Interrupt Sources:
      + RX FIFO is full
      + TX FIFO is empty
      + RX FIFO level is above the set threshold
      + TX FIFO level is below the set threshold
      + Line break detection
      + Receiver data match
      + Frame Error
      + Parity Error
      + Overrun
      + Receiver timeout
  repo: https://github.com/efabless/EF_UART.git
  owner: Efabless Corp.
  license: APACHE 2.0
  author: Efabless Corp.
  email: ip_admin@efabless.com
  version: v1.1.8
  date: 16-09-2024
  category: digital
  tags:
    - peripheral
    - UART
    - serial
  bus:
    - generic
  type: soft
  status: verified
  cell_count:
    - IP: 1590
    - APB: 1943
    - AHBL: 1973
    - WB: 2170
  width": "0.0"
  height": "0.0"
  technology: n/a
  clock_freq_mhz:
    - IP: 277
    - APB: 208
    - AHBL: 250
    - WB: 83
  digital_supply_voltage: n/a
  analog_supply_voltage: n/a
  irq_reg_offset: 0xFF00
  fifo_reg_offset: 0xFE00

parameters:
  - name: SC
    default: 8
    description: "Number of samples per bit/baud"
  - name: MDW
    default: 9
    description: "Max data size/width"
  - name: GFLEN
    default: 8
    description: "Length (number of stages) of the glitch filter"
  - name: FAW
    default: 4
    description: "FIFO Address width; Depth=2^AW"

ports:
  - name: prescaler
    width: 16
    direction: input
    description: Prescaler used to determine the baud rate.
  - name: en
    width: 1
    direction: input
    description: Enable for UART
  - name: tx_en
    width: 1
    direction: input
    description: Enable for UART transmission 
  - name: rx_en
    width: 1
    direction: input
    description: Enable for UART receiving  
  - name: wdata
    width: MDW
    direction: input
    description: Transmission data 
  - name: timeout_bits
    width: 6
    direction: input
    description: Receiver Timeout measured in number of bits.
  - name: loopback_en
    width: 1
    direction: input
    description: Loopback enable; connect tx to the rx 
  - name: glitch_filter_en
    width: 1
    direction: input
    description: UART Glitch Filter on RX enable
  - name: tx_level
    width: FAW
    direction: output
    description: The current level of TX FIFO
  - name: rx_level
    width: FAW
    direction: output
    description: The current level of RX FIFO
  - name: rd
    width: 1
    direction: input
    description: Read from RX FIFO signal 
  - name: wr
    width: 1
    direction: input
    description: Write to TX FIFO signal 
  - name: tx_fifo_flush
    width: 1
    direction: input
    description: Flushes the TX FIFO. 
  - name: rx_fifo_flush
    width: 1
    direction: input
    description: Flushes the RX FIFO.
  - name: data_size
    width: 4
    direction: input
    description: Number of data bits in the frame 
  - name: stop_bits_count
    width: 1
    direction: input
    description: Number of stop bits in the frame (could be 1 or 2) 
  - name: parity_type
    width: 3
    direction: input
    description: Type of Parity in the frame 
  - name: txfifotr
    width: FAW
    direction: input
    description: TX FIFO Threshold
  - name: rxfifotr
    width: FAW
    direction: input
    description: RX FIFO Threshold 
  - name: match_data
    width: MDW
    direction: input
    description: Match data (match flag would be raised if it matches what is received)
  - name: tx_empty
    width: 1
    direction: output
    description: TX empty flag
  - name: tx_full
    width: 1
    direction: output
    description: TX full flag
  - name: tx_level_below
    width: 1
    direction: output
    description: TX level below flag
  - name: rdata
    width: MDW
    direction: output
    description: Received Data 
  - name: rx_empty
    width: 1
    direction: output
    description: RX empty flag
  - name: rx_full
    width: 1
    direction: output
    description: RX full flag
  - name: rx_level_above
    width: 1
    direction: output
    description: RX level above flag
  - name: break_flag
    width: 1
    direction: output
    description: Break flag
  - name: match_flag
    width: 1
    direction: output
    description: Match flag
  - name: frame_error_flag
    width: 1
    direction: output
    description: Frame error flag
  - name: parity_error_flag
    width: 1
    direction: output
    description: Parity error flag
  - name: overrun_flag
    width: 1
    direction: output
    description: Overrun flag
  - name: timeout_flag
    width: 1
    direction: output
    description: Timeout flag

external_interface:
  - name: rx
    port: rx
    direction: input
    description: RX connected to the external interface 
    width: 1
  - name: tx
    port: tx
    direction: output
    width: 1
    description: TX connected to external interface 

clock:
  name: clk
  gated: 'yes'

reset:
  name: rst_n
  level: 0

registers:
  - name: RXDATA
    size: MDW
    mode: r
    fifo: yes
    offset: 0
    bit_access: no
    read_port: rdata
    description: RX Data register; the interface to the Receive FIFO.
  - name: TXDATA
    size: MDW
    mode: w
    fifo: yes
    offset: 4
    bit_access: no
    write_port: wdata
    description: TX Data register; ; the interface to the Receive FIFO.
  - name: PR
    size: 16
    mode: w
    fifo: no
    offset: 8
    bit_access: no
    write_port: prescaler
    description: The Prescaler register; used to determine the baud rate. $baud_rate = clock_freq/((PR+1)*16)$.
  - name: CTRL
    size: 5
    mode: w
    fifo: no
    offset: 12
    bit_access: no
    description: UART Control Register
    fields:
      - name: en
        bit_offset: 0
        bit_width: 1
        write_port: en
        description: UART enable
      - name: txen
        bit_offset: 1
        bit_width: 1
        write_port: tx_en
        description: UART Transmitter enable
      - name: rxen
        bit_offset: 2
        bit_width: 1
        write_port: rx_en
        description: UART Receiver enable
      - name: lpen
        bit_offset: 3
        bit_width: 1
        write_port: loopback_en
        description: Loopback (connect RX and TX pins together) enable
      - name: gfen
        bit_offset: 4
        bit_width: 1
        write_port: glitch_filter_en
        description: UART Glitch Filer on RX enable
  - name: CFG
    size: 14
    mode: w
    fifo: no
    offset: 16
    bit_access: no
    init: "'h3F08"
    description: UART Configuration Register
    fields:
      - name: wlen
        bit_offset: 0
        bit_width: 4
        write_port: data_size
        description: "Data word length: 5-9 bits"
      - name: stp2
        bit_offset: 4
        bit_width: 1
        write_port: stop_bits_count
        description: "Two Stop Bits Select"
      - name: parity
        bit_offset: 5
        bit_width: 3
        write_port: parity_type
        description: "Parity Type: 000: None, 001: odd, 010: even, 100: Sticky 0, 101:
          Sticky 1"
      - name: timeout
        bit_offset: 8
        bit_width: 6
        write_port: timeout_bits
        description: Receiver Timeout measured in number of bits
  - name: MATCH
    size: MDW
    mode: w
    fifo: no
    offset: 28
    bit_access: no
    write_port: match_data
    description: Match Register

flags:
  - name: TXE
    port: tx_empty
    description: Transmit FIFO is Empty.
  - name: RXF
    port: rx_full
    description: Receive FIFO is Full.
  - name: TXB
    port: tx_level_below
    description: Transmit FIFO level is Below Threshold.
  - name: RXA
    port: rx_level_above
    description: Receive FIFO level is Above Threshold.
  - name: BRK
    port: break_flag
    description: Line Break; 13 consecutive 0's have been detected on the line. 
  - name: MATCH
    port: match_flag
    description: Match; the received data matches the MATCH register.
  - name: FE
    port: frame_error_flag
    description: Framing Error; the receiver does not see a "stop" bit at the expected "stop" bit time.
  - name: PRE
    port: parity_error_flag
    description: Parity Error; the receiver calculated parity does not match the received one.
  - name: OR
    port: overrun_flag
    description: Overrun; data has been received but the RX FIFO is full.
  - name: RTO
    port: timeout_flag
    description: Receiver Timeout; no data has been received for the time of a specified number of bits.

fifos:
  - name: RX_FIFO
    type: read  
    width: MDW
    address_width: FAW
    register: RXDATA
    data_port: rdata
    control_port: rd
    flush_enable: True
    flush_port: rx_fifo_flush
    threshold_port: rxfifotr
    level_port: rx_level
  - name: TX_FIFO
    type: write
    width: MDW
    address_width: FAW
    register: TXDATA
    data_port: wdata
    control_port: wr
    flush_enable: True
    flush_port: tx_fifo_flush
    threshold_port: txfifotr
    level_port: tx_level