{"id":29640609,"url":"https://github.com/wipeseals/nekov","last_synced_at":"2025-07-21T21:04:02.044Z","repository":{"id":304364052,"uuid":"1017753022","full_name":"wipeseals/nekov","owner":"wipeseals","description":"A RISC-V emulator (rv32ima) written in Rust.🐈","archived":false,"fork":false,"pushed_at":"2025-07-12T15:04:03.000Z","size":158,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-12T17:29:38.640Z","etag":null,"topics":["riscv","riscv-emulator","rust","vibecoding"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wipeseals.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-11T03:44:35.000Z","updated_at":"2025-07-12T15:45:35.000Z","dependencies_parsed_at":"2025-07-12T17:39:49.383Z","dependency_job_id":null,"html_url":"https://github.com/wipeseals/nekov","commit_stats":null,"previous_names":["wipeseals/nekov"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/wipeseals/nekov","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wipeseals%2Fnekov","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wipeseals%2Fnekov/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wipeseals%2Fnekov/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wipeseals%2Fnekov/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wipeseals","download_url":"https://codeload.github.com/wipeseals/nekov/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wipeseals%2Fnekov/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266379212,"owners_count":23920157,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-21T11:47:31.412Z","response_time":64,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["riscv","riscv-emulator","rust","vibecoding"],"created_at":"2025-07-21T21:02:13.213Z","updated_at":"2025-07-21T21:04:02.028Z","avatar_url":"https://github.com/wipeseals.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nekov\n\n[![CI](https://github.com/wipeseals/nekov/workflows/CI/badge.svg)](https://github.com/wipeseals/nekov/actions)\n\nA RISC-V emulator in Rust, probably written by a cat. 🐈\n\n## Features\n\n- **RV32IMA Instruction Set Support**: Complete implementation of RISC-V base integer (RV32I), multiplication (RV32M), and atomic (RV32A) instruction sets\n- **40+ Instructions Implemented**: All major RISC-V instruction types including arithmetic, logical, memory, branch, jump, and atomic operations\n- **ELF Binary Loading**: Parses and loads ELF binaries into emulator memory\n- **Memory Management**: HashMap-based memory with bounds checking and little-endian support\n- **Register File**: 32 general-purpose registers (x0-x31) with x0 hardwired to zero\n- **Instruction Execution**: Fetch-decode-execute cycle with instruction limits for safety\n- **RISC-V Tests Integration**: Support for running official RISC-V test suite\n- **WebAssembly Support**: Full WASM compilation for browser execution\n- **Peripheral System**: Memory-mapped peripheral support with console output\n- **Web Demo**: Interactive Conway's Game of Life running in the browser\n\n## Building\n\n```bash\ncargo build --release\n```\n\n## Web Demo\n\nTry the emulator in your browser! The web demo features Conway's Game of Life running on the RISC-V emulator compiled to WebAssembly.\n\n🌐 **[Live Demo](https://wipeseals.github.io/nekov)** (GitHub Pages)\n\n### Running Locally\n\n```bash\n# Quick start - builds and serves the demo\n./demo/serve.sh\n\n# Manual build\nwasm-pack build --target web --out-dir demo/web/pkg\ncd demo/web \u0026\u0026 python3 -m http.server 8000\n```\n\nThe web demo includes:\n- Interactive RISC-V emulator controls\n- Conway's Game of Life demonstration  \n- Real-time CPU state monitoring\n- Console output from memory-mapped UART\n- Support for uploading custom RISC-V binaries\n\n## Running\n\n```bash\n# Run an ELF binary through the emulator\n./target/release/nekov path/to/program.elf\n```\n\n### Example Usage\n\n```bash\n./target/debug/nekov ./riscv-tests-binaries/share/riscv-tests/isa/rv32ui-p-addi -vvv --riscv-tests\nNekov RISC-V Emulator\nLoading ELF binary: ./riscv-tests-binaries/share/riscv-tests/isa/rv32ui-p-addi\nRISC-V tests mode enabled\nVerbose output level: 3\nLoaded segment at 0x80000000 (size: 1148 bytes)\nLoaded segment at 0x80001000 (size: 72 bytes)\nEntry point: 0x80000000\nStarting emulation...\n=== Starting CPU execution (verbose level 3) ===\n\nCycle 1: PC=0x80000000\n  Instruction: 0x0500006f\n  Before: x1=0x00000000 x2=0x00000000 x3=0x00000000 x10=0x00000000\n  Fetched instruction: 0x0500006f\n  Opcode: 0x6f\n  JAL instruction\n  After:  x1=0x00000000 x2=0x00000000 x3=0x00000000 x10=0x00000000\n\n(snipped)\n\nCycle 277: PC=0x80000440\n  Instruction: 0x00000073\n  Before: x1=0x00000021 x2=0x00000000 x3=0x00000001 x10=0x00000000\n  Fetched instruction: 0x00000073\n  Opcode: 0x73\n  System instruction\nECALL termination at PC: 0x80000440\n=== CPU execution completed ===\nTotal instructions executed: 277\nEmulation completed. Executed 277 instructions.\n\n=== Final CPU State ===\nFinal PC: 0x80000440\nRegisters:\nx0: 0x00000000  x8: 0x00000000  x16: 0x00000000  x24: 0x00000000\nx1: 0x00000021  x9: 0x00000000  x17: 0x0000005d  x25: 0x00000000\nx2: 0x00000000  x10: 0x00000000  x18: 0x00000000  x26: 0x00000000\nx3: 0x00000001  x11: 0x00000018  x19: 0x00000000  x27: 0x00000000\nx4: 0x00000002  x12: 0x00000000  x20: 0x00000000  x28: 0x00000000\nx5: 0x00000002  x13: 0x7fffffff  x21: 0x00000000  x29: 0x00000000\nx6: 0x00000016  x14: 0x00000016  x22: 0x00000000  x30: 0x00000000\nx7: 0x00000000  x15: 0x00000000  x23: 0x00000000  x31: 0x00000000\n=== RISC-V Test Result Analysis ===\nRegister state at termination:\n  gp (x3)  = 0x00000001 (TESTNUM)\n  a0 (x10) = 0x00000000 (exit code)\n  a7 (x17) = 0x0000005d (syscall number)\n\nTest result determination:\n  ✓ System call number is 93 (exit syscall)\n  ✓ TESTNUM=1 and exit code=0 → PASS\nRISC-V test PASSED\n```\n\n## Testing\n\n```bash\n# Run unit tests\ncargo test\n\n# Run integration tests with sample programs\n./scripts/test.sh\n\n# Run instruction verification test\ncargo run --bin instruction_test\n```\n\n## Current Implementation Status\n\n- ✅ **Basic Infrastructure**: CPU, memory, and register management\n- ✅ **ELF Loading**: Parse ELF binaries and load them into memory\n- ✅ **Instruction Decoding**: All RISC-V instruction formats (R, I, S, B, U, J)\n- ✅ **RV32I Implementation**: Complete base integer instruction set (40+ instructions)\n- ✅ **RV32M Implementation**: Multiplication and division extension (8 instructions)\n- ✅ **RV32A Implementation**: Atomic instruction extension (11 instructions)\n- ✅ **Test Suite**: Comprehensive unit tests for all instruction categories (27 tests)\n- ✅ **CI/CD**: GitHub Actions for testing, linting, and formatting\n- ✅ **WebAssembly**: Browser execution with full emulator functionality\n- ✅ **Peripherals**: Memory-mapped device support with console output\n- ✅ **Web Demo**: Conway's Game of Life running in the browser\n\n### Supported Instructions\n\n#### RV32I Base Integer Instructions\n\n| Category              | Instructions                       | Status |\n| --------------------- | ---------------------------------- | ------ |\n| **I-type Arithmetic** | ADDI, SLTI, SLTIU, ANDI, ORI, XORI | ✅     |\n| **I-type Shifts**     | SLLI, SRLI, SRAI                   | ✅     |\n| **R-type Arithmetic** | ADD, SUB, SLT, SLTU                | ✅     |\n| **R-type Logical**    | AND, OR, XOR                       | ✅     |\n| **R-type Shifts**     | SLL, SRL, SRA                      | ✅     |\n| **Load**              | LB, LH, LW, LBU, LHU               | ✅     |\n| **Store**             | SB, SH, SW                         | ✅     |\n| **Branch**            | BEQ, BNE, BLT, BGE, BLTU, BGEU     | ✅     |\n| **Jump**              | JAL, JALR                          | ✅     |\n| **Upper Immediate**   | LUI, AUIPC                         | ✅     |\n| **System**            | ECALL, EBREAK                      | ✅     |\n\n#### RV32M Multiplication Extension\n\n| Category           | Instructions             | Status |\n| ------------------ | ------------------------ | ------ |\n| **Multiplication** | MUL, MULH, MULHSU, MULHU | ✅     |\n| **Division**       | DIV, DIVU, REM, REMU     | ✅     |\n\n#### RV32A Atomic Extension\n\n| Category                | Instructions                             | Status |\n| ----------------------- | ---------------------------------------- | ------ |\n| **Load/Store Reserved** | LR.W, SC.W                               | ✅     |\n| **Atomic Memory Ops**   | AMOSWAP.W, AMOADD.W, AMOXOR.W            | ✅     |\n| **Atomic Logical**      | AMOAND.W, AMOOR.W                        | ✅     |\n| **Atomic Min/Max**      | AMOMIN.W, AMOMAX.W, AMOMINU.W, AMOMAXU.W | ✅     |\n\n**Total: 50+ instructions implemented covering RV32IMA**\n\n### Peripheral System\n\nThe emulator includes a flexible peripheral system for hardware simulation:\n\n| Peripheral | Base Address | Description |\n|------------|--------------|-------------|\n| **Console UART** | 0x10000000 | Character output to console/browser |\n\n#### Memory Map\n- **Program Memory**: 0x80000000+ (loaded binaries)\n- **Console UART**: 0x10000000-0x10000FFF (4KB range)\n- **General Memory**: Other addresses as needed\n\n#### UART Interface\n```c\n#define UART_BASE 0x10000000\n#define UART_TX   (*(volatile uint32_t*)(UART_BASE + 0))\n\nvoid putchar(char c) {\n    UART_TX = (uint32_t)c;  // Write character to console\n}\n```\n\n### Test Results\n\nThe emulator passes all 27 unit tests including:\n\n- **I-type instructions**: ADDI, SLTI, SLTIU, XORI, ORI, ANDI, SLLI, SRLI, SRAI\n- **R-type instructions**: ADD, SUB, SLL, SLT, SLTU, XOR, SRL, SRA, OR, AND\n- **M-type instructions**: MUL, MULH, DIV, DIVU, REM, REMU with proper overflow handling\n- **Load/Store operations**: All memory access patterns with proper alignment\n- **Branch instructions**: Conditional branching with correct offset calculation\n- **Jump instructions**: JAL and JALR with return address handling\n- **Upper immediate**: LUI and AUIPC with proper immediate placement\n- **Atomic operations**: Complete RV32A instruction set with memory synchronization\n- **Edge cases**: Division by zero, arithmetic overflow, memory bounds checking\n\n## Development\n\nThis project follows a TDD (Test-Driven Development) approach with:\n\n- Unit tests for all components\n- Integration tests using real instruction sequences\n- CI pipeline ensuring code quality\n\n## Architecture\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│   ELF Loader    │───▶│      CPU        │───▶│     Memory      │\n│                 │    │                 │    │                 │\n│ • Parse ELF     │    │ • 32 Registers  │    │ • HashMap-based │\n│ • Load segments │    │ • RV32IMA ISA   │    │ • Bounds Check  │\n│ • Entry point   │    │ • Fetch/Decode  │    │ • Little-endian │\n│                 │    │ • Execute 50+   │    │ • Atomic Ops    │\n│                 │    │   Instructions  │    │                 │\n└─────────────────┘    └─────────────────┘    └─────────────────┘\n```\n\n**Instruction Pipeline:**\n\n1. **Fetch**: Read 32-bit instruction from memory at PC\n2. **Decode**: Parse instruction format (R/I/S/B/U/J) and extract fields\n3. **Execute**: Perform operation based on instruction type:\n   - **Arithmetic**: ALU operations with proper overflow handling\n   - **Memory**: Load/store with alignment checks and endianness\n   - **Control**: Branches and jumps with target calculation\n   - **Atomic**: Memory synchronization with acquire/release semantics\n\n## Contributing\n\n### Pull Request Requirements\n\nBefore submitting a PR, ensure the following requirements are met:\n\n1. **Linting**: Code must pass all linting checks\n\n   ```bash\n   cargo clippy -- -D warnings\n   ```\n\n2. **Formatting**: Code must be properly formatted\n\n   ```bash\n   cargo fmt --check\n   ```\n\n3. **Build**: Code must build successfully\n\n   ```bash\n   cargo build\n   ```\n\n4. **CI**: All CI checks must pass (except for known failing tests that are documented)\n\nThese are mandatory requirements that will be checked before any PR review.\n\n### Development Process\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass: `cargo test \u0026\u0026 ./scripts/test.sh`\n5. Run lint, format, and build checks (see requirements above)\n6. Submit a pull request\n\n## License\n\nMIT License (see LICENSE file)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwipeseals%2Fnekov","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwipeseals%2Fnekov","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwipeseals%2Fnekov/lists"}