Skip to content

Decorators And Sessions

Legato uses decorators to define compiled entry points and reusable functions that can be composed into them.

@legato.compile

@legato.compile(backend=...) creates the user-facing compiled entry point. The backend argument is a callable that receives the active MLIR context and returns a compute model.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import legato
import legato.model.bertha as bertha


def get_bertha(ctx):
    return bertha.Bertha(ctx, "bertha")


@legato.compile(backend=get_bertha)
def kernel(
    x: legato.get_model().tensor_type(
        legato.types.float("bfloat16"), [10, 64], "shared_memory"
    ),
):
    device = legato.get_context().get_device()
    with device.get_core(0):
        yield x

Compiled functions are called from Python, not from other compiled Legato functions. They must run inside legato.session(...).

1
2
with legato.session(output_type=legato.OutputType.MLIR, output_path="test-output"):
    kernel(input_tensor)

Sessions And Output Types

legato.session(output_type, output_path) controls the compiler artifact kind and destination.

Supported OutputType values:

  • legato.OutputType.MLIR (disabled in secure mode)
  • legato.OutputType.CORE_IR (disabled in secure mode)
  • legato.OutputType.BACKEND_IR (disabled in secure mode)
  • legato.OutputType.ASM (disabled in secure mode)
  • legato.OutputType.BINARY

If output_path is provided, artifacts and logs are written under a function-specific directory inside that path. If both output_type and output_path are None, Legato uses its cache and log directories.

param_kinds

@legato.compile accepts param_kinds to describe where parameters may be used in the generated regions.

Valid values are:

  • "universal": parameter can be used in any executor region.
  • "top": parameter is intended for top-executor use.
  • "core": parameter is intended for core-executor use.
1
2
3
4
5
6
@legato.compile(
    backend=get_bertha,
    param_kinds={"a": "universal", "weight": "top", "out": "core"},
)
def matmul_kernel(a, weight, out):
    ...

This is useful for kernels where inputs, weights, and outputs have different placement requirements. param_kinds is the compile-time half of argument placement; the runtime half — binding each call argument to a device target — is covered in Argument Binding.

@legato.primitive

@legato.primitive(backend=...) defines reusable Legato code that is called from compiled functions or other primitives. Primitive calls are compiled as part of their caller and are not called directly from Python.

Frontend MLIR can retain a primitive function and a func.call to it. Inlining depends on later compiler passes; the decorator does not guarantee that every output stage eliminates the call.

1
2
3
4
5
6
7
8
9
@legato.primitive(backend=get_bertha)
def add_pair(a: legato.types.integer("int64"), b: legato.types.integer("int64")) -> legato.types.integer("int64"):
    return a + b


@legato.compile(backend=get_bertha)
def caller(a: legato.types.integer("int64"), b: legato.types.integer("int64")):
    with legato.get_context().get_device().get_core(0):
        add_pair(a, b)

Primitives can return values. Compiled entry points are intended to produce compiler artifacts and side effects such as stores, not Python return values.

Constexpr Parameters

Use legato.types.constexpr(...) when a parameter must be known at compile time. Different constexpr values produce different compiled specializations.

1
2
3
4
5
6
7
8
9
@legato.compile(backend=get_bertha)
def static_loop(
    value: legato.types.integer("int64"),
    count: legato.types.constexpr(legato.types.integer("int64")),
):
    device = legato.get_context().get_device()
    with device.get_all_cores():
        rng = legato.range(0, count)
        legato.static.for_each(rng, lambda i: value + i)