Add VEXos "linked files" support to `armv7a-vex-v5` by lewisfm · Pull Request #145578 · rust-lang/rust
rustbot
added
S-waiting-on-review
labels
Aug 18, 2025Third-party programs running on the VEX V5
platform need a linker script to ensure code and
data are always placed in the allowed range
`0x3800000-0x8000000` which is read/write/execute.
However, users can also configure the operating
system to preload a separate file at any location
between these two addresses before the program
starts (as a sort of basic linking system).
Programs have to know about this at
compile time - in the linker script - to avoid
placing data in a spot that overlaps where the
file will be loaded. This is a very popular
feature with existing V5 runtimes because it can be
used to modify a program's behavior without
re-uploading the entire binary to the robot
controller. Also, while VEXos's user-exposed
file system APIs may only read data from an external
SD card, linked files have the advantage of being
able to load data directly from the device's
onboard storage.
This PR adds the `__linked_file_start` symbol
to the existing VEX V5 linker script which can be
used to shrink the stack and heap so that they
do not overlap with the memory region containing a
linked file.
With these changes, a developer targeting VEX V5
might add a second linker script to their project
by specifying `-Clink-arg=-Tcustom.ld` and creating
the file `custom.ld` to configure their custom
memory layout:
```ld
/* Reserve 10MiB for a linked file. */
/* (0x7600000-0x8000000) */
__linked_file_start = __linked_file_end - 10M;
/* Optional: specify one or more sections that */
/* represent the developer's custom format. */
SECTIONS {
.linked_file_metadata (NOLOAD) : {
__linked_file_metadata_start = .
. += 1M;
__linked_file_metadata_end = .
}
.linked_file_data (NOLOAD) : {
__linked_file_data_start = .
. += 9M;
__linked_file_data_end = .
}
} INSERT AFTER .stack;
```
Then, using an external tool like the `vex-v5-serial`
crate, they would configure the metadata of their
uploaded program to specify the path of their linked file
and the address where it should be loaded into memory
(in this example, 0x7600000).
bors
added
S-waiting-on-bors
and removed S-waiting-on-review
Status: Awaiting review from the assignee but also interested parties.labels
Aug 19, 2025bors added a commit that referenced this pull request
Aug 19, 2025Rollup of 10 pull requests Successful merges: - #145538 (bufreader::Buffer::backshift: don't move the uninit bytes) - #145542 (triagebot: Don't warn no-mentions on subtree updates) - #145549 (Update rust maintainers in openharmony.md) - #145550 (Avoid using `()` in `derive(From)` output.) - #145556 (Allow stability attributes on extern crates) - #145560 (Remove unused `PartialOrd`/`Ord` from bootstrap) - #145568 (ignore frontmatters in `TokenStream::new`) - #145571 (remove myself from some adhoc-groups and pings) - #145576 (Add change tracker entry for `--timings`) - #145578 (Add VEXos "linked files" support to `armv7a-vex-v5`) r? `@ghost` `@rustbot` modify labels: rollup
rust-timer added a commit that referenced this pull request
Aug 20, 2025Rollup merge of #145578 - vexide:armv7a-vex-v5+linked-files, r=davidtwco Add VEXos "linked files" support to `armv7a-vex-v5` Third-party programs running on the VEX V5 platform need a linker script to ensure code and data are always placed in the allowed range `0x3800000-0x8000000` which is read/write/execute. However, developers can also configure the operating system (VEXos) to preload a separate file at any location between these two addresses before the program starts (as a sort of basic linking or configuration loading system). Programs have to know about this at compile time - in the linker script - to avoid placing data in a spot that overlaps where the linked file will be loaded. This is a very popular feature with existing V5 runtimes because it can be used to modify a program's behavior without re-uploading the entire binary to the robot controller. It's important for Rust to support this because while VEXos's runtime user-exposed file system APIs may only read data from an external SD card, linked files are allowed to load data directly from the device's onboard storage. This PR adds the `__linked_file_start` symbol to the existing VEX V5 linker script which can be used to shrink the stack and heap so that they do not overlap with a memory region containing a linked file. It expects the linked file to be loaded in the final N bytes of user RAM (this is not technically required but every existing runtime does it this way to avoid having discontinuous memory regions). With these changes, a developer targeting VEX V5 might add a second linker script to their project by specifying `-Clink-arg=-Tcustom.ld` and creating the file `custom.ld` to configure their custom memory layout. The linker would prepend this to the builtin target linker script. ```c /* custom.ld: Reserves 10MiB for a linked file. */ /* (0x7600000-0x8000000) */ __linked_file_length = 10M; /* The above line is equivalent to -Clink-arg=--defsym=__linked_file_length=10M */ /* Optional: specify one or more sections that */ /* represent the developer's custom format. */ SECTIONS { .linked_file_metadata (NOLOAD) : { __linked_file_metadata_start = .; . += 1M; __linked_file_metadata_end = .; } .linked_file_data (NOLOAD) : { __linked_file_data_start = .; . += 9M; __linked_file_data_end = .; } } INSERT AFTER .stack; ``` Then, using an external tool like the `vex-v5-serial` crate, they would configure the metadata of their uploaded program to specify the path of their linked file and the address where it should be loaded into memory (in the above example, `0x7600000`).
github-actions bot pushed a commit to rust-lang/rustc-dev-guide that referenced this pull request
Aug 25, 2025github-actions bot pushed a commit to model-checking/verify-rust-std that referenced this pull request
Aug 26, 2025
lewisfm
deleted the
armv7a-vex-v5+linked-files
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters