From fb6ac48c74e77e5e90d39b953b1e529e57634fa3 Mon Sep 17 00:00:00 2001 From: NouranAbdelaziz Date: Sun, 12 Jan 2025 13:48:04 +0200 Subject: [PATCH] update documentation --- EF_UART.yaml | 4 ++-- README.md | 47 ++++++++++++++++++++++------------------------- 2 files changed, 24 insertions(+), 27 deletions(-) diff --git a/EF_UART.yaml b/EF_UART.yaml index 8f28032..c97bf2f 100644 --- a/EF_UART.yaml +++ b/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 diff --git a/README.md b/README.md index 570d04f..86a4417 100644 --- a/README.md +++ b/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,30 +279,18 @@ 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: +> **Note:** This method is recommended as it automatically installs [EF_IP_UTIL](https://github.com/efabless/EF_IP_UTIL.git) as a dependency. +## Run cocotb UVM Testbench: In IP directory run: ```shell cd verify/uvm-python/