Development Guide

Debugging FINN+

To enable debug mode for the FINN+ command line interface:

FINN_DEBUG=1 finn <your-command>

When building custom steps and transformations:

• Use the debug environment variable for basic output
• For more detailed logging, enable the verbose flag in the DataflowBuildConfig

FINN+ Execution Flow

When you run the finn command, the system performs several initialization steps:

1. Entry point: src/finn/interface/run_finn.py initializes the execution
2. Configuration: System reads settings.yaml files (local and global)
3. Dependencies resolution:
   • Poetry dependencies (from pyproject.toml)
   • External dependencies (configured in src/finn/interface/manage_deps.py)
4. Environment setup:
   • FINN_DEPS: Points to dependency location
   • FINN_BUILD_DIR: Specifies where generated files are stored

After initialization, the system:

1. Creates a DataflowBuildConfig object
2. Starts the build flow

Warning

During testing, finn is not called directly. See the VS Code Integration section for testing-specific setup.

VS Code Integration

Environment Setup

Create an .env file with the following variables:

FINN_ROOT             # Your repository path
FINN_BUILD_DIR        # Temporary files location (e.g., /tmp/FINN_TEST_BUILD_DIR)
FINN_DEPS             # Dependency location
NUM_DEFAULT_WORKERS   # Number of parallel transformation workers
VIVADO_PATH           # Path to Vivado (e.g., .../Vivado/2023.1)
VITIS_PATH            # Path to Vitis
HLS_PATH              # Path to Vitis HLS

Tip

See the Settings wiki page for detailed information about these variables.

Important

Run finn deps update at least once manually before testing, as the test setup doesn't automatically fetch dependencies.

Important

FINN_BUILD_DIR determines where test-generated files are placed. Consider the resolution order.

Debugging Configuration

Configure VS Code's debugger by adding this to .vscode/launch.json:

{
    "name": "Python Debugger: Run FINN",
    "type": "debugpy",
    "request": "launch",
    "program": "${workspaceFolder}/src/finn/interface/run_finn.py",
    "console": "integratedTerminal",
    "args": "${command:pickArgs}",
    "subProcess": true
}

Testing Configuration

Configure VS Code to use pytest by adding this to .vscode/settings.json:

"python.testing.pytestArgs": [
    "tests",
    "src/finn/transformation/fpgadataflow",
    "-n",
    "10",
    "--doctest-modules"
],
"python.testing.unittestEnabled": false,
"python.testing.pytestEnabled": true,

Important

Settings in .vscode/settings.json override your pyproject.toml testing settings. Update both when changing test configurations.

Test Environment Variables

Control test execution with these environment variables:

• FINN_TESTS_ISOLATE_BUILD_DIRS (default: 1)

  • When set to 1, creates a separate directory for each test
  • Example: /tmp/FINN_TESTS/test_operator_a, /tmp/FINN_TESTS/test_operator_b, etc.
  • During the test, FINN_BUILD_DIR points to the test-specific directory

• FINN_TESTS_CLEANUP_BUILD_DIRS (default: 0)

  • When set to 1, removes the test build directory after execution
  • Requires FINN_TESTS_ISOLATE_BUILD_DIRS=1
  • Set to 0 by default to allow post-test debugging