trezor-firmware/docs/core/misc/layout-lifecycle.md

# UI Layout Lifecycle

## Overview

There can be at most one UI layout running. The running layout is stored in
`ui.CURRENT_LAYOUT`. The value of this attribute must only be managed internally by the
layout objects themselves.

There are two kinds of layouts. The `Layout` class represents the normal kind of layout
which can accept user interaction or timer events. Such layout can return a _result_
of the interaction, retrievable from the `Layout.get_result()` async method. Typically,
calling code will block on an `await` for the result.

`ProgressLayout` represents loaders for long-running operations. It does not respond to
events and cannot return a result. Calling code will start the progress layout in the
background, call to it to update progress via `ProgressLayout.report()`, and then stop
it when done.

## Individual layout lifecycle

A newly created layout object is in **READY** state. It does not accept events, has no
background tasks, does not draw on screen.

When started, it moves into **RUNNING** state. It is drawn on screen (with backlight
on), accepts events, and runs background tasks. The value of `ui.CURRENT_LAYOUT` is set
to the running layout object.

(This implies that at most one layout can be in **RUNNING** state.)

Layout in **RUNNING** state may stop and return a result, either in response to a user
interaction event (touch, button click, USB) or an internal timer firing. This moves it
into a **STOPPED** state. It is no longer shown on screen (backlight is off unless
another layout turns it on again), does not accept events, and does not run background
tasks.

A layout in a **STOPPED** state has a **result** value, available for pickup by awaiting
`get_result()`.

Stopping a layout before returning a result, or retrieving a result of a **STOPPED**
layout, will move it back to **READY** state.

### State transitions

```
+-------+    start()   +-----------+    <event>    +-----------+
| READY | -----------> |  RUNNING  | ------------> |  STOPPED  |
+-------+              +-----------+               +-----------+
  ^   ^                      |                           |
  |   |                      |                           |
  |   +------- stop() -------+                           |
  |                                                      |
  +--------------------- get_result() -------------------+
```

Calling `start()` checks if other layout is running, and if it is, stops it first. Then
it performs the setup and moves layout into **RUNNING** state.

(At most one layout can be in **RUNNING** state at one time. That means that before
a layout moves to **RUNNING**, the previously running layout must move out.)

When layout is in **RUNNING** state, calling `start()` is a no-op. When layout is in
**STOPPED** state, calling `start()` fails an assertion.

After `start()` returns, the layout is in **RUNNING** state. It will stay in this state
until it returns a result, or is stopped.

Calling `stop()` on a **READY** or **STOPPED** layout is a no-op. Calling `stop()` on a
**RUNNING** layout will shut down any tasks waiting on the layout's result, and move to
**READY** state.

After `stop()` returns, the layout is not in **RUNNING** state and the current layout is
no longer this layout.

Awaiting `get_result()` will resume the lifecycle from its current stage, that is:

* in **READY** state, starts the layout and waits for its result
* in **RUNNING** state, waits for the result
* in **STOPPED** state, returns the result

After `get_result()` returns, the layout is in **READY** state.

All state transitions are synchronous -- so, in terms of trezor-core's cooperative
multitasking, effectively atomic.

## Global layout lifecycle

When Trezor boots, `ui.CURRENT_LAYOUT is None`. The screen backlight is on and displays
the "filled lock" welcome screen with model name.

When a layout is started, the backlight is turned on and the layout is drawn on screen.
`ui.CURRENT_LAYOUT` is the instance of the layout.

When a layout is stopped, the backlight is turned off and `ui.CURRENT_LAYOUT` is set to
`None`.

Between two different layouts, there is always an interval where backlight is off and
the value of `ui.CURRENT_LAYOUT` is `None`. This state may not be visible from the
outside; it is possible to synchronously go from `A -> None -> B`. However, there MUST
be a `None` inbetween in all cases.

## Button requests

A `ButtonRequest` MUST be sent while the corresponding layout is already in **RUNNING**
state. That is, in particular, the value of `ui.CURRENT_LAYOUT` is of the corresponding
layout.

The best choice is to always use the `interact()` function to take care of
`ButtonRequest`s. Explicitly sending `ButtonRequest`s is not supported.

## Debuglink

We assume that only one caller is using the debuglink and that debuglink commands are
strongly ordered on the caller side. On the firmware side, we impose strong ordering on
the received debuglink calls based on the time of arrival.

There are two layout-relevant debuglink commands.

### `DebugLinkDecision`

Caller can send a decision to the **RUNNING** layout. This injects an event into the
layout. In response, the layout can move to a **STOPPED** state.

A next debug command is read only after a `DebugLinkDecision` is fully processed. This
means that:

* if the decision caused the layout to stop, subsequent debug commands will be received
  by the next layout up, and
* if the decision did not cause the layout to stop, subsequent debug commands will be
  received by the same layout.

### `DebugLinkGetState`

Caller can read the contents of the **RUNNING** layout.

There are three available waiting behaviors:

* `IMMEDIATE` (default) returns the contents of the layout that is currently
  **RUNNING**, or empty response if no layout is running.
* `NEXT_LAYOUT` waits for the layout to change before returning. If no layout is
  running, waits until one is started and returns its contents. If a layout is running,
  waits until it shuts down and a new one appears.
* `CURRENT_LAYOUT` waits until a layout is running and returns its contents. If no
  layout is running, the behavior is the same as `NEXT_LAYOUT`. If a layout is running,
  the behavior is the same as `IMMEDIATE`.

When received after a `ButtonRequest` has been sent, the modes guarantee the following:

* `IMMEDIATE` and `CURRENT_LAYOUT`: return the contents of the layout corresponding to
  the button request (unless the layout has already been terminated by a timer event or
  user interaction, in which case the result is undefined).
* `NEXT_LAYOUT`: waits until the layout corresponding to `ButtonRequest` changes.

When received after a `DebugLinkDecision` has been received, the behavior is:

* `IMMEDIATE`: If the layout did not shut down (e.g., when paginating), returns the
  contents of the layout as modified by the decision. If the layout shut down, the
  result is not guaranteed.
* `CURRENT_LAYOUT`: Returns the layout that is the result of the decision.
* `NEXT_LAYOUT`: No guarantees.

While `DebugLinkGetState` is waiting, **no other debug commands are processed**. In
particular, it is impossible to start waiting and then send a `DebugLinkDecision` to
cause the layout to change. Doing so will result in a deadlock.

(TODO it _might_ be possible to lift this restriction.)

If a layout is shut down by a `DebugLinkDecision`, and the firmware expects more
messages, a new layout might not come up until those messages are exchanged. Calling
`DebugLinkGetState` except in `IMMEDIATE` mode will block the debuglink until the new
layout comes up. If the calling code is waiting for a `DebugLinkGetState` to return, it
will deadlock.

(Firmware tries to detect the above condition and sends an error over debuglink if the
wait state is `CURRENT_LAYOUT` and there is no current layout for more than 2 seconds.)

## Synchronizing

`ButtonRequest` is a synchronization event. After a `ButtonRequest` has been sent from
firmware, all debug commands are guaranteed to hit the layout corresponding to the
`ButtonRequest` (unless the layout is terminated by a timer event or user interaction).

`DebugLinkDecision` is also a synchronization event. After a `DebugLinkDecision` has
been received by the firmware, all debug commands are guaranteed to hit the layout
that is the "result" of the decision.

In order to synchronize on a homescreen, it is possible to either:

* invoke any workflow that triggers a `ButtonRequest`, and follow it until end
  (`Ping(button_protection=True)` would work fine), or
* poll `DebugLinkGetState` until the layout is `Homescreen`. Typically, running
  `DebugLinkGetState(wait_layout=CURRENT_LAYOUT)` will work on the first try if you are
  close enough to homescreen (such as after completing a workflow).

`wait_layout=NEXT_LAYOUT` _cannot_ be used for synchronization, because it always
returns the _next_ layout. If the current one is already homescreen, it will wait
forever.