From: Julien Grall <julien.grall@arm.com>
Date: Thu, 31 Oct 2019 15:09:07 +0000 (+0000)
Subject: docs/misc: xen-command-line: Rework documentation of the option 'serrors'
X-Git-Tag: RELEASE-4.12.2~42
X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=0b22b839d4f50e88ca8e941f6e984b38500a654b;p=xen.git

docs/misc: xen-command-line: Rework documentation of the option 'serrors'

The current documentation is misleading for a few reasons:
    1) The synchronization happens on all exit/entry from/to the guest.
       This includes from EL0 (i.e userspace).
    2) Trusted guest can also generate SErrors (e.g. memory failure)
    3) Without RAS support, SErrors are IMP DEFINED. Unless you have a
    complete TRM in hand, you can't really make a decision.
    4) The documentation is written around performance when this is not
    the first concern.

The documentation is now reworked to focus on the consequences of using
serrors="panic" and avoid to go in details on the exact implementation.

Signed-off-by: Julien Grall <julien.grall@arm.com>
Acked-by: Stefano Stabellini <sstabellini@kernel.org>
Release-acked-by: Juergen Gross <jgross@suse.com>
(cherry picked from commit dfdb0066368b3766e7e4b0a7cb9d24280002d771)
---

diff --git a/docs/misc/xen-command-line.pandoc b/docs/misc/xen-command-line.pandoc
index 82535c31bf..519851c278 100644
--- a/docs/misc/xen-command-line.pandoc
+++ b/docs/misc/xen-command-line.pandoc
@@ -1822,34 +1822,19 @@ Set the serial transmit buffer size.
 
 > Default: `diverse`
 
-This parameter is provided to administrators to determine how the
-hypervisors handle SErrors.
-
-In order to distinguish guest-generated SErrors from hypervisor-generated
-SErrors we have to place SError checking code in every EL1 <-> EL2 paths.
-That will cause overhead on entries and exits due to dsb/isb. However, not all
-platforms need to categorize SErrors. For example, a host that is running with
-trusted guests. The administrator can confirm that all guests that are running
-on the host will not trigger such SErrors. In this case, the administrator can
-use this parameter to skip categorizing SErrors and reduce the overhead of
-dsb/isb.
-
-We provided the following 2 options to administrators to determine how the
-hypervisors handle SErrors:
+This parameter is provided to administrators to determine how the hypervisor
+handles SErrors.
 
 * `diverse`:
-  The hypervisor will distinguish guest SErrors from hypervisor SErrors.
-  The guest generated SErrors will be forwarded to guests, the hypervisor
-  generated SErrors will cause the whole system to crash.
-  It requires:
-  1. dsb/isb on all EL1 -> EL2 trap entries to categorize SErrors correctly.
-  2. dsb/isb on EL2 -> EL1 return paths to prevent slipping hypervisor
-     SErrors to guests.
+  The hypervisor will distinguish guest SErrors from hypervisor SErrors:
+    - The guest generated SErrors will be forwarded to the currently running
+      guest.
+    - The hypervisor generated SErrors will cause the whole system to crash
 
 * `panic`:
-  The hypervisor will not distinguish guest SErrors from hypervisor SErrors.
-  All SErrors will crash the whole system. This option will avoid all overhead
-  of the dsb/isb pairs.
+  All SErrors will cause the whole system to crash. This option should only
+  be used if you trust all your guests and/or they don't have a gadget (e.g.
+  device) to generate SErrors in normal run.
 
 ### shim_mem (x86)
 > `= List of ( min:<size> | max:<size> | <size> )`