opentitanlib/app/config/
structs.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
5//! Schema for configuration files, exact encoding json/xml to be worked out.
6
7use std::collections::HashMap;
8use std::time::Duration;
9
10use crate::io::gpio::{PinMode, PullMode};
11use crate::io::spi::TransferMode;
12
13use serde::Deserialize;
14
15/// Configuration of a particular GPIO pin.
16#[derive(Deserialize, Clone, Debug)]
17pub struct PinConfiguration {
18    /// The user-visible name of the GPIO pin.
19    pub name: String,
20    /// The input/output mode of the GPIO pin.
21    pub mode: Option<PinMode>,
22    /// The default/initial level of the pin (true means high), has effect only in `PushPull` and
23    /// `OpenDrain` modes.
24    pub level: Option<bool>,
25    /// Whether the pin has pullup/down resistor enabled.
26    pub pull_mode: Option<PullMode>,
27    /// The default/initial analog level of the pin in Volts, has effect only in `AnalogOutput`
28    /// mode.
29    pub volts: Option<f32>,
30    /// If present, the name given by the first member of this struct is to be an alias of the pin
31    /// named in this field, (which may by defined by the transport natively, or through alias in
32    /// nother PinConfiguration).  This field is mutually exclusive with `on_io_expander`.
33    pub alias_of: Option<String>,
34    /// If true, value of this pins will be inverted both at reading and writing.
35    pub invert: Option<bool>,
36    /// If present, this pin is not natively supported by the transport, but is to be accessed
37    /// through an IO expander.  This field is mutually exclusive with `alias_of`.
38    pub on_io_expander: Option<IoExpanderPin>,
39}
40
41/// Declaration of a name of an IO expander and pin number on it.
42#[derive(Deserialize, Clone, Debug)]
43pub struct IoExpanderPin {
44    pub io_expander: String,
45    pub pin_no: u32,
46}
47
48/// Declaration of an IO expander.  Its name, how to reach it, and which protocol driver to use.
49#[derive(Deserialize, Clone, Debug)]
50pub struct IoExpander {
51    /// Name used to refer to this IO expander.
52    pub name: String,
53    /// Identifier of the driver to use.
54    pub driver: IoExpanderDriver,
55    /// I2C bus on which this IO expander sits (if the driver uses I2C).
56    pub i2c_bus: Option<String>,
57    /// I2C address of this IO expander sits (if the driver uses I2C).
58    pub i2c_address: Option<u8>,
59    /// Optional gpio strapping for MUXing the bus from the transport to this IO expander.
60    pub mux_strapping: Option<String>,
61}
62
63/// Identifier of the driver/protocol uses by an IO expander.
64#[derive(Deserialize, Clone, Debug)]
65pub enum IoExpanderDriver {
66    Sx1503,
67}
68
69/// Configuration of a particular GPIO pin.
70#[derive(Deserialize, Clone, Debug)]
71pub struct StrappingConfiguration {
72    /// The user-visible name of the strapping combination.
73    pub name: String,
74    /// List of GPIO pin configurations (the alias_of) field should not be used in these.
75    #[serde(default)]
76    pub pins: Vec<PinConfiguration>,
77}
78
79/// Parity configuration for UART communication.
80#[derive(Deserialize, Clone, Copy, Debug, PartialEq)]
81pub enum UartParity {
82    None,
83    Even,
84    Odd,
85    Mark,
86    Space,
87}
88
89/// Stop bits configuration for UART communication.
90#[derive(Deserialize, Clone, Copy, Debug, PartialEq)]
91pub enum UartStopBits {
92    Stop1,
93    Stop1_5,
94    Stop2,
95}
96
97/// Configuration of a particular UART port.
98#[derive(Default, Deserialize, Clone, Debug)]
99pub struct UartConfiguration {
100    /// The user-visible name of the UART.
101    pub name: String,
102    /// Data communication rate in bits/second.
103    pub baudrate: Option<u32>,
104    /// Parity configuration for UART communication.
105    pub parity: Option<UartParity>,
106    /// Stop bits configuration for UART communication.
107    pub stopbits: Option<UartStopBits>,
108    /// Name of the UART as defined by the transport.
109    pub alias_of: Option<String>,
110}
111
112/// Configuration of a particular SPI controller port.
113#[derive(Default, Deserialize, Clone, Debug)]
114pub struct SpiConfiguration {
115    /// The user-visible name of the SPI controller port.
116    pub name: String,
117    /// SPI transfer mode to use with this target.
118    /// See <https://en.wikipedia.org/wiki/Serial_Peripheral_Interface#Clock_polarity_and_phase>
119    /// for details about SPI transfer modes.
120    pub mode: Option<TransferMode>,
121    /// Number of bits in each SPI transmissiong "word".
122    pub bits_per_word: Option<u32>,
123    /// Data communication rate in bits/second.
124    pub bits_per_sec: Option<u32>,
125    /// Which GPIO pin should be used for clock.
126    pub serial_clock: Option<String>,
127    /// Which GPIO pin should be used for signal from debugger to OpenTitan.
128    pub host_out_device_in: Option<String>,
129    /// Which GPIO pin should be used for signal from OpenTitan to debugger.
130    pub host_in_device_out: Option<String>,
131    /// Which GPIO pin should be used for chip select.
132    pub chip_select: Option<String>,
133    /// Name of the SPI controller as defined by the transport.
134    pub alias_of: Option<String>,
135}
136
137/// Configuration of a particular I2C bus.
138#[derive(Default, Deserialize, Clone, Debug)]
139pub struct I2cConfiguration {
140    /// The user-visible name of the I2C bus.
141    pub name: String,
142    /// I2C address of the "default" device on the bus.
143    pub address: Option<u8>,
144    /// Data communication rate in bits/second.
145    pub bits_per_sec: Option<u32>,
146    /// Name of the I2C bus as defined by the transport.
147    pub alias_of: Option<String>,
148}
149
150/// Representation of the complete and unresolved content of a single
151/// confguration file.
152#[derive(Deserialize, Clone, Debug)]
153pub struct ConfigurationFile {
154    /// Optional specification of transport backend, for which this
155    /// configuration applies (to be implemented).
156    pub interface: Option<String>,
157    /// List of names of other configuration files to include recursively.
158    #[serde(default)]
159    pub includes: Vec<String>,
160    /// List of user-defined features "provided" by the testing setup using this file.
161    #[serde(default)]
162    pub provides: HashMap<String, String>,
163    /// List of user-defined features which must be "provided" by the testing setup (through other
164    /// configuration files), in order for it to make sense to use this file.
165    #[serde(default)]
166    pub requires: HashMap<String, String>,
167    /// Duration of time to assert reset and wait after de-asserting reset.
168    #[serde(default)]
169    #[serde(with = "humantime_serde")]
170    pub reset_delay: Option<Duration>,
171    /// List of GPIO pin configurations.
172    #[serde(default)]
173    pub pins: Vec<PinConfiguration>,
174    /// List of named sets of additional GPIO pin configurations (pullup/pulldown).
175    #[serde(default)]
176    pub strappings: Vec<StrappingConfiguration>,
177    /// List of SPI port configurations.
178    #[serde(default)]
179    pub spi: Vec<SpiConfiguration>,
180    /// List of I2C port configurations.
181    #[serde(default)]
182    pub i2c: Vec<I2cConfiguration>,
183    /// List of UART port configurations.
184    #[serde(default)]
185    pub uarts: Vec<UartConfiguration>,
186    /// List of IO expander chips.
187    #[serde(default)]
188    pub io_expanders: Vec<IoExpander>,
189    /// List of GPIO pins.
190    #[serde(default)]
191    pub gpios: Vec<String>,
192}
opentitanlib/app/config/structs.rs

opentitanlib/app/config/
structs.rs
