Re: [PATCH V4 2/2] kvm/x86 : add document for coalesced pio

[Stefan Hajnoczi]

On Fri, Aug 31, 2018 at 12:17:21AM +0800, Peng Hao wrote:
> Signed-off-by: Peng Hao <peng.hao2@xxxxxxxxxx>
> ---
>  Documentation/virtual/kvm/00-INDEX          |  2 ++
>  Documentation/virtual/kvm/coalesced-pio.txt | 15 +++++++++++++++
>  2 files changed, 17 insertions(+)
>  create mode 100644 Documentation/virtual/kvm/coalesced-pio.txt
> 
> diff --git a/Documentation/virtual/kvm/00-INDEX b/Documentation/virtual/kvm/00-INDEX
> index 3492458..4b7a37b 100644
> --- a/Documentation/virtual/kvm/00-INDEX
> +++ b/Documentation/virtual/kvm/00-INDEX
> @@ -9,6 +9,8 @@ arm
>  	- internal ABI between the kernel and HYP (for arm/arm64)
>  cpuid.txt
>  	- KVM-specific cpuid leaves (x86).
> +coalesced-pio.txt
> +	- KVM_CAP_COALESCED_PIO

Please document KVM_(UN)REGISTER_COALESCED_MMIO in api.txt instead of
creating a new file.  This is part of the ioctl API and it should be
documented there.

The first patch could document the existing
KVM_(UN)REGISTER_COALESCED_MMIO ioctls and then a second patch could add
PIO.

> diff --git a/Documentation/virtual/kvm/coalesced-pio.txt b/Documentation/virtual/kvm/coalesced-pio.txt
> new file mode 100644
> index 0000000..38dac11
> --- /dev/null
> +++ b/Documentation/virtual/kvm/coalesced-pio.txt
> @@ -0,0 +1,15 @@
> +Linux KVM Coalesced PIO:
> +============================
> +Coalesced pio is base on coalesced mmio. When the write access to a port

s/base/based/

> +of a device does a simple work (just like setting a register ID or address
> +index), then we can use coalesced pio.

"Simple work" is vague and does not describe when or when not to use
coalesced I/O.

I think the point of coalesced I/O is:

  Coalesced I/O is a performance optimization that defers hardware
  register write emulation so that userspace exits are avoided.  It is
  typically used to reduce the overhead of emulating frequently accessed
  hardware registers.

(and then your next paragraph below explains how it works)

> +
> +Setting a port as coalesced pio, the write access to the port don't need to
> +exit to userspace, and just record the value in shared coalesced ring in kernel.

Minor tweaks to the wording and s/port/hardware register/ so this can be
used to document both PIO and MMIO:

  When a hardware register is configured for coalesced I/O, write accesses
  do not exit to userspace and their value is recorded in a shared
  coalesced ring in the kernel.

> +Then following access to another port of the same device which relys on the
> +first port's setting or a read access to the first port will set the previous
> +write value of the first port firstly in usersapce according to the shared
> +coalesced ring.

Similar tweaks:

  A read access to the hardware register or a write access to another
  hardware register on the same device which relies on the first hardware
  register's value will cause the shared coalesced ring to be processed by
  userspace before emulating the current access.

> +
> +Coalesced pio can be used for rtc 0x70 port, pci-host config port, virtio-pci
> +config port and so on.
> -- 
> 1.8.3.1
>

Attachment: signature.asc
Description: PGP signature