From 98ebc26c43fb8d88224e4a3f1b7e30480dfe5c6e Mon Sep 17 00:00:00 2001 From: Brian Silver Date: Fri, 13 Feb 2015 13:39:53 -0600 Subject: Add FFDC xml parsing documentation Change-Id: I56844e96c80fb3eb345b2254a7b42dd95c434ce3 Reviewed-on: http://gfw160.aus.stglabs.ibm.com:8080/gerrit/16041 Reviewed-by: Thi N. Tran Reviewed-by: MATTHEW A. PLOETZ Reviewed-by: Brian Silver Tested-by: Brian Silver --- src/import/hwpf/fapi2/docs/topics/Ffdc.md | 149 ++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100755 src/import/hwpf/fapi2/docs/topics/Ffdc.md (limited to 'src/import/hwpf/fapi2/docs') 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= ... +- 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: + + + RC_MBVPD_INVALID_MT_DATA + + To get the proper MT data, we need a valid + dimm rank combination. + + RANK_NUM + + CODE + HIGH + + + +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) + { } + + 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. + + + RC_FAPI2_BUFFER + + fapi2 error from a buffer operation + + BUFFER + + CODE + HIGH + + + +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& i_value) + { ... } + }; + +And it can be used: + + fapi2::buffer 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 -- cgit v1.2.1