update docs and regenerate wrappers

Author: NouranAbdelaziz

SW_AES.yaml EF_AES.yaml

@@ -1,14 +1,12 @@
 ---
 info:
-  name: SW_AES
-  description: Verilog implementation of the symmetric block cipher AES (Advanced
-    Encryption Standard) as specified in NIST FIPS 197. This implementation supports
-    128 and 256 bit keys.
-  repo: github.com/efabless/SW_AES
-  owner: secworks
-  license: MIT
-  author: Joachim Strombergson
-  email: ''
+  name: EF_AES
+  description: APB, AHBL and wishbone wrappers for the symmetric block cipher AES (Advanced Encryption Standard) which is implemented in Verilog in the [secworks/aes](https://github.com/secworks/aes/tree/master) repository.
+  repo: github.com/efabless/EF_AES
+  owner: Efabless Corp.
+  license: Apache 2.0
+  author: Efabless Corp.
+  email: [email protected]
   version: v1.0.2
   date: 12-11-2024
   category: digital
@@ -254,6 +252,7 @@ registers:
 
 clock:
   name: clk
+  gated: "yes"
 reset:
   name: reset_n
   level: 0

README.md

@@ -1,31 +1,41 @@
-# SW_AES
-
-Verilog implementation of the symmetric block cipher AES (Advanced Encryption Standard) as specified in NIST FIPS 197. This implementation supports 128 and 256 bit keys. The AES rtl is based on [this repo](https://github.com/secworks/aes/tree/master) 
+# EF_AES
 
+APB, AHBL and wishbone wrappers for the symmetric block cipher AES (Advanced Encryption Standard) which is implemented in Verilog in the [secworks/aes](https://github.com/secworks/aes/tree/master) repository.
 ## 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
+#### 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
-SW_AES_APB INST (
-        `TB_APB_SLAVE_CONN
+EF_AES_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),
 );
 ```
-> **_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 disable the clock gate whenever the scan chain testmode is enabled.
 
 ## Implementation example  
 
-The following table is the result for implementing the SW_AES IP with different wrappers using Sky130 PDK and [OpenLane2](https://github.com/efabless/openlane2) flow.
+The following table is the result for implementing the EF_AES IP with different wrappers using Sky130 PDK and [OpenLane2](https://github.com/efabless/openlane2) flow.
 |Module | Number of cells | Max. freq |
 |---|---|---|
-|SW_AES|TBD| TBD |
-|SW_AES_APB|TBD|TBD|
-|SW_AES_AHBL|TBD|TBD|
-|SW_AES_WB|TBD|TBD|
+|EF_AES|TBD| TBD |
+|EF_AES_APB|TBD|TBD|
+|EF_AES_AHBL|TBD|TBD|
+|EF_AES_WB|TBD|TBD|
 ## The Programmer's Interface
 
 
@@ -55,6 +65,7 @@ The following table is the result for implementing the SW_AES 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|
 
 ### STATUS Register [Offset: 0x0, mode: r]
 
@@ -66,7 +77,6 @@ Status register bit 6: ready , bit 7: valid
 |6|ready_reg|1|Ready to start|
 |7|valid_reg|1|Result is valid|
 
-
 ### CTRL Register [Offset: 0x4, mode: w]
 
 Control register bit 0: Initial bit (init), bit 1: Next bit , bit 2: Encipher/Decipher control, bit 3: Key length control
@@ -79,115 +89,108 @@ Control register bit 0: Initial bit (init), bit 1: Next bit , bit 2: Encipher/De
 |2|encdec_reg|1|Encipher/Decipher control (“0” means Decipher “1” means Encipher)|
 |3|keylen_reg|1|Key length control (“0” means 128 bit key length “1” means 256 bit key length")|
 
-
 ### KEY0 Register [Offset: 0x8, mode: w]
 
 Contains the bits 31-0 of the input key value
 <img src="https://svg.wavedrom.com/{reg:[{name:'KEY0', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
-
 ### KEY1 Register [Offset: 0xc, mode: w]
 
 Contains the bits 63-32 of the input key value
 <img src="https://svg.wavedrom.com/{reg:[{name:'KEY1', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
-
 ### KEY2 Register [Offset: 0x10, mode: w]
 
 Contains the bits 95-64 of the input key value
 <img src="https://svg.wavedrom.com/{reg:[{name:'KEY2', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
-
 ### KEY3 Register [Offset: 0x14, mode: w]
 
 Contains the bits 127-96 of the input key value
 <img src="https://svg.wavedrom.com/{reg:[{name:'KEY3', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
-
 ### KEY4 Register [Offset: 0x18, mode: w]
 
 Contains the bits 159-128 of the input key value
 <img src="https://svg.wavedrom.com/{reg:[{name:'KEY4', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
-
 ### KEY5 Register [Offset: 0x1c, mode: w]
 
 Contains the bits 191-160 of the input key value
 <img src="https://svg.wavedrom.com/{reg:[{name:'KEY5', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
-
 ### KEY6 Register [Offset: 0x20, mode: w]
 
 Contains the bits 223-192 of the input key value
 <img src="https://svg.wavedrom.com/{reg:[{name:'KEY6', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
-
 ### KEY7 Register [Offset: 0x24, mode: w]
 
 Contains the bits 255-224 of the input key value
 <img src="https://svg.wavedrom.com/{reg:[{name:'KEY7', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
-
 ### BLOCK0 Register [Offset: 0x28, mode: w]
 
 Contains the bits 31-0 of the input block value
 <img src="https://svg.wavedrom.com/{reg:[{name:'BLOCK0', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
-
 ### BLOCK1 Register [Offset: 0x2c, mode: w]
 
 Contains the bits 63-32 of the input block value
 <img src="https://svg.wavedrom.com/{reg:[{name:'BLOCK1', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
-
 ### BLOCK2 Register [Offset: 0x30, mode: w]
 
 Contains the bits 95-64 of the input block value
 <img src="https://svg.wavedrom.com/{reg:[{name:'BLOCK2', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
-
 ### BLOCK3 Register [Offset: 0x34, mode: w]
 
 Contains the bits 127-96 of the input block value
 <img src="https://svg.wavedrom.com/{reg:[{name:'BLOCK3', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
-
 ### RESULT0 Register [Offset: 0x38, mode: w]
 
 Contains the bits 31-0 of the input result value
 <img src="https://svg.wavedrom.com/{reg:[{name:'RESULT0', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
-
 ### RESULT1 Register [Offset: 0x3c, mode: w]
 
 Contains the bits 63-32 of the input result value
 <img src="https://svg.wavedrom.com/{reg:[{name:'RESULT1', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
-
 ### RESULT2 Register [Offset: 0x40, mode: w]
 
 Contains the bits 95-64 of the input result value
 <img src="https://svg.wavedrom.com/{reg:[{name:'RESULT2', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
-
 ### RESULT3 Register [Offset: 0x44, mode: w]
 
 Contains the bits 127-96 of the input result value
 <img src="https://svg.wavedrom.com/{reg:[{name:'RESULT3', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
 
+### 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:
@@ -196,11 +199,18 @@ The following are the bit definitions for the interrupt registers:
 |---|---|---|---|
 |0|VALID|1|Result is valid|
 |1|READY|1|Ready to start|
+### Clock Gating
+The IP includes a clock gating feature that allows selective activation and deactivation of the clock using the ``GCLK`` register. This capability is implemented through the ``ef_util_gating_cell`` module, which is part of 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 clock gating is disabled. To enable behavioral implmentation clock gating, only for simulation purposes, you should define the ``CLKG_GENERIC`` macro. Alternatively, define the ``CLKG_SKY130_HD`` macro if you wish to use the SKY130 HD library clock gating cell, ``sky130_fd_sc_hd__dlclkp_4``.
 
-### The Interface 
+**Note:** If you choose the [OpenLane2](https://github.com/efabless/openlane2) flow for implementation and would like to enable the clock gating feature, you need to add ``CLKG_SKY130_HD`` macro to the ``VERILOG_DEFINES`` configuration variable. Update OpenLane2 YAML configuration file as follows: 
+```
+VERILOG_DEFINES:
+- CLKG_SKY130_HD
+```
 
-<img src="docs/aes_core.svg" width="600"/>
+### The Interface 
 
+<img src="docs/_static/EF_AES.svg" width="600"/>
 
 #### Ports 
 
@@ -215,13 +225,17 @@ The following are the bit definitions for the interrupt registers:
 |block|input|128|block value|
 |result|output|128|result value|
 |result_valid|output|1|result is valid|
-## F/W Usage Guidelines:
-TBD
+## Firmware Drivers:
+Firmware drivers for EF_AES can be found in the [fw](https://github.com/efabless/EF_AES/tree/main/fw) directory. EF_AES driver documentation  is available [here](https://github.com/efabless/EF_AES/blob/main/fw/README.md).
+You can also find an example C application using the EF_AES 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/SW_AES```
-* To download via IPM , follow installation guides [here](https://github.com/efabless/IPM/blob/main/README.md) then run 
-```ipm install SW_AES```
-### Run cocotb UVM Testbench:
-TBD
+You can install the IP either by cloning this repository or by using [IPM](https://github.com/efabless/IPM).
+##### 1. Using [IPM](https://github.com/efabless/IPM):
+- [Optional] If you do not have IPM installed, follow the installation guide [here](https://github.com/efabless/IPM/blob/main/README.md)
+- After installing IPM, execute the following command ```ipm install EF_AES```.
+> **Note:** This method is recommended as it automatically installs [EF_IP_UTIL](https://github.com/efabless/EF_IP_UTIL.git) as a dependency.
+##### 2. Cloning this repo: 
+- Clone [EF_IP_UTIL](https://github.com/efabless/EF_IP_UTIL.git) repository, which includes the 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).
+```git clone https://github.com/efabless/EF_IP_UTIL.git```
+- Clone the IP repository
+```git clone github.com/efabless/EF_AES```