[PATCH 0/2] s390: Add API Docs for DIAGNOSE 0x318 and fix rst

[PATCH 0/2] s390: Add API Docs for DIAGNOSE 0x318 and fix rst

[Collin Walling]

Adds documentation for the s390-specfic DIAGNOSE 0x318 instruction, as
well as fixes some missing rst symbols for the neighboring entries.

Suggested-by: Cornelia Huck <cohuck@redhat.com>

Collin Walling (2):
  docs: kvm: add documentation for KVM_CAP_S390_DIAG318
  docs: kvm: fix rst formatting

 Documentation/virt/kvm/api.rst | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

-- 
2.26.2

[PATCH 1/2] docs: kvm: add documentation for KVM_CAP_S390_DIAG318

[Collin Walling]

Documentation for the s390 DIAGNOSE 0x318 instruction handling.

Signed-off-by: Collin Walling <walling@linux.ibm.com>
---
 Documentation/virt/kvm/api.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 426f94582b7a..056608e8f243 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -6150,3 +6150,22 @@ KVM can therefore start protected VMs.
 This capability governs the KVM_S390_PV_COMMAND ioctl and the
 KVM_MP_STATE_LOAD MP_STATE. KVM_SET_MP_STATE can fail for protected
 guests when the state change is invalid.
+
+8.24 KVM_CAP_S390_DIAG318
+-------------------------
+
+:Architecture: s390
+
+This capability allows for information regarding the control program that may
+be observed via system/firmware service events. The availability of this
+capability indicates that KVM handling of the register synchronization, reset,
+and VSIE shadowing of the DIAGNOSE 0x318 related information is present.
+
+The information associated with the instruction is an 8-byte value consisting
+of a one-byte Control Program Name Code (CPNC), and a 7-byte Control Program
+Version Code (CPVC). The CPNC determines what environment the control program
+is running in (e.g. Linux, z/VM...), and the CPVC is used for extraneous
+information specific to OS (e.g. Linux version, Linux distribution...)
+
+If this capability is available, then the CPNC and CPVC can be synchronized
+between KVM and userspace via the sync regs mechanism (KVM_SYNC_DIAG318).
-- 
2.26.2

[PATCH 2/2] docs: kvm: fix rst formatting

[Collin Walling]

KVM_CAP_S390_VCPU_RESETS and KVM_CAP_S390_PROTECTED needed
just a little bit of rst touch-up

Signed-off-by: Collin Walling <walling@linux.ibm.com>
---
 Documentation/virt/kvm/api.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 056608e8f243..2d1572d92616 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -6134,16 +6134,17 @@ in CPUID and only exposes Hyper-V identification. In this case, guest
 thinks it's running on Hyper-V and only use Hyper-V hypercalls.
 
 8.22 KVM_CAP_S390_VCPU_RESETS
+-----------------------------
 
-Architectures: s390
+:Architectures: s390
 
 This capability indicates that the KVM_S390_NORMAL_RESET and
 KVM_S390_CLEAR_RESET ioctls are available.
 
 8.23 KVM_CAP_S390_PROTECTED
+---------------------------
 
-Architecture: s390
-
+:Architecture: s390
 
 This capability indicates that the Ultravisor has been initialized and
 KVM can therefore start protected VMs.
-- 
2.26.2

Re: [PATCH 1/2] docs: kvm: add documentation for KVM_CAP_S390_DIAG318

[Cornelia Huck]

On Wed, 24 Jun 2020 16:21:59 -0400
Collin Walling <walling@linux.ibm.com> wrote:

> Documentation for the s390 DIAGNOSE 0x318 instruction handling.
> 
> Signed-off-by: Collin Walling <walling@linux.ibm.com>
> ---
>  Documentation/virt/kvm/api.rst | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 426f94582b7a..056608e8f243 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -6150,3 +6150,22 @@ KVM can therefore start protected VMs.
>  This capability governs the KVM_S390_PV_COMMAND ioctl and the
>  KVM_MP_STATE_LOAD MP_STATE. KVM_SET_MP_STATE can fail for protected
>  guests when the state change is invalid.
> +
> +8.24 KVM_CAP_S390_DIAG318
> +-------------------------
> +
> +:Architecture: s390
> +
> +This capability allows for information regarding the control program that may

Maybe s/allows for/covers/ ?

> +be observed via system/firmware service events. The availability of this
> +capability indicates that KVM handling of the register synchronization, reset,
> +and VSIE shadowing of the DIAGNOSE 0x318 related information is present.
> +
> +The information associated with the instruction is an 8-byte value consisting
> +of a one-byte Control Program Name Code (CPNC), and a 7-byte Control Program
> +Version Code (CPVC). The CPNC determines what environment the control program
> +is running in (e.g. Linux, z/VM...), and the CPVC is used for extraneous
> +information specific to OS (e.g. Linux version, Linux distribution...)
> +
> +If this capability is available, then the CPNC and CPVC can be synchronized
> +between KVM and userspace via the sync regs mechanism (KVM_SYNC_DIAG318).

Anyway,

Reviewed-by: Cornelia Huck <cohuck@redhat.com>

Re: [PATCH 2/2] docs: kvm: fix rst formatting

[Cornelia Huck]

On Wed, 24 Jun 2020 16:22:00 -0400
Collin Walling <walling@linux.ibm.com> wrote:

> KVM_CAP_S390_VCPU_RESETS and KVM_CAP_S390_PROTECTED needed
> just a little bit of rst touch-up
> 

Fixes: 7de3f1423ff9 ("KVM: s390: Add new reset vcpu API")
Fixes: 04ed89dc4aeb ("KVM: s390: protvirt: Add KVM api documentation")

> Signed-off-by: Collin Walling <walling@linux.ibm.com>
> ---
>  Documentation/virt/kvm/api.rst | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 056608e8f243..2d1572d92616 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -6134,16 +6134,17 @@ in CPUID and only exposes Hyper-V identification. In this case, guest
>  thinks it's running on Hyper-V and only use Hyper-V hypercalls.
>  
>  8.22 KVM_CAP_S390_VCPU_RESETS
> +-----------------------------
>  
> -Architectures: s390
> +:Architectures: s390
>  
>  This capability indicates that the KVM_S390_NORMAL_RESET and
>  KVM_S390_CLEAR_RESET ioctls are available.
>  
>  8.23 KVM_CAP_S390_PROTECTED
> +---------------------------
>  
> -Architecture: s390
> -
> +:Architecture: s390
>  
>  This capability indicates that the Ultravisor has been initialized and
>  KVM can therefore start protected VMs.

Reviewed-by: Cornelia Huck <cohuck@redhat.com>

Re: [PATCH 2/2] docs: kvm: fix rst formatting

[Janosch Frank]

[-- Attachment #1.1: Type: text/plain, Size: 1555 bytes --]

On 6/25/20 8:34 AM, Cornelia Huck wrote:
> On Wed, 24 Jun 2020 16:22:00 -0400
> Collin Walling <walling@linux.ibm.com> wrote:
> 
>> KVM_CAP_S390_VCPU_RESETS and KVM_CAP_S390_PROTECTED needed
>> just a little bit of rst touch-up
>>
> 
> Fixes: 7de3f1423ff9 ("KVM: s390: Add new reset vcpu API")
> Fixes: 04ed89dc4aeb ("KVM: s390: protvirt: Add KVM api documentation")

Do we really do that for documentation changes?


> 
>> Signed-off-by: Collin Walling <walling@linux.ibm.com>
>> ---
>>  Documentation/virt/kvm/api.rst | 7 ++++---
>>  1 file changed, 4 insertions(+), 3 deletions(-)
>>
>> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
>> index 056608e8f243..2d1572d92616 100644
>> --- a/Documentation/virt/kvm/api.rst
>> +++ b/Documentation/virt/kvm/api.rst
>> @@ -6134,16 +6134,17 @@ in CPUID and only exposes Hyper-V identification. In this case, guest
>>  thinks it's running on Hyper-V and only use Hyper-V hypercalls.
>>  
>>  8.22 KVM_CAP_S390_VCPU_RESETS
>> +-----------------------------
>>  
>> -Architectures: s390
>> +:Architectures: s390
>>  
>>  This capability indicates that the KVM_S390_NORMAL_RESET and
>>  KVM_S390_CLEAR_RESET ioctls are available.
>>  
>>  8.23 KVM_CAP_S390_PROTECTED
>> +---------------------------
>>  
>> -Architecture: s390
>> -
>> +:Architecture: s390
>>  
>>  This capability indicates that the Ultravisor has been initialized and
>>  KVM can therefore start protected VMs.
> 
> Reviewed-by: Cornelia Huck <cohuck@redhat.com>
> 



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 2/2] docs: kvm: fix rst formatting

[David Hildenbrand]

On 25.06.20 09:07, Janosch Frank wrote:
> On 6/25/20 8:34 AM, Cornelia Huck wrote:
>> On Wed, 24 Jun 2020 16:22:00 -0400
>> Collin Walling <walling@linux.ibm.com> wrote:
>>
>>> KVM_CAP_S390_VCPU_RESETS and KVM_CAP_S390_PROTECTED needed
>>> just a little bit of rst touch-up
>>>
>>
>> Fixes: 7de3f1423ff9 ("KVM: s390: Add new reset vcpu API")
>> Fixes: 04ed89dc4aeb ("KVM: s390: protvirt: Add KVM api documentation")
> 
> Do we really do that for documentation changes?

Had a similar discussion recently, I prefer to just mention the commits
in the commit message like "Introduced in commit ...".

-- 
Thanks,

David / dhildenb

Re: [PATCH 2/2] docs: kvm: fix rst formatting

[David Hildenbrand]

On 24.06.20 22:22, Collin Walling wrote:
> KVM_CAP_S390_VCPU_RESETS and KVM_CAP_S390_PROTECTED needed
> just a little bit of rst touch-up
> 
> Signed-off-by: Collin Walling <walling@linux.ibm.com>
> ---
>  Documentation/virt/kvm/api.rst | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 056608e8f243..2d1572d92616 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -6134,16 +6134,17 @@ in CPUID and only exposes Hyper-V identification. In this case, guest
>  thinks it's running on Hyper-V and only use Hyper-V hypercalls.
>  
>  8.22 KVM_CAP_S390_VCPU_RESETS
> +-----------------------------
>  
> -Architectures: s390
> +:Architectures: s390
>  
>  This capability indicates that the KVM_S390_NORMAL_RESET and
>  KVM_S390_CLEAR_RESET ioctls are available.
>  
>  8.23 KVM_CAP_S390_PROTECTED
> +---------------------------
>  
> -Architecture: s390
> -
> +:Architecture: s390
>  
>  This capability indicates that the Ultravisor has been initialized and
>  KVM can therefore start protected VMs.
> 

Reviewed-by: David Hildenbrand <david@redhat.com>

-- 
Thanks,

David / dhildenb

Re: [PATCH 2/2] docs: kvm: fix rst formatting

[Cornelia Huck]

[-- Attachment #1: Type: text/plain, Size: 581 bytes --]

On Thu, 25 Jun 2020 09:07:43 +0200
Janosch Frank <frankja@linux.ibm.com> wrote:

> On 6/25/20 8:34 AM, Cornelia Huck wrote:
> > On Wed, 24 Jun 2020 16:22:00 -0400
> > Collin Walling <walling@linux.ibm.com> wrote:
> >   
> >> KVM_CAP_S390_VCPU_RESETS and KVM_CAP_S390_PROTECTED needed
> >> just a little bit of rst touch-up
> >>  
> > 
> > Fixes: 7de3f1423ff9 ("KVM: s390: Add new reset vcpu API")
> > Fixes: 04ed89dc4aeb ("KVM: s390: protvirt: Add KVM api documentation")  
> 
> Do we really do that for documentation changes?

Feel free to keep it or leave it :)

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] docs: kvm: add documentation for KVM_CAP_S390_DIAG318

[David Hildenbrand]

On 24.06.20 22:21, Collin Walling wrote:
> Documentation for the s390 DIAGNOSE 0x318 instruction handling.
> 
> Signed-off-by: Collin Walling <walling@linux.ibm.com>
> ---
>  Documentation/virt/kvm/api.rst | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 426f94582b7a..056608e8f243 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -6150,3 +6150,22 @@ KVM can therefore start protected VMs.
>  This capability governs the KVM_S390_PV_COMMAND ioctl and the
>  KVM_MP_STATE_LOAD MP_STATE. KVM_SET_MP_STATE can fail for protected
>  guests when the state change is invalid.
> +
> +8.24 KVM_CAP_S390_DIAG318
> +-------------------------
> +
> +:Architecture: s390
> +
> +This capability allows for information regarding the control program that may
> +be observed via system/firmware service events. The availability of this
> +capability indicates that KVM handling of the register synchronization, reset,
> +and VSIE shadowing of the DIAGNOSE 0x318 related information is present.
> +
> +The information associated with the instruction is an 8-byte value consisting
> +of a one-byte Control Program Name Code (CPNC), and a 7-byte Control Program
> +Version Code (CPVC). The CPNC determines what environment the control program
> +is running in (e.g. Linux, z/VM...), and the CPVC is used for extraneous
> +information specific to OS (e.g. Linux version, Linux distribution...)
> +
> +If this capability is available, then the CPNC and CPVC can be synchronized
> +between KVM and userspace via the sync regs mechanism (KVM_SYNC_DIAG318).
> 

Reviewed-by: David Hildenbrand <david@redhat.com>

-- 
Thanks,

David / dhildenb

Re: [PATCH 1/2] docs: kvm: add documentation for KVM_CAP_S390_DIAG318

[Janosch Frank]

[-- Attachment #1.1: Type: text/plain, Size: 2107 bytes --]

On 6/24/20 10:21 PM, Collin Walling wrote:
> Documentation for the s390 DIAGNOSE 0x318 instruction handling.
> 
> Signed-off-by: Collin Walling <walling@linux.ibm.com>
> ---
>  Documentation/virt/kvm/api.rst | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 426f94582b7a..056608e8f243 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -6150,3 +6150,22 @@ KVM can therefore start protected VMs.
>  This capability governs the KVM_S390_PV_COMMAND ioctl and the
>  KVM_MP_STATE_LOAD MP_STATE. KVM_SET_MP_STATE can fail for protected
>  guests when the state change is invalid.
> +
> +8.24 KVM_CAP_S390_DIAG318
> +-------------------------
> +
> +:Architecture: s390
> +
> +This capability allows for information regarding the control program that may
> +be observed via system/firmware service events. The availability of this

I'm not sure if control program is understood universally, it's a rather
old term to say guest kernel.

How about:

This capability allows a guest to set information about its control
program (i.e. guest kernel type and version). The information is helpful
on system/firmware service events, providing additional data about what
environments are running on the machine.


> +capability indicates that KVM handling of the register synchronization, reset,
> +and VSIE shadowing of the DIAGNOSE 0x318 related information is present.
> +
> +The information associated with the instruction is an 8-byte value consisting
> +of a one-byte Control Program Name Code (CPNC), and a 7-byte Control Program
> +Version Code (CPVC). The CPNC determines what environment the control program
> +is running in (e.g. Linux, z/VM...), and the CPVC is used for extraneous
> +information specific to OS (e.g. Linux version, Linux distribution...)
> +
> +If this capability is available, then the CPNC and CPVC can be synchronized
> +between KVM and userspace via the sync regs mechanism (KVM_SYNC_DIAG318).
> 



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] docs: kvm: add documentation for KVM_CAP_S390_DIAG318

[Collin Walling]

On 6/25/20 3:16 AM, Janosch Frank wrote:
> On 6/24/20 10:21 PM, Collin Walling wrote:
>> Documentation for the s390 DIAGNOSE 0x318 instruction handling.
>>
>> Signed-off-by: Collin Walling <walling@linux.ibm.com>
>> ---
>>  Documentation/virt/kvm/api.rst | 19 +++++++++++++++++++
>>  1 file changed, 19 insertions(+)
>>
>> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
>> index 426f94582b7a..056608e8f243 100644
>> --- a/Documentation/virt/kvm/api.rst
>> +++ b/Documentation/virt/kvm/api.rst
>> @@ -6150,3 +6150,22 @@ KVM can therefore start protected VMs.
>>  This capability governs the KVM_S390_PV_COMMAND ioctl and the
>>  KVM_MP_STATE_LOAD MP_STATE. KVM_SET_MP_STATE can fail for protected
>>  guests when the state change is invalid.
>> +
>> +8.24 KVM_CAP_S390_DIAG318
>> +-------------------------
>> +
>> +:Architecture: s390
>> +
>> +This capability allows for information regarding the control program that may
>> +be observed via system/firmware service events. The availability of this
> 
> I'm not sure if control program is understood universally, it's a rather
> old term to say guest kernel.
> 
> How about:
> 
> This capability allows a guest to set information about its control
> program (i.e. guest kernel type and version). The information is helpful
> on system/firmware service events, providing additional data about what
> environments are running on the machine.
> 
> 

Fair point. I'll add some clarity to this.

>> +capability indicates that KVM handling of the register synchronization, reset,
>> +and VSIE shadowing of the DIAGNOSE 0x318 related information is present.
>> +
>> +The information associated with the instruction is an 8-byte value consisting
>> +of a one-byte Control Program Name Code (CPNC), and a 7-byte Control Program
>> +Version Code (CPVC). The CPNC determines what environment the control program
>> +is running in (e.g. Linux, z/VM...), and the CPVC is used for extraneous
>> +information specific to OS (e.g. Linux version, Linux distribution...)
>> +
>> +If this capability is available, then the CPNC and CPVC can be synchronized
>> +between KVM and userspace via the sync regs mechanism (KVM_SYNC_DIAG318).
>>
> 
> 


-- 
Regards,
Collin

Stay safe and stay healthy

Re: [PATCH 2/2] docs: kvm: fix rst formatting

[Collin Walling]

On 6/25/20 3:09 AM, Cornelia Huck wrote:
> On Thu, 25 Jun 2020 09:07:43 +0200
> Janosch Frank <frankja@linux.ibm.com> wrote:
> 
>> On 6/25/20 8:34 AM, Cornelia Huck wrote:
>>> On Wed, 24 Jun 2020 16:22:00 -0400
>>> Collin Walling <walling@linux.ibm.com> wrote:
>>>   
>>>> KVM_CAP_S390_VCPU_RESETS and KVM_CAP_S390_PROTECTED needed
>>>> just a little bit of rst touch-up
>>>>  
>>>
>>> Fixes: 7de3f1423ff9 ("KVM: s390: Add new reset vcpu API")
>>> Fixes: 04ed89dc4aeb ("KVM: s390: protvirt: Add KVM api documentation")  
>>
>> Do we really do that for documentation changes?
> 
> Feel free to keep it or leave it :)
> 

I'm indifferent. I suppose I'll go with David's suggestion of
"Introduced in commit..."

Thanks for all the feedback. Will sent out v2 shortly.

-- 
Regards,
Collin

Stay safe and stay healthy