# 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