xous_sys/definitions/
mod.rs

1#[cfg(feature = "unstable_mem")]
2mod memoryflags;
3
4#[cfg(feature = "unstable_mem")]
5pub use memoryflags::*;
6
7/// Indicates a particular syscall number as used by the Xous kernel.
8#[derive(Copy, Clone)]
9#[repr(usize)]
10pub enum Syscall {
11    MapMemory = 2,
12    Yield = 3,
13    UpdateMemoryFlags = 12,
14    ReceiveMessage = 15,
15    SendMessage = 16,
16    Connect = 17,
17    CreateThread = 18,
18    UnmapMemory = 19,
19    ReturnMemory = 20,
20    TerminateProcess = 22,
21    TrySendMessage = 24,
22    TryConnect = 25,
23    GetThreadId = 32,
24    Disconnect = 35,
25    JoinThread = 36,
26    AdjustProcessLimit = 38,
27    ReturnScalar = 40,
28}
29
30/// Copies of these invocation types here for when we're running
31/// in environments without libxous.
32#[derive(Copy, Clone)]
33#[repr(usize)]
34pub enum SyscallResult {
35    /// The operation completed successfully
36    Ok = 0,
37    /// An error was encountered, with the exact error stored in $a1
38    Error = 1,
39    /// A slice with the offset in $a1 and the length in $a2
40    MemoryRange = 3,
41    /// A `u32` connection ID stored in $a1
42    ConnectionId = 7,
43    /// A message was received
44    Message = 9,
45    /// A `u32` thread id stored in $a1
46    ThreadId = 10,
47    /// One scalar value, stored in $a1
48    Scalar1 = 14,
49    /// Two scalar values, stored in $a1 and $a2
50    Scalar2 = 15,
51    /// Memory that was returned from a syscall, with return values in $a1 and $a2
52    MemoryReturned = 18,
53    /// Five scalar values, stored in $a1..=$a5
54    Scalar5 = 20,
55}
56
57#[derive(Copy, Clone)]
58/// A list of all known errors that may be returned by the Xous kernel.
59#[repr(usize)]
60pub enum Error {
61    NoError = 0,
62    BadAlignment = 1,
63    BadAddress = 2,
64    OutOfMemory = 3,
65    MemoryInUse = 4,
66    InterruptNotFound = 5,
67    InterruptInUse = 6,
68    InvalidString = 7,
69    ServerExists = 8,
70    ServerNotFound = 9,
71    ProcessNotFound = 10,
72    ProcessNotChild = 11,
73    ProcessTerminated = 12,
74    Timeout = 13,
75    InternalError = 14,
76    ServerQueueFull = 15,
77    ThreadNotAvailable = 16,
78    UnhandledSyscall = 17,
79    InvalidSyscall = 18,
80    ShareViolation = 19,
81    InvalidThread = 20,
82    InvalidPid = 21,
83    UnknownError = 22,
84    AccessDenied = 23,
85    UseBeforeInit = 24,
86    DoubleFree = 25,
87    DebugInProgress = 26,
88    InvalidLimit = 27,
89}
90
91impl From<usize> for Error {
92    // Marking this function as "cold" ensures this error path
93    // does not get inlined.
94    #[cold]
95    fn from(src: usize) -> Self {
96        match src {
97            0 => Self::NoError,
98            1 => Self::BadAlignment,
99            2 => Self::BadAddress,
100            3 => Self::OutOfMemory,
101            4 => Self::MemoryInUse,
102            5 => Self::InterruptNotFound,
103            6 => Self::InterruptInUse,
104            7 => Self::InvalidString,
105            8 => Self::ServerExists,
106            9 => Self::ServerNotFound,
107            10 => Self::ProcessNotFound,
108            11 => Self::ProcessNotChild,
109            12 => Self::ProcessTerminated,
110            13 => Self::Timeout,
111            14 => Self::InternalError,
112            15 => Self::ServerQueueFull,
113            16 => Self::ThreadNotAvailable,
114            17 => Self::UnhandledSyscall,
115            18 => Self::InvalidSyscall,
116            19 => Self::ShareViolation,
117            20 => Self::InvalidThread,
118            21 => Self::InvalidPid,
119            23 => Self::AccessDenied,
120            24 => Self::UseBeforeInit,
121            25 => Self::DoubleFree,
122            26 => Self::DebugInProgress,
123            27 => Self::InvalidLimit,
124            22 | _ => Self::UnknownError,
125        }
126    }
127}
128
129impl From<i32> for Error {
130    #[cold]
131    fn from(src: i32) -> Self {
132        let Ok(src) = core::convert::TryInto::<usize>::try_into(src) else {
133            return Self::UnknownError;
134        };
135        src.into()
136    }
137}
138
139impl core::fmt::Display for Error {
140    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
141        write!(
142            f,
143            "{}",
144            match self {
145                Error::NoError => "no error occurred",
146                Error::BadAlignment => "memory was not properly aligned",
147                Error::BadAddress => "an invalid address was supplied",
148                Error::OutOfMemory => "the process or service has run out of memory",
149                Error::MemoryInUse => "the requested address is in use",
150                Error::InterruptNotFound =>
151                    "the requested interrupt does not exist on this platform",
152                Error::InterruptInUse => "the requested interrupt is currently in use",
153                Error::InvalidString => "the specified string was not formatted correctly",
154                Error::ServerExists => "a server with that address already exists",
155                Error::ServerNotFound => "the requetsed server could not be found",
156                Error::ProcessNotFound => "the target process does not exist",
157                Error::ProcessNotChild =>
158                    "the requested operation can only be done on child processes",
159                Error::ProcessTerminated => "the target process has crashed",
160                Error::Timeout => "the requested operation timed out",
161                Error::InternalError => "an internal error occurred",
162                Error::ServerQueueFull => "the server has too many pending messages",
163                Error::ThreadNotAvailable => "the specified thread does not exist",
164                Error::UnhandledSyscall => "the kernel did not recognize that syscall",
165                Error::InvalidSyscall => "the syscall had incorrect parameters",
166                Error::ShareViolation => "an attempt was made to share memory twice",
167                Error::InvalidThread => "tried to resume a thread that was not ready",
168                Error::InvalidPid => "kernel attempted to use a pid that was not valid",
169                Error::AccessDenied => "no permission to perform the requested operation",
170                Error::UseBeforeInit => "attempt to use a service before initialization finished",
171                Error::DoubleFree => "the requested resource was freed twice",
172                Error::DebugInProgress => "kernel attempted to activate a thread being debugged",
173                Error::InvalidLimit => "process attempted to adjust an invalid limit",
174                Error::UnknownError => "an unknown error occurred",
175            }
176        )
177    }
178}
179
180impl core::fmt::Debug for Error {
181    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
182        write!(f, "{}", self)
183    }
184}
185
186impl core::error::Error for Error {}
187
188/// Indicates the type of Message that is sent when making a `SendMessage` syscall.
189pub enum InvokeType {
190    /// Mutably lend the buffer to the server
191    LendMut = 1,
192    /// Immutably lend
193    Lend = 2,
194    #[cfg(feature = "unstable_mem")]
195    /// Move the buffer from this process into the server
196    Move = 3,
197    /// Send a scalar message to the server without blocking
198    Scalar = 4,
199    /// Send a scalar message to the server and wait for a reply
200    BlockingScalar = 5,
201}
202
203#[derive(Debug, Copy, Clone)]
204/// A representation of a connection to a Xous service.
205pub struct Connection(pub(crate) u32);
206
207impl From<u32> for Connection {
208    fn from(src: u32) -> Connection {
209        Connection(src)
210    }
211}
212
213impl TryFrom<usize> for Connection {
214    type Error = core::num::TryFromIntError;
215    fn try_from(src: usize) -> Result<Self, Self::Error> {
216        Ok(Connection(src.try_into()?))
217    }
218}
219
220impl Into<u32> for Connection {
221    fn into(self) -> u32 {
222        self.0
223    }
224}
225
226impl TryInto<usize> for Connection {
227    type Error = core::num::TryFromIntError;
228    fn try_into(self) -> Result<usize, Self::Error> {
229        self.0.try_into()
230    }
231}
232
233#[derive(Debug)]
234/// The specified Server address could not be parsed
235pub enum ServerAddressError {
236    /// the length was not 16 bytes
237    InvalidLength,
238}
239
240pub struct ServerAddress(pub(crate) [u32; 4]);
241
242impl TryFrom<&str> for ServerAddress {
243    type Error = ServerAddressError;
244    fn try_from(value: &str) -> Result<Self, Self::Error> {
245        let b = value.as_bytes();
246        if b.len() == 0 || b.len() > 16 {
247            return Err(Self::Error::InvalidLength);
248        }
249
250        let mut this_temp = [0u8; 16];
251        for (dest, src) in this_temp.iter_mut().zip(b.iter()) {
252            *dest = *src;
253        }
254
255        let mut this = [0u32; 4];
256        for (dest, src) in this.iter_mut().zip(this_temp.chunks_exact(4)) {
257            *dest = u32::from_le_bytes(src.try_into().unwrap());
258        }
259        Ok(ServerAddress(this))
260    }
261}
262
263impl Into<[u32; 4]> for ServerAddress {
264    fn into(self) -> [u32; 4] {
265        self.0
266    }
267}
268
269#[derive(Debug, Copy, Clone)]
270pub struct ThreadId(usize);
271
272impl From<usize> for ThreadId {
273    fn from(src: usize) -> ThreadId {
274        ThreadId(src)
275    }
276}
277
278impl Into<usize> for ThreadId {
279    fn into(self) -> usize {
280        self.0
281    }
282}
283
284#[derive(Copy, Clone)]
285#[repr(usize)]
286/// Limits that can be passed to `AdjustLimit`
287pub enum Limits {
288    HeapMaximum = 1,
289    HeapSize = 2,
290}
xous_sys/definitions/mod.rs

xous_sys/definitions/
mod.rs
