update documentation to have clock gating, dft, and some notes

efabless · Jan 6, 2025 · b73f3a6 · b73f3a6
1 parent bae86e3
commit b73f3a6
Show file tree

Hide file tree

Showing 2 changed files with 82 additions and 54 deletions.
diff --git a/EF_UART.yaml b/EF_UART.yaml
@@ -1,7 +1,31 @@
 ---
 info:
   name: EF_UART
-  description: A Universal Asynchronous Receiver Transmitter
+  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
@@ -16,7 +40,7 @@ info:
     - serial
   bus:
     - generic
-  type": soft
+  type: soft
   status: verified
   cell_count:
     - IP: 1590
@@ -35,6 +59,20 @@ info:
   analog_supply_voltage: n/a
   irq_reg_offset: 0xFF00
   fifo_reg_offset: 0xFE00
+  firmware_guidelines: |
+    1. Set the prescaler according to the required transmission and receiving baud rate where:  $Baud\ rate = Bus\ Clock\ Freq/((Prescaler+1)\times16)$. Setting the prescaler is done through writing to ``PR`` register
+    2. Configure the frame format by :
+      * Choosing the number of data bits which could vary from 5 to 9. This is done by setting the ```wlen``` field in the ```CFG``` register
+      * Choosing whether the stop bits are one or two by setting the ```stb2``` bit in ```CFG``` register where ‘0’ means one bit and ‘1’ means two bits
+      * Choosing the parity type by setting ```parity``` field in ```CFG``` register where 000: None, 001: odd, 010: even, 100: Sticky 0, 101: Sticky 1
+    3. Set the receiver timeout value which fires the ```RTO``` interrupt after a certain amount of bits are received. This would be useful when the message received is not a multiple of the FIFO’s width.Timeout can be set by writing to the ```timeout``` field in the ```CFG``` register
+    4. Set the FIFO thresholds  by writing to the ```RXLT``` and ```TXLT``` fields in ```FIFOCTRL``` register. This would fire ```RXA``` and ```TXB``` interrupts when the RX FIFO level is above the threshold and TX FIFO level is below the threshold.
+    5. Enable the UART as well as RX or TX or both by setting ```en``` , ```txen```, and ```rxen``` bits to ones in the ```CTRL``` register
+    6. To optionally connect the RX signal to the TX signal so the UART transmits whatever it receives then enable loopback by setting the ```loopback``` bit to one in the ```CTRL``` register.
+    7. To optionally enable the glitch filter on RX , set the ```gfen``` bit to one in the ```CTRL``` register.
+    8. To read what was received , you can read ```RXDATA``` register. Note: you should check that there is something in the FIFO before reading using the interrupts registers.
+    9. To optionally check if the data received matches a certain value by writing to the ```MATCH``` register. This would fire the ```MATCH``` interrupt if the received data matches the match value.
+    10. To transmit, write to the ```TXDATA``` register. Note: you should check that the FIFO is not full before adding something to it using the interrupts register to avoid losing data.
 
 parameters:
   - name: SC
@@ -82,7 +120,7 @@ ports:
   - name: glitch_filter_en
     width: 1
     direction: input
-    description: UART Glitch Filer on RX enable
+    description: UART Glitch Filter on RX enable
   - name: tx_level
     width: FAW
     direction: output
@@ -130,7 +168,7 @@ ports:
   - name: match_data
     width: MDW
     direction: input
-    description: Match data (match flag would be raised if it matches what is recieved)
+    description: Match data (match flag would be raised if it matches what is received)
   - name: tx_empty
     width: 1
     direction: output
@@ -146,7 +184,7 @@ ports:
   - name: rdata
     width: MDW
     direction: output
-    description: Recieved Data 
+    description: Received Data 
   - name: rx_empty
     width: 1
     direction: output
@@ -198,6 +236,7 @@ external_interface:
 
 clock:
   name: clk
+  gated: 'yes'
 
 reset:
   name: rst_n
@@ -318,7 +357,7 @@ flags:
     description: Line Break; 13 consecutive 0's have been detected on the line. 
   - name: MATCH
     port: match_flag
-    description: Match; the receive data matches the MATCH register.
+    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.

diff --git a/README.md b/README.md
@@ -1,10 +1,11 @@
 # EF_UART
+
 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
+  - 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
@@ -13,34 +14,35 @@ EF_UART is a Soft IP with the following features:
 - 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
-
+  + 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
 
 ## The wrapped IP
 
 
  APB, AHBL, and Wishbone wrappers, generated by the [BusWrap](https://github.com/efabless/BusWrap/tree/main) `bus_wrap.py` utility, are provided. All wrappers provide the same programmer's interface as outlined in the following sections.
 
-### Wrapped IP System Integration
+#### Wrapped IP System Integration
 
 Based on your use case, use one of the provided wrappers or create a wrapper for your system bus type. For an example of how to integrate the APB wrapper:
 ```verilog
 EF_UART_APB INST (
-        `TB_APB_SLAVE_CONN,
-        .rx(rx),
-        .tx(tx)
+	`TB_APB_SLAVE_CONN,
+	.rx(rx),
+	.tx(tx)
 );
 ```
 > **_NOTE:_** `TB_APB_SLAVE_CONN is a convenient macro provided by [BusWrap](https://github.com/efabless/BusWrap/tree/main).
+#### Wrappers with DFT support
+Wrappers in the directory ``/hdl/rtl/bus_wrappers/DFT`` have an extra input port to enable the clock gate whenever the scan chain testmode is enabled.
 
 ## Implementation example  
 
@@ -51,9 +53,7 @@ The following table is the result for implementing the EF_UART IP with different
 |EF_UART_APB|1943|208|
 |EF_UART_AHBL|1973|250|
 |EF_UART_WB|2170|83|
-## The Programming Interface
-
-
+## The Programmer's Interface
 
 
 ### Registers
@@ -76,6 +76,7 @@ The following table is the result for implementing the EF_UART IP with different
 |RIS|ff08|0x00000000|w|Raw Interrupt Status; reflects the current interrupts status;check the interrupt flags table for more details|
 |MIS|ff04|0x00000000|w|Masked Interrupt Status; On a read, this register gives the current masked status value of the corresponding interrupt. A write has no effect; check the interrupt flags table for more details|
 |IC|ff0c|0x00000000|w|Interrupt Clear Register; On a write of 1, the corresponding interrupt (both raw interrupt and masked interrupt, if enabled) is cleared; check the interrupt flags table for more details|
+|GCLK|ff10|0x00000000|w|Gated clock enable; 1: enable clock, 0: disable clock|
 
 ### RXDATA Register [Offset: 0x0, mode: r]
 
@@ -190,28 +191,20 @@ TX_FIFO Flush Register
 
 ### Interrupt Flags
 
-
-The wrapped IP provides four registers to deal with interrupts: IM, RIS, MIS and IC. These registers exist for all wrapper types generated by the [BusWrap](https://github.com/efabless/BusWrap/tree/main) `bus_wrap.py` utility.
-
+The wrapped IP provides four registers to deal with interrupts: IM, RIS, MIS and IC. These registers exist for all wrapper types generated by the [BusWrap](https://github.com/efabless/BusWrap/tree/main) `bus_wrap.py` utility. 
 
 Each register has a group of bits for the interrupt sources/flags.
 - `IM`: is used to enable/disable interrupt sources.
 
-
 - `RIS`: has the current interrupt status (interrupt flags) whether they are enabled or disabled.
 
-
 - `MIS`: is the result of masking (ANDing) RIS by IM.
 
-
 - `IC`: is used to clear an interrupt flag.
 
 
-
-
 The following are the bit definitions for the interrupt registers:
 
-
 |Bit|Flag|Width|Description|
 |---|---|---|---|
 |0|TXE|1|Transmit FIFO is Empty.|
@@ -224,14 +217,14 @@ The following are the bit definitions for the interrupt registers:
 |7|PRE|1|Parity Error; the receiver calculated parity does not match the received one.|
 |8|OR|1|Overrun; data has been received but the RX FIFO is full.|
 |9|RTO|1|Receiver Timeout; no data has been received for the time of a specified number of bits.|
+### Clock Gating
+The IP has clock gating feature, enabling the selective activation and deactivation of the clock as required through the ``GCLK`` register. This functionality is implemented through the ``ef_gating_cell``, which is part of the the common modules library, [aucohl_lib.v](https://github.com/efabless/IP_Utilities/blob/main/rtl/aucohl_lib.v). By default, the cell operates with a behavioral implementation, but when the ``SKY130`` macro is enabled, the ``sky130_fd_sc_hd__dlclkp_4`` clock gating cell is used.
 
+### The Interface 
 
-### The Interface
 <img src="docs/_static/EF_UART.svg" width="600"/>
 
-
-#### Module Parameters
-
+#### Module Parameters 
 
 |Parameter|Description|Default Value|
 |---|---|---|
@@ -240,9 +233,7 @@ The following are the bit definitions for the interrupt registers:
 |GFLEN|Length (number of stages) of the glitch filter|8|
 |FAW|FIFO Address width; Depth=2^AW|4|
 
-
-#### Ports
-
+#### Ports 
 
 |Port|Direction|Width|Description|
 |---|---|---|---|
@@ -260,6 +251,8 @@ The following are the bit definitions for the interrupt registers:
 |rx_level|output|FAW|The current level of RX FIFO|
 |rd|input|1|Read from RX FIFO signal|
 |wr|input|1|Write to TX FIFO signal|
+|tx_fifo_flush|input|1|Flushes the TX FIFO.|
+|rx_fifo_flush|input|1|Flushes the RX FIFO.|
 |data_size|input|4|Number of data bits in the frame|
 |stop_bits_count|input|1|Number of stop bits in the frame (could be 1 or 2)|
 |parity_type|input|3|Type of Parity in the frame|
@@ -282,9 +275,9 @@ The following are the bit definitions for the interrupt registers:
 ## F/W Usage Guidelines:
 1. Set the prescaler according to the required transmission and receiving baud rate where:  $Baud\ rate = Bus\ Clock\ Freq/((Prescaler+1)\times16)$. Setting the prescaler is done through writing to ``PR`` register
 2. Configure the frame format by :
-   * Choosing the number of data bits which could vary from 5 to 9. This is done by setting the ```wlen``` field in the ```CFG``` register
-   * Choosing whether the stop bits are one or two by setting the ```stb2``` bit in ```CFG``` register where ‘0’ means one bit and ‘1’ means two bits
-   * Choosing the parity type by setting ```parity``` field in ```CFG``` register where 000: None, 001: odd, 010: even, 100: Sticky 0, 101: Sticky 1
+  * Choosing the number of data bits which could vary from 5 to 9. This is done by setting the ```wlen``` field in the ```CFG``` register
+  * Choosing whether the stop bits are one or two by setting the ```stb2``` bit in ```CFG``` register where ‘0’ means one bit and ‘1’ means two bits
+  * Choosing the parity type by setting ```parity``` field in ```CFG``` register where 000: None, 001: odd, 010: even, 100: Sticky 0, 101: Sticky 1
 3. Set the receiver timeout value which fires the ```RTO``` interrupt after a certain amount of bits are received. This would be useful when the message received is not a multiple of the FIFO’s width.Timeout can be set by writing to the ```timeout``` field in the ```CFG``` register
 4. Set the FIFO thresholds  by writing to the ```RXLT``` and ```TXLT``` fields in ```FIFOCTRL``` register. This would fire ```RXA``` and ```TXB``` interrupts when the RX FIFO level is above the threshold and TX FIFO level is below the threshold.
 5. Enable the UART as well as RX or TX or both by setting ```en``` , ```txen```, and ```rxen``` bits to ones in the ```CTRL``` register
@@ -294,19 +287,15 @@ The following are the bit definitions for the interrupt registers:
 9. To optionally check if the data received matches a certain value by writing to the ```MATCH``` register. This would fire the ```MATCH``` interrupt if the received data matches the match value.
 10. To transmit, write to the ```TXDATA``` register. Note: you should check that the FIFO is not full before adding something to it using the interrupts register to avoid losing data.
 
-
 ## Installation:
 You can either clone repo or use [IPM](https://github.com/efabless/IPM) which is an open-source IPs Package Manager
 * To clone repo:
 ```git clone https://https://github.com/efabless/EF_UART.git```
-* To download via IPM , follow installation guides [here](https://github.com/efabless/IPM/blob/main/README.md) then run
+> **Note:** If you choose this method, you need to clone [IP_Utilities](https://github.com/efabless/IP_Utilities/tree/main) repository, as it includes required modules from the common modules library, [aucohl_lib.v](https://github.com/efabless/IP_Utilities/blob/main/rtl/aucohl_lib.v)
+* To download via IPM , follow installation guides [here](https://github.com/efabless/IPM/blob/main/README.md) then run 
 ```ipm install EF_UART```
-## Simulation:
-### Run Verilog Testbench:
-1. Clone [IP_Utilities](https://github.com/shalan/IP_Utilities) repo in the same directory as the IP
-2. In the directory ``EF_UART/verify/utb/`` run ``make APB-RTL`` to run testbench for APB or ``make AHBL-RTL`` to run testbench for AHBL
+> **Note:** This method is recommended as it automatically installs [IP_Utilities](https://github.com/efabless/IP_Utilities/tree/main) as a dependency.
 ### Run cocotb UVM Testbench:
-
 In IP directory run:
  ```shell
  cd verify/uvm-python/
@@ -336,4 +325,4 @@ In IP directory run:
  To run all tests with a tag: 
  ```shell
  make run_all_tests TAG=<new_tag> BUS_TYPE=AHB
-```
+```