# 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. ## Python layout object 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 **FINISHED** 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 **FINISHED** 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 **FINISHED** layout, will move it back to **READY** state. ### State transitions ``` +-------+ start() +-----------+ +------------+ | READY | -----------> | RUNNING | ------------> | FINISHED | +-------+ +-----------+ +------------+ ^ ^ | | | | | | | +------- 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 **FINISHED** 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 **FINISHED** 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 **FINISHED** 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. ## Rust layout object lifecycle A layout on the Rust side is represented by the trait `Layout`, whose `event()` method returns a value of type `Option`. If this event caused a state transition, the new state is returned. Layout can be in one of four states: * `Initial`: the layout is freshly constructed. This is never returned as a result of `event()`. * `Attached`: the layout is running. Its timers have been started and it is accepting events. The state transition carries an `Option`. If set, this is the ButtonRequest that should be sent to the host, as an indication that the layout is ready. * `Transitioning`: the layout is running, but not ready to receive events; either a transition-in or a transition-out animation is running.
The enum value carries an `AttachType`, indicating which direction the transition is going. If this is an outgoing transition, the runtime is supposed to pass the attach type to the next layout, so that it can properly transition-in. * `Done`: the layout has finished running. All its timers should be stopped, and there is a return value available via the `value()` method. We currently _do not keep precise track_ of transitioning animations; it would be a lot of effort to factor the code properly, while the only use case is debuglink state tracking, which works well enough as-is. ### Simple layouts Layouts that are not flows (i.e., have only one screen) are implemented as `Components` with a `ComponentMsgObj` implementation. They are wrapped in a `RootComponent` struct which essentially _simulates_ the layout lifecycle, in the following manner: 1. At start, the layout is `Initial`. 2. After processing the `Attach` event, the layout is `Attached`. The ButtonRequest value is picked up from `ctx.button_request()`. 3. When `Component::event()` returns non-`None` value, the layout is `Done`. The return value is converted to `Obj` via `ComponentMsgObj::msg_try_into_obj()` and cached as `value` on the `RootComponent`. ### Flows Flow layouts in `mercury` are implemented as a `SwipeFlow` struct, which implements `Layout` directly. A flow lifecycle works like this: 1. At start, the layout is `Initial`. 2. After processing the `Attach` event, the layout is `Attached`. The ButtonRequest value is picked up from `ctx.button_request()`. 3. When the flow controller returns a transition from a _swipe_ event, the layout goes directly to `Attached` state. This is because at that point the transition animation is already finished. 4. When the flow controller returns a transition from a _non-swipe_ event (e.g., a button click), the flow controller starts an automatic transition-out animation, and the layout goes to `Transitioning` state, with the transition direction set to the swipe animation direction. 5. When the flow controller returns a `Return` decision, the layout goes to `Done`. Transition-in animations are currently not tracked properly. This is fine for tests because animations are disabled there, but it may break at some point. Correctly tracking transitions would require a more significant refactor of the flow controllers. Transition-out animations are partially tracked, when the animation is directed by the `FlowState` object. In some cases (such as when a swipe is triggered), the animation is instead controlled by the destination screen, in which case they are not tracked. ## 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. `ButtonRequest`s sent from Rust get sent as part of the `Attached` state transition, which can only happen when the layout is already running. TODO: instead of relying on `interact()`, it may be better to pass the `ButtonRequest` inside the layout object and enqueue it so that when the respective Rust layout is `Attached`, the outside-provided `ButtonRequest` is used. ## 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** and `Attached` layout. This injects an event into the layout. In response, the layout can move to a **FINISHED** state. If a `DebugLinkDecision` is received while a layout is not **RUNNING** or not `Attached`, debuglink pauses until some layout becomes ready to receive decisions. 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, * if the decision caused the layout to transition, subsequent debug commands will be received by the respective layout when the transition is done, and * if the decision did not cause the layout to change state, 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. Rust layout lifecycle state is not taken into account. * `NEXT_LAYOUT` waits for the layout to change before returning -- that is, waits until the next time a **RUNNING** layout transitions into an `Attached` state: - If no layout is running, waits until one is started. - If a layout is running but not attached, waits until it is attached. - If a layout is running and attached, waits until the layout stops or becomes attached again. * `CURRENT_LAYOUT` waits until a layout is running and attached, and returns its contents. If no layout is running or it is not attached, the behavior is the same as `NEXT_LAYOUT`. If a layout is running and attached, 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 3 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.