Add `std` support for `armv7a-vex-v5` #145973

Tropix126 · 2025-08-28T22:13:29Z

This PR adds standard library support for the VEX V5 Brain (armv7a-vex-v5 target). It is more-or-less an updated version of the library-side work done in #131530.

This was a joint effort between me, @lewisfm, @max-niederman, @Gavin-Niederman and several other members of the vexide project.

Background

VEXos is a fairly unconventional operating system, with user code running in a restricted enviornment with regards to I/O capabilities and whatnot. As such, several OS-dependent APIs are unsupported or have partial support (such as std::net, std::process, and most of std::thread). A more comprehensive list of what does or doesn't work is outlined in the updated target documentation. Despite these limitations, we believe that libstd support on this target still has value to users, especially given the popular use of this hardware for educational purposes. For some previous discussion on this matter, see this comment.

SDK Linkage

VEXos doesn't really ship with an official libc or POSIX-style platform API (and though it does port newlib, these are stubbed on top of the underlying SDK). Instead, VEX provides their own SDK for calling platform APIs. Their official SDK is kept proprietary (with public headers), though open-source implementations exist. Following the precedent of the armv6k-nintendo-3ds team's work in #95897, we've opted not to directly link libstd to any SDK with the expectation that users will provide their own - either through vex-sdk-build (which will download the official SDK from VEX), vex-sdk-jumptable (a compatible, open-source reimplementation), or potentially through linking the PROS kernel. The vex-sdk crate used in the VEXos PAL provides libc-style FFI bindings for any compatible system library, so any of these options should work fine. A functional demo project using vex-sdk-build can be found here.

Future Work

This PR implements virtually everything we are currently able to implement given the current capabilities of the platform. The exception to this is file directory enumeration, though the implementation of that is sufficiently gross enough to drive us away from supporting this officially.

Additionally, I have a working branch implementing the panic_unwind runtime for this target, which is something that would be nice to see in the future, though given the volume of compiler changes i've deemed it out-of-scope for this PR.

rustbot · 2025-08-28T22:13:34Z

r? @tgross35

rustbot has assigned @tgross35.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

rustbot · 2025-08-28T22:13:38Z

Some changes occurred in src/doc/rustc/src/platform-support

cc @Noratrieb

These commits modify the library/Cargo.lock file. Unintentional changes to library/Cargo.lock can be introduced when switching branches and rebasing PRs.

If this was unintentional then you should revert the changes before this PR is merged.
Otherwise, you can ignore this comment.

These commits modify compiler targets.
(See the Target Tier Policy.)

The list of allowed third-party dependencies may have been modified! You must ensure that any new dependencies have compatible licenses before merging.

cc @davidtwco, @wesleywiser

library/std/src/sys/alloc/vexos.rs

library/std/src/sys/fs/vexos.rs

tgross35 · 2025-08-28T22:53:46Z

I think the limitations here seem fine, and from a quick skim nothing jumps out to me as problematic. Nominating to make sure the team doesn't have any concerns.

@rustbot label +I-libs-nominated

library/std/Cargo.toml

library/std/src/sys/alloc/vexos.rs

library/std/src/sys/fs/vexos.rs

library/std/src/sys/pal/vexos/mod.rs

library/std/src/sys/pal/vexos/time.rs

tgross35 · 2025-08-30T01:14:52Z

@rustbot author

rustbot · 2025-08-30T01:14:55Z

Reminder, once the PR becomes ready for a review, use @rustbot ready.

Tropix126 · 2025-08-30T02:47:53Z

@rustbot ready

tgross35 · 2025-08-30T03:00:48Z

Thanks for the updates here, I'll take a more thorough look through after the libs meeting (next Wednesday).

bors · 2025-09-03T18:49:56Z

☔ The latest upstream changes (presumably #146160) made this pull request unmergeable. Please resolve the merge conflicts.

rustbot · 2025-09-05T23:02:10Z

Some changes occurred in src/tools/cargo

cc @ehuss

library/std/src/sys/fs/vexos.rs

rustbot · 2025-09-20T23:16:22Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

tgross35 · 2025-09-23T11:01:16Z

library/std/src/sys/stdio/vexos.rs

+        while let Some((out_byte, new_buf)) = buf.split_first_mut() {
+            buf = new_buf;
+
+            let byte = unsafe { vex_sdk::vexSerialReadChar(STDIO_CHANNEL) };
+            if byte < 0 {
+                break;
+            }
+
+            *out_byte = byte as u8;
+            count += 1;
+        }


I think this can be simplified as for out_byte in buf rather than using the split API and reassigning.

tgross35 · 2025-09-23T11:51:30Z

library/std/src/sys/fs/vexos.rs

+    File { size: u64 },
+}
+
+pub struct ReadDir(!);


I think you could reexport from unsupported, and just move your comment from fn readdir to the reexport for now.

I can't do that for reasons similar to the FilePermissions situation:

ReadDir must impl Iterator<Item = io::Result<DirEntry>>.

DirEntry must return FileAttr/FileType, which do have proper implementations in this case (though not for directories).

I tried this a while back and ran into this issue; I'm pretty sure the current code re-exports everything it possibly can from unsupported at the moment. Maybe I could have DirEntry just store ! rather than an actual path and just return that here? Not sure.

tgross35 · 2025-09-23T11:57:16Z

library/std/src/sys/fs/vexos.rs

+pub fn copy(from: &Path, to: &Path) -> io::Result<u64> {
+    use crate::fs::File;
+
+    let mut reader = File::open(from)?;
+    let mut writer = File::create(to)?;
+
+    io::copy(&mut reader, &mut writer)
+}


There's an implementation in common that does this, but also verifies it's a file and sets permissions. Would that work here?

rust/library/std/src/sys/fs/common.rs

Line 13 in 4056082

pub fn copy(from: &Path, to: &Path) -> io::Result<u64> {

VEXos will return unsupported for writer.set_permissions(perm)?; (we can't support changing file permissions after a file has been opened), meaning the copy function in common will always fail.

Makes sense. Should the file vs. dir check be included, or will the reads handle failing if from is a directory?

tgross35 · 2025-09-23T11:59:28Z

library/std/src/sys/fs/vexos.rs

+fn map_fresult(fresult: vex_sdk::FRESULT) -> io::Result<()> {
+    // VEX uses a derivative of FatFs (Xilinx's xilffs library) for filesystem operations.
+    match fresult {
+        vex_sdk::FRESULT::FR_OK => Ok(()),
+        vex_sdk::FRESULT::FR_DISK_ERR => Err(io::Error::new(
+            io::ErrorKind::Uncategorized,
+            "internal function reported an unrecoverable hard error",
+        )),


You should use io::const_error! for errors known ahead of time if possible, saves the allocation. Also applies quite a few other places in this module.

tgross35 · 2025-09-23T12:30:14Z

library/std/src/sys/fs/vexos.rs

+                    if *create_new {
+                        if vex_sdk::vexFileStatus(path.as_ptr()) != 0 {
+                            return Err(io::Error::new(
+                                io::ErrorKind::AlreadyExists,
+                                "File exists",
+                            ));
+                        }
+                    } else if !*create {
+                        if vex_sdk::vexFileStatus(path.as_ptr()) == 0 {
+                            return Err(io::Error::new(
+                                io::ErrorKind::NotFound,
+                                "No such file or directory",
+                            ));
+                        }
+                    }
+
+                    vex_sdk::vexFileOpenWrite(path.as_ptr())


The status checks aren't required for the correctness of vexFileOpenWrite are they? It's a convenience, but we probably shouldn't be doing this check: it's an extra syscall that the user may not need, plus a bit of TOCTU. If VEX doesn't have a more detailed error from the file APIs (or errno), it would be better to return a generic error and let the user do this check themselves (via fs::metadata) if they need more details.

The checks are required for correctness here. The create/create_new flags are kind of "smoke and mirrors" in this implementation. Since we don't have anything like an oflag system or global errno, ensuring that files already exist or are created with create/create_new is verified by libstd rather than the OS itself. If those status checks weren't there, we could violate the contract requiring create_new to disallow existing files of the same name or !create requiring a file to already be there.

As for the overhead of vexFileStatus - I think that it should be negligable here, since it would just be a simple lookup rather than a full syscall since most of the filesystem is implemented in "userspace" (though I'm cautious to use that word here, since the distinction is blurry on this target).

tgross35 · 2025-09-23T12:40:18Z

library/std/src/sys/fs/vexos.rs

+};
+
+#[derive(Debug)]
+struct FileDesc(*mut vex_sdk::FIL);


Is this a real pointer to something that the OS will dereference? Or is it more like a Unix file descriptor (int) / Windows handle where the OS does some validity checking and lookup? Would be worth a comment.

This is a real pointer - there is no unix-like file descriptor table exposed to us. I believe it points to a FatFs file object structure under the hood. I'll add a comment, though the SDK intentionally keeps this type opaque (FIL is just c_void), so actually dereferencing it from libstd or treating it as anything other than opaque would be a bad idea since there's no stability guarantees regarding size/layout of FIL in firmware.

tgross35 · 2025-09-23T12:44:10Z

library/std/src/sys/fs/vexos.rs

+#[derive(Clone, PartialEq, Eq, Debug)]
+pub struct FilePermissions {}


Mostly curious, why is an empty struct used here rather than unsupported?

In the sys api, File::perm must infallibly return an instance of FilePermissions. This is also why I can't re-export this type from unsupported, because it stores ! due to the fact that FileAttr is verified to be never-initialized as well (and therefore it can get away with just returning ! rather than the real type).

tgross35 · 2025-09-23T12:52:43Z

library/std/src/sys/fs/vexos.rs

+        let len = buf.len() as _;
+        let buf_ptr = buf.as_mut_ptr();
+        let read = unsafe { vex_sdk::vexFileRead(buf_ptr.cast(), 1, len, self.fd.0) };


Suggested change

let len = buf.len() as _;

let buf_ptr = buf.as_mut_ptr();

let read = unsafe { vex_sdk::vexFileRead(buf_ptr.cast(), 1, len, self.fd.0) };

let len = buf.len() as u32;

let buf_ptr = buf.as_mut_ptr();

let read = unsafe { vex_sdk::vexFileRead(buf_ptr.cast::<c_char>(), 1, len, self.fd.0) };

Just explicit for a bit more readability

tgross35 · 2025-09-23T12:53:07Z

library/std/src/sys/fs/vexos.rs

+        let len = buf.len();
+        let buf_ptr = buf.as_ptr();
+        let written =
+            unsafe { vex_sdk::vexFileWrite(buf_ptr.cast_mut().cast(), 1, len as _, self.fd.0) };


Ditto

Suggested change

let len = buf.len();

let buf_ptr = buf.as_ptr();

let written =

unsafe { vex_sdk::vexFileWrite(buf_ptr.cast_mut().cast(), 1, len as _, self.fd.0) };

let len = buf.len() as u32;

let buf_ptr = buf.as_ptr();

let written =

unsafe { vex_sdk::vexFileWrite(buf_ptr.cast_mut().cast::<c_char>(), 1, len, self.fd.0) };

tgross35 · 2025-09-23T13:03:45Z

library/std/src/sys/fs/vexos.rs

+                    // `vexFileSeek` does not support seeking with negative offset, meaning
+                    // we have to calculate the offset from the end of the file ourselves.
+                    map_fresult(vex_sdk::vexFileSeek(
+                        self.fd.0,
+                        try_convert_offset(self.file_attr()?.size() as i64 + offset)?,
+                        SEEK_SET,
+                    ))?


Would it be better to seek to the end, tell, then seek to an offset from there? I'm speculating about the inner workings here but if vexFileSize reads the size from disk, it may not be the same as the size as seen from the open (potentially unflushed) buffer.

rustbot assigned tgross35 Aug 28, 2025

lewisfm suggested changes Aug 28, 2025

View reviewed changes

library/std/src/sys/alloc/vexos.rs Show resolved Hide resolved

library/std/src/sys/fs/vexos.rs Outdated Show resolved Hide resolved

library/std/src/sys/fs/vexos.rs Outdated Show resolved Hide resolved

rustbot added the I-libs-nominated Nominated for discussion during a libs team meeting. label Aug 28, 2025

This comment has been minimized.

Sign in to view

tgross35 reviewed Aug 28, 2025

View reviewed changes

library/std/Cargo.toml Show resolved Hide resolved

tgross35 reviewed Aug 30, 2025

View reviewed changes

rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 30, 2025

rustbot added the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Aug 30, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Aug 30, 2025

tgross35 added S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 30, 2025

Tropix126 force-pushed the vex-std branch from 3288184 to 09ab298 Compare September 3, 2025 20:37

This comment has been minimized.

Sign in to view

Tropix126 force-pushed the vex-std branch from 09ab298 to 2796a03 Compare September 5, 2025 23:02

This comment has been minimized.

Sign in to view

lewisfm suggested changes Sep 15, 2025

View reviewed changes

library/std/src/sys/fs/vexos.rs Show resolved Hide resolved

lewisfm and others added 23 commits September 20, 2025 19:13

wip: port some old std work

29a29f8

vexos: move fs and stdio into respective modules

75569a6

vexos: implement global dlmalloc fallback

02ba7f3

vexos: finish bringing modules up to date

38a4fc8

vexos: provide dlmalloc::Allocator implementation

d01ce78

vexos: block on stdout writes with size>2048

26f0a65

bump to vex-sdk 0.27.0

2d29e16

vexos: simplify logic by casting count to usize early

63dc910

vexos: remove accidental semicolon

02af5a3

vexos: fix file opening logic

041877e

vexos: improve error message when opening files in RW mode

330b4f1

vexos: fix logic regarding create and create_new

bb9cf5d

update armv7a-vex-v5 target documentation

d7497ff

clarify details regarding system ABI, fix typos

9da82f3

simplify vexFileStatus check in fs::exists

964b521

remove unnecessary allocator lock on VEXos

645cad6

switch to run_path_with_cstr for path conversion

e270713

vexos: refactor FileAttr, clean up open logic

7513b28

vexos: improve unsafe hygiene in alloc and PAL, fix fs issues

3669261

re-export relevant items from unsupported in vexos modules

2521f24

fix type incompatibilities from unsupported re-exports

b12dee6

Resolve std warnings on VEXos

270ff62

impl Send/Sync for VEXos files

e08dea6

lewisfm force-pushed the vex-std branch from 6aaf14c to e08dea6 Compare September 20, 2025 23:16

vexos: move thread from sys::pal to sys::thread

63b2758

tgross35 requested changes Sep 23, 2025

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 23, 2025

		#[derive(Clone, PartialEq, Eq, Debug)]
		pub struct FilePermissions {}

Add std support for armv7a-vex-v5 #145973

Are you sure you want to change the base?

Add std support for armv7a-vex-v5 #145973

Conversation

Tropix126 commented Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

SDK Linkage

Future Work

Uh oh!

rustbot commented Aug 28, 2025

Uh oh!

rustbot commented Aug 28, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tgross35 commented Aug 28, 2025

Uh oh!

This comment has been minimized.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tgross35 commented Aug 30, 2025

Uh oh!

rustbot commented Aug 30, 2025

Uh oh!

Tropix126 commented Aug 30, 2025

Uh oh!

tgross35 commented Aug 30, 2025

Uh oh!

bors commented Sep 3, 2025

Uh oh!

This comment has been minimized.

rustbot commented Sep 5, 2025

Uh oh!

This comment has been minimized.

Uh oh!

rustbot commented Sep 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tropix126 Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tropix126 Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tropix126 Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tropix126 Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tropix126 Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Add `std` support for `armv7a-vex-v5` #145973

Add `std` support for `armv7a-vex-v5` #145973

Tropix126 commented Aug 28, 2025 •

edited

Loading

Tropix126 Sep 23, 2025 •

edited

Loading

Tropix126 Sep 23, 2025 •

edited

Loading

Tropix126 Sep 23, 2025 •

edited

Loading

Tropix126 Sep 23, 2025 •

edited

Loading

Tropix126 Sep 23, 2025 •

edited

Loading