Re: [PATCH docs/guest-common/qemu-server v4 0/7] add new pci passthrough specific hookscript phase

["Jakob Klocker" <j.klocker@proxmox.com>]

Tested this on an NVIDIA RTX A5000 (SR-IOV vGPU) plus plain PCI
passthrough.

What I tested:
- Confirmed the state of the VM and the PCIe devices in the 
  `post-pci-prepare` hook:
    - VM status is `stopped` with no PID, QEMU hasn't launched yet
    - The device is prepared at this point: for the nvidia SR-IOV
      vGPU, `current_vgpu_type` on the VF goes from `0` (pre-start)
      to `2170` (post-pci-prepare); for plain passthrough the device
      is bound to `vfio-pci`.
    - `PVE_HOOK_ID` and `PVE_HOOK_PCIID` correctly identify the config
      slot and the specific device.
    - The hook fires once per prepared PCI function.
- Successfully wrote `frame_rate_limiter=0` via the `post-pci-prepare`
  hook (verified via read-back). Note: the value needs a trailing
  newline -- without it, it's written truncated and the VF ends up in
  a state where QEMU fails to open it (device start fails with an I/O
  error).
- Checked that devices are cleaned up via `cleanup_pci_devices` if the
  hookscript dies.

Backwards-compatibility concern (thanks to Elias):
the `post-pci-prepare` hook is called with `stop_on_error=1`, and the
example script dies on unknown phases (`else { die }`). Existing
hookscripts modeled on the old example will therefore abort VM start
as soon as they encounter the new phase. Might be worth either calling
this phase non-fatally, or noting it in the docs/example.

The nits mentioned on the patches are of course none blocking, so once
the backwards-compatibility concern is addressed/acknowleded
consider this:

Reviewed-by: Jakob Klocker <j.klocker@proxmox.com>
Tested-by: Jakob Klocker <j.klocker@proxmox.com>

On Tue Aug 25, 2026 at 3:54 PM CEST, Dominik Csapak wrote:
> this series adds a new phase to the guest hookscript that is called for each
> passed throug pci device after it's prepared, but before the qemu process is
> started.
>
> See the last qemu-server commit for why that is interesting.
>
> changes from v4:
> * rebase on current master
> * fix `local %ENV` clearing the whole environment instead of
>   just shadowing it, so the hookscript keeps the inherited environment
> * split the uuid handling out of the refactoring commit
> * call the hookscript once for both the mdev and the plain passthrough
>   case instead of duplicating the call in both branches
> * add missing `use PVE::GuestHelpers;`
> * move the new phase before 'post-start' to match the actual call
>   order, document that PVE_HOOK_MDEV_UUID is only set for mdevs, and
>   mention what the phase is useful for
> * fix typos
>
> changes from v3:
> * split unrelated logic/refactoring changes out to their own patches
> * fix typos
>
> changes from v2:
> * rebase on current master
> * prefix hook script env variables with 'PVE_HOOK_'
>
>
> pve-guest-common:
>
> Dominik Csapak (1):
>   helpers: exec hookscript: add optional parameters
>
>  src/PVE/GuestHelpers.pm | 12 +++++++++++-
>  1 file changed, 11 insertions(+), 1 deletion(-)
>
>
> qemu-server:
>
> Dominik Csapak (5):
>   pci: mdev preparation: always generate local uuid first
>   pci: nvidia vgpu: correct wrong comment about uuid
>   pci: factor 'prepare_pci_devices' out to PVE::QemuServer::PCI module
>   pci: preparation: mdev: only generate uuid once
>   pci: call hookscript for each prepared pci device
>
>  src/PVE/QemuServer.pm     | 45 ++++++---------------------------
>  src/PVE/QemuServer/PCI.pm | 52 +++++++++++++++++++++++++++++++++++++++
>  2 files changed, 60 insertions(+), 37 deletions(-)
>
>
> pve-docs:
>
> Dominik Csapak (1):
>   examples: add new hookscript phase to example hookscript
>
>  examples/guest-example-hookscript.pl | 29 ++++++++++++++++++++++++++++
>  1 file changed, 29 insertions(+)
>
>
> Summary over all repositories:
>   4 files changed, 100 insertions(+), 38 deletions(-)