[PATCH 18/18] powerpc/fadump: Update documentation about backup area support

[Hari Bathini <hbathini@linux.ibm.com>]

With backup area support available for FADump on PowerNV platform,
update FADump documentation with these details.

Signed-off-by: Hari Bathini <hbathini@linux.ibm.com>
---
 Documentation/powerpc/firmware-assisted-dump.txt |   71 +++++++++++++---------
 1 file changed, 43 insertions(+), 28 deletions(-)

diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.txt
index 6411449..42a0065 100644
--- a/Documentation/powerpc/firmware-assisted-dump.txt
+++ b/Documentation/powerpc/firmware-assisted-dump.txt
@@ -117,6 +117,17 @@ to ensure that crash data is preserved to process later.
    e.g.
      # echo 1 > /sys/kernel/fadump_release_opalcore
 
+To process dump on OPAL platform, additional meta data (PIR to
+Logical CPU map) from the crashing kernel is required. This info
+has to be backed up by the crashing kernel for capture kernel to
+use it in making sense of the register state data provided by the
+F/W. The start address of the area where this info is backed up
+is stored at the tail end of FADump crash info header. To indicate
+the presence of this additional meta data (backup info), the magic
+number field in FADump crash info header is overloaded as version
+identifier.
+
+
 Implementation details:
 ----------------------
 
@@ -131,12 +142,12 @@ that are run. If there is dump data, then the
 memory is held.
 
 If there is no waiting dump data, then only the memory required to
-hold CPU state, HPTE region, boot memory dump, FADump header and
-elfcore header, is usually reserved at an offset greater than boot
-memory size (see Fig. 1). This area is *not* released: this region
+hold CPU state, HPTE region, boot memory dump, FADump header, elfcore
+header and backup area, is usually reserved at an offset greater than
+boot memory size (see Fig. 1). This area is *not* released: this region
 will be kept permanently reserved, so that it can act as a receptacle
-for a copy of the boot memory content in addition to CPU state and
-HPTE region, in the case a crash does occur.
+for a copy of the boot memory content in addition to CPU state and HPTE
+region, in the case a crash does occur.
 
 Since this reserved memory area is used only after the system crash,
 there is no point in blocking this significant chunk of memory from
@@ -150,19 +161,19 @@ that were present in CMA region.
 
   o Memory Reservation during first kernel
 
-  Low memory                                                 Top of memory
-  0      boot memory size    |<--- Reserved dump area --->|       |
-  |           |              |    Permanent Reservatio    |       |
-  V           V              |       (Preserve area)      |       V
-  +-----------+--------/ /---+---+----+-------+-----+-----+-------+
-  |           |              |///|////|  DUMP | HDR | ELF |       |
-  +-----------+--------/ /---+---+----+-------+-----+-----+-------+
-        |                      ^    ^     ^      ^
-        |                      |    |     |      |
-        \                     CPU  HPTE   /      |
-         ---------------------------------       |
-      Boot memory content gets transferred       |
-      to reserved area by firmware at the        |
+  Low memory                                                  Top of memory
+  0      boot memory size    |<---- Reserved dump area ---->|       |
+  |           |              |     Permanent Reservation    |       |
+  V           V              |       (Preserve area)        |       V
+  +-----------+--------/ /---+---+----+-------+-----+----+--+-------+
+  |           |              |///|////|  DUMP |HDR|/|ELF |//|       |
+  +-----------+--------/ /---+---+----+-------+-----+----+--+-------+
+        |                      ^    ^     ^      ^ |      ^^
+        |                      |    |     |      | |      ||
+        \                     CPU  HPTE   /      |  \    / Backup Info
+         ---------------------------------       |   ----
+      Boot memory content gets transferred       | Start address of
+      to reserved area by firmware at the        | Backup Info.
       time of crash.                             |
                                              FADump Header
                                               (meta area)
@@ -171,13 +182,13 @@ that were present in CMA region.
 
   o Memory Reservation during second kernel after crash
 
-  Low memory                                                 Top of memory
-  0      boot memory size                                         |
-  |           |<--------------- Reserved dump area -------------->|
-  V           V              |<---- Preserve area ------->|       |
-  +-----------+--------/ /---+---+----+-------+-----+-----+-------+
-  |           |              |///|////|  DUMP | HDR | ELF |       |
-  +-----------+--------/ /---+---+----+-------+-----+-----+-------+
+  Low memory                                                  Top of memory
+  0      boot memory size                                           |
+  |           |<--------------- Reserved dump area ---------------->|
+  V           V              |<----- Preserve area -------->|       |
+  +-----------+--------/ /---+---+----+-------+-----+----+--+-------+
+  |           |              |///|////|  DUMP |HDR|/|ELF |//|       |
+  +-----------+--------/ /---+---+----+-------+-----+----+--+-------+
         |                                              |
         V                                              V
    Used by second                                /proc/vmcore
@@ -185,9 +196,10 @@ that were present in CMA region.
                    Fig. 2
 
         +---+
-        |///| -> Regions (CPU & HPTE) marked like this in the above figures
-        +---+    are not always present. For example, OPAL platform does not
-                 have CPU & HPTE regions.
+        |///| -> Regions (CPU, HPTE, HDR extension & Backup area) marked
+        +---+    like this in the above figures are not always present.
+                 For example, OPAL platform does not have CPU & HPTE regions
+                 while PSeries platform doesn't use Backup area currently.
 
 
 Currently the dump will be copied from /proc/vmcore to a new file upon
@@ -330,7 +342,10 @@ TODO:
 	2. Reserve the area of predefined size (say PAGE_SIZE) for this
 	structure and have unused area as reserved (initialized to zero)
 	for future field additions.
+
    The advantage of approach 1 over 2 is we don't need to reserve extra space.
+   Using approach 1 to provide additional meta data on OPAL platform while
+   overloading magic number field as version identifier for version tracking.
 ---
 Author: Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>
 This document is based on the original documentation written for phyp