EF_SPI.yaml

---
info:
  name: EF_SPI
  description: SPI master controller with receive and transmit FIFOs.
  repo: github.com/efabless/EF_SPI
  owner: Efabless Corp.
  license: APACHE 2.0
  author: Efabless Corp.
  email: ip_admin@efabless.com
  version: v1.1.0
  date: 23-01-2025
  category: digital
  tags:
    - peripheral
    - comm
    - spi
  bus:
    - generic
  type: soft
  status: verified
  cell_count:
    - IP: TBD
    - APB: TBD
    - AHBL: TBD
    - WB: TBD
  width: "0.0"
  height: "0.0"
  technology: n/a
  clock_freq_mhz:
    - IP: TBD
    - APB: TBD
    - AHBL: TBD
    - WB: TBD
  digital_supply_voltage: n/a
  analog_supply_voltage: n/a
  irq_reg_offset: 0xFF00
  fifo_reg_offset: 0xFE00
  firmware_guidelines: |
    1. Set the prescaler by writing to the ``PR`` register where SPI Clock Frequency = System Clock / PR. Note: should have a value >= 2.
    2. Configure clock polarity and clock phase bu setting ``cpol`` and ``cpha`` fields in the ``CFG`` register.
    3. Set the ``SSn`` field in the ``CTRL`` register

parameters:
- name: CDW
  default: 8
  description: The width of the clock divider used to generate the SPI clock.
- name: FAW
  default: 4
  description: Log2 of the FIFO depth.

ports:
- name: CPOL
  width: 1
  direction: input
  description: SPI Clock Polarity.
- name: CPHA
  width: 1
  direction: input
  description: SPI CLock Phase. 
- name: clk_divider
  width: CDW
  direction: input
  description: The SPI clock divider; SPI clock frequency = System Clock Frequency / clk_divider.
- name: wr
  width: 1
  direction: input
  description: Write to the TX FIFO.
- name: rd
  width: 1
  direction: input
  description: Read from the RX FIFO.
- name: datai
  width: 8
  direction: input
  description: Data to place into the TX FIFO.
- name: datao
  width: 8
  direction: output
  description: Data from the RX FIFO.
- name: rx_en
  width: 1
  direction: input
  description: Enable the RX FIFO.
- name: rx_flush
  width: 1
  direction: input
  description: Flush the RX FIFO.
- name: rx_threshold
  width: FAW
  direction: input
  description: RX FIFO level threshold.
- name: rx_empty
  width: 1
  direction: output
  description: RX FIFO is empty.
- name: rx_full
  width: 1
  direction: output
  description: RX FIFO is full.
- name: rx_level_above
  width: 1
  direction: output
  description: RX FIFO level is above the threshold.
- name: rx_level
  width: FAW
  direction: output
  description: RX FIFO data level.
- name: tx_flush
  width: 1
  direction: input
  description: Flush the TX FIFO.
- name: tx_threshold
  width: FAW
  direction: input
  description: TX FIFO level threshold.
- name: tx_empty
  width: 1
  direction: output
  description: TX FIFO is empty.
- name: tx_full
  width: 1
  direction: output
  description: TX FIFO is full.
- name: tx_level_below
  width: 1
  direction: output
  description: TX FIFO level is below trhe threshold.
- name: tx_level
  width: FAW
  direction: output
  description: TX FIFO data level.
- name: ss
  width: 1
  direction: input
  description: 
- name: enable
  width: 1
  direction: input
  description: enable for spi master pulse generation
- name: done
  width: 1
  direction: output
  description: spi done flag.
- name: busy
  width: 1
  direction: output
  description: spi busy flag.

external_interface:
- name: miso
  port: miso
  width: 1
  direction: input
  description: Master In Slave Out; this line carries data from the slave device to the master.
  sync: False
- name: mosi
  port: mosi
  width: 1
  direction: output
  description: Master Out Slave In; this line carries data from the master device to the slave.
- name: csb
  port: csb
  width: 1
  direction: output
  description: Chip Select Bar; this signal selects the slave device to communicate with, typically active low.
- name: sclk
  port: sclk
  width: 1
  direction: output
  description: Serial Clock; this provides the clock signal that synchronizes data transfer between master and slave devices.

clock:
  name: clk
  gated: "yes"
reset:
  name: rst_n  
  level: 0

registers:
- name: RXDATA
  size: 8
  mode: r
  fifo: yes
  offset: 0
  bit_access: no
  read_port: datao
  description: RX Data register; the interface to the Receive FIFO.
- name: TXDATA
  size: 8
  mode: w
  fifo: yes
  offset: 4
  bit_access: no
  write_port: datai
  description: TX Data register; ; the interface to the Receive FIFO.
- name: CFG
  size: 2
  mode: w
  fifo: no
  offset: 8
  bit_access: no
  description: Configuration Register.
  fields:
  - name: cpol
    bit_offset: 0
    bit_width: 1
    write_port: CPOL
    description: SPI Clock Polarity.
  - name: cpha
    bit_offset: 1
    bit_width: 1
    write_port: CPHA
    description: SPI Clock Phase.
- name: CTRL
  size: 3
  mode: w
  fifo: no
  offset: 12
  bit_access: no
  description: Control Register.
  fields:
  - name: SS
    bit_offset: 0
    bit_width: 1
    write_port: ss
    description: Slave Select (Active High).  
  - name: enable
    bit_offset: 1
    bit_width: 1
    write_port: enable
    description: enable spi master pulse generation
  - name: rx_en
    bit_offset: 2
    bit_width: 1
    write_port: rx_en
    description: enable storing bytes recieved from slave 
- name: PR
  size: CDW
  mode: w
  fifo: no
  offset: 16
  init: "'h2"
  bit_access: no
  write_port: clk_divider
  description: SPI clock Prescaler; should have a value >= 2. SPI Clock Frequency = System Clock / PR.
- name: STATUS
  size: 8
  mode: r
  fifo: no
  offset: 20
  init: "'h0"
  bit_access: no
  description:  Status resgister
  fields:
    - name: TX_E
      bit_offset: 0
      bit_width: 1
      read_port: tx_empty
      description: Transmit FIFO is Empty.
    - name: TX_F
      bit_offset: 1
      bit_width: 1
      read_port: tx_full
      description: Transmit FIFO is Full.
    - name: RX_E
      bit_offset: 2
      bit_width: 1
      read_port: rx_empty
      description: Receive FIFO is Empty.
    - name: RX_F
      bit_offset: 3
      bit_width: 1
      read_port: rx_full
      description: Receive FIFO is Full.
    - name: TX_B
      bit_offset: 4
      bit_width: 1
      read_port: tx_level_below
      description: Transmit FIFO level is Below Threshold.
    - name: RX_A
      bit_offset: 5
      bit_width: 1
      read_port: rx_level_above
      description: Receive FIFO level is Above Threshold.
    - name : busy
      bit_offset: 6
      bit_width: 1
      read_port: busy
      description: spi busy flag.
    - name : done
      bit_offset: 7
      bit_width: 1
      read_port: done
      description: spi done flag.


flags:
- name: TXE
  port: tx_empty
  description: Transmit FIFO is Empty.
- name: TXF
  port: tx_full
  description: Transmit FIFO is Full.
- name: RXE
  port: rx_empty
  description: Receive 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.

fifos:
- name: RX_FIFO
  type: read  
  width: 8
  address_width: FAW
  register: RXDATA
  data_port: datao
  control_port: rd
  flush_enable: True
  flush_port: rx_flush
  threshold_port: rx_threshold
  level_port: rx_level
- name: TX_FIFO
  type: write
  width: 8
  address_width: FAW
  register: TXDATA
  data_port: datai
  control_port: wr
  flush_enable: True
  flush_port: tx_flush
  threshold_port: tx_threshold
  level_port: tx_level