From 86f0c60d95f6e9126b07be08fe683f780fc26584 Mon Sep 17 00:00:00 2001 From: bunnie Date: Thu, 2 Oct 2025 16:35:16 +0800 Subject: [PATCH] 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. --- loader/src/args.rs | 140 ++++++++++++++++++++++++++++++++++++++++++- loader/src/phase1.rs | 111 +++++++--------------------------- 2 files changed, 160 insertions(+), 91 deletions(-) diff --git a/loader/src/args.rs b/loader/src/args.rs index 2fa9a9416..363edd13e 100644 --- a/loader/src/args.rs +++ b/loader/src/args.rs @@ -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::() } + + /// 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::()).sum::(); + if size_bound > dest_region.len() * size_of::() { + 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::() == 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::()); + 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::()) 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::() + size_of::(); + assert!(extra_size % size_of::() == 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::()) 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::()), + 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::() as u32, data } + KernelArgument { base, name, size: size * size_of::() as u32, data } } } diff --git a/loader/src/phase1.rs b/loader/src/phase1.rs index d1d009efe..8b498d9ee 100644 --- a/loader/src/phase1.rs +++ b/loader/src/phase1.rs @@ -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::() + 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::(), + ) }; - // 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::(); - // 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::() + 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::()) + // 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::()) - }; - 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::() - ); - } + // 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(dest: *mut T, src: *const T, count: usize) +pub unsafe fn memcpy(dest: *mut T, src: *const T, count: usize) where T: Copy, {