Update release notes and docs subdirectory to v2.3 (2).

Add an additional file to describe the use of Linux cpu hotplug with the
Virtualizer into the docs subdirectory and adapt the release notes
accordingly.

Signed-off-by: Dietmar Eggemann <dietmar.eggemann@arm.com>

2 files changed, 86 insertions, 11 deletions

diff --git a/Release_Notes.txt b/Release_Notes.txt
index 5e87ac9..cca1528 100644
--- a/Release_Notes.txt
+++ b/Release_Notes.txt
@@ -129,17 +129,10 @@ Release notes
     e.  New features
 
         1.  It is possible to hotplug a cpu using the mechanisms provided
-            by the Linux 3.x cpu hotplug implementation e.g.
-
-            To offline cpu1:
-            echo 0 > /sys/devices/system/cpu/cpu1/online
-
-            To bring cpu1 online:
-            echo 1 > /sys/devices/system/cpu/cpu1/online
-
-            This feature is supported only when the Virtualizer software
-            has been built to support synchronous switching. It is not
-            possible to hotplug cpu0.
+            by the Linux 3.x cpu hotplug implementation. Please refer to
+            "docs/07-Linux-cpu-hotplug-howto.txt" for details regarding
+            how the Virtualizer software and Linux should be configured
+            to support cpu hotplug.
 
         2.  Context of the registers specified by the v7.1 Debug architecture
             is saved and restored during a cluster context switch operation.
diff --git a/docs/07-Linux-cpu-hotplug-howto.txt b/docs/07-Linux-cpu-hotplug-howto.txt
new file mode 100755
index 0000000..873a88c
--- /dev/null
+++ b/docs/07-Linux-cpu-hotplug-howto.txt
@@ -0,0 +1,82 @@
+Instructions & Guidelines to use Linux cpu hotplug
+==================================================
+
+A   Introduction
+
+    This note describes how the Virtualizer software should
+    be configured for use with the Linux cpu hotplug
+    subsystem. It also mentions conditions that both Linux
+    and the Virtualizer software should fulfil for cpu
+    hotplug to work.
+
+B   Guidelines
+
+    A cpu hotplug operation involves migration of all tasks
+    and interrupts from the cpu in question before flushing
+    the relevant cache level(s) and shutting down the cpu.
+    A cpu is shutdown by programming the relevant RST_HOLDx
+    register in the KingFisher System Control Block (KFSCB).
+
+    The Virtualizer software traps accesses to the KFSCB made
+    by Linux to shutdown a cpu to save its HYP mode context
+    and request the Secure world to save its own context. It
+    then proceeds with the shutdown operation as Linux
+    originally intended. The key assumption made here is that
+    Linux will access the KFSCB RST_HOLDx registers only
+    during a cpu hotplug operation.
+
+    It is also assumed that its not possible hotplug cpu0.
+    Hence, Linux cpu hotplug will work only with the MPx4
+    variant of the big.LITTLE FastModels.
+
+    The Virtualizer software is built to switch the payload
+    software between clusters asynchronously. There is a
+    possibility of unpredictable behaviour happenning if a
+    cluster switch is initiated when a cpu hotplug operation
+    is in progress. Hence the following two conditions need
+    to be met to be able to use the Virtualizer software in
+    conjunction with Linux cpu hotplug:
+
+    1.  The Virtualizer software should be built to support
+        synchronous switching by setting the ASYNC
+        environment variable to FALSE prior to building it.
+        For example with the tcsh shell:
+
+        setenv ASYNC FALSE; make
+
+    2.  Linux should invoke a cluster switch explicitly
+        after ensuring that no cpu hotplug operation is in
+        progress and vice versa. It can invoke a cluster
+        switch by using the "HVC #1" assembler instruction
+        from the relevant code.
+
+C   Instructions
+
+    1.  Build a linux kernel as per the steps listed in
+        "docs/03-Linux-kernel-build.txt".
+        The configuration includes support for cpu
+        hotplug by default.
+
+    2.  Use an existing root filesystem or build a new
+        one as per the steps listed in
+        "docs/06-Optional-rootfs-build.txt".
+
+    3.  Place the kernel in the
+        "bootwrapper/payload/kernel" directory and the
+        filesystem in the "bootwrapper/payload/fsimg"
+        directory. Build the Virtualizer software with
+        support for synchronous switching as mentioned
+        in B.1.
+
+    4.  Boot the resulting "bootwrapper/img.axf" file
+        using the "bootwrapper/big-little-mp4.mxscript"
+        file. At the command prompt, the Linux cpu
+        hotplug commands to hotplug cpus should work
+        as expected. For example, to hotplug cpu1 do:
+
+        echo 0 > /sys/devices/system/cpu/cpu1/online
+
+        To bring cpu1 online do:
+
+        echo 1 > /sys/devices/system/cpu/cpu1/online
+