Merge branch 'main' of github.com:efabless/EF_UART

EF_UART.yaml

@@ -29,8 +29,8 @@ info:
   repo: https://github.com/efabless/EF_UART.git
   owner: Efabless Corp.
   license: APACHE 2.0
-  author: Mohamed Shalan
-  email: mshalan@efabless.com
+  author: Efabless Corp.
+  email: ip_admin@efabless.com
   version: v1.1.8
   date: 16-09-2024
   category: digital

README.md

@@ -28,19 +28,28 @@ EF_UART is a Soft IP with the following features:
 ## 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.
+ APB, AHBL, and Wishbone wrappers are provided. All wrappers provide the same programmer's interface as outlined in the following sections.
 
 #### 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:
+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 wishbone wrapper:
 ```verilog
-EF_UART_APB INST (
-	`TB_APB_SLAVE_CONN,
+EF_UART_WB INST (
+	.clk_i(clk_i),
+	.rst_i(rst_i),
+	.adr_i(adr_i),
+	.dat_i(dat_i),
+	.dat_o(dat_o),
+	.sel_i(sel_i),
+	.cyc_i(cyc_i),
+	.stb_i(stb_i),
+	.ack_o(ack_o),
+	.we_i(we_i), 
+	.IRQ(irq),
 	.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 ``sc_testmode`` to enable the clock gate whenever the scan chain testmode is enabled.
 
@@ -189,7 +198,7 @@ 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.
 
 Each register has a group of bits for the interrupt sources/flags.
 - `IM` [offset: 0xff00]: is used to enable/disable interrupt sources.
@@ -216,7 +225,7 @@ The following are the bit definitions for the interrupt registers:
 |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 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, [ef_util_lib.v](https://github.com/efabless/EF_IP_UTIL/blob/main/hdl/ef_util_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 
 
@@ -270,57 +279,14 @@ The IP has clock gating feature, enabling the selective activation and deactivat
 |parity_error_flag|output|1|Parity error flag|
 |overrun_flag|output|1|Overrun flag|
 |timeout_flag|output|1|Timeout flag|
-## 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
-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.
-
+## Drivers Documentation:
+Driver documentation for EF_UART is available [here](https://github.com/efabless/EF_UART/blob/main/fw/README.md).
+You can also find a C example application using EF_UART drivers [here]().
 ## 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```
-> **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)
+> **Note:** If you choose this method, you need to clone [EF_IP_UTIL](https://github.com/efabless/EF_IP_UTIL.git) repository, as it includes required modules from the common modules library, [ef_util_lib.v](https://github.com/efabless/EF_IP_UTIL/blob/main/hdl/ef_util_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```
-> **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/
- ```
- ##### To run testbench for design with APB 
- To run all tests:
- ```shell
- make run_all_tests BUS_TYPE=APB
- ```
- To run a certain test:
- ```shell
- make run_<test_name> BUS_TYPE=APB
- ```
- To run all tests with a tag: 
- ```shell
- make run_all_tests TAG=<new_tag> BUS_TYPE=APB
- ```
- ##### To run testbench for design with APB
- To run all tests:
- ```shell
- make run_all_tests BUS_TYPE=AHB
- ```
- To run a certain test:
- ```shell
- make run_<test_name> BUS_TYPE=AHB
- ```
- To run all tests with a tag: 
- ```shell
- make run_all_tests TAG=<new_tag> BUS_TYPE=AHB
-```
+> **Note:** This method is recommended as it automatically installs [EF_IP_UTIL](https://github.com/efabless/EF_IP_UTIL.git) as a dependency.

verify/README.md

@@ -0,0 +1,31 @@
+## Run cocotb UVM Testbench:
+In IP directory run:
+ ```shell
+ cd verify/uvm-python/
+ ```
+ ##### To run testbench for design with APB 
+ To run all tests:
+ ```shell
+ make run_all_tests BUS_TYPE=APB
+ ```
+ To run a certain test:
+ ```shell
+ make run_<test_name> BUS_TYPE=APB
+ ```
+ To run all tests with a tag: 
+ ```shell
+ make run_all_tests TAG=<new_tag> BUS_TYPE=APB
+ ```
+ ##### To run testbench for design with APB
+ To run all tests:
+ ```shell
+ make run_all_tests BUS_TYPE=AHB
+ ```
+ To run a certain test:
+ ```shell
+ make run_<test_name> BUS_TYPE=AHB
+ ```
+ To run all tests with a tag: 
+ ```shell
+ make run_all_tests TAG=<new_tag> BUS_TYPE=AHB
+```