Arm backend: Add optional Model Converter debug-info generation. (pytorch#23313)

Add optional Model Converter debug-info generation to the VGF backend.

When `emit_debug_info=True` is set in `VgfCompileSpec`, the backend
passes:

```text
--emit-debug-info
```

to Model Converter.

This preserves TOSA debug symbols in the generated VGF and enables
future correlation between ExecuTorch `debug_handle`s and VGF operations
for profiling.

- Add `emit_debug_info` to `VgfCompileSpec`.
- Propagate the option through compile-spec serialization.
- Pass `--emit-debug-info` to Model Converter when enabled.
- Avoid duplicating the flag if it is already present.
- Add unit tests for enabled, disabled, and round-trip compile-spec
behaviour.

The option is disabled by default, so existing VGF compilation behaviour
is unchanged.

cc @digantdesai @freddan80 @per @zingo @oscarandersson8218 @mansnils
@Sebastian-Larsson @robell @rascani

Signed-off-by: Elena Zhelezina <elena.zhelezina@arm.com>

Author: wwwind

backends/arm/public_api_manifests/api_manifest_running.toml

@@ -138,7 +138,7 @@ signature = "VgfBackend.preprocess(edge_program: torch.export.exported_program.E
 
 [python.VgfCompileSpec]
 kind = "class"
-signature = "VgfCompileSpec(tosa_spec: executorch.backends.arm.tosa.specification.TosaSpecification | str | None = None, compiler_flags: list[str] | None = None)"
+signature = "VgfCompileSpec(tosa_spec: executorch.backends.arm.tosa.specification.TosaSpecification | str | None = None, compiler_flags: list[str] | None = None, emit_debug_info: bool = False)"
 
 [python.VgfCompileSpec.DebugMode]
 kind = "enum"

backends/arm/test/misc/test_compile_spec.py

@@ -127,6 +127,16 @@ def test_preserve_tosa_dev_mode_roundtrip_vgf_FP_INT():
     assert roundtripped.tosa_dev_mode is True
 
 
+def test_emit_debug_info_roundtrip_vgf_FP_INT():
+    disabled = VgfCompileSpec()
+    disabled_roundtripped = VgfCompileSpec._from_list(disabled._to_list())
+    assert disabled_roundtripped.emit_debug_info is False
+
+    enabled = VgfCompileSpec(emit_debug_info=True)
+    enabled_roundtripped = VgfCompileSpec._from_list(enabled._to_list())
+    assert enabled_roundtripped.emit_debug_info is True
+
+
 def test_preserve_io_quantization_warns_for_u55_INT():
     with warns(
         UserWarning,

backends/arm/test/misc/test_vgf_backend.py

@@ -117,6 +117,66 @@ def _raise(*args, **kwargs):
         clear_registered_pass_insertions()
 
 
+def test_compile_tosa_flatbuffer_does_not_emit_debug_info_by_default(
+    monkeypatch,
+) -> None:
+    captured_flags = None
+
+    def fake_vgf_compile(tosa_flatbuffer, compile_flags, artifact_path, tag_name):
+        nonlocal captured_flags
+        captured_flags = list(compile_flags)
+        return b"vgf"
+
+    monkeypatch.setattr(vgf_backend, "vgf_compile", fake_vgf_compile)
+
+    result = vgf_backend.VgfBackend._compile_tosa_flatbuffer(
+        b"tosa", VgfCompileSpec(compiler_flags=["--existing-flag"])
+    )
+
+    assert result == b"vgf"
+    assert captured_flags == ["--existing-flag"]
+
+
+def test_compile_tosa_flatbuffer_emits_debug_info_when_enabled(monkeypatch) -> None:
+    captured_flags = None
+
+    def fake_vgf_compile(tosa_flatbuffer, compile_flags, artifact_path, tag_name):
+        nonlocal captured_flags
+        captured_flags = list(compile_flags)
+        return b"vgf"
+
+    monkeypatch.setattr(vgf_backend, "vgf_compile", fake_vgf_compile)
+
+    result = vgf_backend.VgfBackend._compile_tosa_flatbuffer(
+        b"tosa",
+        VgfCompileSpec(compiler_flags=["--existing-flag"], emit_debug_info=True),
+    )
+
+    assert result == b"vgf"
+    assert captured_flags == ["--existing-flag", "--emit-debug-info"]
+
+
+def test_compile_tosa_flatbuffer_does_not_duplicate_emit_debug_info(
+    monkeypatch,
+) -> None:
+    captured_flags = None
+
+    def fake_vgf_compile(tosa_flatbuffer, compile_flags, artifact_path, tag_name):
+        nonlocal captured_flags
+        captured_flags = list(compile_flags)
+        return b"vgf"
+
+    monkeypatch.setattr(vgf_backend, "vgf_compile", fake_vgf_compile)
+
+    result = vgf_backend.VgfBackend._compile_tosa_flatbuffer(
+        b"tosa",
+        VgfCompileSpec(compiler_flags=["--emit-debug-info"], emit_debug_info=True),
+    )
+
+    assert result == b"vgf"
+    assert captured_flags == ["--emit-debug-info"]
+
+
 def test_format_repro_command_quotes_shell_metacharacters():
     command = [
         "model-converter",

backends/arm/vgf/backend.py

@@ -209,7 +209,9 @@ def _compile_tosa_flatbuffer(
             bytes: Target-specific VGF binary stream.
 
         """
-        compile_flags = compile_spec.compiler_flags
+        compile_flags = list(compile_spec.compiler_flags)
+        if compile_spec.emit_debug_info and "--emit-debug-info" not in compile_flags:
+            compile_flags.append("--emit-debug-info")
         artifact_path = compile_spec._get_intermediate_path()
         # Pass on the TOSA flatbuffer to the vgf compiler.
         binary = vgf_compile(tosa_flatbuffer, compile_flags, artifact_path, tag_name)

backends/arm/vgf/compile_spec.py

@@ -8,6 +8,7 @@
 
 from executorch.backends.arm.common.arm_compile_spec import ArmCompileSpec
 from executorch.backends.arm.tosa import TosaSpecification
+from executorch.exir.backend.compile_spec_schema import CompileSpec
 
 if TYPE_CHECKING:
     from executorch.backends.arm.vgf.check_env import VgfEnvironmentReport
@@ -24,13 +25,18 @@ class VgfCompileSpec(ArmCompileSpec):
             target. Strings are parsed via ``TosaSpecification.create_from_string``.
             Defaults to ``"TOSA-1.0+FP+INT+int4+int16"``.
         compiler_flags (list[str] | None): Optional converter-backend flags.
+        emit_debug_info (bool): Preserve Model Converter debug information in
+            the generated VGF. Defaults to ``False``.
 
     """
 
+    _EMIT_DEBUG_INFO_KEY = "vgf_emit_debug_info"
+
     def __init__(
         self,
         tosa_spec: TosaSpecification | str | None = None,
         compiler_flags: list[str] | None = None,
+        emit_debug_info: bool = False,
     ):
         if tosa_spec is None:
             tosa_spec = TosaSpecification.create_from_string(
@@ -42,12 +48,32 @@ def __init__(
         if compiler_flags is None:
             compiler_flags = []
         self._set_compile_specs(tosa_spec, compiler_flags)
+        self.emit_debug_info = emit_debug_info
         # intermediate handling needed until release 2027.02 of tosa-tools
         self._set_tosa_dev_mode(True)
         self._validate()
 
+    def _to_list(self):
+        """Return compile specs including the VGF debug-info setting."""
+        compile_specs = super()._to_list()
+        if self.emit_debug_info:
+            compile_specs.append(CompileSpec(self._EMIT_DEBUG_INFO_KEY, b"True"))
+        return compile_specs
+
+    @classmethod
+    def _from_list_hook(cls, compile_spec, specs: dict[str, str]):
+        """Restore VGF-specific settings from serialized compile specs."""
+        emit_debug_info = specs.get(cls._EMIT_DEBUG_INFO_KEY)
+        compile_spec.emit_debug_info = (
+            str(emit_debug_info).lower() in ("1", "true", "yes")
+            if emit_debug_info is not None
+            else False
+        )
+
     def _validate(self):
         """Validate the configuration against VGF-supported TOSA profiles."""
+        if type(self.emit_debug_info) is not bool:
+            raise ValueError("emit_debug_info must be a bool.")
         tosa_version = self.tosa_spec.version  # type: ignore[attr-defined]
         tosa_profiles = self.tosa_spec.profiles  # type: ignore[attr-defined]
 

docs/source/backends/arm-vgf/arm-vgf-overview.md

@@ -41,7 +41,7 @@ To extract the VGF file for integration into applications without the ExecuTorch
 The full user-facing API is documented below.
 
 ```python
-class VgfCompileSpec(tosa_spec: executorch.backends.arm.tosa.specification.TosaSpecification | str | None = None, compiler_flags: list[str] | None = None)
+class VgfCompileSpec(tosa_spec: executorch.backends.arm.tosa.specification.TosaSpecification | str | None = None, compiler_flags: list[str] | None = None, emit_debug_info: bool = False)
 ```
 Normalise inputs and populate the underlying Arm compile spec.
 
@@ -50,6 +50,8 @@ Args:
         target. Strings are parsed via ``TosaSpecification.create_from_string``.
         Defaults to ``"TOSA-1.0+FP+INT+int4+int16"``.
 - **compiler_flags (list[str] | None)**: Optional converter-backend flags.
+- **emit_debug_info (bool)**: Preserve Model Converter debug information in
+        the generated VGF. Defaults to ``False``.
 
 ```python
 def VgfCompileSpec.dump_debug_info(self, debug_mode: executorch.backends.arm.common.arm_compile_spec.ArmCompileSpec.DebugMode | None):