refactor argument merging

the original rather unsafe version is replaced with a more readable
version that has a number of safety checks applied.

in the process of doing this, we now support merging of multiple
argument regions and a variable number of tags to merge.

tested to work on at least the base case of one swap region to
merge into the list.
This commit is contained in:
bunnie 2025-10-02 16:35:16 +08:00
parent e1537328fa
commit 86f0c60d95
2 changed files with 160 additions and 91 deletions

View file

@ -50,6 +50,12 @@ pub struct KernelArgumentsIterator {
offset: u32,
}
// Alignment target of the resulting KernelArguments structure. I think we can trim it more
// aggressively but I have had troubles in the past with unsafe code and the optimizer fighting
// each other when alignments are too ragged. 16 bytes is, iirc, what the rv32-llvm expects
// things to be aligned to for function prologues so it's a nice safe number to shoot for
// given the amount of unsafes in the block below.
const TARGET_ALIGNMENT: usize = 16;
impl KernelArguments {
pub fn new(base: *const usize) -> KernelArguments { KernelArguments { base: base as *const u32 } }
@ -57,7 +63,8 @@ impl KernelArguments {
KernelArgumentsIterator { base: self.base, size: self.size(), offset: 0 }
}
pub fn size(self) -> usize {
/// Returns a size in bytes
pub fn size(&self) -> usize {
// Add a rudimentary check to make sure that KernelArguments are pointed to the correct
// structure, by checking for the right magic number in the first field.
let tag = unsafe { (self.base as *const Tag).as_ref().unwrap() };
@ -68,6 +75,133 @@ impl KernelArguments {
let xarg_tag = unsafe { (self.base as *const XargArg).as_ref().unwrap() };
xarg_tag.arg_size_u32 as usize * size_of::<u32>()
}
/// Takes the `self` argument list as the `base`, and creates a copy of the argument list into
/// `dest_region`. At the same time, it will iterate through any other argument lists presented to
/// it from `args`, and filter them for the tags listed in `tag_filter`, and append them to the list.
///
/// `dest_region` needs to be of a size large enough to hold the new merge arguments. `dest_region`
/// will have the new argument list jammed up near the top of its allocation area and a new
/// KernelArguments structure returned as a pointer to that region. The remainder of `dest_region` is
/// free to use after this operation is done.
///
/// Returns `None` if the merged arguments will not fit within the proposed destination region. The final
/// size is often much smaller than `dest_region`; it should be read out of the KernelArguments to
/// determine how far the free memory tracker should be advanced for optimal space packing in the
/// loader.
///
/// Returns `Some<(KernelArguments, allocation size>)` on success. The `cfg.init_size` pointer needs
/// to be advanced by the allocation size.
pub unsafe fn merge_args(
self,
incoming_args: &[KernelArguments],
tag_filter: &[u32],
dest_region: &mut [u32],
) -> Option<(KernelArguments, usize)> {
// computes an upper bound on size. It's an upper bound because we will filter the incoming
// merged arguments according to `tag_filter`, but we want to make sure that we have space
// potentially for all elements before starting the operation.
//
// The final argument list will "waste" the space of the filtered out arguments, but this is
// anticipated to be just a few dozen bytes per argument list, and I'm willing to pay that
// inefficiency for simplicity and safety.
//
// Note that the reason we have to "waste" some space is that free space allocated *down*
// in addresses in the loader, but the argument list has to be copied from low-to-high addresses.
// `dest_region` is a huge area of free space handed to us, and simply placing the argument
// list at the bottom of `dest_region` can't work. So we have to pick & align a spot at the top of
// memory that is large enough to hold the final list before we begin populating it.
//
// Later on we could make this fancier and traverse the incoming argument lists and compute
// an exact size if we wanted to be super fancy. At the moment, we're leaving about 160 bytes
// per merged region on the table by using the simple method of summing together the argument regions.
// I'm not going to lose sleep over this - it's worth revisiting maybe if we get to about ten merged
// regions, but in practice I'm imagining we'll merge 2-3 regions at most.
let size_bound =
self.size() + incoming_args.iter().map(|x| x.size() * size_of::<u32>()).sum::<usize>();
if size_bound > dest_region.len() * size_of::<u32>() {
return None;
}
// check that size_bound meets the alignment requirements of the `KernelArguments` structure.
// This is necessary to enforce guarantees on the `unsafe` operations later on.
assert!(size_bound % size_of::<u32>() == 0);
// we can fit - so now, we're going to do some unsafe casts to manipulate the region of memory
// represented by `dest_region`. These unsafe casts are only going to be safe because every
// value can be represented, and also the alignment guarantee of `dest_region` is appropriate
// per the caller spec in the method invocation comments.
//
// NOTE: `dest_region` is assumed to be *much* larger than the region we need to go into,
// and we want the argument buffer to slot into the top of `dest_region`.
let mut arg_buffer =
(dest_region.as_mut_ptr() as *mut u32).add(dest_region.len()).sub(size_bound / size_of::<u32>());
let alignment_overhead = (arg_buffer as usize) % TARGET_ALIGNMENT;
arg_buffer = (arg_buffer as usize & !(TARGET_ALIGNMENT - 1)) as *mut u32;
let aligned_size = size_bound + alignment_overhead;
// this copy whacks the base arguments into place within the `dest_region`
// It's safe because `dest_region` has an alignment appropriate for `KernelArguments`; it's
// not overlapping with the source buffer (the source buffer should be coming from flash,
// this is going to RAM), and all elements have valid values.
unsafe {
crate::phase1::memcpy(arg_buffer, self.base as *const u32, self.size() as usize);
}
// now iterate through the `incoming_args` and append the records that match the `tag_filter`
// the pointer below tracks where the incoming argument should be appended.
let mut incoming_arg_ptr: usize = arg_buffer.add(self.size() / size_of::<u32>()) as usize;
for arg_list in incoming_args {
for arg in arg_list.iter() {
// filter the argument based on the list of tags to include in the copy
if tag_filter.iter().any(|&t| t == arg.name) {
let extra_size = arg.size as usize * size_of::<u32>() + size_of::<Tag>();
assert!(extra_size % size_of::<usize>() == 0, "Argument did not conform to size spec!");
// safety:
// - all new arguments meet the alignment criteria (as checked by the assert above)
// - all values are representable
// - space at incoming_arg_ptr is guaranteed to be available
unsafe {
crate::phase1::memcpy(incoming_arg_ptr as *mut u32, arg.base as *mut u32, extra_size);
}
// increment the arg pointer to the next argument slot
incoming_arg_ptr += extra_size;
}
}
}
// check that we didn't blow out the size bound after doing the copies
let final_size_bytes = incoming_arg_ptr - arg_buffer as usize;
assert!(final_size_bytes <= size_bound);
// note how much space we ended up wasting. We can reduce this by improving the computation of
// `size_bound` later on if we need to wring out a few more bytes from the boot process. Part
// of the reason the few bytes matters is that these are "unrecoverable", i.e. they are mapped
// into the kernel, used once, and never de-allocated, so we want the convenience overhead to be
// reasonable.
crate::println!("Argument merge complete. {} bytes over-allocated", size_bound - final_size_bytes);
// now fixup the CRC & size of the base XArg argument.
// extract the first argument as an XargArg by just overlaying the structure template on the pointer.
// only safe because the arg_buffer pointer is aligned and is actually an XArg tag.
let xarg = unsafe { (arg_buffer as *mut XargArg).as_mut().unwrap() };
xarg.arg_size_u32 = (final_size_bytes / size_of::<u32>()) as u32;
// compute the CRC of the XArg argument's data section
use crc::{Hasher16, crc16};
// create a u8-region out of the XArg's data section. The data section is known to follow the Tag
// header and be exactly the length of the size in the Tag section.
let xarg_data = unsafe {
core::slice::from_raw_parts(
(self.base as *const u8).add(size_of::<Tag>()),
xarg.tag.size as usize,
)
};
let mut digest = crc16::Digest::new(crc16::X25);
digest.write(&xarg_data);
xarg.tag.crc16 = digest.sum16();
// return the new argument buffer
Some((KernelArguments::new(arg_buffer as *const usize), aligned_size))
}
}
/// KernelArgument is a stack-allocated structure that describes a pointer to tagged data.
@ -77,6 +211,8 @@ impl KernelArguments {
/// It is constructed by referring to the base of the tag structure, and then providing an
/// offset. The base + offset should point to the top of a Tag structure.
pub struct KernelArgument {
pub base: *const u32,
pub name: u32,
// Total number of bytes in the data section
@ -96,7 +232,7 @@ impl KernelArgument {
unsafe { core::slice::from_raw_parts((tag as *const Tag).add(1) as *const u32, size as usize) };
// Return the stack-allocated KernelArgument, which embeds a reference to the now base/bounds
// protected data slice.
KernelArgument { name, size: size * size_of::<u32>() as u32, data }
KernelArgument { base, name, size: size * size_of::<u32>() as u32, data }
}
}

View file

@ -369,105 +369,38 @@ pub fn allocate_swap(cfg: &mut BootConfig) {
pub fn copy_args(cfg: &mut BootConfig) {
// With swap enabled, copy_args also merges the IniS arguments from the swap region into the kernel
// arguments, and patches the length field accordingly.
//
// So much terrible, no-good awful code. This is basically not Rust code, because the whole thing
// is operating on pointers conjured out of thin air and confused senses of what is a byte-size
// versus a word-size. Deserves a re-write, but it would also require reworking a bunch of other
// bootloader code because the core issue is the way the kernel arguments are defined for parsing and
// iteration.
//
// Suspect many bugs in this code.
// Read in the swap arguments: should be located at beginning of the first page of swap.
// Safety: only safe because we know that the decrypt was setup by read_swap_config(), and no pages
// were decrypted between then and now!
let page0 = unsafe { cfg.swap_hal.as_mut().unwrap().get_decrypt() };
let swap_args = KernelArguments::new(page0.as_ptr() as *const usize);
let mut j = swap_args.iter();
// skip the first argument
let swap_xarg = j.next().expect("couldn't read initial swap tag");
// Merge the args list to target RAM
// Reserve space for the primary arg list + swap args - swap's XArg structure (7 words long)
let final_len = cfg.args.size() / size_of::<u32>() + swap_xarg.data[0] as usize - 7;
cfg.init_size += final_len * 4;
let runtime_arg_buffer = cfg.get_top();
// places the boot image kernel arguments
unsafe {
#[allow(clippy::cast_ptr_alignment)]
memcpy(runtime_arg_buffer, cfg.args.base as *const usize, cfg.args.size() as usize)
// Carve out a much larger region than anticipated for argument processing. A "typical" target for
// the new argument stack is around 1800 bytes.
//
// It's assumed we have at least 4 pages of RAM at this point because we haven't allocated anything and
// our target should have more memory than that. So, pass a total of 16,384 bytes region with the
// anticipation that the actual allocation will be much smaller than that.
let dest_region = unsafe {
core::slice::from_raw_parts_mut(
(cfg.get_top() as usize - PAGE_SIZE * 4) as *mut u32,
PAGE_SIZE * 4 / size_of::<u32>(),
)
};
// safety: this should be aligned, allowing this conversion. Note that we do violate a safety condition
// in that we haven't fully initialized the region (the swap arg extension area is uninit), but I think
// it's OK because we will write only to that region (but I suppose in practice, Rust could assume the
// untouched data is 0 or something and try an optimization based on that).
let merged_arg_slice =
unsafe { core::slice::from_raw_parts_mut(runtime_arg_buffer as *mut usize, final_len) };
let mut arg_index = cfg.args.size() / size_of::<u32>();
// append the swap arguments, and patch the size field accordingly
for a in j {
// turn the argument into a raw slice
// this is safe because:
// - arguments are always guaranteed to be aligned to a word boundary by the image creator
// - arguments are fully initialized with no UB fields under this transformation
// +2 is for the tag field
if a.name == u32::from_le_bytes(*b"IniS") {
let arg_slice = unsafe {
core::slice::from_raw_parts(
a.data.as_ptr().sub(2) as *const usize, // backup by 2 to accommodate the tag field
a.size as usize / size_of::<usize>() + 2,
)
};
if SDBG {
println!(
"Extending args with: 0x{:x}, size: {}. index: {}, len: {}, data: {:x?}",
a.name,
a.size,
arg_index,
arg_slice.len(),
arg_slice
);
}
merged_arg_slice[arg_index..arg_index + arg_slice.len()].copy_from_slice(arg_slice);
arg_index += arg_slice.len();
} else {
println!("Unhandled arg type: {:x}", a.name);
}
}
// redirect the arg buffer to point at the newly copied arguments
cfg.args = KernelArguments::new(runtime_arg_buffer);
// extract the new XArg field, pointing into RAM
let args = cfg.args;
let mut i = args.iter();
let xarg = i.next().expect("couldn't read initial tag");
// patch the total length of the arguments - just jam the value into the data field of the XArg by
// dead-reckoning to the offset
assert!(merged_arg_slice[2] == xarg.data[0] as usize); // sanity checks the dead-reckoning
merged_arg_slice[2] = arg_index;
use crc::{Hasher16, crc16};
// compute the new CRC
let mut digest = crc16::Digest::new(crc16::X25);
// safe because we know the entire region can map into a u8 slice with no UB
let xarg_data = unsafe {
core::slice::from_raw_parts(xarg.data.as_ptr() as *const u8, xarg.data.len() * size_of::<u32>())
// Replace the original args pointer in FLASH with a new copy in RAM that incorporates any merged
// regions that the kernel should be aware of.
let args_size: usize;
(cfg.args, args_size) = unsafe {
cfg.args
.merge_args(&[swap_args], &[u32::from_le_bytes(*b"IniS")], dest_region)
.expect("Couldn't merge kernel arguments")
};
digest.write(&xarg_data);
// patch the CRC
let merged_arg_slice_u8 = unsafe {
core::slice::from_raw_parts_mut(runtime_arg_buffer as *mut u8, final_len * size_of::<u32>())
};
merged_arg_slice_u8[4..6].copy_from_slice(&digest.sum16().to_le_bytes());
if SDBG {
println!(
" -> Patched kernel args range: {:x} - {:x}",
runtime_arg_buffer as usize,
runtime_arg_buffer as usize + final_len * size_of::<usize>()
);
}
// Advance the init_size pointer by the actual allocation consumed by the merge_args() function.
cfg.init_size += args_size;
crate::println!("Argument merge done, total size consumed: {}", args_size);
}
#[cfg(feature = "swap")]
@ -905,7 +838,7 @@ fn copy_processes(cfg: &mut BootConfig) {
}
}
unsafe fn memcpy<T>(dest: *mut T, src: *const T, count: usize)
pub unsafe fn memcpy<T>(dest: *mut T, src: *const T, count: usize)
where
T: Copy,
{