1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
//! Error and result types for the crate.
use std::fmt;
use std::time::Duration;
use crate::proto::KernelErrorPtr;
/// The result type returned throughout `et_soc1`.
pub type Result<T> = std::result::Result<T, Error>;
/// Errors surfaced by the host-side interface.
///
/// `#[non_exhaustive]`: new variants may be added in any minor or patch release.
/// Match with a catch-all arm or use `if let`.
#[derive(Debug)]
#[non_exhaustive]
pub enum Error {
/// A `libc` call (open, ioctl, poll, ...) failed. Carries the operation
/// name and the underlying `errno`.
Io {
/// The syscall or ioctl that failed, for diagnostic context.
op: &'static str,
/// The underlying operating-system error.
source: std::io::Error,
},
/// The device firmware returned a non-success status code in a command
/// response. `code` is the raw `dev_ops_api_*_response_e` value.
Device {
/// The command family that reported the failure.
command: &'static str,
/// The raw device status code.
code: u32,
},
/// A kernel launch did not complete successfully. `status` is the raw
/// `dev_ops_api_kernel_launch_response_e` code and `status_name` its symbolic
/// name (e.g. `"EXCEPTION"`). When the firmware appended diagnostics, `detail`
/// carries the faulting shire mask and the device addresses of the U-mode
/// exception and trace buffers.
KernelLaunch {
/// The raw kernel-launch status code.
status: u32,
/// Symbolic name of the status code, or `"UNKNOWN"`.
status_name: &'static str,
/// Appended exception/trace pointers, if the device provided them.
detail: Option<KernelErrorPtr>,
},
/// A device response could not be parsed, or did not match the command it
/// was expected to answer (wrong `msg_id`, short buffer, mismatched tag).
Protocol(String),
/// A request exceeded a device-advertised limit (DMA element size/count,
/// submission-queue message size, DRAM capacity, ...).
Limit(String),
/// The supplied kernel image could not be parsed as a RISC-V ELF.
Elf(String),
/// The device DRAM bump allocator has been exhausted.
OutOfMemory {
/// Bytes requested by the failing allocation.
requested: u64,
/// Bytes still available in the region.
available: u64,
},
/// A host-side deadline elapsed while waiting for a device operation.
///
/// `operation` names what was being awaited (e.g. `"kernel completion"`,
/// `"DMA completion"`, `"submission-queue space"`). `limit` is the deadline
/// that elapsed. For kernel launches, the limit is configurable via
/// [`crate::LaunchOptions::with_timeout`] or
/// [`crate::Device::set_default_launch_timeout`].
Timeout {
/// The device operation that did not complete within `limit`.
operation: &'static str,
/// The timeout duration that elapsed.
limit: Duration,
},
}
impl Error {
/// Construct an [`Error::Io`] from the current `errno`.
pub(crate) fn last_os(op: &'static str) -> Self {
Error::Io {
op,
source: std::io::Error::last_os_error(),
}
}
/// Wrap a [`std::io::Error`] with the name of the operation that failed.
///
/// Convenient in `map_err`, e.g.
/// `std::fs::read(path).map_err(|e| Error::io("read kernel ELF", e))`.
pub fn io(op: &'static str, source: std::io::Error) -> Self {
Error::Io { op, source }
}
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Error::Io { op, source } => write!(f, "{op} failed: {source}"),
Error::Device { command, code } => {
write!(f, "device rejected {command} with status {code}")
}
Error::KernelLaunch {
status,
status_name,
detail,
} => {
write!(f, "kernel-launch failed: {status_name} (status {status})")?;
if let Some(d) = detail {
write!(f, "; faulting shires {:#x}", d.shire_mask)?;
if d.exception_buffer != 0 {
write!(f, "; exception buffer @ {:#x}", d.exception_buffer)?;
}
if d.trace_buffer != 0 {
write!(f, "; trace buffer @ {:#x}", d.trace_buffer)?;
}
}
Ok(())
}
Error::Protocol(msg) => write!(f, "protocol error: {msg}"),
Error::Limit(msg) => write!(f, "limit exceeded: {msg}"),
Error::Elf(msg) => write!(f, "invalid kernel ELF: {msg}"),
Error::OutOfMemory {
requested,
available,
} => write!(
f,
"device DRAM exhausted: requested {requested} bytes, {available} available"
),
Error::Timeout { operation, limit } => write!(
f,
"timed out after {limit:.1?} waiting for {operation}; \
for kernel launches, set a longer limit with \
LaunchOptions::with_timeout or Device::set_default_launch_timeout"
),
}
}
}
impl std::error::Error for Error {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Error::Io { source, .. } => Some(source),
_ => None,
}
}
}