Skip to content

Commit

Permalink
update wrappers and docs with the latest buswrap updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@M0stafaRady
M0stafaRady committed Jan 12, 2025
1 parent 5d7467b commit 46c4bb3
Show file tree
Hide file tree
Showing 20 changed files with 3,790 additions and 1,830 deletions.
5 changes: 3 additions & 2 deletions EF_I2S.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ info:
repo: github.com/efabless/EF_I2S
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.14
date: 17-09-2024
category: digital
Expand Down Expand Up @@ -161,6 +161,7 @@ external_interface:

clock:
name: clk
gated: 'yes'

reset:
name: rst_n
Expand Down
135 changes: 49 additions & 86 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,41 +1,36 @@
# EF_I2S

Two-wire I2S synchronous serial interface, compatible with I2S specification.
- Receiver only
- 32x32 Receive FIFO
- Sample Size selection
- Left channel, Right channel only or Stereo
- Programmable prescaler
- Supports both the classical I2S and the Left-aligned formats
- Programmable sample size
- Zero/Sign extension for the samples


## The wrapped IP


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

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


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_I2S_APB INST (
`TB_APB_SLAVE_CONN,
.ws(ws),
.sck(sck),
.sdi(sdi)
EF_I2S_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),
.ws(ws),
.sck(sck),
.sdi(sdi)
);
```
> **_NOTE:_** `TB_APB_SLAVE_CONN is a convenient macro provided by [BusWrap](https://github.com/efabless/BusWrap/tree/main).

## Implementation example
#### 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.

## Implementation example

The following table is the result for implementing the EF_I2S IP with different wrappers using Sky130 PDK and [OpenLane2](https://github.com/efabless/openlane2) flow.
|Module | Number of cells | Max. freq |
Expand All @@ -47,8 +42,6 @@ The following table is the result for implementing the EF_I2S IP with different
## The Programmer's Interface




### Registers

|Name|Offset|Reset Value|Access Mode|Description|
Expand All @@ -66,31 +59,28 @@ The following table is the result for implementing the EF_I2S 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]

The received sample
<img src="https://svg.wavedrom.com/{reg:[{name:'RXDATA', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>


### PR Register [Offset: 0x4, mode: w]

The Prescaler register; used to determine the sck signal frequency . $Prescaler = clk_freq/(2 x sck_freq) - 1$.
<img src="https://svg.wavedrom.com/{reg:[{name:'PR', bits:8},{bits: 24}], config: {lanes: 2, hflip: true}} "/>


### AVGT Register [Offset: 0x8, mode: w]

The Average threshold
<img src="https://svg.wavedrom.com/{reg:[{name:'AVGT', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>


### ZCRT Register [Offset: 0xc, mode: w]

The ZCR threshold
<img src="https://svg.wavedrom.com/{reg:[{name:'ZCRT', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>


### CTRL Register [Offset: 0x10, mode: w]

Control Register; 0:Enable, 1:FIFO Enable.
Expand All @@ -103,7 +93,6 @@ Control Register; 0:Enable, 1:FIFO Enable.
|2|avg_en|1|Averaging enable|
|3|zcr_en|1|ZCR enable|


### CFG Register [Offset: 0x14, mode: w]

Configuration Register, 0-1: Channels to read, '01': right, '10': left, '11': Both (stereo) 2: Sign Extend 3: Left Justify 4-8: Sample Size (0-31)
Expand All @@ -118,7 +107,6 @@ Configuration Register, 0-1: Channels to read, '01': right, '10': left, '11': Bo
|10|AVGSEL|1|Select the number of samples to average|
|11|ZCRSEL|1|Select the number of samples to calculate the ZCR|


### RX_FIFO_LEVEL Register [Offset: 0xfe00, mode: r]

RX_FIFO Level Register
Expand All @@ -128,7 +116,6 @@ RX_FIFO Level Register
|---|---|---|---|
|0|level|4|FIFO data level|


### RX_FIFO_THRESHOLD Register [Offset: 0xfe04, mode: w]

RX_FIFO Level Threshold Register
Expand All @@ -138,7 +125,6 @@ RX_FIFO Level Threshold Register
|---|---|---|---|
|0|threshold|4|FIFO level threshold value|


### RX_FIFO_FLUSH Register [Offset: 0xfe08, mode: w]

RX_FIFO Flush Register
Expand All @@ -148,19 +134,28 @@ RX_FIFO Flush Register
|---|---|---|---|
|0|flush|1|FIFO flush|

### GCLK Register [Offset: 0xff10, mode: w]

Gated clock enable register
<img src="https://svg.wavedrom.com/{reg:[{name:'gclk_enable', bits:1},{bits: 31}], config: {lanes: 2, hflip: true}} "/>

|bit|field name|width|description|
|---|---|---|---|
|0|gclk_enable|1|Gated clock enable; 1: enable clock, 0: disable clock|


### 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`: is used to enable/disable interrupt sources.
- `IM` [offset: 0xff00]: is used to enable/disable interrupt sources.

- `RIS`: has the current interrupt status (interrupt flags) whether they are enabled or disabled.
- `RIS` [offset: 0xff08]: has the current interrupt status (interrupt flags) whether they are enabled or disabled.

- `MIS`: is the result of masking (ANDing) RIS by IM.
- `MIS` [offset: 0xff04]: is the result of masking (ANDing) RIS by IM.

- `IC`: is used to clear an interrupt flag.
- `IC` [offset: 0xff0c]: is used to clear an interrupt flag.


The following are the bit definitions for the interrupt registers:
Expand All @@ -173,9 +168,17 @@ The following are the bit definitions for the interrupt registers:
|3|AVGF|1|The avg is above the threshold.|
|4|ZCRF|1|The ZCR is above the threshold.|
|5|VADF|1|The Voice Activity Detector flag; active when both ZCR & AVG flags are active.|
### 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_util_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 ``CLKG_SKY130_HD`` macro is enabled, the ``sky130_fd_sc_hd__dlclkp_4`` clock gating cell is used.
**Note:** If you choose the [OpenLane2](https://github.com/efabless/openlane2) flow for implementation and would like to add the clock gating feature, you need to add ``SKY130`` macro to the ``VERILOG_DEFINES`` configuration variable. Update the YAML configuration file as follows:
```
VERILOG_DEFINES:
- SKY130
```

### The Interface

<img src="docs/_static/EF_I2S.svg" width="600"/>

#### Module Parameters

Expand Down Expand Up @@ -215,54 +218,14 @@ The following are the bit definitions for the interrupt registers:
|vad_flag|output|1|The VAD flag|
|channels|input|2|Channels used (left, right, or stereo)|
|en|input|1|Enable signal|




## F/W Usage Guidelines:
1. Set the prescaler value in the ``PR`` register where sck_freq = (clk_freq / (prescaler+1))/2. Note that for the controller to function correctly, the prescaler needs to be greater than 1.
2. Check the I2S device data sheet to know the sample size sent and configure the ``sample_size`` field in the ``CFG`` reg accordingly.
3. Check the I2S device data sheet to know if the samples sent are in left justified or i2s mode and configure the ``left_justified`` field in the ``CFG`` reg.
4. Configure the ``channels`` field in ``CFG`` by specifying which channel you want to capture or both channels (stereo)
5. If you want the sample to be sign extended by the controller, enable ``sign_extended`` field in ``CFG`` register
6. After configuring the controller, enable it along with the FIFO to capture the samples by setting ``en`` and ``fifo_en`` fields in the ``CTRL`` register.
7. If you want to use the averaging feature in the controller, you can set the ``avg_en`` field and set the average threshold ``AVGT`` register. The average flag ``AVGF`` will be fired when the average of the samples sent are above this threshold. Note that the averaging mode works only when the sign extension mode is on.


## Firmware Drivers:
Firmware drivers for EF_I2S can be found in the [fw](https://github.com/efabless/EF_I2S/tree/main/fw) directory. EF_I2S driver documentation is available [here](https://github.com/efabless/EF_I2S/blob/main/fw/README.md).
You can also find an example C application using the EF_I2S 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://github.com/efabless/EF_I2S```
> **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_I2S```
### 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.
Loading

0 comments on commit 46c4bb3

Please sign in to comment.