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

opentitanlib/app/config/
structs.rs
