doc: Update "Enable S5 in ACRN" tutorial

Update the "Enable S5 in ACRN" tutorial to:
* Make the language clearer at places
* Consistent use of "Lifecycle Manager" and "life_mngr"
* Change "ACK" to "ACKED"
* Use a ReST reference to point at the architectural diagram
* Update build instructions
* Replace 'literalinclude' by static code-blocks to avoid the
  content going out of date

Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>

doc/tutorials/enable_s5.rst

@@ -51,16 +51,16 @@ The diagram below shows the overall architecture:
 Initiate a system S5 from within a User VM (e.g. HMI)
 =====================================================
 
-As in Figure 56, a request to Service VM initiates the shutdown flow.
+As shown in the :numref:`s5-architecture`, a request to Service VM initiates the shutdown flow.
-This could come from a User VM, most likely the HMI (Windows or user-friendly Linux). 
+This could come from a User VM, most likely the HMI (running Windows or Linux).
-When a human operator click to initiate the flow, the lifecycle_mgr in it will send 
+When a human operator initiates the flow, the Lifecycle Manager (``life_mngr``) running in that
-the request via vUART to the lifecycle manager in the Service VM which in turn acknowledge 
+User VM will send the request via the vUART to the Lifecycle Manager in the Service VM which in
-the request and trigger the following flow. 
+turn acknowledges the request and triggers the following flow.
 
 .. note:: The User VM need to be authorized to be able to request a Shutdown, this is achieved by adding 
-   "``--pm_notify_channel uart,allow_trigger_s5``" in the launch script of that VM.
+   ``--pm_notify_channel uart,allow_trigger_s5`` in the launch script of that VM.
    And, there is only one VM in the system can be configured to request a shutdown. If there is a second User 
-   VM launched with "``--pm_notify_channel uart,allow_trigger_s5``", ACRN will stop launching it and throw
+   VM launched with ``--pm_notify_channel uart,allow_trigger_s5``, ACRN will stop launching it and throw
    out below error message:
    ``initiate a connection on a socket error``
    ``create socket to connect life-cycle manager failed``
@@ -70,18 +70,18 @@ Trigger the User VM's S5
 
 On the Service VM side, it uses the ``acrnctl`` tool to trigger the User VM's S5 flow:
 ``acrnctl stop user-vm-name``. Then, the Device Model sends a ``shutdown`` command
-to the User VM through a channel. If the User VM receives the command, it will send an "ACK"
+to the User VM through a channel. If the User VM receives the command, it will send an ``ACKED``
-to the Device Model. It is the Service VM's responsibility to check if the User VMs
+to the Device Model. It is the Service VM's responsibility to check whether the User VMs
-shut down successfully or not, and decides when to power off itself.
+shut down successfully or not, and to decide when to shut the Service VM itself down.
 
 User VM "Lifecycle Manager"
 ===========================
 
-As part of the current S5 reference design, a lifecycle manager daemon (life_mngr) runs in the
+As part of the S5 reference design, a Lifecycle Manager daemon (``life_mngr`` in Linux,
-User VM to implement S5. It waits for the command from the Service VM on the
+``life_mngr_win.exe`` in Windows) runs in the User VM to implement S5. It waits for the shutdown
-paired serial port. The simple protocol between the Service VM and User VM is as follows:
+request from the Service VM on the serial port. The simple protocol between the Service VM and
-When the daemon receives ``shutdown``, it sends "ACKed" to the Service VM;
+User VM is as follows: when the daemon receives ``shutdown``, it sends ``ACKED`` to the Service VM;
-then it can power off the User VM. If the User VM is not ready to power off,
+then it shuts down the User VM. If the User VM is not ready to shut down,
 it can ignore the ``shutdown`` command.
 
 .. _enable_s5:
@@ -91,26 +91,35 @@ Enable S5
 
 The procedure for enabling S5 is specific to the particular OS:
 
-* For Linux (LaaG) or Windows (WaaG), refer to the following configurations in the
+* For Linux (LaaG) or Windows (WaaG), include these lines in the launch script:
-  ``misc/config_tools/data/sample_launch_scripts/nuc/launch_uos.sh`` launch script for ``acrn-dm``.
 
-  .. literalinclude:: ../../../../misc/config_tools/data/sample_launch_scripts/nuc/launch_uos.sh
+  .. code-block:: bash
-     :name: laag-waag-script
-     :caption: LaaG/WaaG launch script
-     :linenos:
-     :lines: 97-117
-     :emphasize-lines: 2-4,17
-     :language: bash
 
-* For RT-Linux, refer to the ``misc/config_tools/data/sample_launch_scripts/nuc/launch_hard_rt_vm.sh`` script:
+     # Power Management (PM) configuration using vUART channel
+     pm_channel="--pm_notify_channel uart"
+     pm_by_vuart="--pm_by_vuart pty,/run/acrn/life_mngr_"$vm_name
+     pm_vuart_node="-s 1:0,lpc -l com2,/run/acrn/life_mngr_"$vm_name
 
-  .. literalinclude:: ../../../../misc/config_tools/data/sample_launch_scripts/nuc/launch_hard_rt_vm.sh
+     acrn-dm -A -m $mem_size -s 0:0,hostbridge \
-     :name: rt-script
+       ...
-     :caption: RT-Linux launch script
+       $pm_channel \
-     :linenos:
+       $pm_by_vuart \
-     :lines: 42-58
+       $pm_vuart_node \
-     :emphasize-lines: 2-3,13
+       ...
-     :language: bash
+
+* For RT-Linux, include these lines in the launch script:
+
+  .. code-block:: bash
+
+     # Power Management (PM) configuration
+     pm_channel="--pm_notify_channel uart"
+     pm_by_vuart="--pm_by_vuart tty,/dev/ttyS1"
+
+     /usr/bin/acrn-dm -A -m $mem_size -s 0:0,hostbridge \
+        ...
+        $pm_channel \
+        $pm_by_vuart \
+        ...
 
   .. note:: For RT-Linux, the vUART is emulated in the hypervisor; expose the node as ``/dev/ttySn``.
 
@@ -120,15 +129,15 @@ The procedure for enabling S5 is specific to the particular OS:
 
       .. code-block:: none
 
-         $ cd acrn-hypervisor/misc/life_mngr
+         $ cd acrn-hypervisor
          $ make life_mngr
 
    #. Copy ``life_mngr`` and ``life_mngr.service`` into the User VM:
 
       .. code-block:: none
 
-         $ scp life_mngr root@<test board address>:/usr/bin/life_mngr
+         $ scp build/misc/services/life_mngr root@<test board address>:/usr/bin/life_mngr
-         $ scp life_mngr.service root@<test board address>:/lib/systemd/system/life_mngr.service
+         $ scp build/misc/services/life_mngr.service root@<test board address>:/lib/systemd/system/life_mngr.service
 
    #. Use the below commands to enable ``life_mngr.service`` and restart the User VM.
 
@@ -142,7 +151,7 @@ The procedure for enabling S5 is specific to the particular OS:
 
    a) Build the ``life_mngr_win.exe`` application::
 
-        $ cd acrn-hypervisor/misc
+        $ cd acrn-hypervisor
         $ make life_mngr
 
       .. note:: If there is no ``x86_64-w64-mingw32-gcc`` compiler, you can run ``sudo apt install gcc-mingw-w64-x86-64``