mirror of
https://github.com/rust-lang/rust.git
synced 2025-10-04 03:07:25 +00:00
dbb8190b9c
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, 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).
rustc_target contains some very low-level details that are
specific to different compilation targets and so forth.
For more information about how rustc works, see the rustc dev guide.