collect writes in a one-page buffer, so a write may span pages (#41)

Author: aq1018

CHANGELOG.md

@@ -22,7 +22,7 @@ Releases up through `v0.4.0` were workspace-wide and tagged `vX.Y.Z`. From `0.4.
 - `boot_version!(compat = "name")` and `app_version!(compat = "name")` (re-exported from core): a bootloader with a compatibility key accepts only app images with the same key. The V00x and V103 examples set one.
 - The bootloader runs its USART at the baud stored in boot metadata, falling back to `UsartConfig::baud` when nothing is stored or `pclk` cannot reach the rate (divisor below 16). Divisors are computed at build time, so there is no runtime divide; the CH32V003 example bootloader grows by 64 bytes.
 - `app::BaudRate` re-export for `App::set_baud` / `App::baud`.
-- `boot::run_with_payload::<N>` runs the bootloader with an `N`-byte frame payload, up to a flash page; `boot::run` uses the 52-byte default.
+- `boot::run_with_payload::<N>` runs the bootloader with an `N`-byte frame payload (at least 18; a Write may span flash pages); `boot::run` uses the 52-byte default.
 
 ### Changed
 
@@ -44,6 +44,7 @@ Releases up through `v0.4.0` were workspace-wide and tagged `vX.Y.Z`. From `0.4.
 - **Breaking:** `BootMetaStore` has `baud` and `set_baud`, and `refresh` keeps the stored baud.
 - **Breaking:** `Core`, `Dispatcher` and `App` take the frame's payload capacity as a const parameter (default `DEFAULT_PAYLOAD`), and `AppConfig` has `boot_compat`. Info reports the stored boot baud, the bootloader's compatibility key and the payload capacity, in both modes.
 - **Breaking:** the image tail is 6 bytes, `[compat u32, version u16]`, read through the `__tb_tail` symbol the macros define. `tb-app.x` starts it word-aligned and exports `__tb_boot_tail` (was `__tb_boot_version_addr`); `tb-boot.x` places it in the last 6 bytes of BOOT. The version stays in the last 2 bytes of each image.
+- **Breaking:** writes collect in a one-page buffer instead of a two-page ring buffer, and the `ringbuf` module is gone. `BUF` on `Core` and `Dispatcher` is the storage's write size (was twice it), halving the RAM. The CH32V003 example bootloader shrinks by about 100 bytes.
 - `Reset` to the app is refused with `Unsupported` while an update is in progress (`Updating`). Chips that hand off by run mode start the app without the bootloader checking META, so a half-written image used to run. `Reset` with `BOOTLOADER` and `Erase` still restart the update.
 
 ## [tinyboot-protocol 0.5.0] - 2026-10-20

ch32/README.md

@@ -46,7 +46,7 @@ fn main() -> ! {
 
 `Storage` and `BootMetaStore` are initialized from linker symbols automatically. `boot_version!()` ends the image with its tail: a compatibility key and the crate's `Cargo.toml` version. `boot_version!(compat = "name")` sets the key, and the bootloader then accepts only app images built with the same `app_version!(compat = "name")` (see [app integration](https://openservocore.github.io/tinyboot/app-integration.html)).
 
-`boot::run` reads frames with up to 52 payload bytes (a whole frame fits one 64-byte USB packet); `boot::run_with_payload::<N>` takes up to a flash page per Write for faster updates, at `N` bytes of RAM. Hosts read the capacity from Info.
+`boot::run` reads frames with up to 52 payload bytes (a whole frame fits one 64-byte USB packet); `boot::run_with_payload::<N>` takes `N` bytes per Write (at least 18, not limited to a flash page) for faster updates, at `N` bytes of RAM. Hosts read the capacity from Info.
 
 For configuring RS-485 half-duplex, DXL TTL, or alternate pin remaps, see the [transports guide](https://openservocore.github.io/tinyboot/transports.html). For CH32V103 in system-flash mode, `BootCtl::new` takes additional arguments for the external BOOT_CTL circuit — see [boot-ctl](https://openservocore.github.io/tinyboot/boot-ctl.html).
 

ch32/src/boot.rs

@@ -31,16 +31,16 @@ pub fn run(transport: impl tinyboot_core::traits::Transport, ctl: BootCtl) -> !
 }
 
 /// Run the bootloader with a `P`-byte frame payload, at least the 18-byte
-/// Info reply and at most a flash page. A larger payload takes fewer
+/// Info reply; a Write may span flash pages. A larger payload takes fewer
 /// Writes for an image and costs `P` bytes of RAM. Does not return.
 #[inline(always)]
 pub fn run_with_payload<const P: usize>(
     transport: impl tinyboot_core::traits::Transport,
     ctl: BootCtl,
 ) -> ! {
     const {
-        assert!(P >= InfoData::SIZE as usize && P <= PAGE_SIZE);
+        assert!(P >= InfoData::SIZE as usize);
     }
     let platform = Platform::new(transport, Storage::default(), BootMetaStore::default(), ctl);
-    tinyboot_core::Core::<_, _, _, _, { 2 * PAGE_SIZE }, P>::new(platform).run()
+    tinyboot_core::Core::<_, _, _, _, PAGE_SIZE, P>::new(platform).run()
 }

docs/design.md

@@ -30,6 +30,7 @@ Beyond the usual Cargo profile tricks (`opt-level = "z"`, LTO, `codegen-units =
 - **`repr(C)` frame with union data** — CRC is computed directly over the struct memory via pointer cast; no serialization step, no intermediate buffer.
 - **`MaybeUninit` frame buffer** — the 64-byte `Frame` struct (default 52-byte payload) is reused every iteration without zero-initialization.
 - **Bit-bang CRC16** — no lookup table, trades speed for ~512 bytes of flash savings.
+- **One-page write buffer** - Write data is copied into a single page buffer that goes to flash each time it fills, so a Write may span pages without a ring buffer's index arithmetic.
 - **Bit-clear state transitions** — forward state changes (Idle → Updating, trial consumption) flip 1→0 bits without erasing, avoiding a full erase + rewrite cycle.
 - **Avoid `memset` / `memcpy`** — these pull in expensive `core` routines; manual byte loops and volatile writes keep the linker from dragging in library code.
 - **`.write()` over `.modify()`** — register writes use direct writes instead of read-modify-write, saving the read and mask operations.

lib/core/src/lib.rs

@@ -14,8 +14,6 @@ pub mod core;
 pub mod platform;
 /// Protocol frame dispatcher.
 pub mod protocol;
-/// Fixed-size ring buffer for buffered flash writes.
-pub mod ringbuf;
 /// Platform abstraction traits.
 pub mod traits;
 

lib/core/src/protocol.rs

@@ -1,16 +1,15 @@
 use crate::platform::Platform;
-use crate::ringbuf::RingBuf;
 use crate::traits::{BootCtl, BootMetaStore, BootState, RunMode, Storage, Transport};
 use tinyboot_protocol::crc::{CRC_INIT, crc16};
 use tinyboot_protocol::frame::{DEFAULT_PAYLOAD, Frame, InfoData, VerifyData};
 use tinyboot_protocol::{COMPAT_UNSET, Cmd, ReadError, ResetFlags, Status, WriteFlags};
 
 /// Protocol dispatcher with write buffering.
 ///
-/// Writes are accumulated in a ring buffer and flushed a page at a time.
+/// Writes are accumulated in a page buffer and written a page at a time.
 /// The host sets [`WriteFlags::FLUSH`] on the last write of each contiguous
-/// region to commit the trailing partial page. `P` is the frame's data
-/// capacity, reported by Info; `BUF` must hold a page plus `P - 1` bytes.
+/// region to commit the trailing partial page. `BUF` is the page, the
+/// storage's write size; `P` is the frame's data capacity, reported by Info.
 pub struct Dispatcher<
     'a,
     T: Transport,
@@ -24,12 +23,19 @@ pub struct Dispatcher<
     pub platform: &'a mut Platform<T, S, B, C>,
     /// Reusable frame buffer.
     pub frame: Frame<P>,
-    /// 2 × page size.
-    buf: RingBuf<BUF>,
-    /// Expected address of the next sequential write; `None` accepts any.
-    next_addr: Option<u32>,
+    /// Page being filled; `fill` bytes, ending just before `next`.
+    page: Page<BUF>,
+    fill: usize,
+    /// Address of the next sequential write; [`ANY`] after a flush.
+    next: u32,
 }
 
+/// No write is pending: the next may start at any page-aligned address.
+const ANY: u32 = u32::MAX;
+
+#[repr(align(4))]
+struct Page<const N: usize>(core::mem::MaybeUninit<[u8; N]>);
+
 impl<'a, T: Transport, S: Storage, B: BootMetaStore, C: BootCtl, const BUF: usize, const P: usize>
     Dispatcher<'a, T, S, B, C, BUF, P>
 {
@@ -38,18 +44,18 @@ impl<'a, T: Transport, S: Storage, B: BootMetaStore, C: BootCtl, const BUF: usiz
         Self {
             platform,
             frame: Frame::default(),
-            buf: RingBuf::default(),
-            next_addr: None,
+            page: Page(core::mem::MaybeUninit::uninit()),
+            fill: 0,
+            next: ANY,
         }
     }
 
-    fn write_buf(&mut self, next: u32, n: usize) {
-        let addr = next - self.buf.len() as u32;
-        let data = self.buf.peek(n);
-        if self.platform.storage.write(addr, data).is_err() {
+    fn write_page(&mut self, end: u32, n: usize) {
+        // SAFETY: the first n <= BUF bytes were filled.
+        let data = unsafe { core::slice::from_raw_parts(self.page.0.as_ptr().cast::<u8>(), n) };
+        if self.platform.storage.write(end - n as u32, data).is_err() {
             self.frame.status = Status::WriteError;
         }
-        self.buf.consume(n);
     }
 
     #[inline(always)]
@@ -61,36 +67,45 @@ impl<'a, T: Transport, S: Storage, B: BootMetaStore, C: BootCtl, const BUF: usiz
         capacity: u32,
         state: BootState,
     ) {
+        const { assert!(BUF == S::WRITE_SIZE) };
         if state != BootState::Updating {
             self.frame.status = Status::Unsupported;
             return;
         }
 
-        let flush = flags.contains(WriteFlags::FLUSH);
-
+        let mut fill = self.fill;
         if addr + data_len as u32 > capacity
-            || (self.next_addr.is_none() && !addr.is_multiple_of(S::WRITE_SIZE as u32))
-            || self.next_addr.is_some_and(|n| n != addr)
+            || if self.next == ANY {
+                !addr.is_multiple_of(BUF as u32)
+            } else {
+                addr != self.next
+            }
         {
             self.frame.status = Status::AddrOutOfBounds;
             return;
         }
 
-        // SAFETY: data_len <= P validated by frame.read()
-        self.buf
-            .push(unsafe { self.frame.data.raw.get_unchecked(..data_len) });
-        let next = addr + data_len as u32;
-        self.next_addr = Some(next);
-        if self.buf.len() >= S::WRITE_SIZE {
-            self.write_buf(next, S::WRITE_SIZE);
+        let mut next = addr;
+        let dst = self.page.0.as_mut_ptr().cast::<u8>();
+        for i in 0..data_len {
+            // SAFETY: i < data_len <= P (frame.read() validated it), fill < BUF.
+            unsafe { *dst.add(fill) = *self.frame.data.raw.get_unchecked(i) };
+            fill += 1;
+            next += 1;
+            if fill == BUF {
+                self.write_page(next, BUF);
+                fill = 0;
+            }
         }
-        if flush {
-            if !self.buf.is_empty() {
-                self.write_buf(next, self.buf.len());
+        if flags.contains(WriteFlags::FLUSH) {
+            if fill != 0 {
+                self.write_page(next, fill);
+                fill = 0;
             }
-            self.buf.reset();
-            self.next_addr = None;
+            next = ANY;
         }
+        self.fill = fill;
+        self.next = next;
     }
 
     #[inline(always)]

lib/core/src/ringbuf.rs

@@ -138,6 +138,11 @@ impl nor_flash::NorFlash for MockStorage {
     fn write(&mut self, offset: u32, bytes: &[u8]) -> Result<(), Self::Error> {
         let start = offset as usize;
         let end = start + bytes.len();
+        assert!(
+            start.is_multiple_of(Self::WRITE_SIZE),
+            "write not page-aligned"
+        );
+        assert!(bytes.len() <= Self::WRITE_SIZE, "write crosses a page");
         if end > self.data.len() {
             return Err(nor_flash::NorFlashErrorKind::OutOfBounds);
         }
@@ -224,7 +229,7 @@ impl BootMetaStore for MockBootMeta {
 }
 
 pub type TestPlatform = Platform<MockTransport, MockStorage, MockBootMeta, MockBootCtl>;
-pub const TEST_BUF_SIZE: usize = 128;
+pub const TEST_BUF_SIZE: usize = 4;
 
 pub fn platform(state: BootState) -> TestPlatform {
     Platform::new(