Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
147 lines (110 loc) · 3.64 KB

CONTRIBUTING.md

File metadata and controls

147 lines (110 loc) · 3.64 KB

Contributing to RISC-V Multi-Precision Processor

Thank you for your interest in contributing! This project welcomes contributions from students, educators, and engineers.

🚀 Quick Start

  1. Fork the repository
  2. Clone your fork locally
  3. Create a branch for your feature
  4. Make changes following the coding standards below
  5. Test your changes in simulation
  6. Commit with clear messages
  7. Push and create a Pull Request

📋 Areas for Contribution

High Priority

  • M Extension: Multiply/Divide instructions
  • C Extension: Compressed instructions (16-bit)
  • Branch Prediction: Improve pipeline CPI
  • Cache Implementation: Instruction and Data caches

Documentation

  • Tutorial improvements
  • Video walkthroughs
  • Example programs

Testing

  • Additional testbenches
  • Formal verification properties
  • Compliance tests (riscv-tests)

📐 Coding Standards

SystemVerilog Style Guide

Naming Conventions

Element Convention Example
Modules PascalCase or snake_case Control_Unit, hazard_unit
Signals snake_case alu_result, pc_plus4
Parameters UPPER_CASE DATA_WIDTH, MEM_SIZE
Constants UPPER_CASE OP_RTYPE, ALU_ADD

File Structure

// ============================================================================
// MODULE: Module Name
// Description: Brief description of purpose
// ============================================================================

module Module_Name #(
    parameter WIDTH = 32
) (
    input  logic             clk,
    input  logic             reset,
    input  logic [WIDTH-1:0] input_signal,
    output logic [WIDTH-1:0] output_signal
);

    // ========================================
    // Internal Signals
    // ========================================
    logic [WIDTH-1:0] internal_reg;

    // ========================================
    // Main Logic
    // ========================================
    always_ff @(posedge clk or posedge reset) begin
        if (reset)
            internal_reg <= '0;
        else
            internal_reg <= input_signal;
    end

    assign output_signal = internal_reg;

endmodule

Best Practices

  • Use logic instead of wire/reg
  • Use always_ff for sequential logic
  • Use always_comb for combinational logic
  • Avoid latches (complete case/if statements)
  • Add assertions where appropriate
  • Comment non-obvious logic

Git Commit Messages

feat: Add branch prediction unit
fix: Correct forwarding logic for load-use hazard
docs: Update pipeline walkthrough
test: Add testbench for M extension
refactor: Simplify control unit decode logic

🧪 Testing Requirements

Before submitting a PR:

  1. Syntax Check: Ensure no compilation errors

    iverilog -g2012 -o test *.sv

  2. Simulation: Run existing testbenches

    vvp test

  3. Lint Check (if available):

    verilator --lint-only -Wall *.sv

🐛 Reporting Issues

When opening an issue, include:

  • Title: Clear, descriptive summary
  • Environment: OS, tool version (e.g., Vivado 2023.1)
  • Description: What happened vs. what you expected
  • Steps to Reproduce: Minimal example if possible
  • Screenshots: Waveforms or error messages

📜 License

By contributing, you agree that your contributions will be licensed under the project's MIT License.

🙏 Acknowledgments

Contributors will be acknowledged in the repository. Thank you for helping improve this educational resource!