diff mbox series

[v7,9/10] KVM: arm64: docs: document KVM support of pointer authentication

Message ID 1552984243-7689-10-git-send-email-amit.kachhap@arm.com (mailing list archive)
State New, archived
Headers show
Series Add ARMv8.3 pointer authentication for kvm guest | expand

Commit Message

Amit Daniel Kachhap March 19, 2019, 8:30 a.m. UTC
This adds sections for KVM API extension for pointer authentication.
A brief description about usage of pointer authentication for KVM guests
is added in the arm64 documentations.

Signed-off-by: Amit Daniel Kachhap <amit.kachhap@arm.com>
Cc: Mark Rutland <mark.rutland@arm.com>
Cc: Christoffer Dall <christoffer.dall@arm.com>
Cc: Marc Zyngier <marc.zyngier@arm.com>
Cc: kvmarm@lists.cs.columbia.edu
---
 Documentation/arm64/pointer-authentication.txt | 15 +++++++++++----
 Documentation/virtual/kvm/api.txt              |  6 ++++++
 2 files changed, 17 insertions(+), 4 deletions(-)

Comments

Julien Thierry March 20, 2019, 1:37 p.m. UTC | #1
Hi Amit,

On 19/03/2019 08:30, Amit Daniel Kachhap wrote:
> This adds sections for KVM API extension for pointer authentication.
> A brief description about usage of pointer authentication for KVM guests
> is added in the arm64 documentations.
> 
> Signed-off-by: Amit Daniel Kachhap <amit.kachhap@arm.com>
> Cc: Mark Rutland <mark.rutland@arm.com>
> Cc: Christoffer Dall <christoffer.dall@arm.com>
> Cc: Marc Zyngier <marc.zyngier@arm.com>
> Cc: kvmarm@lists.cs.columbia.edu
> ---
>  Documentation/arm64/pointer-authentication.txt | 15 +++++++++++----
>  Documentation/virtual/kvm/api.txt              |  6 ++++++
>  2 files changed, 17 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/arm64/pointer-authentication.txt b/Documentation/arm64/pointer-authentication.txt
> index 5baca42..4b769e6 100644
> --- a/Documentation/arm64/pointer-authentication.txt
> +++ b/Documentation/arm64/pointer-authentication.txt
> @@ -87,7 +87,14 @@ used to get and set the keys for a thread.
>  Virtualization
>  --------------
>  
> -Pointer authentication is not currently supported in KVM guests. KVM
> -will mask the feature bits from ID_AA64ISAR1_EL1, and attempted use of
> -the feature will result in an UNDEFINED exception being injected into
> -the guest.
> +Pointer authentication is enabled in KVM guest when each virtual cpu is
> +initialised by passing flags KVM_ARM_VCPU_PTRAUTH_[ADDRESS/GENERIC] and
> +requesting this feature to be enabled. Without this flag, pointer

"Without these flags"*

> +authentication is not enabled in KVM guests and attempted use of the
> +feature will result in an UNDEFINED exception being injected into the
> +guest.
> +
> +Additionally, when these vcpu feature flags are not set then KVM will
> +filter out the Pointer Authentication system key registers from
> +KVM_GET/SET_REG_* ioctls and mask those features from cpufeature ID
> +register.
> diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
> index 7de9eee..b5c66bc 100644
> --- a/Documentation/virtual/kvm/api.txt
> +++ b/Documentation/virtual/kvm/api.txt
> @@ -2659,6 +2659,12 @@ Possible features:
>  	  Depends on KVM_CAP_ARM_PSCI_0_2.
>  	- KVM_ARM_VCPU_PMU_V3: Emulate PMUv3 for the CPU.
>  	  Depends on KVM_CAP_ARM_PMU_V3.
> +	- KVM_ARM_VCPU_PTRAUTH_ADDRESS:
> +	- KVM_ARM_VCPU_PTRAUTH_GENERIC:
> +	  Enables Pointer authentication for the CPU.
> +	  Depends on KVM_CAP_ARM_PTRAUTH and only on arm64 architecture. If
> +	  set, then the KVM guest allows the execution of pointer authentication
> +	  instructions. Otherwise, KVM treats these instructions as undefined.
>  

Overall I feel one could easily get confused to whether
PTRAUTH_ADDRESS/GENERIC are two individual features, whether one is a
superset of the other, if the names are just an alias of one another, etc...

I think the doc should at least stress out that *both* flags are
required to enable ptrauth in a guest. However it raises the question,
if we don't plan to support the features individually (because we
can't), should we really expose two feature flags? I seems odd to
introduce two flags that only do something if used together...

Cheers,
Kristina Martšenko March 20, 2019, 3:04 p.m. UTC | #2
On 20/03/2019 13:37, Julien Thierry wrote:
> Hi Amit,
> 
> On 19/03/2019 08:30, Amit Daniel Kachhap wrote:
>> This adds sections for KVM API extension for pointer authentication.
>> A brief description about usage of pointer authentication for KVM guests
>> is added in the arm64 documentations.

[...]

>> diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
>> index 7de9eee..b5c66bc 100644
>> --- a/Documentation/virtual/kvm/api.txt
>> +++ b/Documentation/virtual/kvm/api.txt
>> @@ -2659,6 +2659,12 @@ Possible features:
>>  	  Depends on KVM_CAP_ARM_PSCI_0_2.
>>  	- KVM_ARM_VCPU_PMU_V3: Emulate PMUv3 for the CPU.
>>  	  Depends on KVM_CAP_ARM_PMU_V3.
>> +	- KVM_ARM_VCPU_PTRAUTH_ADDRESS:
>> +	- KVM_ARM_VCPU_PTRAUTH_GENERIC:
>> +	  Enables Pointer authentication for the CPU.
>> +	  Depends on KVM_CAP_ARM_PTRAUTH and only on arm64 architecture. If
>> +	  set, then the KVM guest allows the execution of pointer authentication
>> +	  instructions. Otherwise, KVM treats these instructions as undefined.
>>  
> 
> Overall I feel one could easily get confused to whether
> PTRAUTH_ADDRESS/GENERIC are two individual features, whether one is a
> superset of the other, if the names are just an alias of one another, etc...
> 
> I think the doc should at least stress out that *both* flags are
> required to enable ptrauth in a guest. However it raises the question,
> if we don't plan to support the features individually (because we
> can't), should we really expose two feature flags? I seems odd to
> introduce two flags that only do something if used together...

Why can't we support the features individually? For example, if we ever
get a system where all CPUs support address authentication and none of
them support generic authentication, then we could still support address
authentication in the guest.

Thanks,
Kristina
Julien Thierry March 20, 2019, 6:06 p.m. UTC | #3
On 20/03/2019 15:04, Kristina Martsenko wrote:
> On 20/03/2019 13:37, Julien Thierry wrote:
>> Hi Amit,
>>
>> On 19/03/2019 08:30, Amit Daniel Kachhap wrote:
>>> This adds sections for KVM API extension for pointer authentication.
>>> A brief description about usage of pointer authentication for KVM guests
>>> is added in the arm64 documentations.
> 
> [...]
> 
>>> diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
>>> index 7de9eee..b5c66bc 100644
>>> --- a/Documentation/virtual/kvm/api.txt
>>> +++ b/Documentation/virtual/kvm/api.txt
>>> @@ -2659,6 +2659,12 @@ Possible features:
>>>  	  Depends on KVM_CAP_ARM_PSCI_0_2.
>>>  	- KVM_ARM_VCPU_PMU_V3: Emulate PMUv3 for the CPU.
>>>  	  Depends on KVM_CAP_ARM_PMU_V3.
>>> +	- KVM_ARM_VCPU_PTRAUTH_ADDRESS:
>>> +	- KVM_ARM_VCPU_PTRAUTH_GENERIC:
>>> +	  Enables Pointer authentication for the CPU.
>>> +	  Depends on KVM_CAP_ARM_PTRAUTH and only on arm64 architecture. If
>>> +	  set, then the KVM guest allows the execution of pointer authentication
>>> +	  instructions. Otherwise, KVM treats these instructions as undefined.
>>>  
>>
>> Overall I feel one could easily get confused to whether
>> PTRAUTH_ADDRESS/GENERIC are two individual features, whether one is a
>> superset of the other, if the names are just an alias of one another, etc...
>>
>> I think the doc should at least stress out that *both* flags are
>> required to enable ptrauth in a guest. However it raises the question,
>> if we don't plan to support the features individually (because we
>> can't), should we really expose two feature flags? I seems odd to
>> introduce two flags that only do something if used together...
> 
> Why can't we support the features individually? For example, if we ever
> get a system where all CPUs support address authentication and none of
> them support generic authentication, then we could still support address
> authentication in the guest.
> 
> 

That's a good point, I didn't think of that.

Although, currently we don't have a way to detect that we are in such a
configuration. So as is, both flags are required to enable either
feature, and I feel the documentation should be clear on that aspect.

Another option would be to introduce a flag that enables both for now,
and if one day we decide to support the configuration you mentioned we
could add "more modular" flags that allow you to control those features
individually. While a bit cumbersome, I would find that less awkward
than having two flags that only do something if both are present.

Thanks,
Kristina Martšenko March 20, 2019, 8:56 p.m. UTC | #4
On 20/03/2019 18:06, Julien Thierry wrote:
> 
> 
> On 20/03/2019 15:04, Kristina Martsenko wrote:
>> On 20/03/2019 13:37, Julien Thierry wrote:
>>> Hi Amit,
>>>
>>> On 19/03/2019 08:30, Amit Daniel Kachhap wrote:
>>>> This adds sections for KVM API extension for pointer authentication.
>>>> A brief description about usage of pointer authentication for KVM guests
>>>> is added in the arm64 documentations.
>>
>> [...]
>>
>>>> diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
>>>> index 7de9eee..b5c66bc 100644
>>>> --- a/Documentation/virtual/kvm/api.txt
>>>> +++ b/Documentation/virtual/kvm/api.txt
>>>> @@ -2659,6 +2659,12 @@ Possible features:
>>>>  	  Depends on KVM_CAP_ARM_PSCI_0_2.
>>>>  	- KVM_ARM_VCPU_PMU_V3: Emulate PMUv3 for the CPU.
>>>>  	  Depends on KVM_CAP_ARM_PMU_V3.
>>>> +	- KVM_ARM_VCPU_PTRAUTH_ADDRESS:
>>>> +	- KVM_ARM_VCPU_PTRAUTH_GENERIC:
>>>> +	  Enables Pointer authentication for the CPU.
>>>> +	  Depends on KVM_CAP_ARM_PTRAUTH and only on arm64 architecture. If
>>>> +	  set, then the KVM guest allows the execution of pointer authentication
>>>> +	  instructions. Otherwise, KVM treats these instructions as undefined.
>>>>  
>>>
>>> Overall I feel one could easily get confused to whether
>>> PTRAUTH_ADDRESS/GENERIC are two individual features, whether one is a
>>> superset of the other, if the names are just an alias of one another, etc...
>>>
>>> I think the doc should at least stress out that *both* flags are
>>> required to enable ptrauth in a guest. However it raises the question,
>>> if we don't plan to support the features individually (because we
>>> can't), should we really expose two feature flags? I seems odd to
>>> introduce two flags that only do something if used together...
>>
>> Why can't we support the features individually? For example, if we ever
>> get a system where all CPUs support address authentication and none of
>> them support generic authentication, then we could still support address
>> authentication in the guest.
>>
>>
> 
> That's a good point, I didn't think of that.
> 
> Although, currently we don't have a way to detect that we are in such a
> configuration. So as is, both flags are required to enable either
> feature, and I feel the documentation should be clear on that aspect.

For now we only support enabling both features together, so both flags
need to be set. I agree that the documentation should be made clear on this.

In the future, if we need to, we can add "negative" cpucaps to detect
that a feature is absent on all CPUs.

> 
> Another option would be to introduce a flag that enables both for now,
> and if one day we decide to support the configuration you mentioned we
> could add "more modular" flags that allow you to control those features
> individually. While a bit cumbersome, I would find that less awkward
> than having two flags that only do something if both are present.

That would work too.

I find it more logical to have two flags since there are two features
(two ID register fields), and KVM enables two features for the guest.
The fact that KVM does not currently support enabling them separately is
a KVM implementation choice, and could change in the future.

Thanks,
Kristina
Amit Daniel Kachhap March 21, 2019, 6:41 a.m. UTC | #5
Hi Julien/Kristina,

On 3/21/19 2:26 AM, Kristina Martsenko wrote:
> On 20/03/2019 18:06, Julien Thierry wrote:
>>
>>
>> On 20/03/2019 15:04, Kristina Martsenko wrote:
>>> On 20/03/2019 13:37, Julien Thierry wrote:
>>>> Hi Amit,
>>>>
>>>> On 19/03/2019 08:30, Amit Daniel Kachhap wrote:
>>>>> This adds sections for KVM API extension for pointer authentication.
>>>>> A brief description about usage of pointer authentication for KVM guests
>>>>> is added in the arm64 documentations.
>>>
>>> [...]
>>>
>>>>> diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
>>>>> index 7de9eee..b5c66bc 100644
>>>>> --- a/Documentation/virtual/kvm/api.txt
>>>>> +++ b/Documentation/virtual/kvm/api.txt
>>>>> @@ -2659,6 +2659,12 @@ Possible features:
>>>>>   	  Depends on KVM_CAP_ARM_PSCI_0_2.
>>>>>   	- KVM_ARM_VCPU_PMU_V3: Emulate PMUv3 for the CPU.
>>>>>   	  Depends on KVM_CAP_ARM_PMU_V3.
>>>>> +	- KVM_ARM_VCPU_PTRAUTH_ADDRESS:
>>>>> +	- KVM_ARM_VCPU_PTRAUTH_GENERIC:
>>>>> +	  Enables Pointer authentication for the CPU.
>>>>> +	  Depends on KVM_CAP_ARM_PTRAUTH and only on arm64 architecture. If
>>>>> +	  set, then the KVM guest allows the execution of pointer authentication
>>>>> +	  instructions. Otherwise, KVM treats these instructions as undefined.
>>>>>   
>>>>
>>>> Overall I feel one could easily get confused to whether
>>>> PTRAUTH_ADDRESS/GENERIC are two individual features, whether one is a
>>>> superset of the other, if the names are just an alias of one another, etc...
>>>>
>>>> I think the doc should at least stress out that *both* flags are
>>>> required to enable ptrauth in a guest. However it raises the question,
>>>> if we don't plan to support the features individually (because we
>>>> can't), should we really expose two feature flags? I seems odd to
>>>> introduce two flags that only do something if used together...
>>>
>>> Why can't we support the features individually? For example, if we ever
>>> get a system where all CPUs support address authentication and none of
>>> them support generic authentication, then we could still support address
>>> authentication in the guest.
>>>
>>>
>>
>> That's a good point, I didn't think of that.
>>
>> Although, currently we don't have a way to detect that we are in such a
>> configuration. So as is, both flags are required to enable either
>> feature, and I feel the documentation should be clear on that aspect.
> 
> For now we only support enabling both features together, so both flags
> need to be set. I agree that the documentation should be made clear on this.
> 
> In the future, if we need to, we can add "negative" cpucaps to detect
> that a feature is absent on all CPUs.
> 
>>
>> Another option would be to introduce a flag that enables both for now,
>> and if one day we decide to support the configuration you mentioned we
>> could add "more modular" flags that allow you to control those features
>> individually. While a bit cumbersome, I would find that less awkward
>> than having two flags that only do something if both are present.
> 
> That would work too.
> 
> I find it more logical to have two flags since there are two features
> (two ID register fields), and KVM enables two features for the guest.
> The fact that KVM does not currently support enabling them separately is
> a KVM implementation choice, and could change in the future.
Kristina, this comments of yours is actually what this patch series is 
trying to do. I should have added more details about the necessity of 
keeping two flags and enhancement of them is actually a future work.

Thanks,
Amit Daniel
> 
> Thanks,
> Kristina
>
Kristina Martšenko March 25, 2019, 8:05 p.m. UTC | #6
On 19/03/2019 08:30, Amit Daniel Kachhap wrote:
> This adds sections for KVM API extension for pointer authentication.
> A brief description about usage of pointer authentication for KVM guests
> is added in the arm64 documentations.
> 
> Signed-off-by: Amit Daniel Kachhap <amit.kachhap@arm.com>
> Cc: Mark Rutland <mark.rutland@arm.com>
> Cc: Christoffer Dall <christoffer.dall@arm.com>
> Cc: Marc Zyngier <marc.zyngier@arm.com>
> Cc: kvmarm@lists.cs.columbia.edu

I think it makes sense to also update the Kconfig symbol description for
CONFIG_ARM64_PTR_AUTH, since it currently only mentions userspace
support, but now the option also enables KVM guest support.

It's also worth mentioning that CONFIG_ARM64_VHE=y is required for guest
support.

Thanks,
Kristina
Dave Martin March 27, 2019, 10:44 a.m. UTC | #7
On Mon, Mar 25, 2019 at 08:05:49PM +0000, Kristina Martsenko wrote:
> On 19/03/2019 08:30, Amit Daniel Kachhap wrote:
> > This adds sections for KVM API extension for pointer authentication.
> > A brief description about usage of pointer authentication for KVM guests
> > is added in the arm64 documentations.
> > 
> > Signed-off-by: Amit Daniel Kachhap <amit.kachhap@arm.com>
> > Cc: Mark Rutland <mark.rutland@arm.com>
> > Cc: Christoffer Dall <christoffer.dall@arm.com>
> > Cc: Marc Zyngier <marc.zyngier@arm.com>
> > Cc: kvmarm@lists.cs.columbia.edu
> 
> I think it makes sense to also update the Kconfig symbol description for
> CONFIG_ARM64_PTR_AUTH, since it currently only mentions userspace
> support, but now the option also enables KVM guest support.
> 
> It's also worth mentioning that CONFIG_ARM64_VHE=y is required for guest
> support.

Is it worth making this dependency explicit in Kconfig?

For SVE, I have

config ARM64_SVE
	depends on !KVM || ARM64_VHE

to implement this.

Cheers
---Dave
Amit Daniel Kachhap March 27, 2019, 11:49 a.m. UTC | #8
Hi,

On 3/27/19 4:14 PM, Dave Martin wrote:
> On Mon, Mar 25, 2019 at 08:05:49PM +0000, Kristina Martsenko wrote:
>> On 19/03/2019 08:30, Amit Daniel Kachhap wrote:
>>> This adds sections for KVM API extension for pointer authentication.
>>> A brief description about usage of pointer authentication for KVM guests
>>> is added in the arm64 documentations.
>>>
>>> Signed-off-by: Amit Daniel Kachhap <amit.kachhap@arm.com>
>>> Cc: Mark Rutland <mark.rutland@arm.com>
>>> Cc: Christoffer Dall <christoffer.dall@arm.com>
>>> Cc: Marc Zyngier <marc.zyngier@arm.com>
>>> Cc: kvmarm@lists.cs.columbia.edu
>>
>> I think it makes sense to also update the Kconfig symbol description for
>> CONFIG_ARM64_PTR_AUTH, since it currently only mentions userspace
>> support, but now the option also enables KVM guest support.
>>
>> It's also worth mentioning that CONFIG_ARM64_VHE=y is required for guest
>> support.
> 
> Is it worth making this dependency explicit in Kconfig?
Currently there is discrepancy that userspace supports ptrauth in both 
nVHE/VHE mode and KVM guest only in VHE mode. I suppose adding explicit 
dependency flag here makes both of them similar.

Thanks,
Amit D
> 
> For SVE, I have
> 
> config ARM64_SVE
> 	depends on !KVM || ARM64_VHE
> 
> to implement this.
> 
> Cheers
> ---Dave
>
Dave Martin March 27, 2019, 1:50 p.m. UTC | #9
On Wed, Mar 27, 2019 at 05:19:28PM +0530, Amit Daniel Kachhap wrote:
> Hi,
> 
> On 3/27/19 4:14 PM, Dave Martin wrote:
> >On Mon, Mar 25, 2019 at 08:05:49PM +0000, Kristina Martsenko wrote:
> >>On 19/03/2019 08:30, Amit Daniel Kachhap wrote:
> >>>This adds sections for KVM API extension for pointer authentication.
> >>>A brief description about usage of pointer authentication for KVM guests
> >>>is added in the arm64 documentations.
> >>>
> >>>Signed-off-by: Amit Daniel Kachhap <amit.kachhap@arm.com>
> >>>Cc: Mark Rutland <mark.rutland@arm.com>
> >>>Cc: Christoffer Dall <christoffer.dall@arm.com>
> >>>Cc: Marc Zyngier <marc.zyngier@arm.com>
> >>>Cc: kvmarm@lists.cs.columbia.edu
> >>
> >>I think it makes sense to also update the Kconfig symbol description for
> >>CONFIG_ARM64_PTR_AUTH, since it currently only mentions userspace
> >>support, but now the option also enables KVM guest support.
> >>
> >>It's also worth mentioning that CONFIG_ARM64_VHE=y is required for guest
> >>support.
> >
> >Is it worth making this dependency explicit in Kconfig?
> Currently there is discrepancy that userspace supports ptrauth in both
> nVHE/VHE mode and KVM guest only in VHE mode. I suppose adding explicit
> dependency flag here makes both of them similar.

Looking at the history, for SVE this Kconfig restriction has always been
present.  Since ptrauth initially upstreamed without an equivalent
restriction in Kconfig, adding it now could be seen as a regression.

So, maybe it's not worth it here.

You could add a separate option, say

config ARM64_PTR_AUTH_KVM
	bool "Pointer authentication support for KVM guests"
	default y
	depends on ARM64_PTR_AUTH && ARM64_VHE && KVM

...but that may be overkill.

Cheers,
---Dave
Amit Daniel Kachhap March 28, 2019, 10:13 a.m. UTC | #10
Hi Dave,

On 3/27/19 7:20 PM, Dave Martin wrote:
> On Wed, Mar 27, 2019 at 05:19:28PM +0530, Amit Daniel Kachhap wrote:
>> Hi,
>>
>> On 3/27/19 4:14 PM, Dave Martin wrote:
>>> On Mon, Mar 25, 2019 at 08:05:49PM +0000, Kristina Martsenko wrote:
>>>> On 19/03/2019 08:30, Amit Daniel Kachhap wrote:
>>>>> This adds sections for KVM API extension for pointer authentication.
>>>>> A brief description about usage of pointer authentication for KVM guests
>>>>> is added in the arm64 documentations.
>>>>>
>>>>> Signed-off-by: Amit Daniel Kachhap <amit.kachhap@arm.com>
>>>>> Cc: Mark Rutland <mark.rutland@arm.com>
>>>>> Cc: Christoffer Dall <christoffer.dall@arm.com>
>>>>> Cc: Marc Zyngier <marc.zyngier@arm.com>
>>>>> Cc: kvmarm@lists.cs.columbia.edu
>>>>
>>>> I think it makes sense to also update the Kconfig symbol description for
>>>> CONFIG_ARM64_PTR_AUTH, since it currently only mentions userspace
>>>> support, but now the option also enables KVM guest support.
>>>>
>>>> It's also worth mentioning that CONFIG_ARM64_VHE=y is required for guest
>>>> support.
>>>
>>> Is it worth making this dependency explicit in Kconfig?
>> Currently there is discrepancy that userspace supports ptrauth in both
>> nVHE/VHE mode and KVM guest only in VHE mode. I suppose adding explicit
>> dependency flag here makes both of them similar.
> 
> Looking at the history, for SVE this Kconfig restriction has always been
> present.  Since ptrauth initially upstreamed without an equivalent
> restriction in Kconfig, adding it now could be seen as a regression.
ok it makes sense to keep it this way.
> 
> So, maybe it's not worth it here.
> 
> You could add a separate option, say
> 
> config ARM64_PTR_AUTH_KVM
> 	bool "Pointer authentication support for KVM guests"
> 	default y
> 	depends on ARM64_PTR_AUTH && ARM64_VHE && KVM
> 
> ...but that may be overkill.
I was thinking for adding some details for this in virtualization 
section in Documentation/arm64/pointer-authentication.txt along with 
brief comment in arch/arm64/Kconfig.

Thanks,
Amit D
> 
> Cheers,
> ---Dave
>
diff mbox series

Patch

diff --git a/Documentation/arm64/pointer-authentication.txt b/Documentation/arm64/pointer-authentication.txt
index 5baca42..4b769e6 100644
--- a/Documentation/arm64/pointer-authentication.txt
+++ b/Documentation/arm64/pointer-authentication.txt
@@ -87,7 +87,14 @@  used to get and set the keys for a thread.
 Virtualization
 --------------
 
-Pointer authentication is not currently supported in KVM guests. KVM
-will mask the feature bits from ID_AA64ISAR1_EL1, and attempted use of
-the feature will result in an UNDEFINED exception being injected into
-the guest.
+Pointer authentication is enabled in KVM guest when each virtual cpu is
+initialised by passing flags KVM_ARM_VCPU_PTRAUTH_[ADDRESS/GENERIC] and
+requesting this feature to be enabled. Without this flag, pointer
+authentication is not enabled in KVM guests and attempted use of the
+feature will result in an UNDEFINED exception being injected into the
+guest.
+
+Additionally, when these vcpu feature flags are not set then KVM will
+filter out the Pointer Authentication system key registers from
+KVM_GET/SET_REG_* ioctls and mask those features from cpufeature ID
+register.
diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
index 7de9eee..b5c66bc 100644
--- a/Documentation/virtual/kvm/api.txt
+++ b/Documentation/virtual/kvm/api.txt
@@ -2659,6 +2659,12 @@  Possible features:
 	  Depends on KVM_CAP_ARM_PSCI_0_2.
 	- KVM_ARM_VCPU_PMU_V3: Emulate PMUv3 for the CPU.
 	  Depends on KVM_CAP_ARM_PMU_V3.
+	- KVM_ARM_VCPU_PTRAUTH_ADDRESS:
+	- KVM_ARM_VCPU_PTRAUTH_GENERIC:
+	  Enables Pointer authentication for the CPU.
+	  Depends on KVM_CAP_ARM_PTRAUTH and only on arm64 architecture. If
+	  set, then the KVM guest allows the execution of pointer authentication
+	  instructions. Otherwise, KVM treats these instructions as undefined.
 
 
 4.83 KVM_ARM_PREFERRED_TARGET