kernel/
process_printer.rs

1// Licensed under the Apache License, Version 2.0 or the MIT License.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3// Copyright Tock Contributors 2022.
4
5//! Tools for displaying process state.
6
7use crate::process::Process;
8use crate::utilities::binary_write::BinaryWrite;
9
10/// A context token that the caller must pass back to us. This allows us to
11/// track where we are in the print operation.
12#[derive(PartialEq, Eq, Copy, Clone)]
13pub struct ProcessPrinterContext {
14    /// The overall print message is broken in to chunks so that it can be fit
15    /// in a small buffer that is called multiple times. This tracks which byte
16    /// we are at so we can ignore the text before and print the next bytes.
17    pub offset: usize,
18}
19
20/// Trait for creating a custom "process printer" that formats process state in
21/// some sort of presentable format.
22///
23/// Typically, implementations will display process state in a text UI over some
24/// sort of terminal.
25///
26/// This trait also allows for experimenting with different process display
27/// formats. For example, some use cases might want more or less detail, or to
28/// encode the process state in some sort of binary format that can be expanded
29/// into a human readable format later. Other cases might want to log process
30/// state to nonvolatile storage rather than display it immediately.
31pub trait ProcessPrinter {
32    /// Print a process overview to the `writer`. As `print_overview()` uses a
33    /// `&dyn` [`Process`] to access the process, only state which can be
34    /// accessed via the [`Process`] trait can be printed.
35    ///
36    /// This is a synchronous function which also supports asynchronous
37    /// operation. This function does not issue a callback, but the return value
38    /// indicates whether the caller should call `print_overview()` again (after
39    /// the underlying write operation finishes). This allows asynchronous
40    /// implementations to still use `print_overview()`, while still supporting
41    /// the panic handler which runs synchronously.
42    ///
43    /// When `print_overview()` is called the first time `None` should be passed
44    /// in for `context`.
45    ///
46    /// ### Return Value
47    ///
48    /// The return indicates whether `print_overview()` has more printing to do
49    /// and should be called again. If `print_overview()` returns `Some()` then
50    /// the caller should call `print_overview()` again (providing the returned
51    /// [`ProcessPrinterContext`] as the `context` argument) once the `writer`
52    /// is ready to accept more data. If `print_overview()` returns `None`, the
53    /// `writer` indicated it accepted all output and the caller does not need
54    /// to call `print_overview()` again to finish the printing.
55    fn print_overview(
56        &self,
57        process: &dyn Process,
58        writer: &mut dyn BinaryWrite,
59        context: Option<ProcessPrinterContext>,
60    ) -> Option<ProcessPrinterContext>;
61}
kernel/process_printer.rs

kernel/
process_printer.rs
