Skip to content

Synchronization

Legato regions can run asynchronously when there is no explicit dependency. Data movement operations create the synchronization points that connect top and core work.

Load And Receive Order

legato.tensor.request_load issues a load request. legato.tensor.receive or legato.tensor.receive_type materializes the requested data in the target context.

1
2
3
4
5
with device.get_top():
    legato.tensor.request_load(x, device.get_core(0), "sram")

with device.get_core(0):
    received_x = legato.tensor.receive(x, 0, "sram")

The third argument is the target name. Common Bertha targets include "sram" and "mpu_buffer".

Multiple Requests

When issuing multiple requests to the same target, current Bertha flows commonly consume them by request order.

1
2
3
4
5
6
7
with device.get_top():
    legato.tensor.request_load(x, device.get_core(0), "sram")
    legato.tensor.request_load(y, device.get_core(0), "sram")

with device.get_core(0):
    received_x = legato.tensor.receive(x, 0, "sram")
    received_y = legato.tensor.receive(y, 1, "sram")

For typed receives, provide the target tensor type and optional dynamic shape.

1
2
3
4
5
6
weight_type = legato.get_model().tensor_type(
    legato.types.float("bfloat16"), [256, 128], "mpu_weight"
)

with device.get_core(0):
    weight = legato.tensor.receive_type(weight_type, 0, None, "mpu_buffer")

Ordering requirements

Keep matching requests and receives in the documented order and in the appropriate execution contexts. Use explicit synchronization when a dependency is carried through shared storage rather than a value.

Cross-Context Barriers (legato.sync)

When data flows through opaque DRAM parameters rather than value-carried dependencies, use explicit barrier ids to serialize producer and consumer contexts.

1
2
3
4
5
6
7
with device.get_core(0):
    legato.tensor.memcpy(k_view, k)
    legato.sync.signal(0)          # core producer

with device.get_top():
    legato.sync.wait(0, device.get_core(0))   # top consumer
    legato.tensor.request_load(k_view, device.get_core(0), "mpu_buffer")

Static barrier handle

Use legato.sync.barrier(id) when a static barrier id is shared across multiple places and a named handle makes the pairing easier to read. The handle is interpreted at compile time and lowers exactly like passing the integer id.

1
2
3
4
5
6
7
8
9
k_ready = legato.sync.barrier(1)

with device.get_core(0):
    legato.tensor.memcpy(k_view, k)
    legato.sync.signal(k_ready)

with device.get_top():
    legato.sync.wait(k_ready, device.get_core(0))
    legato.tensor.request_load(k_view, device.get_core(0), "mpu_buffer")

Dynamic barrier id

When the barrier id is only known at runtime (for example it comes from a kernel argument), cast it to index inside the executor context and use that SSA value for both signal and wait. Top-side wait still requires devices=.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
from legato.language import arith

# barrier_slot: legato.types.integer("int64")  — kernel parameter

with device.get_core(0):
    legato.tensor.memcpy(k_view, k)
    dyn_id = arith.cast(barrier_slot, legato.types.index())
    legato.sync.signal(dyn_id)

with device.get_top():
    dyn_id = arith.cast(barrier_slot, legato.types.index())
    legato.sync.wait(dyn_id, device.get_core(0))
    legato.tensor.request_load(k_view, device.get_core(0), "mpu_buffer")

The compiler cannot infer producer cores from a runtime id alone, so omitting devices= on wait is a compile error.

Dynamic core mask (devices=)

Instead of a static executor list such as device.get_core(0), you can pass an index SSA core bitmask—the same shape of value used for dynamic request_load targets. A literal barrier id may stay constant.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from legato.language import arith

# core_mask: legato.types.integer("int64")  — runtime bitmap, e.g. (1 << core_id)

with device.get_core(0):
    legato.tensor.memcpy(k_view, k)
    legato.sync.signal(0)

with device.get_top():
    cores = arith.cast(core_mask, legato.types.index())
    legato.sync.wait(0, cores)
    legato.tensor.request_load(k_view, device.get_core(0), "mpu_buffer")

Build arith.cast(...) inside with device.get_top(): (or the producing core context for signal); casts at function scope have no executor and fail to lower.

Fully dynamic id and core mask

When both the barrier id and the core mask are runtime values, cast inside each executor context and use the same dyn_id on the producing core and on the top:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from legato.language import arith

with device.get_core(0):
    legato.tensor.memcpy(k_view, k)
    dyn_id = arith.cast(barrier_slot, legato.types.index())
    legato.sync.signal(dyn_id)

with device.get_top():
    dyn_id = arith.cast(barrier_slot, legato.types.index())
    cores = arith.cast(core_mask, legato.types.index())
    legato.sync.wait(dyn_id, cores)

For these patterns the compiler emits warnings when producer/consumer balance cannot be proved statically; correctness then relies on the program pairing ids and core masks correctly.

API summary:

API Context Behavior
legato.sync.signal(id) core Mark the producer as ready.
legato.sync.wait(id, devices=...) top Wait for the selected producers.
legato.sync.barrier(id) — readability handle for an explicit id

Rules (v1):

  • devices= is required on every top-side sync_wait (the compiler does not infer producer cores). It uses the same executor selection as legato.tensor.request_load (static executor list or dynamic index bitmask).
  • devices= on a core context is an error.
  • Top→core fan-out signal(id, devices=...) is not supported yet.
  • Pair every wait with a matching signal on the producing core(s); the compiler warns on unverifiable balance and errors on provable deadlock.
  • Keep barriers in straight-line code. A signal/wait nested in unfolded control flow (scf.for/scf.if) has an unknown runtime execution count, so the compiler cannot prove balance: it lowers the barrier but downgrades all deadlock checks to a warning and relies on the program being correct.