[PATCH 1/1] Documentation: hyperv: Update documentation for sending VMBus packets

[PATCH 1/1] Documentation: hyperv: Update documentation for sending VMBus packets

[Michael Kelley]

The functions for sending VMBus packets have been simplified.
vmbus_sendpacket_mpb_desc() can target multiple ranges, and
vmbus_sendpacket_pagebuffer() has been removed. Update the
documentation accordingly.

Fixes: 45a442fe369e ("Drivers: hv: vmbus: Remove vmbus_sendpacket_pagebuffer()")
Cc: stable@vger.kernel.org
Signed-off-by: Michael Kelley <mhklinux@outlook.com>
---
The Fixes: tag reflects the code change that was made. The
documentation update should have been included with the
original code change.

 Documentation/virt/hyperv/vmbus.rst | 13 ++++---------
 1 file changed, 4 insertions(+), 9 deletions(-)

diff --git a/Documentation/virt/hyperv/vmbus.rst b/Documentation/virt/hyperv/vmbus.rst
index 654bb4849972..77a437969b49 100644
--- a/Documentation/virt/hyperv/vmbus.rst
+++ b/Documentation/virt/hyperv/vmbus.rst
@@ -137,18 +137,13 @@ control message contains a list of GPAs that describe the data
 buffer.  For example, the storvsc driver uses this approach to
 specify the data buffers to/from which disk I/O is done.
 
-Three functions exist to send VMBus channel messages:
+Two functions exist to send VMBus channel messages:
 
 1. vmbus_sendpacket():  Control-only messages and messages with
    embedded data -- no GPAs
-2. vmbus_sendpacket_pagebuffer(): Message with list of GPAs
-   identifying data to transfer.  An offset and length is
-   associated with each GPA so that multiple discontinuous areas
-   of guest memory can be targeted.
-3. vmbus_sendpacket_mpb_desc(): Message with list of GPAs
-   identifying data to transfer.  A single offset and length is
-   associated with a list of GPAs.  The GPAs must describe a
-   single logical area of guest memory to be targeted.
+2. vmbus_sendpacket_mpb_desc(): Message with one or more data ranges
+   to target. Each range consists of a single offset and length plus
+   a list of GPAs that describe a logical area of guest memory.
 
 Historically, Linux guests have trusted Hyper-V to send well-formed
 and valid messages, and Linux drivers for synthetic devices did not
-- 
2.25.1

Re: [PATCH 1/1] Documentation: hyperv: Update documentation for sending VMBus packets

[Naman Jain]

On 10/9/2026 8:36 AM, Michael Kelley wrote:
> The functions for sending VMBus packets have been simplified.
> vmbus_sendpacket_mpb_desc() can target multiple ranges, and
> vmbus_sendpacket_pagebuffer() has been removed. Update the
> documentation accordingly.
> 
> Fixes: 45a442fe369e ("Drivers: hv: vmbus: Remove vmbus_sendpacket_pagebuffer()")
> Cc: stable@vger.kernel.org
> Signed-off-by: Michael Kelley <mhklinux@outlook.com>
> ---
> The Fixes: tag reflects the code change that was made. The
> documentation update should have been included with the
> original code change.
> 
>   Documentation/virt/hyperv/vmbus.rst | 13 ++++---------
>   1 file changed, 4 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/virt/hyperv/vmbus.rst b/Documentation/virt/hyperv/vmbus.rst
> index 654bb4849972..77a437969b49 100644
> --- a/Documentation/virt/hyperv/vmbus.rst
> +++ b/Documentation/virt/hyperv/vmbus.rst
> @@ -137,18 +137,13 @@ control message contains a list of GPAs that describe the data
>   buffer.  For example, the storvsc driver uses this approach to
>   specify the data buffers to/from which disk I/O is done.
>   
> -Three functions exist to send VMBus channel messages:
> +Two functions exist to send VMBus channel messages:
>   
>   1. vmbus_sendpacket():  Control-only messages and messages with
>      embedded data -- no GPAs
> -2. vmbus_sendpacket_pagebuffer(): Message with list of GPAs
> -   identifying data to transfer.  An offset and length is
> -   associated with each GPA so that multiple discontinuous areas
> -   of guest memory can be targeted.
> -3. vmbus_sendpacket_mpb_desc(): Message with list of GPAs
> -   identifying data to transfer.  A single offset and length is
> -   associated with a list of GPAs.  The GPAs must describe a
> -   single logical area of guest memory to be targeted.
> +2. vmbus_sendpacket_mpb_desc(): Message with one or more data ranges
> +   to target. Each range consists of a single offset and length plus
> +   a list of GPAs that describe a logical area of guest memory.
>   
>   Historically, Linux guests have trusted Hyper-V to send well-formed
>   and valid messages, and Linux drivers for synthetic devices did not

vmbus_sendpacket_getid() is also part of the exported VMBus API and has
an active caller in pci-hyperv.c. It might be useful to include it here
and explain that it uses the same packet format as vmbus_sendpacket(),
but additionally returns the transaction ID assigned to the packet.

Otherwise, the update LGTM.

Reviewed-by: Naman Jain <namjain@linux.microsoft.com>

Thanks,
Naman Jain

RE: [PATCH 1/1] Documentation: hyperv: Update documentation for sending VMBus packets

[Michael Kelley]

From: Naman Jain <namjain@linux.microsoft.com> Sent: Thursday, October 8, 2026 9:39 PM
> 
> On 10/9/2026 8:36 AM, Michael Kelley wrote:
> > The functions for sending VMBus packets have been simplified.
> > vmbus_sendpacket_mpb_desc() can target multiple ranges, and
> > vmbus_sendpacket_pagebuffer() has been removed. Update the
> > documentation accordingly.
> >
> > Fixes: 45a442fe369e ("Drivers: hv: vmbus: Remove vmbus_sendpacket_pagebuffer()")
> > Cc: stable@vger.kernel.org
> > Signed-off-by: Michael Kelley <mhklinux@outlook.com>
> > ---
> > The Fixes: tag reflects the code change that was made. The
> > documentation update should have been included with the
> > original code change.
> >
> >   Documentation/virt/hyperv/vmbus.rst | 13 ++++---------
> >   1 file changed, 4 insertions(+), 9 deletions(-)
> >
> > diff --git a/Documentation/virt/hyperv/vmbus.rst
> b/Documentation/virt/hyperv/vmbus.rst
> > index 654bb4849972..77a437969b49 100644
> > --- a/Documentation/virt/hyperv/vmbus.rst
> > +++ b/Documentation/virt/hyperv/vmbus.rst
> > @@ -137,18 +137,13 @@ control message contains a list of GPAs that describe the data
> >   buffer.  For example, the storvsc driver uses this approach to
> >   specify the data buffers to/from which disk I/O is done.
> >
> > -Three functions exist to send VMBus channel messages:
> > +Two functions exist to send VMBus channel messages:
> >
> >   1. vmbus_sendpacket():  Control-only messages and messages with
> >      embedded data -- no GPAs
> > -2. vmbus_sendpacket_pagebuffer(): Message with list of GPAs
> > -   identifying data to transfer.  An offset and length is
> > -   associated with each GPA so that multiple discontinuous areas
> > -   of guest memory can be targeted.
> > -3. vmbus_sendpacket_mpb_desc(): Message with list of GPAs
> > -   identifying data to transfer.  A single offset and length is
> > -   associated with a list of GPAs.  The GPAs must describe a
> > -   single logical area of guest memory to be targeted.
> > +2. vmbus_sendpacket_mpb_desc(): Message with one or more data ranges
> > +   to target. Each range consists of a single offset and length plus
> > +   a list of GPAs that describe a logical area of guest memory.
> >
> >   Historically, Linux guests have trusted Hyper-V to send well-formed
> >   and valid messages, and Linux drivers for synthetic devices did not
> 
> vmbus_sendpacket_getid() is also part of the exported VMBus API and has
> an active caller in pci-hyperv.c. It might be useful to include it here
> and explain that it uses the same packet format as vmbus_sendpacket(),
> but additionally returns the transaction ID assigned to the packet.
> 

Good point.  I'll add it. I know enough about the _getid() variant to
properly document it.

Michael