virtio: add peek support to VirtioQueue

[jstarks]

Add try_peek and peek methods to VirtioQueue that return a PeekedWork handle for inspecting the next available descriptor without advancing the available index. This allows a device to examine payload contents before deciding whether to consume the descriptor. Dropping a PeekedWork without calling consume is a no-op -- the descriptor stays in the available ring for the next call.

To support this, refactor the queue internals to separate availability checking from index advancement:

• Split QueueCore::try_next_work into try_peek_work + advance.
• Add SplitQueueGetWork::advance and PackedQueueGetWork::advance methods that each handle their own index bookkeeping.
• Hoist descriptor_index out of per-queue-type completion contexts into QueueWork directly, since both split and packed queues need it.
• Extract payload-reading helpers (read_from_payload, read_from_payload_at_offset, readable_payload_length) as free functions shared between VirtioQueueCallbackWork and PeekedWork.

Also simplify the Stream implementation: poll_next_buffer now returns Poll<Result<..., Error>> instead of wrapping in an extra Option, since the stream never yields None before an error.

[Copilot]

Pull request overview

This PR adds “peek” support to the virtio queue abstraction so devices can inspect the next available descriptor without consuming it, and refactors queue internals to separate availability checks from index advancement.

Changes:

• Add VirtioQueue::{try_peek, peek} and a PeekedWork handle that can later be consume()d into a normal VirtioQueueCallbackWork.
• Refactor QueueCoreGetWork and split/packed queue implementations to split “peek” vs “advance” behavior and move descriptor_index into QueueWork.
• Extract shared payload-reading helpers and simplify the Stream implementation to never yield None.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
vm/devices/virtio/virtio/src/queue/split.rs	Split queue: make availability checking non-advancing and add explicit advance().
vm/devices/virtio/virtio/src/queue/packed.rs	Packed queue: add advance(count) and adjust completion context construction/access.
vm/devices/virtio/virtio/src/queue.rs	Core queue refactor: introduce try_peek_work + advance, move descriptor index into QueueWork.
vm/devices/virtio/virtio/src/common.rs	Add PeekedWork, shared payload read helpers, and streamline Stream polling.

---

You can also share your feedback on Copilot code review. Take the survey.

[github-actions]

⚠️ Unsafe Code Detected

This PR modifies files containing unsafe Rust code. Extra scrutiny is required during review.

For more on why we check whole files, instead of just diffs, check out the Rustonomicon

[Copilot]

Pull request overview

This PR adds “peek” support to the virtio queue abstraction so devices can inspect the next available descriptor without consuming it, enabling conditional consumption based on payload contents. It refactors queue internals to separate availability checking from advancing the available index, and updates the async Stream surface to remove an unnecessary Option layer.

Changes:

• Add VirtioQueue::try_peek / VirtioQueue::peek returning a PeekedWork handle, with consume() to advance and convert into normal completion work.
• Refactor QueueCoreGetWork into try_peek_work + advance, and move descriptor_index onto QueueWork.
• Add tests validating that peeking does not advance for both split and packed queues.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
vm/devices/virtio/virtio/src/common.rs	Adds PeekedWork, shared payload read helpers, and stream/poll refactor integration in VirtioQueue.
vm/devices/virtio/virtio/src/queue.rs	Splits “peek vs advance” mechanics in QueueCoreGetWork and adjusts QueueWork/completion context layout.
vm/devices/virtio/virtio/src/queue/split.rs	Refactors split queue availability checking to avoid advancing the index until advance().
vm/devices/virtio/virtio/src/queue/packed.rs	Refactors packed queue advancement and adjusts completion context to support deferred advancement.
vm/devices/virtio/virtio/src/tests.rs	Adds split/packed tests for peek semantics (no-advance, peek-then-next behavior).

---

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

This PR adds non-consuming “peek” support to the core virtio queue API (VirtioQueue) by introducing try_peek/peek returning a PeekedWork handle, and refactors queue internals so availability checks are separated from index advancement. This enables devices to inspect the next descriptor payload before deciding to consume it.

Changes:

• Add VirtioQueue::{try_peek, peek} and PeekedWork with consume() to explicitly advance after peeking.
• Refactor queue internals: split try_next_work into try_peek_work + advance, and move descriptor index into QueueWork.
• Add unit tests validating that peeking does not advance for both split and packed queues.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
vm/devices/virtio/virtio/src/common.rs	Introduces PeekedWork, adds try_peek/peek, and extracts shared payload-reading helpers.
vm/devices/virtio/virtio/src/queue.rs	Refactors core work retrieval into peek + explicit advancement; moves descriptor index into QueueWork.
vm/devices/virtio/virtio/src/queue/split.rs	Splits availability checking from index advancement for split queues; adjusts completion API.
vm/devices/virtio/virtio/src/queue/packed.rs	Adds advance(count) for packed queues and refactors completion context construction.
vm/devices/virtio/virtio/src/tests.rs	Adds new tests covering peek behavior for split and packed queues.

---

You can also share your feedback on Copilot code review. Take the survey.