Create reference implementation pages for flashing FW on Power9

docs/source/references/coral/cluster_mgmt/firmware/index.rst

@@ -0,0 +1,8 @@
+Power9 Firmware Update
+======================
+
+.. toctree::
+   :maxdepth: 2
+
+   ipmi.rst
+   openbmc.rst

docs/source/references/coral/cluster_mgmt/firmware/ipmi.rst

@@ -0,0 +1,38 @@
+IPMI Firmware Update
+====================
+
+The process for updating firmware on the IBM Power9 Server (Boston) is documented below.
+
+
+Collect the required files
+--------------------------
+
+Collect the following files and put them into a directory on the Management Node. 
+
+   * pUpdate
+   * pnor
+   * bmc 
+
+Flash Firmware
+--------------
+
+Using xCAT ``rflash`` command, specify the directory containing the files with the ``-d`` option. ::
+
+   rflash <noderange> -d /path-to-directory/ 
+
+The ``pUpdate`` utility is leveraged in doing the firmware update against the target node and will do the following: 
+
+   * power off the host
+   * flash bmc and reboot
+   * flash pnor 
+   * power on the host 
+
+Monitor the progress for the nodes by looking at the files under ``/var/log/xcat/rflash/``.
+
+Validatation
+------------
+
+Use the ``rinv`` command to validate firmware level: ::
+
+    rinv <noderange> firm | xcoll
+

docs/source/references/coral/cluster_mgmt/firmware/openbmc.rst

@@ -0,0 +1,74 @@
+OpenBMC Firmware Update
+=======================
+
+The process of updating firmware on the OpenBMC managed servers is documented below.  
+
+The sequence of events that must happen is the following: 
+
+  * Power off the Host 
+  * Update and Activate PNOR
+  * Update and Activate BMC 
+  * Reboot the BMC (applies BMC)
+  * Power on the Host (applies PNOR) 
+
+**Note:** xCAT is working on streamlining this process to reduce the flexibility of the above steps at the convenience of the Administrator to handle the necessary reboots.  See `Issue #4245 <https://github.com/xcat2/xcat-core/issues/4245>`_
+
+
+Power off Host 
+--------------
+
+Use the rpower command to power off the host: ::
+
+   rpower <noderange> off 
+
+Update and Activate PNOR Firmware
+---------------------------------
+
+Use the rflash command to upload and activate the PNOR firmware: ::
+
+   rflash <noderange> -a /path/to/witherspoon.pnor.squashfs.tar
+
+**Note:** The ``-a`` option does an upload and activate in one step, after firmware is activated, use the ``rflash <noderange> -l`` to view.  The ``rflash`` command shows ``(*)`` as the active firmware and ``(+)`` on the firmware that requires reboot to become effective. 
+
+Update and Activate BMC Firmware
+--------------------------------
+
+Use the rflash command to upload and activate the PNOR firmware: ::
+
+   rflash <noderange> -a /path/to/obmc-phosphor-image-witherspoon.ubi.mtd.tar
+
+**Note:** The ``-a`` option does an upload and activate in one step, after firmware is activated, use the ``rflash <noderange> -l`` to view.  The ``rflash`` command shows ``(*)`` as the active firmware and ``(+)`` on the firmware that requires reboot to become effective. 
+
+Reboot the BMC
+--------------
+
+Use the ``rpower`` command to reboot the BMC: ::
+ 
+   rpower <noderange> bmcreboot`
+
+The BMC will take 2-5 minutes to reboot, check the status using: ``rpower <noderange> bmcstate`` and wait for ``BMCReady`` to be returned. 
+
+**Known Issue:**  On reboot, the first call to the BMC after reboot, xCAT will return ``Error: BMC did not respond within 10 seconds, retry the command.``.  Please retry. 
+
+
+Power on Host
+-------------
+
+User the ``rpower`` command to power on the Host: ::
+
+   rpower <noderange> on 
+
+
+Validation
+----------
+
+Use one of the following commands to validate firmware levels are in sync: 
+
+* Use the ``rinv`` command to validate firmware level: ::
+
+    rinv <noderange> firm -V | grep -i ibm | grep "\*" | xcoll 
+
+* Use the ``rflash`` command to validate the firmware level: ::
+
+   rflash <noderange> -l | grep "\*" | xcoll 
+

docs/source/references/coral/cluster_mgmt/index.rst

@@ -0,0 +1,7 @@
+Cluster Management
+==================
+
+.. toctree::
+   :maxdepth: 2
+
+   firmware/index.rst

docs/source/references/coral/index.rst

@@ -7,6 +7,7 @@ CORAL stands for Collaboration of Oak Ridge, Argonne, and Livermore and is solut
 .. toctree::
    :maxdepth: 2
 
+   cluster_mgmt/index.rst
    known_issues/index.rst 
 ..   mn/index.rst
 ..   discovery/index.rst