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