diff options
author | Brian Silver <bsilver@us.ibm.com> | 2015-02-13 13:39:53 -0600 |
---|---|---|
committer | Patrick Williams <iawillia@us.ibm.com> | 2015-12-11 13:40:20 -0600 |
commit | 98ebc26c43fb8d88224e4a3f1b7e30480dfe5c6e (patch) | |
tree | a3716f8ca0853c9f411538598cd529dbe60a6632 /src/import/hwpf/fapi2/docs | |
parent | 7f9a11f532c96b8c50b9f9d0d1e6edd5f60f1f53 (diff) | |
download | talos-hostboot-98ebc26c43fb8d88224e4a3f1b7e30480dfe5c6e.tar.gz talos-hostboot-98ebc26c43fb8d88224e4a3f1b7e30480dfe5c6e.zip |
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>
Diffstat (limited to 'src/import/hwpf/fapi2/docs')
-rwxr-xr-x | src/import/hwpf/fapi2/docs/topics/Ffdc.md | 149 |
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 |