update docs and wrappers

MS_WDT32.yaml → EF_WDT32.yaml

@@ -1,8 +1,15 @@
 ---
 info:
-  name: MS_WDT32
-  description: A 32-bit Watchdog Timer
-  repo: https://github.com/efabless/MS_WDT32
+  name: EF_WDT32
+  description: |
+    A simple 32-bit WatchDog Timer (WDT). It can be used to interrupt the CPU to:
+
+    Indicate a software malfunction.
+    Wakeup the CPU after a certain sleep time.
+    The WDT is a simple 32-bit down-counter which is decremented every system clock cycle. When it reached zero, the counter is loaded with the value stored in the load register and the TO flag is raised..
+
+    The WDT can be enabled/disabled. When it is disabled the counter is loaded with the value in the load register.
+  repo: https://github.com/efabless/EF_WDT32
   owner: Mohamed Shalan
   license: Apache 2.0
   author: Mohamed Shalan
@@ -40,22 +47,23 @@ ports:
 - name: WDTMR
   width: 32
   direction: output
-  description: 
+  description: The current value of the timer
 - name: WDTLOAD
   width: 32
   direction: input
-  description: 
+  description: The value loaded into the timer when it reaches zero
 - name: WDTTO
   width: 1
   direction: output
-  description: 
+  description: Time out flag
 - name: WDTEN
   width: 1
   direction: input
-  description: 
+  description: watchdog timer enable 
 
 clock:
   name: clk
+  gated: "yes"
 reset:
   name: rst_n  
   level: 0
@@ -68,25 +76,28 @@ registers:
   offset: 0
   bit_access: no 
   read_port: WDTMR
+  description: The current value of the timer
 - name: load
   size: 32
   mode: w
   fifo: no
   offset: 4
   bit_access: no 
   write_port: WDTLOAD
+  description: The value loaded into the timer when it reaches zero
 - name: control
   size: 1
   mode: w
   fifo: no
   offset: 8
   bit_access: no 
   write_port: WDTEN
+  description: Writing 0 disables the WDT and writing 1 enables it
 
 
 flags:
 - name: wdtto
   port: WDTTO
-  description: 
+  description: Time out flag 
 
 

README.md

@@ -1,30 +1,140 @@
-# MS_WDT32
+# EF_WDT32
+
 A simple 32-bit WatchDog Timer (WDT). It can be used to interrupt the CPU to:
-- Indicate a software malfunction.
-- Wakeup the CPU after a certain sleep time.
 
-The WDT is a simple 32-bit down-counter which is decremented every system clock cycle. When it reached zero, the counter is loaded with the value stored in the load register and the TO flag is raised.. 
+Indicate a software malfunction.
+Wakeup the CPU after a certain sleep time.
+The WDT is a simple 32-bit down-counter which is decremented every system clock cycle. When it reached zero, the counter is loaded with the value stored in the load register and the TO flag is raised..
 
 The WDT can be enabled/disabled. When it is disabled the counter is loaded with the value in the load register.
-
-## Registers
-|Offset|Register| Size |Description|
-|------|--------|------|-----------|
-|0x0000| Timer | 32 | The current value of the timer |
-|0x0004| Load | 32 | The value loaded into the timer when it reaches zero|
-|0x0008| Control | 1 | Writing 0 disables the WDT and writing 1 enables it |
-|0x0F00| RIS | 1 | Raw Status Register |
-|0x0F04| MIS | 1 | Masked Status Register |
-|0x0F08| IM | 1 | Interrupts Masking Register; enable and disables interrupts |
-|0x0F0C| ICR | 1 | Interrupts Clear Register; write 1 to clear the flag |
-
-## Interrupt Flags
-The Time Out (TO) flag is the only available flag. The TO is raised when the down-counter reaches 0. 
-
-## How to use
-### Configuring the timeout value
-Timeout Value (sec) = load/clk_freq
-
-### Restarting the WDT (software monitoring)
-Just disable then re-enable the WDT. You code should do this frequently before the WDT times out.
 
+## 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
+
+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_WDT32_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),
+);
+```
+#### 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 EF_WDT32 IP with different wrappers using Sky130 PDK and [OpenLane2](https://github.com/efabless/openlane2) flow.
+|Module | Number of cells | Max. freq |
+|---|---|---|
+|EF_WDT32|TBD| TBD |
+|EF_WDT32_APB|TBD|TBD|
+|EF_WDT32_AHBL|TBD|TBD|
+|EF_WDT32_WB|TBD|TBD|
+## The Programmer's Interface
+
+
+### Registers
+
+|Name|Offset|Reset Value|Access Mode|Description|
+|---|---|---|---|---|
+|timer|0000|0x00000000|r|The current value of the timer|
+|load|0004|0x00000000|w|The value loaded into the timer when it reaches zero|
+|control|0008|0x00000000|w|Writing 0 disables the WDT and writing 1 enables it|
+|IM|ff00|0x00000000|w|Interrupt Mask Register; write 1/0 to enable/disable interrupts; check the interrupt flags table for more details|
+|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|
+
+### timer Register [Offset: 0x0, mode: r]
+
+The current value of the timer
+<img src="https://svg.wavedrom.com/{reg:[{name:'timer', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
+
+### load Register [Offset: 0x4, mode: w]
+
+The value loaded into the timer when it reaches zero
+<img src="https://svg.wavedrom.com/{reg:[{name:'load', bits:32},{bits: 0}], config: {lanes: 2, hflip: true}} "/>
+
+### control Register [Offset: 0x8, mode: w]
+
+Writing 0 disables the WDT and writing 1 enables it
+<img src="https://svg.wavedrom.com/{reg:[{name:'control', bits:1},{bits: 31}], 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.
+
+Each register has a group of bits for the interrupt sources/flags.
+- `IM` [offset: 0xff00]: is used to enable/disable interrupt sources.
+
+- `RIS` [offset: 0xff08]: has the current interrupt status (interrupt flags) whether they are enabled or disabled.
+
+- `MIS` [offset: 0xff04]: is the result of masking (ANDing) RIS by IM.
+
+- `IC` [offset: 0xff0c]: is used to clear an interrupt flag.
+
+
+The following are the bit definitions for the interrupt registers:
+
+|Bit|Flag|Width|Description|
+|---|---|---|---|
+|0|WDTTO|1|Time out flag|
+### 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``.
+
+**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
+```
+
+### The Interface 
+
+<img src="docs/_static/EF_WDT32.svg" width="600"/>
+
+#### Ports 
+
+|Port|Direction|Width|Description|
+|---|---|---|---|
+|WDTMR|output|32|The current value of the timer|
+|WDTLOAD|input|32|The value loaded into the timer when it reaches zero|
+|WDTTO|output|1|Time out flag|
+|WDTEN|input|1|watchdog timer enable|
+## Firmware Drivers:
+Firmware drivers for EF_WDT32 can be found in the [fw](https://github.com/efabless/EF_WDT32/tree/main/fw) directory. EF_WDT32 driver documentation  is available [here](https://github.com/efabless/EF_WDT32/blob/main/fw/README.md).
+You can also find an example C application using the EF_WDT32 drivers [here]().
+## Installation:
+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_WDT32```.
+> **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 https://github.com/efabless/EF_WDT32```

fw/MS_WDT32.c → fw/EF_WDT32.c

@@ -1,55 +1,55 @@
-#ifndef MS_WDT32_C
-#define MS_WDT32_C
+#ifndef EF_WDT32_C
+#define EF_WDT32_C
 
-#include <MS_WDT32.h>
+#include <EF_WDT32.h>
 
 void WDT32_enable(uint32_t wdt_base, int is_enable){
 
-    MS_WDT32_TYPE* wdt = (MS_WDT32_TYPE*)wdt_base;
+    EF_WDT32_TYPE* wdt = (EF_WDT32_TYPE*)wdt_base;
     wdt->control = is_enable;
 }
 
 int WDT32_readTimer(uint32_t wdt_base){
 
-    MS_WDT32_TYPE* wdt = (MS_WDT32_TYPE*)wdt_base;
+    EF_WDT32_TYPE* wdt = (EF_WDT32_TYPE*)wdt_base;
     return (wdt->timer);
 }
 
 int WDT32_loadTimer(uint32_t wdt_base, int load_val){
 
-    MS_WDT32_TYPE* wdt = (MS_WDT32_TYPE*)wdt_base;
+    EF_WDT32_TYPE* wdt = (EF_WDT32_TYPE*)wdt_base;
     wdt->load = load_val;
 }
 
 
 int WDT32_getRIS(uint32_t wdt_base){
 
-    MS_WDT32_TYPE* wdt = (MS_WDT32_TYPE*)wdt_base;
+    EF_WDT32_TYPE* wdt = (EF_WDT32_TYPE*)wdt_base;
     return (wdt->RIS);
 }
 
 int WDT32_getMIS(uint32_t wdt_base){
 
-    MS_WDT32_TYPE* wdt = (MS_WDT32_TYPE*)wdt_base;
+    EF_WDT32_TYPE* wdt = (EF_WDT32_TYPE*)wdt_base;
     return (wdt->MIS);
 }
 
 void WDT32_setIM(uint32_t wdt_base, int mask){
 
-    MS_WDT32_TYPE* wdt = (MS_WDT32_TYPE*)wdt_base;
+    EF_WDT32_TYPE* wdt = (EF_WDT32_TYPE*)wdt_base;
 
     wdt->IM = mask;
 }
 
 int WDT32_getIM(uint32_t wdt_base){
 
-    MS_WDT32_TYPE* wdt = (MS_WDT32_TYPE*)wdt_base;
+    EF_WDT32_TYPE* wdt = (EF_WDT32_TYPE*)wdt_base;
     return (wdt->IM);
 }
 
 void WDT32_setICR(uint32_t wdt_base, int mask){
 
-    MS_WDT32_TYPE* wdt = (MS_WDT32_TYPE*)wdt_base;
+    EF_WDT32_TYPE* wdt = (EF_WDT32_TYPE*)wdt_base;
     wdt->IC = mask;
 }
 #endif // WDT32_C

fw/MS_WDT32.h → fw/EF_WDT32.h

@@ -1,7 +1,7 @@
-#ifndef MS_WDT32_H
-#define MS_WDT32_H
+#ifndef EF_WDT32_H
+#define EF_WDT32_H
 
-#include <MS_WDT32_regs.h>
+#include <EF_WDT32_regs.h>
 #include <stdint.h>
 #include <stdbool.h>
 

fw/MS_WDT32_regs.h → fw/EF_WDT32_regs.h

@@ -1,5 +1,5 @@
 /*
-	Copyright 2020 Mohamed Shalan
+	Copyright 2025 Mohamed Shalan
 
 	Author: Mohamed Shalan ([email protected])
 
@@ -17,8 +17,8 @@
 
 */
 
-#ifndef MS_WDT32REGS_H
-#define MS_WDT32REGS_H
+#ifndef EF_WDT32REGS_H
+#define EF_WDT32REGS_H
 
 #ifndef IO_TYPES
 #define IO_TYPES
@@ -28,9 +28,9 @@
 #endif
 
 
-#define MS_WDT32_WDTTO_FLAG	0x1
+#define EF_WDT32_WDTTO_FLAG	0x1
 
-typedef struct _MS_WDT32_TYPE_ {
+typedef struct _EF_WDT32_TYPE_ {
 	__R 	timer;
 	__W 	load;
 	__W 	control;
@@ -40,7 +40,7 @@ typedef struct _MS_WDT32_TYPE_ {
 	__R 	RIS;
 	__W 	IC;
 	__W 	GCLK;
-} MS_WDT32_TYPE;
+} EF_WDT32_TYPE;
 
 #endif
 

hdl/rtl/MS_WDT.v → hdl/rtl/EF_WDT32.v

@@ -17,7 +17,7 @@
 `timescale          1ns/1ps
 `default_nettype    none
 
-module MS_WDT32 (
+module EF_WDT32 (
 		input wire          clk,
 		input wire          rst_n,
 		output reg [31:0]   WDTMR,