s390: Add API Docs for DIAGNOSE 0x318 and fix rst
Subsystems (3)
cover s390: Add API Docs for DIAGNOSE 0x318 and fix rst
Adds documentation for the s390-specfic DIAGNOSE 0x318 instruction, as well as fixes some missing rst symbols for the neighboring entries.
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(-)
Signature · 1 line
2.26.2
PATCH 1/2 docs: kvm: add documentation for KVM_CAP_S390_DIAG318
Documentation for the s390 DIAGNOSE 0x318 instruction handling.
--- Documentation/virt/kvm/api.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+)
Documentation/virt/kvm/api.rst +19 -0
@@ -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).
Signature · 1 line
2.26.2
Re: [PATCH 1/2] docs: kvm: add documentation for KVM_CAP_S390_DIAG318
Quoted 12 lines · On Wed, 24 Jun 2020 16:21:59 -0400 Collin Walling <[email protected]> wrote:
Documentation for the s390 DIAGNOSE
0x318instruction handling.Signed-off-by Collin Walling <[email protected]>--- Documentation/virt/kvm/api.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+)Documentation/virt/kvm/api.rst +0
-0
Documentation/virt/kvm/api.rst KVM can therefore start protected VMs. · line 6159
Quoted 10 lines
Documentation/virt/kvm/api.rst +7
-0@@ -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/ ?
Documentation/virt/kvm/api.rst KVM can therefore start protected VMs. · line 6171
Quoted 12 lines
Documentation/virt/kvm/api.rst +12
-0+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,
Re: [PATCH 1/2] docs: kvm: add documentation for KVM_CAP_S390_DIAG318
In reply to Collin WallingQuoted 25 lines · Collin Walling
Documentation for the s390 DIAGNOSE
0x318instruction handling.Signed-off-by Collin Walling <[email protected]>--- Documentation/virt/kvm/api.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+)Documentation/virt/kvm/api.rst +9
-0@@ -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,
Documentation/virt/kvm/api.rst KVM can therefore start protected VMs. · line 6171
Quoted 10 lines
Documentation/virt/kvm/api.rst +10
-0+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).
Signature · 3 lines
Thanks, David / dhildenb
Re: [PATCH 1/2] docs: kvm: add documentation for KVM_CAP_S390_DIAG318
In reply to Collin WallingQuoted 13 lines · Collin Walling
Documentation for the s390 DIAGNOSE
0x318instruction handling.Signed-off-by Collin Walling <[email protected]>--- Documentation/virt/kvm/api.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+)Documentation/virt/kvm/api.rst +0
-0@@ -6150,3 +6150,22 @@ KVM can therefore start protected VMs. This capability governs the KVM_S390_PV_COMMAND ioctl and the
Documentation/virt/kvm/api.rst KVM can therefore start protected VMs. · line 6160
Quoted 10 lines
Documentation/virt/kvm/api.rst +8
-0KVM_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.
Quoted 12 lines
Documentation/virt/kvm/api.rst +11
-0+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).
Re: [PATCH 1/2] docs: kvm: add documentation for KVM_CAP_S390_DIAG318
Quoted 28 lines · Janosch Frank
Quoted 13 lines · Collin Walling
Documentation for the s390 DIAGNOSE
0x318instruction handling.Signed-off-by Collin Walling <[email protected]>--- Documentation/virt/kvm/api.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+)Documentation/virt/kvm/api.rst +0
-0@@ -6150,3 +6150,22 @@ KVM can therefore start protected VMs. This capability governs the KVM_S390_PV_COMMAND ioctl and theDocumentation/virt/kvm/api.rst KVM can therefore start protected VMs. · line 6160
Quoted 10 lines
Documentation/virt/kvm/api.rst +8
-0KVM_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 thisI'm not sure if control program is understood universally, it's a rather old term to say guest kernel.
Quoted 8 lines
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.
Quoted 14 lines
Quoted 12 lines
Documentation/virt/kvm/api.rst +11
-0+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).
Signature · 4 lines
Regards, Collin Stay safe and stay healthy
PATCH 2/2 docs: kvm: fix rst formatting
In reply to Collin WallingKVM_CAP_S390_VCPU_RESETS and KVM_CAP_S390_PROTECTED needed just a little bit of rst touch-up
--- Documentation/virt/kvm/api.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)
Documentation/virt/kvm/api.rst +4 -3
@@ -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.
Signature · 1 line
2.26.2
Re: [PATCH 2/2] docs: kvm: fix rst formatting
Quoted 3 lines · On Wed, 24 Jun 2020 16:22:00 -0400 Collin Walling <[email protected]> wrote:
KVM_CAP_S390_VCPU_RESETSandKVM_CAP_S390_PROTECTEDneeded just a little bit of rst touch-up
Quoted 20 lines
Signed-off-by Collin Walling <[email protected]>--- Documentation/virt/kvm/api.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)Documentation/virt/kvm/api.rst +2
-1@@ -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.
Documentation/virt/kvm/api.rst in CPUID and only exposes Hyper-V identification. In this case, guest · line 6150
Quoted 10 lines
Documentation/virt/kvm/api.rst +2
-28.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.
Re: [PATCH 2/2] docs: kvm: fix rst formatting
Quoted 9 lines · Cornelia Huck
Quoted 3 lines · On Wed, 24 Jun 2020 16:22:00 -0400 Collin Walling <[email protected]> wrote:
KVM_CAP_S390_VCPU_RESETSandKVM_CAP_S390_PROTECTEDneeded just a little bit of rst touch-upFixes 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?
Quoted 34 lines
Quoted 21 lines
Signed-off-by Collin Walling <[email protected]>--- Documentation/virt/kvm/api.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)Documentation/virt/kvm/api.rst +2
-1@@ -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.Documentation/virt/kvm/api.rst in CPUID and only exposes Hyper-V identification. In this case, guest · line 6150
Quoted 10 lines
Documentation/virt/kvm/api.rst +2
-28.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 <[email protected]>
Re: [PATCH 2/2] docs: kvm: fix rst formatting
Quoted 4 lines · Janosch Frank
Quoted 3 lines · Cornelia Huck
On Wed, 24 Jun 2020 16:22:00 -0400
Collin Walling <[email protected]> wrote:
Quoted 8 lines
Quoted 6 lines
Quoted 3 lines
KVM_CAP_S390_VCPU_RESETSandKVM_CAP_S390_PROTECTEDneeded just a little bit of rst touch-upFixes 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 ...".
Signature · 3 lines
Thanks, David / dhildenb
Re: [PATCH 2/2] docs: kvm: fix rst formatting
In reply to Janosch FrankQuoted 4 lines · On Thu, 25 Jun 2020 09:07:43 +0200 Janosch Frank <[email protected]> wrote:
Quoted 3 lines · Cornelia Huck
On Wed, 24 Jun 2020 16:22:00 -0400
Collin Walling <[email protected]> wrote:
Quoted 8 lines
Quoted 6 lines
Quoted 3 lines
KVM_CAP_S390_VCPU_RESETSandKVM_CAP_S390_PROTECTEDneeded just a little bit of rst touch-upFixes 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 :)
Re: [PATCH 2/2] docs: kvm: fix rst formatting
Quoted 11 lines · Cornelia Huck
Quoted 8 lines · On Thu, 25 Jun 2020 09:07:43 +0200 Janosch Frank <[email protected]> wrote:
Quoted 7 lines · Cornelia Huck
Quoted 3 lines · On Wed, 24 Jun 2020 16:22:00 -0400 Collin Walling <[email protected]> wrote:
KVM_CAP_S390_VCPU_RESETSandKVM_CAP_S390_PROTECTEDneeded just a little bit of rst touch-up
Quoted 7 lines
Quoted 4 lines
Quoted 2 lines
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.
Signature · 4 lines
Regards, Collin Stay safe and stay healthy
Re: [PATCH 2/2] docs: kvm: fix rst formatting
In reply to Collin WallingQuoted 24 lines · Collin Walling
KVM_CAP_S390_VCPU_RESETSandKVM_CAP_S390_PROTECTEDneeded just a little bit of rst touch-upSigned-off-by Collin Walling <[email protected]>--- Documentation/virt/kvm/api.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)Documentation/virt/kvm/api.rst +2
-1@@ -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.
Documentation/virt/kvm/api.rst in CPUID and only exposes Hyper-V identification. In this case, guest · line 6150
Quoted 10 lines
Documentation/virt/kvm/api.rst +2
-28.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.
Signature · 3 lines
Thanks, David / dhildenb