docs(dn): added xhovani's notebook entry for summer 2025 regarding mi…

src/design_notebooks/2025spring/xxm202.md

@@ -0,0 +1,41 @@
+# Xhovani's VIP Processor Design Notebook - Spring/Summer 2025
+
+## Project Repository
+**Main Repository**: [https://github.com/XhovaniM8/riscv16](https://github.com/XhovaniM8/riscv16)
+
+This repository contains the implementation of a 16-bit RISC-V processor design, including ALU components, testbenches, and build automation using Verilator and CMake.
+
+## Week of [Date] - Project Setup and Initial ALU Implementation
+
+### Project Work:
+* **[Repository Setup](https://github.com/XhovaniM8/riscv16)**: Created initial project structure with organized directories for source files (`src/`), testbenches (`tb/`, `dv/`), and build automation
+* **[ALU Implementation](https://github.com/XhovaniM8/riscv16/tree/main/src)**: Implemented 16-bit Arithmetic Logic Unit in SystemVerilog with support for basic arithmetic and logical operations
+* **[Verilator Integration](https://github.com/XhovaniM8/riscv16/blob/main/CMakeLists.txt)**: Set up CMake-based build system for Verilator simulation and C++ testbench integration
+* **[Testbench Development](https://github.com/XhovaniM8/riscv16/tree/main/dv)**: Created comprehensive C++ testbench for ALU verification with waveform generation
+
+### Weekly Narrative:
+This week focused on establishing the foundational infrastructure for the RISC-V processor project. Multiple significant technical challenges were encountered and resolved during the development process.
+
+**Primary Issue - Verilator Build System on macOS:**
+The most critical problem emerged when using Verilator's `--build` flag, which caused consistent linker failures with the error: `ld: archive member '/' not a mach-o file in 'Vrisc16_top__ALL.a'`. This issue appears to be platform-specific to macOS (Apple Silicon) where Verilator's auto-generated Makefiles include malformed paths in archive file lists, creating invalid archive members that cause the linker to fail.
+
+**Secondary Issues Discovered:**
+- **Missing Generated Files**: Initial attempts at manual compilation failed because expected files like `obj_dir/Vrisc16_top__ALL.cpp` didn't exist, revealing gaps in understanding Verilator's file generation process
+- **Build Process Dependencies**: The standard workflow of generate → compile → link was disrupted by Verilator's internal build dependencies, requiring deeper investigation into the tool's operation
+- **Cross-Platform Compatibility**: What works on Linux development environments doesn't necessarily translate to macOS, highlighting the need for platform-aware build strategies
+
+**Resolution Strategy:**
+The solution involved completely abandoning Verilator's `--build` approach and implementing a manual compilation workflow. This included: (1) generating C++ sources only with Verilator, (2) verifying all expected files exist before compilation, (3) using CMake for explicit build control rather than relying on Verilator's Makefiles, and (4) implementing proper cleanup procedures between build attempts.
+
+**Validation Success:**
+The ALU implementation now successfully compiles and generates verification waveforms, confirming the approach works. However, the more complex RISC16 top-level design still requires build system refactoring to apply these lessons learned.
+
+This debugging process reinforced the importance of understanding toolchain internals and having fallback strategies when automated build systems fail on different platforms.
+
+---
+
+## Resources and References
+* [Verilator Documentation](https://verilator.org/guide/latest/)
+* [SystemVerilog Language Reference](https://ieeexplore.ieee.org/document/8299595)
+* [CMake Documentation](https://cmake.org/documentation/)
+* [RISC-V Specification](https://riscv.org/technical/specifications/)