docs: add serial recovery throughput tuning guide#2640
Conversation
There was a problem hiding this comment.
Pull request overview
Adds documentation to help users tune serial recovery upload throughput by aligning device-side receive buffers with host-side mcumgr MTU settings, including example timings for USB CDC-ACM on nRF52840.
Changes:
- Document Zephyr-related Kconfig options affecting SMP receive buffering.
- Provide a
mcumgrexample using a largermtuto increase throughput. - Add a small results table showing measured upload time improvements.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
JayToltTech
force-pushed
the
docs/serial-recovery-throughput
branch
from
67c31d0 to
97e115d
Compare
| How to enable and configure the serial recovery feature depends on the given mcuboot-port implementation. | ||
| Refer to the respective documentation and source code for more details. | ||
|
|
||
| ## Throughput tuning |
There was a problem hiding this comment.
This is a generic MCUboot doc page, the parts added here are zephyr specific, they cannot go on this page and would need to go on a separate page or under a separate heading - thoughts on which @de-nordic @d3zd3z ?
There was a problem hiding this comment.
I think putting them in readme-zephyr.md makes sense here.
de-nordic
added
area: zephyr
JayToltTech
force-pushed
the
docs/serial-recovery-throughput
branch
from
97e115d to
9fbfd49
Compare
|
@nordicjm Per conversation on the last MCUBoot call, I have moved the doc edits into docs/readme-zephyr.md. |
JayToltTech
force-pushed
the
docs/serial-recovery-throughput
branch
from
9fbfd49 to
fb9611c
Compare
JayToltTech
force-pushed
the
docs/serial-recovery-throughput
branch
2 times, most recently
from
0c5bbd9 to
4adbe71
Compare
|
@de-nordic Thanks to some weird decisions by github, you will need to either actually "approve" this change, or an admin will need to dismiss your change request. Any preference? |
@d3zd3z We can add automatic dismiss of reviews on changes pushed to commit, but I do not know whether that fixes the issue. |
| (8 buffers × 128 = 1024), each upload request carries roughly 228 bytes of | ||
| image data after base64 and CBOR overhead. |
There was a problem hiding this comment.
this does not seem right, if you send 1024 bytes of data (total size after SMP over console) then you get the following in the first request (for a dummy file I have):
- 4-byte Length
- 32-byte SHA256 hash
- 0 byte offset
- 633 data bytes
so something is amiss if you are only get 228 bytes here
| On the host side, pass a matching MTU in the ``mcumgr`` connstring: | ||
|
|
||
| ``` console | ||
| mcumgr --conntype serial --connstring "dev=/dev/ttyACM0,baud=115200,mtu=4096" image upload <image> |
There was a problem hiding this comment.
never use this garbage tool
The serial recovery documentation did not mention the Kconfig options that control upload throughput (BOOT_SERIAL_MAX_RECEIVE_SIZE, BOOT_MAX_LINE_INPUT_LEN, BOOT_LINE_BUFS) or the host-side --mtu flag. With defaults, each SMP round-trip carries only ~228 bytes of image data, making large uploads unnecessarily slow. Document how to increase buffer sizes and pass a matching MTU for significantly faster uploads. Signed-off-by: Jay <jay@tolt.us>
JayToltTech
force-pushed
the
docs/serial-recovery-throughput
branch
from
4adbe71 to
4398701
Compare
Summary
CONFIG_BOOT_SERIAL_MAX_RECEIVE_SIZE,CONFIG_BOOT_MAX_LINE_INPUT_LEN,CONFIG_BOOT_LINE_BUFS)mcumgrconnstring