Commit 6656cda0 authored by Jing Zhang's avatar Jing Zhang Committed by Oliver Upton
Browse files

KVM: arm64: Document KVM_ARM_GET_REG_WRITABLE_MASKS 



Add some basic documentation on how to get feature ID register writable
masks from userspace.

Signed-off-by: default avatarJing Zhang <jingzhangos@google.com>
Reviewed-by: default avatarCornelia Huck <cohuck@redhat.com>
Reviewed-by: default avatarMarc Zyngier <maz@kernel.org>
Link: https://lore.kernel.org/r/20231003230408.3405722-3-oliver.upton@linux.dev


Signed-off-by: default avatarOliver Upton <oliver.upton@linux.dev>
parent 3f9cd0ca

Documentation/virt/kvm/api.rst

+48 −0
Original line number Diff line number Diff line
@@ -6070,6 +6070,54 @@ writes to the CNTVCT_EL0 and CNTPCT_EL0 registers using the SET_ONE_REG 
interface. No error will be returned, but the resulting offset will not be

applied.



4.139 KVM_ARM_GET_REG_WRITABLE_MASKS

-------------------------------------------



:Capability: KVM_CAP_ARM_SUPPORTED_REG_MASK_RANGES

:Architectures: arm64

:Type: vm ioctl

:Parameters: struct reg_mask_range (in/out)

:Returns: 0 on success, < 0 on error





::



        #define KVM_ARM_FEATURE_ID_RANGE	0

        #define KVM_ARM_FEATURE_ID_RANGE_SIZE	(3 * 8 * 8)



        struct reg_mask_range {

                __u64 addr;             /* Pointer to mask array */

                __u32 range;            /* Requested range */

                __u32 reserved[13];

        };



This ioctl copies the writable masks for a selected range of registers to

userspace.



The ``addr`` field is a pointer to the destination array where KVM copies

the writable masks.



The ``range`` field indicates the requested range of registers.

``KVM_CHECK_EXTENSION`` for the ``KVM_CAP_ARM_SUPPORTED_REG_MASK_RANGES``

capability returns the supported ranges, expressed as a set of flags. Each

flag's bit index represents a possible value for the ``range`` field.

All other values are reserved for future use and KVM may return an error.



The ``reserved[13]`` array is reserved for future use and should be 0, or

KVM may return an error.



KVM_ARM_FEATURE_ID_RANGE (0)

^^^^^^^^^^^^^^^^^^^^^^^^^^^^



The Feature ID range is defined as the AArch64 System register space with

op0==3, op1=={0, 1, 3}, CRn==0, CRm=={0-7}, op2=={0-7}.



The mask returned array pointed to by ``addr`` is indexed by the macro

``ARM64_FEATURE_ID_RANGE_IDX(op0, op1, crn, crm, op2)``, allowing userspace

to know what fields can be changed for the system register described by

``op0, op1, crn, crm, op2``. KVM rejects ID register values that describe a

superset of the features supported by the system.



5. The kvm_run structure

========================