mirror of
https://github.com/trezor/trezor-firmware.git
synced 2024-12-17 20:08:12 +00:00
docs(core): Layout lifecycle documentation
This commit is contained in:
matejcik
matejcik
parent
84d7597d52
commit
e3a478044d
@ -181,8 +181,8 @@ class Layout(Generic[T]):
|
||||
"""True if the layout is in RUNNING state."""
|
||||
return CURRENT_LAYOUT is self
|
||||
|
||||
def is_stopped(self) -> bool:
|
||||
"""True if the layout is in STOPPED state."""
|
||||
def is_finished(self) -> bool:
|
||||
"""True if the layout is in FINISHED state."""
|
||||
return CURRENT_LAYOUT is not self and not self.result_box.is_empty()
|
||||
|
||||
def is_layout_attached(self) -> bool:
|
||||
@ -191,7 +191,7 @@ class Layout(Generic[T]):
|
||||
def start(self) -> None:
|
||||
"""Start the layout, stopping any other RUNNING layout.
|
||||
|
||||
If the layout is already RUNNING, do nothing. If the layout is STOPPED, fail.
|
||||
If the layout is already RUNNING, do nothing. If the layout is FINISHED, fail.
|
||||
"""
|
||||
global CURRENT_LAYOUT
|
||||
|
||||
@ -231,7 +231,7 @@ class Layout(Generic[T]):
|
||||
current layout.
|
||||
|
||||
The resulting state is either READY (if there is no result to be picked up) or
|
||||
STOPPED.
|
||||
FINISHED.
|
||||
|
||||
When called externally, this kills any tasks that wait for the result, assuming
|
||||
that the external `stop()` is a kill. When called internally, `_kill_taker` is
|
||||
@ -267,7 +267,7 @@ class Layout(Generic[T]):
|
||||
"""Wait for, and return, the result of this UI layout."""
|
||||
if self.is_ready():
|
||||
self.start()
|
||||
# else we are (a) still running or (b) already stopped
|
||||
# else we are (a) still running or (b) already finished
|
||||
try:
|
||||
if self.context is not None and self.result_box.is_empty():
|
||||
self._start_task(self._handle_usb_iface())
|
||||
@ -419,6 +419,15 @@ class Layout(Generic[T]):
|
||||
),
|
||||
ButtonAck,
|
||||
)
|
||||
|
||||
if (
|
||||
self.button_request_ack_pending
|
||||
and self.state is LayoutState.TRANSITIONING
|
||||
):
|
||||
self.button_request_ack_pending = False
|
||||
self.state = LayoutState.ATTACHED
|
||||
if __debug__:
|
||||
self.notify_debuglink(self)
|
||||
except Exception:
|
||||
raise
|
||||
|
||||
|
||||
@ -14,12 +14,13 @@
|
||||
- [Miscellaneous](core/misc/index.md)
|
||||
- [Boot stages](core/misc/boot.md)
|
||||
- [Code style](core/misc/codestyle.md)
|
||||
- [Memory layout](core/misc/memory.md)
|
||||
- [SLIP-39](core/misc/slip0039.md)
|
||||
- [DISC1](core/misc/disc1.md)
|
||||
- [Exceptions usage](core/misc/exceptions.md)
|
||||
- [Memory fragmentation management](core/misc/fragmentation.md)
|
||||
- [Memory layout](core/misc/memory.md)
|
||||
- [SLIP-39](core/misc/slip0039.md)
|
||||
- [Translation data format](core/misc/translations.md)
|
||||
- [DISC1](core/misc/disc1.md)
|
||||
- [UI Layout lifecycle](core/misc/layout-lifecycle.md)
|
||||
- [Legacy](legacy/index.md)
|
||||
- [Firmware format](legacy/firmware-format.md)
|
||||
- [Python](python/index.md)
|
||||
@ -43,6 +44,7 @@
|
||||
- [GitLab CI Jobs](ci/jobs.md)
|
||||
- [Miscellaneous](misc/index.md)
|
||||
- [Affected third-parties](misc/third-parties.md)
|
||||
- [Changelog](misc/changelog.md)
|
||||
- [Coins' BIP-44 Paths](misc/coins-bip44-paths.md)
|
||||
- [Contributing](misc/contributing.md)
|
||||
- [FW update and device wipe](misc/update-wipes.md)
|
||||
@ -50,7 +52,6 @@
|
||||
- [Git Hooks](misc/git-hooks.md)
|
||||
- [Monorepo Notes](misc/monorepo.md)
|
||||
- [Review Process](misc/review.md)
|
||||
- [Changelog](misc/changelog.md)
|
||||
- [TOIF Image Format](misc/toif.md)
|
||||
- [Developers guide](developers/index.md)
|
||||
- [Libraries](developers/libraries.md)
|
||||
|
||||
279
docs/core/misc/layout-lifecycle.md
Normal file
279
docs/core/misc/layout-lifecycle.md
Normal file
@ -0,0 +1,279 @@
|
||||
# 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() +-----------+ <event> +------------+
|
||||
| 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<LayoutState>`. 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<ButtonRequest>`. 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.<br>
|
||||
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.
|
||||
Loading…
Reference in New Issue
Block a user