feat: add template-level ivshmem opt-in

[zyl1121]

Motivation

CubeSandbox already uses vsock for host/guest communication. That remains a good default abstraction for command, control, and general streaming use cases.

For performance-sensitive data paths, a shared-memory backend can provide better throughput and latency characteristics than a socket stream. ivshmem gives CubeSandbox a way to add that backend without changing the default communication path for existing templates.

This PR exposes ivshmem as an experimental, template-level opt-in. Keeping it template-scoped makes the capability explicit, avoids changing normal sandbox behavior, and keeps normal snapshot/restore flows unchanged unless the template has requested ivshmem support.

What Changed

• Add template-level enableIvshmem support across CubeAPI, CubeMaster, cubemastercli, and the Python SDK.

• Persist the opt-in as an internal CubeMaster annotation.

• Have CubeShim create and clean up one host-side ivshmem backend file per sandbox:

  • /dev/shm/ivshmem-{sandbox_id}

• Retarget existing snapshot ivshmem devices to the new sandbox backend path during restore.

• Keep ivshmem disabled by default.

• Avoid injecting ivshmem into existing non-ivshmem templates or snapshots.

• Add public examples for host-side mmap benchmarking and minimal host/guest communication over an ivshmem-backed ring buffer.

Validation

Focused tests:

cd CubeAPI && cargo test --locked services::templates::tests
cd CubeMaster && go test ./pkg/templatecenter ./cmd/cubemastercli/commands/cubebox ./pkg/service/sandbox/types
cd hypervisor && cargo test --locked update_ivshmem
cd CubeShim/shim && cargo test --locked ivshmem

The following validation was also run on a real verification server: Tencent Lighthouse, 4 vCPU, 8 GB memory, PVM enabled, Linux kernel 6.6.69-1.1.cubesandbox.oc9.x86_64, AMD EPYC 7K62 CPU.

Guest-visible device and communication:

• Built an ivshmem-enabled template successfully.
• Verified the sandbox used /dev/shm/ivshmem-{sandbox_id} as the host backend path, with a 1 MiB backend file and 0600 permissions.
• Verified the shim process mapped the sandbox shm backend in /proc/<pid>/maps.
• Verified the guest enumerated the ivshmem PCI device as vendor/device 0x1af4/0x1110.
• Verified guest resource2 and resource2_wc were present.
• Verified Host -> Guest and Guest -> Host byte exchange through the guest resource2 mapping.
• Verified examples/ivshmem/ivshmem_ring_demo.py passed host/guest communication.

Snapshot, clone, and rollback lifecycle:

• create/delete: shared-memory read/write succeeded, and /dev/shm/ivshmem-{sandbox_id} was cleaned up after delete.
• pause/resume: shared-memory read/write succeeded before pause and after resume.
• snapshot/rollback: shared-memory read/write succeeded before snapshot and after rollback.
• commit+create: the source sandbox and cloned sandbox used different ivshmem shm paths, and shared-memory read/write succeeded in both sandboxes.
• 5-round create/read-write/delete soak passed with shm cleanup after every round.
• 3 concurrent sandbox create/read-write/delete checks passed with independent shm cleanup.

Default behavior and non-opt-in regression:

• A normal non-ivshmem sandbox did not create an ivshmem shm file.
• A normal snapshot/restore regression preserved state and did not create an ivshmem shm file on the restored clone.
• Restore retargeting was verified only for snapshots that already contain an ivshmem device.

Performance Check

The benchmark compared an ivshmem shared-memory ring buffer with a raw vsock stream on the same host. The guest side used a C helper for both paths.

These numbers are included as a sanity check for the experimental data path, not as a stable performance guarantee.

Benchmark	Direction	Workload / runs	ivshmem ring avg	raw vsock stream avg	Improvement
Throughput	Host → Guest	512 MiB total, 64 KiB chunks, 3 runs	6123.90 MB/s	612.88 MB/s	~10.0×
Throughput	Guest → Host	512 MiB total, 64 KiB chunks, 3 runs	18418.13 MB/s	606.07 MB/s	~30.4×
Throughput	Host → Guest	64 MiB total, 64 KiB chunks, 1 run	8814.47 MB/s	612.51 MB/s	~14.4×
Throughput	Guest → Host	64 MiB total, 64 KiB chunks, 1 run	19931.80 MB/s	835.03 MB/s	~23.9×
Latency	8 B sample	Collected in the 64 MiB one-off run	0.73 μs/op	97.71 μs/op	~134× lower
Latency	8 B sample	Collected in the 512 MiB one-off run	4.70 μs/op	88.76 μs/op	~18.9× lower

The two latency rows are separate one-off samples collected by the same guest-C benchmark script in different throughput runs. They are not a 3-run latency average.

Additional smoke checks:

These Python-based E2E checks validate API wiring, sandbox lifecycle, shared-memory access, and cleanup behavior. They are not intended to represent the ivshmem data-path ceiling because the demo uses per-message acknowledgements, Python-side polling loops, mmap.flush() on each round, and Python payload generation and verification on both sides.

• Python E2E smoke benchmark, 64 KiB payload, 3 runs:
  • Host -> Guest stayed in the 13.08-14.06 MB/s range.
  • Guest -> Host stayed in the 3.93-4.10 MB/s range.
  • All sandboxes were deleted and shm files were cleaned.
• Python E2E smoke benchmark, 4 KiB payload, 3 concurrent runs:
  • 3/3 concurrent sandbox create/communication/delete runs passed.
  • shm files were cleaned after the runs.
• Host-only backend mmap benchmark:
  • 13067.18-18144.02 MB/s across 3 repeated runs.

Scope

This PR adds experimental template-level ivshmem opt-in.

It intentionally does not:

• enable ivshmem by default
• replace the default stdio/vsock path
• change normal non-ivshmem sandbox creation
• change normal non-ivshmem snapshot/restore behavior
• inject ivshmem into existing non-ivshmem templates or snapshots

Restore-time ivshmem handling is limited to snapshots that already contain an ivshmem device. Existing non-ivshmem templates and snapshots keep their original behavior.

Notes

The ivshmem backend file is sandbox-scoped and uses /dev/shm/ivshmem-{sandbox_id} on the host.