x86/spec-ctrl: Detail the safety properties in SPEC_CTRL_ENTRY_*

The complexity is getting out of hand.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Jan Beulich <jbeulich@suse.com>

xen/arch/x86/hvm/svm/entry.S

@@ -100,6 +100,11 @@ __UNLIKELY_END(nsvm_hap)
 
         /* SPEC_CTRL_ENTRY_FROM_SVM    Req: %rsp=regs/cpuinfo, %rdx=0 Clob: acd */
 
+        /*
+         * IBPB is to mitigate BTC/SRSO on AMD/Hygon parts, in particular
+         * making type-confused RETs safe to use.  This is not needed on Zen5
+         * and later parts when SRSO_MSR_FIX (BP-SPEC-REDUCE) is in use.
+         */
         .macro svm_vmexit_cond_ibpb
             testb  $SCF_entry_ibpb, CPUINFO_scf(%rsp)
             jz     .L_skip_ibpb
@@ -111,8 +116,17 @@ __UNLIKELY_END(nsvm_hap)
 	.endm
         ALTERNATIVE "", svm_vmexit_cond_ibpb, X86_FEATURE_IBPB_ENTRY_HVM
 
+        /*
+         * RSB (RAS/RAP) stuffing is to prevents RET predictions following guest
+         * entries.  This is not needed on Zen4 and later, when AutoIBRS is in
+         * use.
+         */
         ALTERNATIVE "", DO_OVERWRITE_RSB, X86_FEATURE_SC_RSB_HVM
 
+        /*
+         * Restore Xen's MSR_SPEC_CTRL setting, making indirect CALLs/JMPs
+         * safe to use.  The guest's setting resides in the VMCB.
+         */
         .macro svm_vmexit_spec_ctrl
             movzbl CPUINFO_xen_spec_ctrl(%rsp), %eax
             movzbl CPUINFO_last_spec_ctrl(%rsp), %edx

xen/arch/x86/hvm/vmx/entry.S

@@ -34,8 +34,22 @@ ENTRY(vmx_asm_vmexit_handler)
         mov  %rax,VCPU_hvm_guest_cr2(%rbx)
 
         /* SPEC_CTRL_ENTRY_FROM_VMX    Req: b=curr %rsp=regs/cpuinfo, Clob: acd */
+        /*
+         * RSB stuffing is to prevents RET predictions following guest
+         * entries.  This is *not* sufficient to flush all RSB entries on
+         * parts enumerating eIBRS, although the following restore_spec_ctrl
+         * does covers us.
+         */
         ALTERNATIVE "", DO_OVERWRITE_RSB, X86_FEATURE_SC_RSB_HVM
 
+        /*
+         * Restore Xen's MSR_SPEC_CTRL setting.  The guest's value resides in
+         * the MSR load/save list.  For Legacy IBRS, this flushes/inhibits
+         * indirect predictions and does not flush the RSB.  For eIBRS, this
+         * prevents CALLs/JMPs using predictions learnt at a lower predictor
+         * mode, and it flushes the RSB.  On eIBRS parts that also suffer from
+         * PBRSB, the prior RSB stuffing suffices to make the RSB safe.
+         */
         .macro restore_spec_ctrl
             mov    $MSR_SPEC_CTRL, %ecx
             movzbl CPUINFO_xen_spec_ctrl(%rsp), %eax

xen/arch/x86/include/asm/spec_ctrl_asm.h

@@ -244,10 +244,32 @@
  */
     movzbl STACK_CPUINFO_FIELD(scf)(%r14), %ebx
 
+    /*
+     * For all safety notes, 32bit PV guest kernels run in Ring 1 and are
+     * therefore supervisor (== Xen) in the architecture.  As a result, most
+     * hardware isolation techniques do not work.
+     */
+
+    /*
+     * IBPB is to mitigate BTC/SRSO on AMD/Hygon parts, in particular making
+     * type-confused RETs safe to use.  This is not needed on Zen5 and later
+     * parts when SRSO_U/S_NO is enumerated.
+     */
     ALTERNATIVE "", DO_COND_IBPB, X86_FEATURE_IBPB_ENTRY_PV
 
+    /*
+     * RSB stuffing is to prevent RET predictions following guest entries.
+     * This is not needed if SMEP is active and the RSB is full-width.
+     */
     ALTERNATIVE "", DO_OVERWRITE_RSB, X86_FEATURE_SC_RSB_PV
 
+    /*
+     * Only used on Intel parts.  Restore Xen's MSR_SPEC_CTRL setting.  The
+     * guest can't change it's value behind Xen's back.  For Legacy IBRS, this
+     * flushes/inhibits indirect predictions and does not flush the RSB.  For
+     * eIBRS, this prevents CALLs/JMPs using predictions learnt at a lower
+     * predictor mode, and it flushes the RSB.
+     */
     ALTERNATIVE "", __stringify(DO_SPEC_CTRL_ENTRY maybexen=0),         \
         X86_FEATURE_SC_MSR_PV
 
@@ -270,6 +292,14 @@
  */
     movzbl STACK_CPUINFO_FIELD(scf)(%r14), %ebx
 
+    /*
+     * All safety notes the same as SPEC_CTRL_ENTRY_FROM_PV, although there is
+     * a conditional jump skipping some actions when interrupting Xen.
+     *
+     * On Intel parts, the IRET #GP path ends up here with the guest's choice
+     * of MSR_SPEC_CTRL.
+     */
+
     testb $3, UREGS_cs(%rsp)
     jz .L\@_skip
 
@@ -320,6 +350,19 @@
  */
     movzbl STACK_CPUINFO_FIELD(scf)(%r14), %ebx
 
+    /*
+     * For all safety notes, 32bit PV guest kernels run in Ring 1 and are
+     * therefore supervisor (== Xen) in the architecture.  As a result, most
+     * hardware isolation techniques do not work.
+     */
+
+    /*
+     * IBPB is to mitigate BTC/SRSO on AMD/Hygon parts, in particular making
+     * type-confused RETs safe to use.  This is not needed on Zen5 and later
+     * parts when SRSO_U/S_NO is enumerated.  The SVM path takes care of
+     * Host/Guest interactions prior to clearing GIF, and it's not used on the
+     * VMX path.
+     */
     test    $SCF_ist_ibpb, %bl
     jz      .L\@_skip_ibpb
 
@@ -329,6 +372,12 @@
 
 .L\@_skip_ibpb:
 
+    /*
+     * RSB stuffing is to prevent RET predictions following guest entries.
+     * SCF_ist_rsb is active if either PV or HVM protections are needed.  The
+     * VMX path cannot guarantee to make the RSB safe ahead of taking an IST
+     * vector.
+     */
     test $SCF_ist_rsb, %bl
     jz .L\@_skip_rsb
 
@@ -336,6 +385,16 @@
 
 .L\@_skip_rsb:
 
+    /*
+     * Only used on Intel parts.  Restore Xen's MSR_SPEC_CTRL setting.  PV
+     * guests can't change their value behind Xen's back.  HVM guests have
+     * their value stored in the MSR load/save list.  For Legacy IBRS, this
+     * flushes/inhibits indirect predictions and does not flush the RSB.  For
+     * eIBRS, this prevents CALLs/JMPs using predictions learnt at a lower
+     * predictor mode, and it flushes the RSB.  On eIBRS parts that also
+     * suffer from PBRSB, the prior RSB stuffing suffices to make the RSB
+     * safe.
+     */
     test $SCF_ist_sc_msr, %bl
     jz .L\@_skip_msr_spec_ctrl