Add FFDC xml parsing documentation

Change-Id: I56844e96c80fb3eb345b2254a7b42dd95c434ce3
Reviewed-on: http://gfw160.aus.stglabs.ibm.com:8080/gerrit/16041
Reviewed-by: Thi N. Tran <thi@us.ibm.com>
Reviewed-by: MATTHEW A. PLOETZ <maploetz@us.ibm.com>
Reviewed-by: Brian Silver <bsilver@us.ibm.com>
Tested-by: Brian Silver <bsilver@us.ibm.com>

1 files changed, 149 insertions, 0 deletions

diff --git a/src/import/hwpf/fapi2/docs/topics/Ffdc.md b/src/import/hwpf/fapi2/docs/topics/Ffdc.md
new file mode 100755
index 000000000..85d696b1a
--- /dev/null
+++ b/src/import/hwpf/fapi2/docs/topics/Ffdc.md
@@ -0,0 +1,149 @@
+
+# Using the FFDC/XML Error Parsing Tools
+
+For FAPI2, the parseErrorInfo PERL script has changed. The main goal was to
+enable FFDC generation classes/methods. This enables a named-parameter
+model as well as tucking the FFDC generation into a container which can
+easily be used by the FAPI_ASSERT macro.
+
+## Using the Tools
+
+parseErrorInfo.pl [--empty-ffdc-classes] [--use-variable-buffers] --output-dir=<output dir> <filename1> <filename2> ...
+- This perl script will parse HWP Error XML files and creates the following files:
+- hwp_return_codes.H. HwpReturnCode enumeration (HWP generated errors)
+- hwp_error_info.H.   Error information (used by FAPI_SET_HWP_ERROR when a HWP generates an error)
+- collect_reg_ffdc.C. Function to collect register FFDC
+- set_sbe_error.H.    Macro to create an SBE error
+
+The --empty-ffdc-classes option is for platforms which don't collect FFDC. It will generate stub classes which
+will allow the source to have the same code, but compile to no-ops on certain platforms.
+
+The --use-variable-bufers option is for platforms which support variable buffers.
+
+The XML input is the same format as for P8
+
+## Using the Generated Classes
+
+Each error found in the XML files generates a class in hwp_ffdc_classes.H.
+The name of the class is the same as the return code itself (lower case)
+and the set methods are the same as the elements the xml described as
+needing colletion.
+
+Take for example RC_MBVPD_INVALID_MT_DATA. Here is the XML:
+
+    <hwpError>
+        <rc>RC_MBVPD_INVALID_MT_DATA</rc>
+        <description>
+            To get the proper MT data, we need a valid
+            dimm rank combination.
+        </description>
+        <ffdc>RANK_NUM</ffdc>
+        <callout>
+          <procedure>CODE</procedure>
+          <priority>HIGH</priority>
+        </callout>
+     </hwpError>
+
+It generates an FFDC class which looks like this (simplified):
+
+    class rc_mbvpd_invalid_mt_data
+    {
+      public:
+        rc_mbvpd_invalid_mt_data( ... )
+        { FAPI_ERR("To get the proper MT data, we need a valid dimm rank combination."); }
+
+        rc_mbvpd_invalid_mt_data& set_rank_num(const T& i_value)
+        { <setup ffdc> }
+
+        void execute(void)
+        {
+            FAPI_SET_HWP_ERROR(..., RC_MBVPD_INVALID_MT_DATA);
+            fapi2::logError( ... );
+        }
+    };
+
+To use this, for example, you may do:
+
+    FAPI_ASSERT( foo != bar,
+                 rc_mbvpd_invalid_mt_data().set_rank_num(l_rank),
+                 "foo didn't equal bar" );
+
+Notice the description of the error is automatically logged.
+
+## Buffer Support
+
+In FAPI, a ReturnCode had a mechanism for "containing" an error from an
+ecmdDataBuffer. The API, setEcmdError(), no longer exists. fapi2::buffers
+return ReturnCodes, and as such the FFDC information is added in a manner
+consistent with the rest of the FFDC gathering.
+
+There is a new error xml file specifically for buffers called
+buffer_error.xml. It will generate an FFDC class which will take a buffer
+as an argument and generate the correct FFDC.
+
+    <hwpError>
+        <rc>RC_FAPI2_BUFFER</rc>
+        <description>
+            fapi2 error from a buffer operation
+        </description>
+        <buffer>BUFFER</buffer>
+        <callout>
+            <procedure>CODE</procedure>
+            <priority>HIGH</priority>
+        </callout>
+    </hwpError>
+
+And its FFDC class:
+
+    class rc_fapi2_buffer
+    {
+      public:
+        rc_fapi2_buffer( ... )
+        { FAPI_ERR("fapi2 error from a buffer operation"); }
+
+        rc_fapi2_buffer& set_buffer(const fapi2::variable_buffer& i_value)
+        { ... }
+
+        template< typename T >
+        rc_fapi2_buffer& set_buffer(const fapi2::buffer<T>& i_value)
+        { ... }
+    };
+
+And it can be used:
+
+    fapi2::buffer<uint64_t> foo;
+    fapi2::variable_buffer  bar;
+
+    FAPI_ASSERT( rc != FAPI2_RC_SUCCESS,
+                 rc_fapi2_buffer().set_fapi2_buffer(foo),
+                 "problem with buffer" );
+
+    FAPI_ASSERT( rc != FAPI2_RC_SUCCESS,
+                 rc_fapi2_buffer().set_fapi2_buffer(bar),
+                 "problem with buffer" );
+
+Note the indifference to integral or variable buffers.
+
+## Error Log Generation
+
+FAPI had a function called fapiLogError() which would generate platform
+errors. The pattern was to call fapiLogError() at the end of the block
+which generated the FFDC. With the addition of the FFDC classes, this
+is no longer needed - the class knows to create these logs for you.
+
+However, the severity information is needed by this logging mechanism.
+It was an argument to fapiLogError(), and so it's been added to the
+constructor of the FFDC class:
+
+rc_repair_ring_invalid_ringbuf_ptr(fapi2::errlSeverity_t i_sev, ...)
+
+It defaults to "unrecoverable" and so only need be set for errors
+which have a different severity. That is, doing nothing will get you
+and error log with unrecoverable severity - which was the default
+for FAPI.
+
+## Known Limitations
+
+- Collecting register FFDC is not presently implemented.
+- Calling out to hwp to collect FFDC is not presently implemented.
+- The FirstFailureData class does not have a platform pointer
\ No newline at end of file