[PATCH v8 02/11] KVM: arm64: Document KVM_ARM_GET_REG_WRITABLE_MASKS

[Jing Zhang]

On Mon, Aug 14, 2023 at 2:46 AM Cornelia Huck <cohuck at redhat.com> wrote:
>
> On Mon, Aug 07 2023, Jing Zhang <jingzhangos at google.com> wrote:
>
> > Add some basic documentation on how to get feature ID register writable
> > masks from userspace.
> >
> > Signed-off-by: Jing Zhang <jingzhangos at google.com>
> > ---
> >  Documentation/virt/kvm/api.rst | 29 +++++++++++++++++++++++++++++
> >  1 file changed, 29 insertions(+)
> >
> > diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> > index c0ddd3035462..92a9b20f970e 100644
> > --- a/Documentation/virt/kvm/api.rst
> > +++ b/Documentation/virt/kvm/api.rst
> > @@ -6068,6 +6068,35 @@ 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: none
> > +:Architectures: arm64
> > +:Type: vm ioctl
> > +:Parameters: struct reg_mask_range (in/out)
> > +:Returns: 0 on success, < 0 on error
> > +
> > +
> > +::
> > +
> > +        #define ARM64_FEATURE_ID_SPACE_SIZE  (3 * 8 * 8)
> > +
> > +        struct reg_mask_range {
> > +                __u64 addr;             /* Pointer to mask array */
> > +                __u64 reserved[7];
> > +        };
> > +
> > +This ioctl would copy the writable masks for feature ID registers to userspace.
> > +The Feature ID space is defined as the System register space in AArch64 with
> > +op0==3, op1=={0, 1, 3}, CRn==0, CRm=={0-7}, op2=={0-7}.
> > +To get the index in the mask array pointed by ``addr`` for a specified feature
> > +ID register, use the macro ``ARM64_FEATURE_ID_SPACE_IDX(op0, op1, crn, crm, op2)``.
> > +This allows the userspace to know upfront whether it can actually tweak the
> > +contents of a feature ID register or not.
> > +The ``reserved[7]`` is reserved for future use to add other register space. For
> > +feature ID registers, it should be 0, otherwise, KVM may return error.
>
> In case of future extensions, this means that userspace needs to figure
> out what the kernel supports via different content in reg_mask_range
> (i.e. try with a value in one of the currently reserved fields and fall
> back to using addr only if that doesn't work.) Can we do better?
>
> Maybe we could introduce a capability that returns the supported ranges
> as flags, i.e. now we would return 1 for id regs masks, and for the
> future case where we have some values in the next reserved field we
> could return 1 & 2 etc. Would make life easier for userspace that needs
> to work with different kernels, but might be overkill if reserved[] is
> more like an insurance without any concrete plans for extensions.
>

Maybe it'd be better to leave this to whenever we do need to add other
range support?

Jing