================================
dv-flow-libfusesoc Documentation
================================

DV Flow extension providing FuseSoC core management and Edalize tool integration.

.. contents:: Table of Contents
   :local:
   :depth: 2

Overview
========

**dv-flow-libfusesoc** is a DV Flow extension that integrates FuseSoC IP core management 
with Edalize tool flows. It provides a unified interface for resolving FuseSoC cores and 
running simulations, synthesis, linting, and formal verification using various EDA tools.

Features
--------

* **FuseSoC Integration**: Resolve and manage FuseSoC IP cores with automatic dependency resolution
* **Edalize Support**: Unified interface to EDA tools via Edalize
* **Simulation Flows**: Run simulations with Icarus Verilog, Verilator, ModelSim, VCS, Xcelium, and GHDL
* **FPGA Flows**: Synthesis and implementation for Vivado, Quartus, and open-source tools
* **Linting**: HDL code quality checks with tool-agnostic interface
* **Formal Verification**: Formal property checking flows

Installation
============

Install from PyPI:

.. code-block:: bash

   pip install dv-flow-libfusesoc

Or install from source:

.. code-block:: bash

   git clone https://github.com/your-org/dv-flow-libfusesoc.git
   cd dv-flow-libfusesoc
   pip install -e .

Quick Start
===========

Basic Simulation Flow
---------------------

.. code-block:: python

   from dv_flow.libfusesoc.fusesoc_core_resolve import CoreResolve
   from dv_flow.libfusesoc.edalize_sim import SimConfigure, SimBuild, SimRun

   # 1. Resolve FuseSoC core
   core_result = await CoreResolve(runner, CoreResolveParams(
       core="vendor:lib:uart:1.0",
       target="sim",
       workspace="/path/to/fusesoc/workspace"
   ))

   # 2. Configure simulation
   config_result = await SimConfigure(runner, SimConfigureParams(
       core_name=core_result.output['core_name'],
       files=core_result.output['files'],
       toplevel="uart_tb",
       tool="icarus",
       parameters={'BAUD_RATE': 115200}
   ))

   # 3. Build simulation
   build_result = await SimBuild(runner, SimBuildParams(
       work_root=config_result.output['work_root'],
       tool="icarus"
   ))

   # 4. Run simulation
   run_result = await SimRun(runner, SimRunParams(
       work_root=build_result.output['work_root'],
       tool="icarus"
   ))

Architecture
============

Pipeline Overview
-----------------

The library provides a complete pipeline from FuseSoC core files to simulation/synthesis results:

.. code-block:: text

   FuseSoC Core File (.core)
       ↓
   ┌───────────────────────┐
   │  CoreResolve Task     │
   │  - Parse VLNV         │
   │  - Resolve deps       │
   │  - Extract files      │
   └───────────┬───────────┘
               ↓
      (files, includes, parameters)
               ↓
   ┌───────────────────────┐
   │  FilesetConverter     │
   │  - Convert formats    │
   │  - Map file types     │
   └───────────┬───────────┘
               ↓
      (converted files)
               ↓
   ┌───────────────────────┐
   │  EdamBuilder          │
   │  - Build EDAM         │
   │  - Add parameters     │
   └───────────┬───────────┘
               ↓
      (EDAM structure)
               ↓
   ┌───────────────────────┐
   │  SimConfigure Task    │
   │  - Setup tool         │
   │  - Create scripts     │
   └───────────┬───────────┘
               ↓
   ┌───────────────────────┐
   │  SimBuild Task        │
   │  - Compile design     │
   │  - Generate model     │
   └───────────┬───────────┘
               ↓
   ┌───────────────────────┐
   │  SimRun Task          │
   │  - Execute sim        │
   │  - Capture results    │
   └───────────────────────┘

Core Components
===============

FuseSoC Integration
-------------------

**fusesoc_manager.py**
   Complete FuseSoC API wrapper providing:
   
   * Core resolution with VLNV parsing
   * Library management with core discovery
   * File list extraction with target/flags support
   * Dependency resolution
   * Full workspace isolation support

**fusesoc_core_resolve.py**
   DV Flow task for resolving FuseSoC cores:
   
   * Pydantic parameter models
   * Output models with file lists
   * Memento support for caching
   * Error handling with markers
   * Async task implementation

**fusesoc_fileset.py**
   Fileset converter:
   
   * FuseSoC → DV Flow format conversion
   * File type mapping (Verilog, SystemVerilog, VHDL, constraints)
   * Include directory extraction
   * Logical name/library handling
   * Separate files_root support

Edalize Integration
-------------------

**edam_builder.py**
   EDAM (Edalize Design Abstraction Model) construction:
   
   * Builder pattern for EDAM structures
   * File list conversion
   * Parameter & plusarg support
   * Tool & flow options
   * Include directory handling
   * Convenience function: ``build_edam_from_core()``

**edalize_backend.py**
   Edalize wrapper:
   
   * Generic wrapper for any Edalize flow
   * Configure/Build/Run lifecycle
   * Error handling and reporting
   * Build artifact checking
   * Tool-specific success verification
   * Convenience functions (``create_sim_backend``, ``create_fpga_backend``)

**edalize_sim.py**
   Simulation tasks:
   
   * ``SimConfigure`` - Configure simulation
   * ``SimBuild`` - Build simulation
   * ``SimRun`` - Execute simulation
   * Task parameter/output models
   * Task chaining support
   * Tool-agnostic API

DV Flow Tasks
=============

fusesoc Package
---------------

CoreResolve
~~~~~~~~~~~

Resolves a FuseSoC core by name/VLNV and extracts file lists, dependencies, and metadata.

**Parameters:**

* ``core`` (str): Core VLNV (vendor:library:name:version)
* ``target`` (str, optional): Target configuration (e.g., 'sim', 'synth')
* ``tool`` (str, optional): Tool name for tool-specific filesets
* ``libraries`` (dict, optional): Additional libraries to add {name: path}
* ``workspace`` (str): FuseSoC workspace directory

**Outputs:**

* ``core_name`` (str): Resolved core name
* ``core_root`` (str): Core root directory
* ``files`` (list): Converted file list
* ``dependencies`` (list): Core dependencies
* ``parameters`` (dict): Core parameters
* ``include_dirs`` (list): Include directories

fusesoc.edalize.sim Package
---------------------------

SimConfigure
~~~~~~~~~~~~

Configures a simulation flow using Edalize. Builds EDAM structure from file lists 
and configures the simulation tool.

**Supported Tools:** Icarus Verilog, Verilator, ModelSim, VCS, Xcelium, GHDL

**Parameters:**

* ``core_name`` (str): Name of the design
* ``files`` (list): File list from core resolution
* ``include_dirs`` (list): Include directories
* ``toplevel`` (str): Toplevel module name
* ``tool`` (str): Simulation tool (icarus, verilator, etc.)
* ``parameters`` (dict, optional): Build-time parameters
* ``plusargs`` (list, optional): Runtime plusargs
* ``tool_options`` (dict, optional): Tool-specific options

**Outputs:**

* ``work_root`` (str): Edalize work directory
* ``tool`` (str): Configured simulation tool
* ``configured`` (bool): Configuration success

SimBuild
~~~~~~~~

Builds the simulation model. Handles compilation, elaboration, and generates simulation executable.

**Parameters:**

* ``work_root`` (str): Edalize work directory
* ``tool`` (str): Simulation tool

**Outputs:**

* ``work_root`` (str): Edalize work directory
* ``build_success`` (bool): Build success status
* ``executable`` (str): Path to simulation executable

SimRun
~~~~~~

Runs the simulation with specified parameters. Captures simulation output and determines 
pass/fail status.

**Parameters:**

* ``work_root`` (str): Edalize work directory
* ``tool`` (str): Simulation tool
* ``runtime_plusargs`` (list, optional): Additional runtime plusargs

**Outputs:**

* ``work_root`` (str): Edalize work directory
* ``run_success`` (bool): Simulation success status
* ``log_file`` (str): Path to simulation log

Supported Tools
===============

Simulators
----------

Via Edalize integration:

* ✅ **Icarus Verilog** - Open-source Verilog simulator
* ✅ **Verilator** - High-performance Verilog/SystemVerilog simulator
* 🔄 **ModelSim/Questa** - Commercial simulator (API ready)
* 🔄 **VCS** - Synopsys Verilog Compiler Simulator (API ready)
* 🔄 **Xcelium** - Cadence advanced simulator (API ready)
* 🔄 **GHDL** - Open-source VHDL simulator (API ready)

FPGA Tools
----------

Via Edalize integration:

* 🔄 **Vivado** - Xilinx FPGA toolchain (API ready)
* 🔄 **Quartus** - Intel FPGA toolchain (API ready)
* 🔄 **Open-source flows** - Yosys, nextpnr, etc. (API ready)

Testing
=======

The project includes comprehensive test coverage:

* **Total Tests**: 38
* **Passing**: 36 ✅ (94.7%)
* **Skipped**: 2 (tool-dependent - Icarus/Verilator)
* **Failing**: 0 ❌

Test Categories
---------------

* Extension registration and discovery (2 tests)
* Isolated test infrastructure (4 tests)
* FuseSoC core resolution (4 tests)
* File format conversion (6 tests)
* EDAM building (11 tests)
* Edalize backend (3 tests)
* FuseSoC tasks (3 tests)
* Edalize tasks (5 tests)

Running Tests
-------------

.. code-block:: bash

   # Run all tests
   pytest

   # Run with coverage
   pytest --cov=dv_flow.libfusesoc

   # Run specific test category
   pytest tests/unit/test_fusesoc_manager.py

Development
===========

Project Structure
-----------------

.. code-block:: text

   src/dv_flow/libfusesoc/
     __ext__.py                    - Extension registration
     flow.dv                       - Main package tasks
     sim_flow.dv                   - Simulation flow tasks
     fpga_flow.dv                  - FPGA flow (stub)
     lint_flow.dv                  - Lint flow (stub)
     fusesoc_manager.py            - FuseSoC API wrapper
     fusesoc_fileset.py            - File format converter
     fusesoc_core_resolve.py       - CoreResolve task
     edam_builder.py               - EDAM builder
     edalize_backend.py            - Edalize wrapper
     edalize_sim.py                - Simulation tasks

   tests/
     conftest.py                   - Test fixtures
     fixtures/test_cores/          - Test .core files
     unit/                         - Unit tests
     integration/                  - Integration tests

Contributing
------------

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run the test suite
5. Submit a pull request

All contributions must:

* Include tests for new functionality
* Maintain or improve test coverage
* Follow existing code style
* Update documentation as needed

License
=======

Apache License 2.0 - See LICENSE file for details.

Documentation Contents
======================

User Guide
==========

.. toctree::
   :maxdepth: 2
   :caption: User Guide:

   getting_started
   usage_examples
   tasks
   quick_reference

API Reference
=============

.. toctree::
   :maxdepth: 2
   :caption: API Documentation:

   fusesoc_integration
   edalize_integration
   modules

Additional Information
======================

.. toctree::
   :maxdepth: 1
   :caption: Additional:

   changelog

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`