[SFangYy]

Description

Improve VCS integration for Python test workflows, native coverage reporting, and Verdi waveform viewing.

Previously, VCS finalization could terminate the host Python process before test teardown and report generation completed. Generated DUT packages also lacked the backend metadata and standalone coverage interface needed by reporting tools.

This PR:

• Exposes SIMULATOR and GetSimulator() in generated Python DUT wrappers.
• Finalizes VCS simulation and coverage in a child process, allowing the host Python process to continue.
• Adds a standalone UCAPI coverage helper with schema-versioned JSON output.
• Exposes the actual coverage database path through GetCoveragePath() and selects per-test coverage data through SetCoverage().
• Serializes coverage finalization and snapshot queries using a database lock.
• Enables -kdb by default for source-based VCS exports so their debug databases can be opened in Verdi.
• Declares the FSDB configuration guard before use while preserving the original generated waveform/control block order.
• Documents the behavior and adds metadata and native-runtime regression tests.

Dependencies:

• VCS and its UCAPI headers/library for coverage-enabled VCS builds.
• Verdi for FSDB viewing.
• No additional Python dependencies.

Existing exported DUT packages must be regenerated and rebuilt to receive these changes. Imported precompiled libraries still require a matching debug database.

Open follow-up: dynamically enabling waveform dumping in an export without a default waveform path timed out during an additional runtime probe. Both export configurations compiled successfully; runtime validation with a default waveform path passed.

Related issue: N/A.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

How Has This Been Tested?

• Rebuilt Picker successfully.
• Ran generated Python metadata checks for VCS and Verilator.
• Compiled VCS Adder exports with and without a default waveform path.
• Verified runtime waveform selection with a default waveform path: the selected FSDB was generated, the default file was not created, and the Adder produced the expected result.
• Verified generated Verilator code contains no VCS-specific FSDB guard.
• Checked patch whitespace with git diff --check.
• Full integration suite.
• Dynamic waveform activation without a default waveform path; the runtime probe timed out.

Build and metadata checks:

cmake --build build --target picker -j 2
python3 test/scripts/test_python_simulator_metadata.py
git diff --check

The native coverage regression can be reproduced in a configured VCS environment using a freshly generated, coverage-enabled Adder package:

PICKER_VCS_DUT_DIR=/absolute/path/to/Adder \
  python3 test/scripts/test_vcs_coverage_runtime.py

This regression checks package relocation, continued execution after Finish(), FSDB generation, and two independently queried coverage snapshots.

Test Configuration:

- Firmware version: N/A
- Hardware: Linux x86_64 host
- Toolchain: CMake, GNU C++ 12.3.0, Python 3.12.2
- SDK: VCS W-2024.09-SP1 with UCAPI; Verdi W-2024.09-SP1

# Checklist:

- [x] My code follows the style guidelines of this project
- [ ] I have added the appropriate labels
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published in downstream modules