A context is the timing environment of a Livt component. It provides the clock and reset used by its clocked processes and scheduled operations. Components that share a context operate in the same clock domain; components in separate contexts need an explicit way to communicate across that boundary.
By default, a component’s owned subcomponents inherit its context. In the diagram below, App, Controller, and Worker all use the same clock and reset. This inheritance continues through further levels of owned subcomponents unless a different context is assigned.
Most designs can begin with one shared context. A separate context becomes useful when a peripheral, sensor interface, or another part of the design runs from a different clock. This page follows a small status worker from ordinary same-context calls to synchronised communication, then shows how to test the boundary and connect it to hardware.
Share a context
A child component uses its owner’s context unless another context is assigned during construction. You can therefore compose a design without passing clock and reset signals through every function. The following worker accepts a command byte, doubles a value on request, and calculates a timeout from its own context.
namespace Examples.Contexts
component StatusWorker
{
public command: byte
public fn Double(value: int) int
{
return value + value
}
public fn TimeoutTicks() uint
{
return this.context.TicksFor(1us)
}
}
Constructing a StatusWorker inside StatusReader leaves both in the same context. The scheduled call uses ordinary function syntax; sharing a context does not make that call combinational or promise that it completes in one cycle. See Execution Models for that distinction.
namespace Examples.Contexts
component StatusReader
{
worker: StatusWorker
new()
{
this.worker = new StatusWorker()
}
public fn ReadDoubled(value: int) int
{
return this.worker.Double(value)
}
}
Create a separate context
To place the worker in another domain, declare a context and assign it to the worker during construction. In a test, a context field annotated with a frequency supplies an additional simulated clock. The following excerpt belongs to the complete ContextTest below, whose default context runs at 100 MHz:
@Context(ClockFrequency = 25MHz)
workerContext: IContext
localWorker: StatusWorker
worker: StatusWorker
new()
{
this.localWorker = new StatusWorker()
this.worker = new StatusWorker()
this.worker.context = this.workerContext
}
localWorker keeps the test’s default context, while worker uses workerContext. The assignment establishes the worker’s timing environment; it is construction-time wiring, not a runtime clock switch. Use names such as sensorContext or busContext when they explain why a domain is separate.
Communicate across contexts
Use sync at the access that crosses contexts. It identifies communication with another component’s public interface: a supported function call, a primitive field read, or a primitive field write. In the test’s scheduled functions, the worker accesses become:
var doubled = sync this.worker.Double(21)
sync this.worker.command = 0x2A
var command = sync this.worker.command
The marker belongs to the caller’s access, because the same worker can be used in either a shared or a separate context. An ordinary call to localWorker.Double(21) needs no marker. Adding sync to a local calculation does not make it safer, and Livt can report redundant markers on same-context accesses.
Recognise a clock-domain crossing
In ContextTest, the caller runs in the 100 MHz context and worker runs in the separate 25 MHz context. If you omit sync from the worker call, the Livt extension marks the function name with a red underline. Hover over it to see the diagnostic explaining the clock-domain crossing. The same check applies to public primitive field accesses across a known context boundary.
// Incorrect: worker uses a different context.
assert (this.worker.Double(21)) == 42
Review the context assignments first. When the separate context is intentional, add sync to the access as shown below. If the components should share a context, correct their construction-time binding instead.
// Correct: synchronise the call across the context boundary.
assert (sync this.worker.Double(21)) == 42
Understand transfer completion
Supported synchronised calls and primitive field accesses use a request-and-acknowledgement transfer. The transferred multi-bit value is held stable while the control signals cross the boundary. The caller waits for acknowledgement before continuing, so successive accesses in that sequence retain their source order.
A completed write followed by a read can check the stored command, as the test below does. Separate reads of several changing fields are separate transfers, however; they do not automatically form one snapshot of the whole component. Design the public operation around the value or transaction the caller actually needs.
Keep these boundaries small and purposeful. Transaction-style communication suits commands, status, and occasional results. A continuous stream may need buffering and a flow-control protocol designed for its throughput. See Interfaces for expressing component contracts; a signal interface alone does not supply a clock-domain crossing mechanism.
Calculate timing from the context
A reusable component should derive timing from the context it runs in. this.context.TicksFor(duration) converts a duration to a tick count and rounds up so the represented duration is not shorter than requested. It calculates a value; it does not wait or create a clock.
For the worker’s TimeoutTicks() function, one microsecond is 100 ticks at 100 MHz and 25 ticks at 25 MHz. Rounding matters for durations between edges: 15 ns requires two ticks at 100 MHz. These calculations let a timeout keep its intended duration when the component moves to another clock.
var setupTicks = this.context.TicksFor(250ns)
var timeoutTicks = this.context.TicksFor(10us)
Time literals such as 250ns and 10us have the semantic type Time. Frequency literals such as 25MHz have type Frequency. They are typed values, not strings. Use duration literals with TicksFor(...) and frequency literals when declaring context timing.
| Context property | Meaning |
|---|---|
ticksPerSecond | The clock rate in ticks per second. |
periodNs | The full clock period in nanoseconds. |
highTimeNs | The high part of the period in nanoseconds. |
lowTimeNs | The low part of the period in nanoseconds. |
Read these properties through this.context when reporting or checking timing assumptions. Prefer TicksFor(...) for duration conversion. A calculated count alone does not establish the elapsed time of a scheduled loop: the states and operations around that loop also contribute to its timing.
Test cross-context behaviour
Place StatusWorker in your project’s source directory and the following complete test component in its test directory. Both use the same namespace. The test compares an ordinary call with a synchronised call, writes and reads a command, and verifies that each worker calculates its timeout using its own context.
namespace Examples.Contexts
@Test
@Context(ClockFrequency = 100MHz)
component ContextTest
{
@Context(ClockFrequency = 25MHz)
workerContext: IContext
localWorker: StatusWorker
worker: StatusWorker
new()
{
this.localWorker = new StatusWorker()
this.worker = new StatusWorker()
this.worker.context = this.workerContext
}
@Test
fn CallsAcrossTheBoundary()
{
assert localWorker.Double(21) == 42
assert (sync this.worker.Double(21)) == 42
}
@Test
fn TransfersACommand()
{
sync this.worker.command = 0x2A
var command = sync this.worker.command
assert command == 0x2A
}
@Test
fn UsesTheWorkersClock()
{
assert localWorker.TimeoutTicks() == 0n100
assert (sync this.worker.TimeoutTicks()) == 0n25
assert this.context.TicksFor(15ns) == 0n2
}
}
Run ContextTest from Livt Tests or Test Explorer in Visual Studio Code. All three tests should pass. The expected results are 42 for both calls, 0x2A for the command, and 100 and 25 ticks for the two workers. See Testing for configuring test discovery and inspecting a failed assertion.
When extending this example with a ready flag or a longer protocol, give polling loops a finite limit and assert that completion occurred after the loop. Advance the simulation deliberately while waiting. A synchronised call already waits for its transaction; its completion is not a promise of a fixed number of caller-clock cycles.
Connect clocks and resets
The annotated context in the test supplies a simulated clock. A hardware design needs actual clock and reset signals from its surrounding system. A frequency annotation describes timing; it does not instantiate a divider, PLL, or board clock source.
Bind those signals at the component boundary. In this example, the constructor connects the supplied inputs to the component’s context, and the recurring state increments the counter on its clock:
component TimedCounter
{
public count: int
new(clk: clock, rst: reset)
{
this.context.clk = clk
this.context.rst = rst
}
process Count()
{
state Tick
{
count++
goto Tick
}
}
}
Children that retain this context follow the same clock and reset connections. For additional domains, make each clock source and reset connection explicit in the surrounding design. Check the generated wrapper and the actual board constraints as described in Hardware Integration. The source-level context and the physical wiring must describe the same system.
Configure reset behaviour
Most components can inherit their context’s reset behaviour. The project default is synchronous reset: stored state and scheduled control return to their initial conditions on an active clock edge while reset is asserted. Asynchronous reset responds to assertion without waiting for that edge.
When a component requires a particular reset style, declare that requirement on its context. For example:
@Context(ResetStyle = ResetStyle.Asynchronous)
component Peripheral
{
public command: byte
}
Omitting ResetStyle leaves the component free to inherit the bound context’s setting. An explicit requirement must be compatible with that binding. The project setting build.default_reset_style selects the default, and --default-reset-style can override it for a command. See Project Configuration for the project-wide controls.
Reset style is resolved during compilation. A component used with different reset styles can require separate generated implementations; it is not a runtime mode or a VHDL generic switch. Rebuild after changing the setting.
A synchronous reset requires an active clock edge, so a pulse entirely between edges does not reset the state. Asynchronous assertion can work while the clock is stopped, but its release still needs appropriate conditioning at the clock boundary. Establish reset in both domains before starting communication, and define what happens to an outstanding transfer if either side resets.