diff options
Diffstat (limited to 'src/usr/diag/prdf/util/prdfFilters.H')
| -rwxr-xr-x | src/usr/diag/prdf/util/prdfFilters.H | 459 |
1 files changed, 459 insertions, 0 deletions
diff --git a/src/usr/diag/prdf/util/prdfFilters.H b/src/usr/diag/prdf/util/prdfFilters.H new file mode 100755 index 000000000..8fff8c387 --- /dev/null +++ b/src/usr/diag/prdf/util/prdfFilters.H @@ -0,0 +1,459 @@ +/* IBM_PROLOG_BEGIN_TAG */ +/* This is an automatically generated prolog. */ +/* */ +/* $Source: src/usr/diag/prdf/util/prdfFilters.H $ */ +/* */ +/* IBM CONFIDENTIAL */ +/* */ +/* COPYRIGHT International Business Machines Corp. 2004,2012 */ +/* */ +/* p1 */ +/* */ +/* Object Code Only (OCO) source materials */ +/* Licensed Internal Code Source Materials */ +/* IBM HostBoot Licensed Internal Code */ +/* */ +/* The source code for this program is not published or otherwise */ +/* divested of its trade secrets, irrespective of what has been */ +/* deposited with the U.S. Copyright Office. */ +/* */ +/* Origin: 30 */ +/* */ +/* IBM_PROLOG_END_TAG */ + +#ifndef PRDFFILTER_H +#define PRDFFILTER_H + +/** + @file prdfFilter.H + @brief FILTER_CLASSes selectivly remove bits from a prdfBitKey type object +*/ + +/*--------------------------------------------------------------------*/ +/* Includes */ +/*--------------------------------------------------------------------*/ + +#if !defined(PRDFBITLKEY_H) +#include <prdfBitKey.H> +#endif + +#include <vector> + +/*--------------------------------------------------------------------*/ +/* Forward References */ +/*--------------------------------------------------------------------*/ + +class prdfBitKey; + +/*--------------------------------------------------------------------*/ +/* User Types */ +/*--------------------------------------------------------------------*/ + +/** + prdfFilter Specifies and interface for removing unwanted bits from a prdfBitKey. + Abstract base class + @see prdfBitKey +*/ +class prdfFilter +{ +public: + + + /** + Destructor. This implementation does nothing + */ + virtual ~prdfFilter(void); + + + /** + Apply filter to the prdfBitKey. + @post bit_list may be modified + @return true if bit_list was modified, otherwise false + */ + virtual bool Apply(prdfBitKey & io_bit_list) = 0; + + /** + * Undo the filter effect (if possible) + * @post bit_list may be modified + * @Return tru if bit_list was modified, otherwise false + * @note: bit_lists are sometimes used to reset an error register based on the bit that was + * analyzed. If the Apply() function modifes the bit_list in such a way that make it unusable + * to reset the error register (eg. moves a bit to a new postition) than the Undo() function + * should put the bit_list back into a state that can be used to reset an error register. + */ + virtual bool Undo(prdfBitKey & io_bit_list) { return false; } + +protected: + + /** + Default Constructor + @note The default compiler generated copy constructor and assignment operator + are adaquate. + */ + prdfFilter(void) {} + +}; + +//! prdfFilterPriority +/*! + prdfFilterPriority maintains a "subset" BitKey or a "priority" set of bits. + When this filter is applied to a BitKey, If the "priority" BitKey is a subset of the + BitKey than the BitKey becomes the priorty BitKey. (The non-priority bits are turned off); + Otherwise the BitKey remains unchanged. + + \verbatim + Examples: + Priority BitKey: ("1") + Original BitKey: ("1", "5", "31") + Filtered BitKey: ("1") + + Priority BitKey: ("1") + Original BitKey: ("5", "31") + Filtered BitKey: ("5", "31") + + Priority BitKey: ("2", "7") + Original BitKey: ("2", "5", "31") + Filtered BitKey: ("2", "5", "31") + + Priority BitKey: ("2", "7") + Original BitKey: ("2", "7", "31") + Filtered BitKey: ("2", "7") + \endverbatim + */ +class prdfFilterPriority : public prdfFilter +{ +public: + + /*! + Constructor + \param i_bld ptr bit list string encoding + */ + prdfFilterPriority(const char * i_ble) + : ivBitKey(i_ble) + {} + + + /*! + Constructor + \param iBitList BitKey + */ + prdfFilterPriority(const prdfBitKey & iBitList) + : ivBitKey(iBitList) + {} + + /*! + Apply the filter to a bit list + \param ioBitList to apply filter to + \returns true if iBitList modified otherwise false + */ + virtual bool Apply(prdfBitKey & ioBitList); + +protected: + + + prdfBitKey ivBitKey; + +}; + +//! PrioritySingleBitFilter +/*! + PrioritySingleBitFilter removes all but one bit from a prdfBitKey object. + Priority (to not be removed) is given to the bits specified and in the order + specified. + @par Example + @code + const char * const BIT_LIST_STRING_31_26 = "\x20\x1B"; // priority bits + PrioritySingleBitFilter psbFilter(BIT_LIST_STRING_31_26); + ScanCommRegisterChip scr(...); // see iipScanCommRegisterChip.h + ResolutionMap resMap(...); // see iipResolutionMap.h + + // when the error register is read, the resulting list of bits on + // is passed to psbFilter. the result is used to look up a resolution + // in the ResultionMapa resMap and the resolution is called + ErrorRegisterMask ereg(scr,resMap,&psbFilter); + ... + rc = ereg.Analyze(serviceData); // See iipErrorRegisterMask.h + // ereg will apply filter prioritizing bit 31 then bit 26 + // and finally any remaining bits + @endcode + @par functionality + - if no priority bits exist in prdfBitKey object then + - eliminate all but first entry in list + - else if priority bits exist then + - eliminate all non-priority bit entries + - if multiple priority bit entries exist then elminate all but one, + favoring the first qualified entry found in the list. +*/ +class PrioritySingleBitFilter : public prdfFilter +{ +public: + + /** + Constructor + @param pbls Priority bit list string: list of bit positions that have priority + @note bit position priority values in pbls are the bit position + 1 of the bit list, + thus to prioritize bit positions 0,1, & 2 in the bit list, pbls would = "\x01\x02\x03"; + */ + PrioritySingleBitFilter(const char * pbls = NULL) + { + if (NULL != pbls) + { + while('\0' != pbls[0]) + { + iv_bitList.push_back(pbls[0]+1); + pbls++; + } + } + }; + + PrioritySingleBitFilter(const std::vector<uint8_t> & pbls) + { + iv_bitList = pbls; + }; + + + /** + Apply filter to bit list + @param bit_list : the bit list to filter + @pre none + @post Bit list will only have one value - the one with the highest + priority. If multiple values have equally highest priority then the first + value in the list is used. + @return true of bit list was modified otherwise false + @note If the bit list is empty then it will be left empty. + */ + virtual bool Apply(prdfBitKey & bit_list); + +private: // functions +private: // Data + + std::vector<uint8_t> iv_bitList; + +}; + +//! prdfFilterTranspose +/*! + prdfFilterTranspose transposes an exactly matching key to a single bit. If there is not an + exact match, the key is not modified. +*/ +class prdfFilterTranspose : public prdfFilterPriority +{ +public: + + /** + Constructor + \param i_bitKey bit list key + \param iBitPos bit to set if i_bitKey matches target. + */ + prdfFilterTranspose(const prdfBitKey &i_bitKey,uint32_t iBitPos) + : prdfFilterPriority(i_bitKey),ivSingleBitPos(iBitPos) + {} + + /** + Apply filter to bit list + \param bit_list : the bit list to filter + \pre none + \post If the provide BitList exactly matches the internal BitList than the provided + bitlist is modified such that all bits are cleared and ivSingleBitPos is set. + \return true of bit list was modified otherwise false + */ + virtual bool Apply(prdfBitKey & iBitList); + + /** + * Undo the filter Apply() + * @post bit_list may be modified + * @Return true if bit_list was modified, otherwise false + * @Note This function will only Undo the transposition if the transposed result bit is on + */ + virtual bool Undo(prdfBitKey & iBitList); + +private: // functions +private: // Data + + uint32_t ivSingleBitPos; + +}; + +//! SingleBitFilter +/*! + Reduces a BitKey to single bit + \code + // usually in chip class header file + SingleBitFilter sbFilter; + ScanCommRegisterChip scr; // @see iipScanCommRegisterChip.h + ResolutionMap resMap; // @see prdfResolutionMap.H + + // in ctor of chip class definition + ErrorRegisterMask ereg(scr,resMap,&sbFilter); + // ... + rc = ereg.Analyze(serviceData); // See iipErrorRegisterMask.h + // ereg will apply filter before analyzing the error + \endcode + */ +class SingleBitFilter: public prdfFilter +{ +public: + /*! + Constructor + */ + SingleBitFilter(): prdfFilter() {} + + /*! + Remove all but one bit from bit_list + \param ioBitList Target bit list + \returns true if ioBitList was modified otherwise false + */ + virtual bool Apply(prdfBitKey & ioBitList); + +private: // functions +private: // Data + +}; + + +//! FilterLink +/*! + FilterLink links two FILTER_CLASS types together allowing two filters + to act on a single prdfBitKey object. + @code + + prdfFilter * foo(prdfFilter & f1, prdfFilter & f2) + { + prdfFilter * joint = new FilterLink(f1,f2); + return joint; + } + @endcode + */ +class FilterLink: public prdfFilter +{ +public: + /** + Constructor + <ul> + <br><b>Parameters: </b> Two Filters to be linked + <br><b>Requirements:</b> parm filters objects must exist and be valid + <br><b>Promises: </b> Object created + <br><b>Exceptions: </b> N/A + <br><b>Notes: </b> + </ul><br> + */ + FilterLink(prdfFilter & f1, prdfFilter & f2); + + /* + Destructor + <ul> + <br><b>Parameters: </b> None. + <br><b>Returns: </b> No value returned + <br><b>Requirements:</b> None. + <br><b>Promises: </b> None. + <br><b>Exceptions: </b> None. + <br><b>Notes: </b> Default is sufficient + </ul><br> + */ + // ~xspprdFilterLink(); + + /** + Apply Filter(s) + <ul> + <br><b>Parameters: </b> reference to a BIT_LIST (see iipbtlst.h) + <br><b>Returns: </b> [TRUE | FALSE] - was bit list modified? + <br><b>Requirements:</b> None. + <br><b>Promises: </b> bit_list is modified (if rc == TRUE) + <br><b>Exceptions: </b> N/A + <br><b>Notes: </b> calls all the other associated filters + </ul><br> + */ + virtual bool Apply ( prdfBitKey & bit_list ); + + /** + * Undo the filter Apply() + * @post bit_list may be modified + * @Return true if bit_list was modified, otherwise false + */ + virtual bool Undo(prdfBitKey & iBitList); + +private: // functions +private: // Data + + // may be extended to use a vector if needed + prdfFilter & xFilter1; + prdfFilter & xFilter2; +}; + + +class SCAN_COMM_REGISTER_CLASS; + +//! ScanCommFilter +/*! + ScanCommFilter reads a HW scom register to determin which bits to + removes bits from a prdfBitKey object + @par Base class prdfFilter + @code + // This class is useful for Error registers whose bits can be + // configured to report different ways depending on another + // enable register. + + ScanCommRegister enableScr(...); // see iipScanCommRegisterChip.h + ScanCommFilter scfFirXstop(enableScr,INVERT); + ScanCommFilter scfFirRer(enableScr,NONINVERT); + ScanCommRegister scr(...); // see iipScanCommRegisterChip.h + ResolutionMap resMap(...); // see iipResolutionMap.h + ErrorRegisterMask eregFirXstop(scr,resMap,&scfFirXstop); + ErrorRegisterMask eregFirRer(scr,resMap,&scfFirRer); + ... + rc = eregFirXstop.Analyze(serviceData); // See iipErrorRegisterMask.h + // ereg will apply filter + @endcode + */ +class ScanCommFilter: public prdfFilter +{ +public: + + // Enum for use as the second parameter in the constructor. + enum InvertValue { + NONINVERT = 0x0, + INVERT = 0x1 + }; + + /*! + Constructor + \param r Reference to a scan comm register + \param invert whether or not to bit-wise invert the value from the scan comm read + */ + ScanCommFilter(SCAN_COMM_REGISTER_CLASS & i_r, InvertValue invert = NONINVERT) + : + prdfFilter(), + scr(i_r), + xInvert(invert) + { } + + /*! + Turn off bits in bit list based on contents of scan com register + @post bit_list may be modified + @return true if bit_list was modified, otherwise false + */ + virtual bool Apply(prdfBitKey & bit_list); + +private: // functions +private: // Data + SCAN_COMM_REGISTER_CLASS & scr; + InvertValue xInvert; +}; + + +inline FilterLink::FilterLink(prdfFilter & f1, prdfFilter & f2) +: xFilter1(f1), xFilter2(f2) {} + + +#endif +// Change Log ************************************************************************************* +// +// Flag Reason Vers Date Coder Description +// ---- -------- ------- -------- -------- ------------------------------------------------------- +// V400 09/12/94 JST Initial Creation +// fips 03/19/04 dgilbert Rename to prdfFilter.H added doxygen comments +// 558003 fips310 06/21/06 dgilbert Add Undo() to filter +// 582595 fips310 12/12/06 iawillia Update priority sb filter to maintain bit order. +// End Change Log ******************************************************************************** + + |
