diff options
Diffstat (limited to 'src/import')
-rwxr-xr-x | src/import/hwpf/fapi2/docs/topics/Ffdc.md | 149 | ||||
-rw-r--r-- | src/import/hwpf/fapi2/include/error_info.H | 38 | ||||
-rw-r--r-- | src/import/hwpf/fapi2/include/utils.H | 4 |
3 files changed, 184 insertions, 7 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 diff --git a/src/import/hwpf/fapi2/include/error_info.H b/src/import/hwpf/fapi2/include/error_info.H index 8da7f7ab7..81e72d2ff 100644 --- a/src/import/hwpf/fapi2/include/error_info.H +++ b/src/import/hwpf/fapi2/include/error_info.H @@ -22,10 +22,11 @@ /* permissions and limitations under the License. */ /* */ /* IBM_PROLOG_END_TAG */ -/** - * @file erro_infor.H - * @brief Defines the Error Information structures and classes - */ + +/// +/// @file error_info.H +/// @brief Defines the Error Information structures and classes +/// #ifndef FAPI2_ERRORINFO_H_ #define FAPI2_ERRORINFO_H_ @@ -174,7 +175,7 @@ namespace fapi2 } /// - /// @enum Enumeration of firmware traces + /// @enum Collect Trace /// /// This enumeration defines the possible firmware traces to collect /// @@ -738,6 +739,9 @@ namespace fapi2 const void* const* i_object) const; }; + /// + /// @brief Structure representing a hardware callout + /// struct ErrorInfoEntryHwCallout { uint8_t iv_hw; @@ -747,6 +751,9 @@ namespace fapi2 const void* const* i_object) const; }; + /// + /// @brief Structure representing a procedure callout + /// struct ErrorInfoEntryProcCallout { uint8_t iv_procedure; @@ -762,6 +769,9 @@ namespace fapi2 ErrorInfoEntryProcCallout(void) = default; }; + /// + /// @brief Structure representing a bus callout + /// struct ErrorInfoEntryBusCallout { uint8_t iv_endpoint1ObjIndex; @@ -771,6 +781,9 @@ namespace fapi2 const void* const* i_object) const; }; + /// + /// @brief Structure representing a target callout + /// struct ErrorInfoEntryTargetCDG { uint8_t iv_targetObjIndex; @@ -782,6 +795,9 @@ namespace fapi2 const void* const* i_object) const; }; + /// + /// @brief Structure representing a child callout + /// struct ErrorInfoEntryChildrenCDG { uint8_t iv_parentObjIndex; @@ -796,6 +812,9 @@ namespace fapi2 const void* const* i_object) const; }; + /// + /// @brief Structure representing collected trace information + /// struct ErrorInfoEntryCollectTrace { uint32_t iv_eieTraceId; @@ -803,6 +822,9 @@ namespace fapi2 const void* const* i_object) const; }; + /// + /// @brief Union of all the error info types + /// struct ErrorInfoEntry { uint8_t iv_type; // Value from ErrorInfoType @@ -816,6 +838,12 @@ namespace fapi2 ErrorInfoEntryChildrenCDG children_cdg; ErrorInfoEntryCollectTrace collect_trace; }; + + /// + /// @brief Add error information to the FFDC object + /// @param[in] i_info a shared pointer to the error info + /// @param[in] i_object the list of ffdc objects being collected + /// void addErrorInfo(std::shared_ptr<ErrorInfo> i_info, const void* const* i_object) const { diff --git a/src/import/hwpf/fapi2/include/utils.H b/src/import/hwpf/fapi2/include/utils.H index c72a9ebd1..658062721 100644 --- a/src/import/hwpf/fapi2/include/utils.H +++ b/src/import/hwpf/fapi2/include/utils.H @@ -23,8 +23,8 @@ /* */ /* IBM_PROLOG_END_TAG */ /** - * @file erro_infor.H - * @brief Defines the Error Information structures and classes + * @file utils.H + * @brief Defines common fapi2 utilities */ #ifndef FAPI2_UTILS_H_ |