opentitanlib/app/command.rs
1// Copyright lowRISC contributors (OpenTitan project).
2// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3// SPDX-License-Identifier: Apache-2.0
4
5use crate::app::TransportWrapper;
6use anyhow::Result;
7pub use opentitantool_derive::*;
8use serde_annotate::Annotate;
9use std::any::Any;
10
11/// The `CommandDispatch` trait should be implemented for all leaf structures
12/// in the application's command hierarchy. It can be automatically derived
13/// on internal nodes in the heirarchy. See the documentation for
14/// [`opentitantool_derive`].
15///
16/// The `context` parameter can be used to carry information from prior levels
17/// in the command hierarchy to the next level. This is typically used to
18/// implement parameters on interior nodes before the next layer of subcommands.
19pub trait CommandDispatch {
20 fn run(
21 &self,
22 context: &dyn Any,
23 transport: &TransportWrapper,
24 ) -> Result<Option<Box<dyn Annotate>>>;
25
26 /// For optimization. Indicates whether this command expects to not run concurrently with
27 /// other manipulations of the backend debugger. Only long-running commands such as `console`
28 /// will return `false` to indicate that to the contrary they expect other invocations of
29 /// `opentitantool` to run during their lifespan. Returning `true` here will allow
30 /// opentitanlib the optimization of keeping USB handles open for the duration of the `run()`
31 /// call, and even across `run()` of multiple commands if `--exec` is used.
32 fn exclusive_use_of_transport(&self) -> bool {
33 true
34 }
35}