Skip to content

Compile Diagnostics

This example deliberately triggers three real compiler failures and catches legato.CompileError. It prints source reports and verifies their structured codes and locations. It uses CPU tensors only, compiles toward ASM with launch=False, and does not initialize a device or simulator.

Kernel Failure demonstrated
invalid_sram_type LE0301: explicitly unaligned BF16 physical width. The report distinguishes 64 elements from 128 bytes.
nonlast_maximum LE0121 with recorded reason LE2119: a valid Core reduction whose axis the EVT0 standalone implementation rejects.
short_receive LE2102: a 1280-byte receive that cannot cover whole 512-byte DRAM lines.

Download compile_diagnostics.py, or run from the legato directory:

1
python "$DOCS_ROOT/docs/legato-language/tutorials/code/compile_diagnostics.py"

The script exits successfully only when all three expected failures occur and the diagnostic checks pass. An unexpected successful compile or a different error makes the script fail. It is included in the documentation example tests.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
"""Read real EVT0 compile diagnostics without allocating or launching on a device."""

import os
from contextlib import redirect_stderr
from io import StringIO
from pathlib import Path

import torch

import legato
import legato.model.bertha as bertha
from legato.diagnostics import LabelStyle
from legato.diagnostics.generated_registry import DiagnosticId

# Store compiler artifacts and optional simulator logs in a configurable directory.
OUTPUT = Path(os.environ.get("LEGATO_EXAMPLE_OUTPUT", "legato_example_output"))


@legato.compile(backend=lambda ctx: bertha.Bertha(ctx, "bertha"))
def invalid_sram_type():
    """Request an explicitly unaligned BF16 SRAM row to show a type error."""
    with legato.get_context().get_device().get_core(0):
        tensor_type = legato.get_model().tensor_type(legato.types.float("bfloat16"), [(8, 8), (10, 10)], "row_major")
        legato.tensor.allocate(tensor_type, None)


@legato.compile(
    backend=lambda ctx: bertha.Bertha(ctx, "bertha"), param_kinds={"source": "universal", "output": "universal"}
)
def nonlast_maximum(
    source: legato.get_model().tensor_type(legato.types.float("float32"), [8, 64], "shared_dram"),
    output: legato.get_model().tensor_type(legato.types.float("float32"), [8, 64], "shared_dram"),
):
    """Keep a valid Core reduction live whose axis the EVT0 standalone path rejects."""
    device = legato.get_context().get_device()
    with device.get_top():
        legato.tensor.request_load(source, device.get_core(0), "sram")
    with device.get_core(0):
        loaded = legato.tensor.receive(source, 0, "sram")
        maximum = legato.math.reduce_max(loaded, 0, True)
        legato.tensor.memcpy(output, loaded - maximum)


@legato.compile(backend=lambda ctx: bertha.Bertha(ctx, "bertha"), param_kinds={"source": "universal"})
def short_receive(
    source: legato.get_model().tensor_type(legato.types.float("bfloat16"), [12, 256], "shared_dram"),
):
    """Request a receive that violates the active backend transfer alignment."""
    device = legato.get_context().get_device()
    with device.get_top():
        legato.tensor.request_load(source, device.get_core(0), "sram")
    with device.get_core(0):
        tensor_type = legato.get_model().tensor_type(legato.types.float("bfloat16"), [10, 64], "row_major")
        legato.tensor.receive_type(tensor_type, 0, None, "sram")


def show_failure(kernel, *arguments, headline, reason=None):
    """Summarize a real compile error and check its source label and registered codes."""
    try:
        # Capture verbose compiler output and report public codes and source labels below.
        with (
            redirect_stderr(StringIO()),
            legato.session(output_type=legato.OutputType.ASM, output_path=str(OUTPUT), launch=False),
        ):
            kernel(*arguments)
    except legato.CompileError as error:
        diagnostic = next(item for item in error.diagnostics if item.err_code == headline.value)
        print("Error code:", diagnostic.err_code)  # noqa: T201
        assert any(
            label.style == LabelStyle.PRIMARY
            and label.span is not None
            and Path(label.span.filename).resolve() == Path(__file__).resolve()
            for label in diagnostic.labels
        ), "The diagnostic must point back to the kernel source"
        for label in diagnostic.labels:
            if label.style == LabelStyle.PRIMARY and label.span is not None:
                print("Source:", label.span.filename, label.span.start_line)  # noqa: T201
        if reason is not None:
            reason_codes = {
                value for key, value in diagnostic.data.items() if key.startswith("failure_") and key.endswith("_code")
            }
            assert reason.value in reason_codes
            print("Recorded reason codes:", ", ".join(sorted(reason_codes)))  # noqa: T201
        if headline == DiagnosticId.TENSOR_TYPE_CONSTRUCTION_FAILED:
            assert "multiple of 64 elements (128 bytes)" in str(error)
    else:
        raise AssertionError("Expected a compile diagnostic, but compilation succeeded")


def main():
    """Exercise frontend validation, executor rejection, and backend transfer checks."""
    show_failure(invalid_sram_type, headline=DiagnosticId.TENSOR_TYPE_CONSTRUCTION_FAILED)
    values = torch.zeros(8, 64, dtype=torch.float32)
    show_failure(
        nonlast_maximum,
        values,
        values.clone(),
        headline=DiagnosticId.NO_EXECUTOR_AVAILABLE,
        reason=DiagnosticId.TARGET_ROW_MAX_AXIS_UNSUPPORTED,
    )
    show_failure(
        short_receive,
        torch.zeros(12, 256, dtype=torch.bfloat16),
        headline=DiagnosticId.CGDMA_LOWERING_FAILED,
    )


if __name__ == "__main__":
    main()