opentitanlib/proxy/
protocol.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 serde::{Deserialize, Serialize};
6use std::collections::HashMap;
7
8use crate::bootstrap::BootstrapOptions;
9use crate::io::emu::{EmuState, EmuValue};
10use crate::io::gpio::{
11    ClockNature, MonitoringReadResponse, MonitoringStartResponse, PinMode, PullMode,
12};
13use crate::io::i2c::DeviceStatus;
14use crate::io::spi::{MaxSizes, TransferMode};
15use crate::io::uart::{FlowControl, Parity};
16use crate::proxy::errors::SerializedError;
17use crate::transport::Capabilities;
18use crate::util::voltage::Voltage;
19
20#[derive(Serialize, Deserialize)]
21pub enum Message {
22    // Request/response pairs.  There is no explicit identifier to link a response to a request,
23    // as requests are processed and responses generated in the order they are received.
24    Req(Request),
25    Res(Result<Response, SerializedError>),
26    // An "asynchronos message" is one that is not a direct response to a request, but can be sent
27    // at any time, as part of a communication "channel" previously set up.
28    Async { channel: u32, msg: AsyncMessage },
29}
30
31#[derive(Serialize, Deserialize)]
32pub enum AsyncMessage {
33    UartData { data: Vec<u8> },
34}
35
36#[derive(Serialize, Deserialize)]
37pub enum Request {
38    GetCapabilities,
39    ApplyDefaultConfiguration,
40    Gpio { id: String, command: GpioRequest },
41    GpioMonitoring { command: GpioMonRequest },
42    GpioBitbanging { command: GpioBitRequest },
43    GpioDacBanging { command: GpioDacRequest },
44    Uart { id: String, command: UartRequest },
45    Spi { id: String, command: SpiRequest },
46    I2c { id: String, command: I2cRequest },
47    Emu { command: EmuRequest },
48    Proxy(ProxyRequest),
49}
50
51#[derive(Serialize, Deserialize)]
52pub enum Response {
53    GetCapabilities(Capabilities),
54    ApplyDefaultConfiguration,
55    Gpio(GpioResponse),
56    GpioMonitoring(GpioMonResponse),
57    GpioBitbanging(GpioBitResponse),
58    GpioDacBanging(GpioDacResponse),
59    Uart(UartResponse),
60    Spi(SpiResponse),
61    I2c(I2cResponse),
62    Emu(EmuResponse),
63    Proxy(ProxyResponse),
64}
65
66#[derive(Serialize, Deserialize)]
67pub enum GpioRequest {
68    Write {
69        logic: bool,
70    },
71    Read,
72    SetMode {
73        mode: PinMode,
74    },
75    SetPullMode {
76        pull: PullMode,
77    },
78    AnalogWrite {
79        value: f32,
80    },
81    AnalogRead,
82    MultiSet {
83        mode: Option<PinMode>,
84        value: Option<bool>,
85        pull: Option<PullMode>,
86        analog_value: Option<f32>,
87    },
88}
89
90#[derive(Serialize, Deserialize)]
91pub enum GpioResponse {
92    Write,
93    Read { value: bool },
94    SetMode,
95    SetPullMode,
96    AnalogWrite,
97    AnalogRead { value: f32 },
98    MultiSet,
99}
100
101#[derive(Serialize, Deserialize)]
102pub enum GpioMonRequest {
103    GetClockNature,
104    Start {
105        pins: Vec<String>,
106    },
107    Read {
108        pins: Vec<String>,
109        continue_monitoring: bool,
110    },
111}
112
113#[derive(Serialize, Deserialize)]
114pub enum GpioMonResponse {
115    GetClockNature { resp: ClockNature },
116    Start { resp: MonitoringStartResponse },
117    Read { resp: MonitoringReadResponse },
118}
119
120#[derive(Serialize, Deserialize)]
121pub enum BitbangEntryRequest {
122    Write { data: Vec<u8> },
123    Both { data: Vec<u8> },
124    Delay { clock_ticks: u32 },
125    Await { mask: u8, pattern: u8 },
126}
127
128#[derive(Serialize, Deserialize)]
129pub enum BitbangEntryResponse {
130    Write,
131    Both { data: Vec<u8> },
132    Delay,
133    Await,
134}
135
136#[derive(Serialize, Deserialize)]
137pub enum GpioBitRequest {
138    Start {
139        pins: Vec<String>,
140        clock_ns: u64,
141        entries: Vec<BitbangEntryRequest>,
142    },
143    Query,
144}
145
146#[derive(Serialize, Deserialize)]
147pub enum GpioBitResponse {
148    Start,
149    // GpioBitRequest::Query will be answered by either QueryNotDone or QueryDone.
150    QueryNotDone,
151    QueryDone { entries: Vec<BitbangEntryResponse> },
152}
153
154#[derive(Serialize, Deserialize)]
155pub enum DacBangEntryRequest {
156    Write { data: Vec<f32> },
157    Delay { clock_ticks: u32 },
158    Linear { clock_ticks: u32 },
159}
160
161#[derive(Serialize, Deserialize)]
162pub enum GpioDacRequest {
163    Start {
164        pins: Vec<String>,
165        clock_ns: u64,
166        entries: Vec<DacBangEntryRequest>,
167    },
168    Query,
169}
170
171#[derive(Serialize, Deserialize)]
172pub enum GpioDacResponse {
173    Start,
174    // GpioDacRequest::Query will be answered by either QueryNotDone or QueryDone.
175    QueryNotDone,
176    QueryDone,
177}
178
179#[derive(Serialize, Deserialize)]
180pub enum UartRequest {
181    GetBaudrate,
182    SetBaudrate {
183        rate: u32,
184    },
185    SetBreak(bool),
186    GetParity,
187    SetParity(Parity),
188    GetFlowControl,
189    SetFlowControl(bool),
190    GetDevicePath,
191    Read {
192        timeout_millis: Option<u32>,
193        len: u32,
194    },
195    Write {
196        data: Vec<u8>,
197    },
198    RegisterNonblockingRead,
199}
200
201#[derive(Serialize, Deserialize)]
202pub enum UartResponse {
203    GetBaudrate { rate: u32 },
204    SetBaudrate,
205    SetBreak,
206    GetParity { parity: Parity },
207    SetParity,
208    GetFlowControl { flow_control: FlowControl },
209    SetFlowControl,
210    GetDevicePath { path: String },
211    Read { data: Vec<u8> },
212    Write,
213    RegisterNonblockingRead { channel: u32 },
214}
215
216#[derive(Serialize, Deserialize)]
217pub enum SpiTransferRequest {
218    Read { len: u32 },
219    Write { data: Vec<u8> },
220    Both { data: Vec<u8> },
221    TpmPoll,
222    GscReady,
223}
224
225#[derive(Serialize, Deserialize)]
226pub enum SpiTransferResponse {
227    Read { data: Vec<u8> },
228    Write,
229    Both { data: Vec<u8> },
230    TpmPoll,
231    GscReady,
232}
233
234#[derive(Serialize, Deserialize)]
235pub enum SpiRequest {
236    GetTransferMode,
237    SetTransferMode {
238        mode: TransferMode,
239    },
240    GetBitsPerWord,
241    SetBitsPerWord {
242        bits_per_word: u32,
243    },
244    GetMaxSpeed,
245    SetMaxSpeed {
246        value: u32,
247    },
248    SupportsBidirectionalTransfer,
249    SupportsTpmPoll,
250    SetPins {
251        serial_clock: Option<String>,
252        host_out_device_in: Option<String>,
253        host_in_device_out: Option<String>,
254        chip_select: Option<String>,
255        gsc_ready: Option<String>,
256    },
257    GetMaxTransferCount,
258    GetMaxTransferSizes,
259    GetEepromMaxTransferSizes,
260    SetVoltage {
261        voltage: Voltage,
262    },
263    GetFlashromArgs,
264    RunTransaction {
265        transaction: Vec<SpiTransferRequest>,
266    },
267    AssertChipSelect,
268    DeassertChipSelect,
269}
270
271#[derive(Serialize, Deserialize)]
272pub enum SpiResponse {
273    GetTransferMode {
274        mode: TransferMode,
275    },
276    SetTransferMode,
277    GetBitsPerWord {
278        bits_per_word: u32,
279    },
280    SetBitsPerWord,
281    GetMaxSpeed {
282        speed: u32,
283    },
284    SetMaxSpeed,
285    SupportsBidirectionalTransfer {
286        has_support: bool,
287    },
288    SupportsTpmPoll {
289        has_support: bool,
290    },
291    SetPins,
292    GetMaxTransferCount {
293        number: usize,
294    },
295    GetMaxTransferSizes {
296        sizes: MaxSizes,
297    },
298    GetEepromMaxTransferSizes {
299        sizes: MaxSizes,
300    },
301    SetVoltage,
302    GetFlashromArgs {
303        programmer: String,
304    },
305    RunTransaction {
306        transaction: Vec<SpiTransferResponse>,
307    },
308    AssertChipSelect,
309    DeassertChipSelect,
310}
311
312#[derive(Serialize, Deserialize)]
313pub enum I2cTransferRequest {
314    Read { len: u32 },
315    Write { data: Vec<u8> },
316    GscReady,
317}
318
319#[derive(Serialize, Deserialize)]
320pub enum I2cTransferResponse {
321    Read { data: Vec<u8> },
322    Write,
323    GscReady,
324}
325
326#[derive(Serialize, Deserialize)]
327pub enum I2cRequest {
328    SetModeHost,
329    SetModeDevice {
330        addr: u8,
331    },
332    GetMaxSpeed,
333    SetMaxSpeed {
334        value: u32,
335    },
336    SetPins {
337        serial_clock: Option<String>,
338        serial_data: Option<String>,
339        gsc_ready: Option<String>,
340    },
341    RunTransaction {
342        address: Option<u8>,
343        transaction: Vec<I2cTransferRequest>,
344    },
345    GetDeviceStatus {
346        timeout_millis: u32,
347    },
348    PrepareReadData {
349        data: Vec<u8>,
350        sticky: bool,
351    },
352}
353
354#[derive(Serialize, Deserialize)]
355pub enum I2cResponse {
356    SetModeHost,
357    SetModeDevice,
358    GetMaxSpeed {
359        speed: u32,
360    },
361    SetMaxSpeed,
362    SetPins,
363    RunTransaction {
364        transaction: Vec<I2cTransferResponse>,
365    },
366    GetDeviceStatus {
367        status: DeviceStatus,
368    },
369    PrepareReadData,
370}
371
372#[derive(Serialize, Deserialize)]
373pub enum EmuRequest {
374    GetState,
375    Start {
376        factory_reset: bool,
377        args: HashMap<String, EmuValue>,
378    },
379    Stop,
380}
381
382#[derive(Serialize, Deserialize)]
383pub enum EmuResponse {
384    GetState { state: EmuState },
385    Start,
386    Stop,
387}
388
389#[derive(Serialize, Deserialize)]
390pub enum ProxyRequest {
391    Provides,
392    Bootstrap {
393        options: BootstrapOptions,
394        payload: Vec<u8>,
395    },
396    ApplyPinStrapping {
397        strapping_name: String,
398    },
399    RemovePinStrapping {
400        strapping_name: String,
401    },
402    ApplyDefaultConfigurationWithStrapping {
403        strapping_name: String,
404    },
405}
406
407#[derive(Serialize, Deserialize)]
408pub enum ProxyResponse {
409    Provides {
410        provides_map: HashMap<String, String>,
411    },
412    Bootstrap,
413    ApplyPinStrapping,
414    RemovePinStrapping,
415    ApplyDefaultConfigurationWithStrapping,
416}