matejcik
6 months ago
parent
cb9f4918ee
commit
7bcbd5a42c
@ -0,0 +1,196 @@
|
||||
# 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.
|
||||
Loading…
Reference in new issue