# common_ip

**Repository Path**: fpga1988/common_ip

## Basic Information

- **Project Name**: common_ip
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-12
- **Last Updated**: 2026-01-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Common IP Library

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](../../../LICENSE)
[![iverilog](https://img.shields.io/badge/iverilog-compatible-green.svg)](https://github.com/steveicarus/iverilog)

English | [中文](README.md)

A comprehensive collection of reusable, parameterized IP cores for FPGA and ASIC designs. All modules are compatible with iverilog (`-g2012 -Wall`) and follow synthesizable RTL design practices.

## Overview

This library provides production-ready IP cores commonly needed in digital design projects. Each module is thoroughly tested, well-documented, and designed for easy integration.

## Features

- **80+ IP modules** across 16 categories
- **Parameterized designs** for flexible configuration
- **iverilog compatible** - tested with `-g2012 -Wall`
- **Synthesizable RTL** - no simulation-only constructs in design files
- **Hierarchical architecture** - complex IPs reuse simpler building blocks
- **Unit tested** - comprehensive testbenches included
- **Production ready** - used in RISC-V heterogeneous computing platform

## Directory Structure

```
common_ip/
├── inc/                    # Common packages and definitions
│   └── ip_common_pkg.sv    # Shared types and constants
├── rtl/                    # RTL source files
│   ├── alu/                # Arithmetic Logic Units
│   ├── arb/                # Arbiters
│   ├── bit/                # Bit manipulation
│   ├── buf/                # Buffers and FIFOs
│   ├── cdc/                # Clock Domain Crossing
│   ├── chk/                # Checksum and CRC
│   ├── clk/                # Clock management
│   ├── cmp/                # Comparators
│   ├── dec/                # Decoders
│   ├── ecc/                # Error Correction Codes
│   ├── enc/                # Encoders
│   ├── mem/                # Memory blocks
│   ├── prng/               # Pseudo-random generators
│   ├── rst/                # Reset management
│   ├── sort/               # Sorting networks
│   └── sys/                # System utilities
├── tb/                     # Testbenches
│   └── unit_tests/         # Unit test files
└── Makefile                # Build and test automation
```

## IP Catalog

### Buffer IPs (`buf`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_buf_sync_fifo` | Synchronous FIFO | DATA_WIDTH, DEPTH |
| `ip_buf_async_fifo` | Asynchronous FIFO with CDC | DATA_WIDTH, DEPTH, SYNC_STAGES |
| `ip_buf_skid` | Skid buffer for pipeline | DATA_WIDTH |
| `ip_buf_credit_ctrl` | Credit-based flow control | DATA_WIDTH, MAX_CREDITS |
| `ip_buf_width_conv` | Bus width converter | IN_WIDTH, OUT_WIDTH |

### Arbiter IPs (`arb`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_arb_priority` | Fixed priority arbiter | NUM_REQ |
| `ip_arb_round_robin` | Round-robin arbiter | NUM_REQ |
| `ip_arb_wrr` | Weighted round-robin | NUM_REQ, WEIGHT_WIDTH |
| `ip_arb_dwrr` | Deficit weighted round-robin | NUM_REQ, WEIGHT_WIDTH |
| `ip_arb_fifo` | FIFO-based arbiter | NUM_REQ |
| `ip_arb_lru` | LRU replacement arbiter | NUM_WAYS |

### CDC IPs (`cdc`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_cdc_sync_2stage` | 2-stage synchronizer | WIDTH |
| `ip_cdc_sync_3stage` | 3-stage synchronizer | WIDTH |
| `ip_cdc_gray_counter` | Gray code counter | WIDTH |
| `ip_cdc_pulse_sync` | Pulse synchronizer | - |
| `ip_cdc_bus_sync` | Multi-bit bus synchronizer | WIDTH |
| `ip_cdc_handshake` | Handshake synchronizer | DATA_WIDTH |

### Clock IPs (`clk`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_clk_gate` | Clock gating cell | - |
| `ip_clk_divider` | Clock divider | DIV_WIDTH |
| `ip_clk_delay_line` | Programmable delay line | STAGES |
| `ip_clk_mux` | Glitch-free clock mux | NUM_CLKS |

### Reset IPs (`rst`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_rst_sync` | Reset synchronizer | STAGES |
| `ip_rst_por` | Power-on reset generator | DELAY_CYCLES |

### Memory IPs (`mem`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_mem_sp_ram` | Single-port RAM | DATA_WIDTH, DEPTH |
| `ip_mem_dp_ram` | Dual-port RAM | DATA_WIDTH, DEPTH |
| `ip_mem_tdp_ram` | True dual-port RAM | DATA_WIDTH, DEPTH |
| `ip_mem_sdp_ram` | Simple dual-port RAM | DATA_WIDTH, DEPTH |
| `ip_mem_rom` | ROM | DATA_WIDTH, DEPTH |
| `ip_mem_regfile` | Multi-port register file | DATA_WIDTH, DEPTH, RD_PORTS, WR_PORTS |
| `ip_mem_cam` | Content-addressable memory | DATA_WIDTH, DEPTH |
| `ip_mem_tcam` | Ternary CAM | DATA_WIDTH, DEPTH |

### ALU IPs (`alu`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_alu_fixed_point` | Fixed-point arithmetic | WIDTH, FRAC_BITS |
| `ip_alu_saturating` | Saturating arithmetic | WIDTH |
| `ip_alu_mult` | Pipelined multiplier | WIDTH, PIPE_STAGES |
| `ip_alu_div` | Iterative divider | WIDTH |
| `ip_alu_mac` | Multiply-accumulate | WIDTH, ACC_WIDTH |

### Bit Operation IPs (`bit`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_bit_lzc` | Leading zero counter | WIDTH |
| `ip_bit_popcnt` | Population count | WIDTH |
| `ip_bit_barrel` | Barrel shifter | WIDTH |
| `ip_bit_reversal` | Bit reversal | WIDTH |
| `ip_bit_xor_tree` | XOR reduction tree | WIDTH |

### Encoder IPs (`enc`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_enc_onehot` | Binary to one-hot | WIDTH |
| `ip_enc_parity` | Parity generator | WIDTH |
| `ip_enc_shift_reg` | Shift register | WIDTH, DEPTH |
| `ip_enc_manchester` | Manchester encoder | - |
| `ip_enc_nrzi` | NRZI encoder | - |
| `ip_enc_pam4` | PAM4 symbol mapper | - |
| `ip_enc_8b10b` | 8b/10b line encoder | - |
| `ip_enc_64b66b` | 64b/66b line encoder | - |
| `ip_enc_128b130b` | 128b/130b PCIe encoder | - |

### Decoder IPs (`dec`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_dec_onehot` | One-hot to binary | WIDTH |
| `ip_dec_manchester` | Manchester decoder | - |
| `ip_dec_nrzi` | NRZI decoder | - |
| `ip_dec_pam4` | PAM4 symbol demapper | - |
| `ip_dec_8b10b` | 8b/10b line decoder | - |
| `ip_dec_64b66b` | 64b/66b line decoder | - |
| `ip_dec_128b130b` | 128b/130b PCIe decoder | - |

### ECC IPs (`ecc`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_ecc_secded` | SEC-DED Hamming code | DATA_WIDTH |
| `ip_ecc_scrambler` | Data scrambler | WIDTH, POLY |
| `ip_ecc_gf_unit` | Galois field arithmetic | M, POLY |
| `ip_ecc_interleaver` | Block interleaver | WIDTH, DEPTH |
| `ip_ecc_conv_encoder` | Convolutional encoder | K, G0, G1 |
| `ip_ecc_viterbi_decoder` | Viterbi decoder | K, TRACEBACK_DEPTH |
| `ip_ecc_bch_encoder` | BCH encoder | N, K, T, M |
| `ip_ecc_bch_decoder` | BCH decoder | N, K, T, M |
| `ip_ecc_rs_encoder` | Reed-Solomon encoder | M, N, K, T |
| `ip_ecc_rs_decoder` | Reed-Solomon decoder | M, N, K, T |
| `ip_ecc_ldpc_encoder` | LDPC encoder | N, K, Z |
| `ip_ecc_ldpc_decoder` | LDPC Min-Sum decoder | N, K, LLR_WIDTH, MAX_ITER |

### Checksum IPs (`chk`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_chk_checksum` | Internet checksum | WIDTH |
| `ip_chk_crc` | CRC generator | DATA_WIDTH, CRC_WIDTH, POLY |

### Comparator IPs (`cmp`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_cmp_array` | Parallel comparator array | WIDTH, NUM_INPUTS |
| `ip_cmp_minmax` | Min/Max finder | WIDTH, NUM_INPUTS |

### Sort IPs (`sort`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_sort_network` | Bitonic sorting network | WIDTH, NUM_INPUTS |

### System IPs (`sys`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_sys_counter` | Parameterized counter | WIDTH |
| `ip_sys_edge_detect` | Edge detector | - |
| `ip_sys_debouncer` | Signal debouncer | DEBOUNCE_CYCLES |
| `ip_sys_watchdog` | Watchdog timer | WIDTH |
| `ip_sys_axi_lite` | AXI-Lite register interface | ADDR_WIDTH, DATA_WIDTH |
| `ip_sys_irq_ctrl` | Interrupt controller | NUM_IRQ |

### PRNG IPs (`prng`)
| Module | Description | Parameters |
|--------|-------------|------------|
| `ip_prng_lfsr` | LFSR random generator | WIDTH, POLY |

## Quick Start

### Compilation

```bash
# Compile all IPs
make compile

# Compile specific category
make compile_buf
make compile_cdc

# Run all tests
make test

# Run specific test
make test_sync_fifo
make test_async_fifo
```

### Usage Example

```systemverilog
`timescale 1ns/1ps

module my_design (
    input  logic        clk,
    input  logic        rst_n,
    input  logic [31:0] data_in,
    output logic [31:0] data_out
);

    // Instantiate synchronous FIFO
    ip_buf_sync_fifo #(
        .DATA_WIDTH(32),
        .DEPTH(16)
    ) u_fifo (
        .clk        (clk),
        .rst_n      (rst_n),
        .wr_en      (wr_en),
        .wr_data    (data_in),
        .full       (full),
        .rd_en      (rd_en),
        .rd_data    (data_out),
        .empty      (empty)
    );

endmodule
```

## Naming Convention

All IPs follow a consistent naming scheme:

- **Module**: `ip_<category>_<name>`
- **File**: `ip_<category>_<name>.sv`
- **Submodule**: `ip_<category>_<name>_<submodule>.sv`
- **Testbench**: `tb_ip_<category>_<name>.sv`

## IP Dependencies

Complex IPs reuse simpler building blocks:

```
Level 0 (Foundation)
├── ip_cdc_sync_2stage, ip_cdc_gray_counter
├── ip_mem_sp_ram, ip_mem_dp_ram
├── ip_enc_onehot, ip_dec_onehot, ip_enc_parity
├── ip_bit_lzc, ip_bit_popcnt, ip_bit_barrel
└── ip_sys_counter, ip_sys_edge_detect

Level 1 (Intermediate)
├── ip_buf_sync_fifo (uses ip_mem_sp_ram)
├── ip_cdc_pulse_sync (uses ip_cdc_sync_2stage)
├── ip_arb_priority, ip_arb_round_robin
└── ip_ecc_secded (uses ip_enc_parity)

Level 2 (Complex)
├── ip_buf_async_fifo (uses ip_cdc_gray_counter, ip_cdc_sync_2stage, ip_mem_dp_ram)
├── ip_cdc_handshake (uses ip_cdc_sync_2stage)
├── ip_clk_mux (uses ip_cdc_sync_2stage, ip_clk_gate)
└── ip_mem_regfile (uses ip_arb_priority)
```

## Test Results

| Test Suite | Tests | Status |
|------------|-------|--------|
| CDC Sync | 11 | ✅ Pass |
| Sync FIFO | 23 | ✅ Pass |
| Async FIFO | 15 | ✅ Pass |
| CDC Handshake | 9 | ✅ Pass |
| Register File | 10 | ✅ Pass |
| SECDED ECC | 15 | ✅ Pass |
| Clock Mux | 8 | ✅ Pass |

## Requirements

- **iverilog** >= 10.3
- **gtkwave** >= 3.3.100 (for waveform viewing)
- **make** >= 3.81

## Integration

This library is designed to be used as a git submodule:

```bash
# Add as submodule
git submodule add https://gitee.com/fpga1988/common_ip common/design/ip

# Update submodule
git submodule update --init --recursive
```

### Include in Your Project

```systemverilog
// Include common package
`include "ip_common_pkg.sv"

// Import package
import ip_common_pkg::*;

// Instantiate IP
ip_buf_sync_fifo #(
    .DATA_WIDTH(32),
    .DEPTH(16)
) u_fifo (
    .clk    (clk),
    .rst_n  (rst_n),
    // ...
);
```

### Makefile Integration

```makefile
# Add to your include paths
IP_INC = common/design/ip/inc
IP_RTL = common/design/ip/rtl

IVERILOG_FLAGS = -g2012 -Wall -I$(IP_INC)

# Include IP sources
IP_SRCS = $(wildcard $(IP_RTL)/*/*.sv) \
          $(wildcard $(IP_RTL)/*/*/*.sv)
```

## Design Guidelines

All IPs follow these design principles:

1. **Synthesizable** - No simulation-only constructs
2. **Parameterized** - Configurable via parameters
3. **Self-contained** - Minimal external dependencies
4. **Well-tested** - Comprehensive testbenches
5. **Documented** - Clear comments and interface descriptions

## Contributing

Contributions are welcome! Please ensure:

1. Code compiles with `iverilog -g2012 -Wall`
2. All comments and identifiers in English
3. Follow existing naming conventions
4. Include testbench for new modules
5. Update README with new IP entries

## License

See [LICENSE](../../../LICENSE) file in the repository root.

## Related Projects

- [RISC-V Heterogeneous Platform](https://gitee.com/cioo/ic1001) - Main project using this IP library
- [CIOO](https://gitee.com/cioo) - China Integrated Circuit Open-source Organization