Re: [PATCH docs v4 7/7] examples: add new hookscript phase to example hookscript

["Elias Huhsovitz" <e.huhsovitz@proxmox.com>]

Comments inline.

On Tue Aug 25, 2026 at 3:54 PM CEST, Dominik Csapak wrote:
> qemu-server has a new phase 'post-pci-prepare' that is called for vms
> with pci passthrough for each device prepared.
>
> add that to the example hookscript and explain when it's called and its
> parameters with a comment.
>
> Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
> ---
>  examples/guest-example-hookscript.pl | 29 ++++++++++++++++++++++++++++
>  1 file changed, 29 insertions(+)
>
> diff --git a/examples/guest-example-hookscript.pl b/examples/guest-example-hookscript.pl
> index 1cce2e3..02e7e7d 100755
> --- a/examples/guest-example-hookscript.pl
> +++ b/examples/guest-example-hookscript.pl
> @@ -31,6 +31,35 @@ if ($phase eq 'pre-start') {
>      # print "preparations failed, aborting."
>      # exit(1);
>  
> +} elsif ($phase eq 'post-pci-prepare') {

The example hookscript ends with 

 else {
     die "got unknown phase '$phase'\n";
 }	

Adding this new phase would then result in a breaking change.
Current hookscripts do not check for 'post-pci-prepare', falling back to
the else branch causing --> die "got unknown phase '$phase'\n";

So all vms using a passed-thorugh GPU would have to update their hookscript to respect
the new phase in order to avoid dying.

I suggest 3 ways of handling this:

A:

Warn users in advance, so they are ready for the switch.

B:

Warn users in advance and change the 

do not die at the end of a hookscript, e.g.

 else {
     warn "got unknown phase '$phase'\n";
 }

(altough this might defeat the purpose of using $stop_on_error=1 when
executing the hookscript)

C:

seperate hookscripts for each phase. You would have
* pre-start.pl
* post-pci-prepare.pl
* post-start.pl
* pre-stop.pl
* post-stop.pl

When no hookscript for a phase (e.g. post-pci-prepare) exists, the
call to 

PVE::GuestHelpers::exec_hookscript($conf, $vmid, 'post-pci-prepare', 1, $params);

is never made, treating them optional for each phase.

Although this would introduce significant overhead for simple uses, it
would resolve this issue in "cleaner" way IMHO.


All 3 Options that came to mind are not very elegant. Is there some
obvious solution that I am missing?


> +
> +    # Only called for virtual machines, not containers.
> +    #
> +    # This phase will be called for each pci device that is passed through,
> +    # after it was prepared by the Proxmox VE stack. In other words when either
> +    # * the mdev/vGPU was created
> +    # * the driver was changed to vfio-pci and the device was reset
> +    #
> +    # This phase can be useful to do additional preparation that the Proxmox VE
> +    # stack does not do, like setting vgpu_params for NVIDIA vGPU.
> +    #
> +    # This phase has 3 additional parameters (one optional) given via the environment:
> +
> +    # the id from the config, e.g. 'hostpci0'
> +    my $hostpci_id = $ENV{PVE_HOOK_ID};
> +
> +    # the pciid of the passed through device or the underlying device in case of an mdev/vGPU
> +    # e.g. '0000:01:00.0'
> +    my $pciid = $ENV{PVE_HOOK_PCIID};
> +
> +    # the uuid of the mediated device if it was one,
> +    # e.g. '00000001-0000-0000-0000-000000008006'
> +    # This is not set if the pci device is not an mdev.
> +    my $mdev_uuid = $ENV{PVE_HOOK_MDEV_UUID};
> +
> +    print "Prepared PCI device for $hostpci_id with pciid: $pciid.\n";
> +    print "It is a mediated device with UUID: $mdev_uuid\n" if $mdev_uuid;
> +
>  } elsif ($phase eq 'post-start') {
>  
>      # Second phase 'post-start' will be executed after the guest