[Pedro Henrique Penna (ppenna)]

Fixes #570.

Section 5.1.2 of the architecture guide still said that the complete NUL-terminated kernel command line must fit in 64 KiB. The x86 guest kernel keeps 2,048 bytes, including the terminating NUL, and since #661, OpenVMM rejects before boot an effective command line that doesn't fit. This pull request states that limit in section 5.1.2, with where it comes from, why the VMM enforces it, and how a restore treats a saved command line over it. That was #570's last open task.

Based on dev at 470378692. One documentation commit. No code, test, or behavior changes.

Where #570 stands

Task	Status
Choose an option and update section 5.1.2	#661 took the first option. This pull request updates section 5.1.2.
Implement it in nanvix/openvmm and promote the pin	Done in #661 with one shared check, check_microvm_command_line, which runs on every cold boot and restore. The current pin, bd2b27a2e, still has it.
Add a boot test near the limit that checks the last machine-profile token	Done in #661: the command-line-limit microVM scenario, in the default test-microvm set.
Make the managed agent read /proc/cmdline to its end if the limit rises above 4 KiB	Not needed, because the limit stays at 2,048 bytes. mappings::prepare reads up to 4,095 bytes, and every other guest reader of /proc/cmdline (cat, read -r, std::fs::read) reads the whole file.

Change

Commit	Files	Change
377f25eaf doc	doc/design/5.1-boot-protocol.md	Replaces the 64-KiB limit in section 5.1.2 with the guest kernel's 2,048-byte COMMAND_LINE_SIZE, which allows at most 2,047 bytes of text. It says why the machine profile enforces the limit: the kernel would silently drop the host-owned tokens first, and an uncompressed ELF image doesn't declare the limit to the loader. The profile rejects an effective command line that doesn't fit before any processor runs. A restore rejects a saved command line over the limit instead of rewriting it.

The text matches the pinned OpenVMM:

• MICROVM_COMMAND_LINE_MAX_SIZE in openvmm_defs/src/microvm.rs is 2,048, documented as "the x86 guest kernel's COMMAND_LINE_SIZE".
• check_microvm_command_line refuses an embedded NUL and any text of 2,048 bytes or more. The profile runs it after it appends each of its tokens.
• validate_machine_contract_shape in openvmm_helpers/src/snapshot/microvm.rs checks a snapshot's saved command line "as saved and never rewritten to fit".

The guest kernel is Linux 6.18.38, which defines COMMAND_LINE_SIZE as 2,048 on x86. kernel/config-microvm sets no built-in command line (CONFIG_CMDLINE_BOOL is not set), and no patch under kernel/patches/ changes the size, so all 2,047 bytes reach the guest.

As in #661, two things are unchanged:

• The loader's 64-KiB placement region for the command line, 0x20000..0x2ffff in Table 2.4 of section 2.3.
• Launcher budgets. Section 5.1.2 states only the VMM's rule, which every launcher must meet. nvx-rs keeps 1,024-byte budgets for its managed launches, its sandboxes, and the share tokens of run's aggregate, but run passes a plain --cmdline to OpenVMM without a budget of its own, so OpenVMM's check is the one that applies there.

Overlap with #591

Draft #591 rewrites the same paragraph, which #661 left for it to update. This pull request makes that change on its own, so #570 can close without waiting for #591's 19 files. #591 will conflict on this paragraph when it rebases. Its version also says that launchers keep a 1,024-byte caller budget, which nvx-rs run doesn't enforce for a plain --cmdline, as described above.

Validation

• Base: dev at 47037869244e754bfef5fb7e471eec3185a9a7ff. Head: 377f25eaf4ca576b153ea05b38e51f8f295bb8d7, signed.

• At the head, on Windows: python scripts\check_markdown_links.py passes. No test reads section 5.1.

• On three remote test hosts, I ran python3 scripts/nvx.py test-microvm --scenario command-line-limit (python on Windows) with the backend shown below. Each host ran this branch's tree, 536e72ff2, in a fresh worktree. nvx-rs download installed the artifacts of release v0.1.0-dev.299d0b4d9851, which CI built from 299d0b4d9. That commit has the same OpenVMM pin (bd2b27a2e) and guest inputs as this head's parent; the two differ only in performance-baseline data.

  Host profile	Backend	Host type	Result
  nvx-kvm-test	KVM	virtual machine	Passed
  nvx-mshv-test	MSHV	virtual machine	Passed
  nvx-whp-test	WHP	virtual machine	Passed

  On every host:

  • The guest's /proc/cmdline held exactly 2,047 bytes, ending with the last host-owned token, virtnet_gw6=fd00::a00:1.
  • OpenVMM refused the 2,048-byte command line before boot with fatal error: microVM kernel command line is 2048 bytes; the limit is 2047 bytes plus the terminating NUL, and no guest boot marker appeared.
  • No run fell back to a host CPU profile.

• Left to CI: the change touches only documentation, so nvx.py classify-ci-changes selects no suite (all six outputs are false). That leaves the quality checks, including the Markdown link check, and the required status check.

[Copilot]

🟢 Approval recommended

No active review issues remain for this documentation-only clarification of command-line limits and their enforcement during boot and restore.

No open issues 🎉

What changed in this PR

This documentation-only PR aligns the boot protocol guide with the command-line limit already enforced by OpenVMM, completing the remaining documentation task in #570.

Changes:

• Replaces the 64-KiB limit with 2,048 bytes including the terminating NUL, allowing 2,047 bytes of text.
• Explains why the machine profile rejects oversized command lines before processors run.
• Clarifies that restore rejects oversized saved command lines rather than rewriting them.

File	Description
doc/​design/​5.1-boot-protocol.md	Documents the guest kernel’s command-line limit and its enforcement during boot and restore.

_{Review effort: Balanced}