Initial Deconfigure and GARD support

Change-Id: I8448480627ad478e8e16377027137e6df410053f
Reviewed-on: http://gfw160.austin.ibm.com:8080/gerrit/460
Tested-by: Jenkins Server
Reviewed-by: MIKE J. JONES <mjjones@us.ibm.com>

2 files changed, 496 insertions, 0 deletions

diff --git a/src/include/usr/hwas/deconfigGard.H b/src/include/usr/hwas/deconfigGard.H
new file mode 100644
index 000000000..25de080fc
--- /dev/null
+++ b/src/include/usr/hwas/deconfigGard.H
@@ -0,0 +1,453 @@
+//  IBM_PROLOG_BEGIN_TAG
+//  This is an automatically generated prolog.
+//
+//  $Source: src/include/usr/hwas/deconfigGard.H $
+//
+//  IBM CONFIDENTIAL
+//
+//  COPYRIGHT International Business Machines Corp. 2011
+//
+//  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 other-
+//  wise divested of its trade secrets, irrespective of what has
+//  been deposited with the U.S. Copyright Office.
+//
+//  Origin: 30
+//
+//  IBM_PROLOG_END
+/**
+ *  @file deconfigGard.H
+ *
+ *  @brief Defines the DeconfigGard class that provides functions to deconfigure
+ *  and create GARD records for Targets
+ */
+
+#ifndef DECONFIGGARD_H_
+#define DECONFIGGARD_H_
+
+#include <vector>
+#include <stdint.h>
+#include <sys/sync.h>
+#include <util/singleton.H>
+#include <errl/errlentry.H>
+#include <targeting/target.H>
+#include <targeting/entitypath.H>
+
+namespace HWAS
+{
+
+/**
+ * @brief Returns a reference to the DeconfigGard singleton.
+ */
+class DeconfigGard;
+DeconfigGard & theDeconfigGard();
+
+/**
+ * @class DeconfigGard
+ *
+ * This class defines the singleton that handles Deconfigure and GARD Record
+ * functionality
+ */
+class DeconfigGard
+{
+public:
+
+    /**
+     * @enum GardSeverity
+     *
+     * Defines the possible severities of a GARD Record
+     */
+    enum GardSeverity
+    {
+        GARD_SEVERITY_FATAL      = 1,
+        GARD_SEVERITY_PREDICTIVE = 2,
+        GARD_SEVERITY_MANUAL     = 3,
+    };
+
+    /**
+     * @enum DeconfigCause
+     *
+     * Defines the possible causes for the creation of a Deconfigure Record
+     */
+    enum DeconfigCause
+    {
+        DECONFIG_CAUSE_GARD_RECORD       = 1,  // Existence of GARD Record
+        DECONFIG_CAUSE_FIRMWARE_REQ      = 2,  // Firmware Request
+        DECONFIG_CAUSE_DECONFIG_BY_ASSOC = 3,  // Deconfigure by Association
+    };
+
+    /**
+     * @struct GardRecord
+     *
+     * Defines a GARD Record.
+     * 
+     * Multiple GARD Records can exist for a specific Target
+     */
+    struct GardRecord
+    {
+        uint32_t              iv_recordId;
+        TARGETING::EntityPath iv_targetId;
+        union
+        {
+            char iv_cardMruSn[12]; // TODO is there a SN type?
+            uint32_t iv_chipMruEcid; // TODO is there an ECID type?
+        };
+        uint32_t              iv_errlogPlid;
+        uint8_t               iv_severity; // Value from GardSeverity
+        uint8_t               iv_padding[3];
+        uint32_t              iv_gardTime;
+    };
+
+    typedef std::vector<GardRecord> GardRecords_t;
+    typedef std::vector<GardRecord>::iterator GardRecordsItr_t;
+    typedef std::vector<GardRecord>::const_iterator GardRecordsCItr_t;
+
+    /**
+     * @struct DeconfigureRecord
+     *
+     * Defines a Deconfigure Record
+     * 
+     * Only one Deconfigure Record can exist for a specific Target
+     */
+    struct DeconfigureRecord
+    {
+        TARGETING::EntityPath iv_targetId;
+        uint32_t              iv_errlogPlid;
+        uint8_t               iv_cause; // Value from DeconfigCause
+        uint8_t               iv_padding[3];
+        uint32_t              iv_deconfigureTime;
+    };
+
+    typedef std::vector<DeconfigureRecord> DeconfigureRecords_t;
+    typedef std::vector<DeconfigureRecord>::iterator DeconfigureRecordsItr_t;
+    typedef std::vector<DeconfigureRecord>::const_iterator DeconfigureRecordsCItr_t;
+
+    /**
+     * @brief Destructor.
+     */
+    ~DeconfigGard();
+
+    /**
+     * @brief Clears GARD Records for replaced Targets.
+     *
+     * Called by HWAS as part of initial IPL steps.
+     *
+     * @return errlHndl_t. Error log handle.
+     */
+    errlHndl_t clearGardRecordsForReplacedTargets();
+
+    /**
+     * @brief Deconfigures Targets that have GARD Records in preparation to IPL.
+     *
+     * Called by HWAS as part of initial IPL steps.
+     *
+     * If deconfiguring all such Targets will result in a configuration that is
+     * unable to IPL then it figures out which subset of Targets to deconfigure
+     * to give the best chance of IPL (Resource Recovery).
+     *
+     * @return errlHndl_t. Error log handle.
+     */
+    errlHndl_t deconfigureTargetsFromGardRecordsForIpl();
+
+    /**
+     * @brief Deconfigures a Target.
+     *
+     * Called by ErrlManager when committing an error log containing a
+     * Deconfigure request.
+     * 
+     * This will Deconfigure the Target (set state to non-functional, do any
+     * Deconfigure actions and create a Deconfigure Record) and Deconfigure
+     * Targets by association. Any errors deconfiguring targets are committed
+     * and the function continues. The only errors returned are usage errors.
+     *
+     * @param[in] i_target Reference to Target to deconfigure.
+     * @param[in] i_pErr   Pointer to error log that will shortly be committed
+     *                     by the caller.
+     *
+     * @return errlHndl_t. Error log handle.
+     */
+    errlHndl_t deconfigureTarget(TARGETING::Target & i_target,
+                                 errlHndl_t i_pErr);
+
+    /**
+     * @brief Creates a GARD Record for a Target.
+     *
+     * Called by ErrlManager when committing an error log containing a
+     * GARD Record request.
+     * 
+     * Called by an administrator to manually create a GARD Record.
+     * 
+     * Any error creating the GARD Record will be returned to the user.
+     *
+     * @param[in] i_target   Reference to Target to create GARD Record for.
+     * @param[in] i_pErr     Pointer to error log that will shortly be committed
+     *                       by the caller.
+     * @param[in] i_severity Severity of the GARD Record.
+     *
+     * @return errlHndl_t. Error log handle.
+     */
+    errlHndl_t createGardRecord(const TARGETING::Target & i_target,
+                                errlHndl_t i_pErr,
+                                const GardSeverity i_severity);
+
+    /**
+     * @brief Gets the specified Deconfigure Records.
+     *
+     * Called by an administrator to view Deconfigure Records. There can only be
+     * one Deconfiguration Record per Target.
+     * 
+     * If the specified record does not exist then no error is returned. The
+     * only errors returned are usage errors and errors accessing the
+     * Deconfigure Records.
+     *
+     * @param[in]  i_pTargetId Pointer to the Target ID to get the Deconfigure
+     *                         Record for. If NULL then all Deconfigure Records
+     *                         are retrieved.
+     * @param[out] o_records   Reference to vector of DeconfigureRecords that is
+     *                         cleared then filled in with records.
+     *
+     * @return errlHndl_t. Error log handle.
+     */
+    errlHndl_t getDeconfigureRecords(const TARGETING::EntityPath * i_pTargetId,
+                                     DeconfigureRecords_t & o_records) const;
+    
+    /**
+     * @brief Clears the specified GARD Records.
+     *
+     * Called by an administrator to clear GARD records manually.
+     * 
+     * If the specified record does not exist then no error is returned. The
+     * only errors returned are usage errors and errors accessing the GARD
+     * Records.
+     *
+     * @param[in] i_recordId RecordId to clear. If zero then all GARD Records
+     *                       are cleared.
+     *
+     * @return errlHndl_t. Error log handle.
+     */
+    errlHndl_t clearGardRecords(const uint32_t i_recordId);
+
+    /**
+     * @brief Clears all GARD Records for the specified Target.
+     *
+     * Called by an administrator to clear GARD records manually.
+     * 
+     * If no GARD Records exist for the Target then no error is returned. The
+     * only errors returned are usage errors and errors accessing the GARD
+     * Records.
+     *
+     * @param[in] i_targetId Reference to Target ID to clear GARD Records for.
+     *
+     * @return errlHndl_t. Error log handle.
+     */
+    errlHndl_t clearGardRecords(const TARGETING::EntityPath & i_targetId);
+
+    /**
+     * @brief Gets the specified GARD Records.
+     *
+     * Called by an administrator to view GARD Records.
+     * 
+     * If the specified record does not exist then no error is returned. The
+     * only errors returned are usage errors and errors accessing the GARD
+     * Records.
+     *
+     * @param[in]  i_recordId RecordId to get. If zero then all GARD Records are
+     *                        retrieved.
+     * @param[out] o_records  Reference to vector of GardRecords that is cleared
+     *                        then filled in with records.
+     *
+     * @return errlHndl_t. Error log handle.
+     */
+    errlHndl_t getGardRecords(const uint32_t i_recordId,
+                              GardRecords_t & o_records);
+
+    /**
+     * @brief Gets all GARD Records for the specified Target.
+     *
+     * Called by an administrator to view GARD Records.
+     * 
+     * If no GARD Records exist for the Target then no error is returned. The
+     * only errors returned are usage errors and errors accessing the GARD
+     * Records.
+     *
+     * @param[in]  i_targetId Reference to Target ID to get GARD Records for.
+     * @param[out] o_records  Reference to vector of GardRecords that is cleared
+     *                        then filled in with records.
+     *
+     * @return errlHndl_t. Error log handle.
+     */
+    errlHndl_t getGardRecords(const TARGETING::EntityPath & i_targetId,
+                              GardRecords_t & o_records);
+    
+protected:
+
+    /**
+     * @brief Default constructor
+     * 
+     * Can only be called by Singleton
+     */
+    DeconfigGard();
+
+private:
+
+    // Copy constructor and assignment operator disabled
+    DeconfigGard(const DeconfigGard & i_right);
+    DeconfigGard & operator=(const DeconfigGard & i_right);
+
+    /**
+     * @brief Deconfigures Targets by association.
+     *
+     * @param[in] i_target Reference to base Target.
+     * @param[in] i_pErr   Pointer to error log that will shortly be committed
+     *                     by the caller.
+     */
+    void _deconfigureByAssoc(TARGETING::Target & i_target,
+                             errlHndl_t i_pErr);
+    
+    /**
+     * @brief Deconfigures a Target.
+     *
+     * This will Deconfigure the Target (set state to non-functional, do any
+     * Deconfigure actions and create a Deconfigure Record).
+     *
+     * @param[in] i_target Reference to Target to deconfigure.
+     * @param[in] i_pErr   Pointer to error log that will shortly be committed
+     *                     by the caller.
+     * @param[in] i_cause  Deconfigure cause.
+     */
+    void _deconfigureTarget(TARGETING::Target & i_target,
+                            errlHndl_t i_pErr,
+                            const DeconfigCause i_cause);
+    
+    /**
+     * @brief Performs Deconfigure Actions.
+     *
+     * @param[in] i_target Reference to Target to perform actions on.
+     */
+    void _doDeconfigureActions(TARGETING::Target & i_target);
+
+    /**
+     * @brief Creates a Deconfigure Record
+     *
+     * @param[in] i_target Reference to Target to create record for.
+     * @param[in] i_pErr   Pointer to error log that will shortly be committed
+     *                     by the caller.
+     * @param[in] i_cause  Deconfigure cause.
+     */
+    void _createDeconfigureRecord(const TARGETING::Target & i_target,
+                                  errlHndl_t i_pErr,
+                                  const DeconfigCause i_cause);
+    
+public:
+    
+    /**
+     * @brief Clears the specified Deconfigure Records.
+     * 
+     * @note Provided for unit test only. Production code should not be
+     *       clearing Deconfigure Records.
+     *
+     * @param[in] i_pTargetId Pointer to the Target ID to clear Deconfigure
+     *                        Records for. If NULL then all Deconfigure Records
+     *                        are cleared.
+     */
+    void _clearDeconfigureRecords(const TARGETING::EntityPath * i_pTargetId);
+    
+private:
+    /**
+     * @brief Gets the specified Deconfigure Records.
+     *
+     * @param[in]  i_pTargetId Pointer to the Target ID to get the Deconfigure
+     *                         Record for. If NULL then all Deconfigure Records
+     *                         are retrieved.
+     * @param[out] o_records   Reference to vector of DeconfigureRecords that is
+     *                         cleared then filled in with records.
+     */
+    void _getDeconfigureRecords(const TARGETING::EntityPath * i_pTargetId,
+                                DeconfigureRecords_t & o_records) const;
+    
+    /**
+     * @brief Creates a GARD Record for a Target.
+     * 
+     * @param[in] i_target   Reference to Target to create GARD Record for.
+     * @param[in] i_pErr     Pointer to error log that will shortly be committed
+     *                       by the caller.
+     * @param[in] i_severity Severity of the GARD Record.
+     *
+     * @return errlHndl_t. Error log handle.
+     */
+    errlHndl_t _createGardRecord(const TARGETING::Target & i_target,
+                                 errlHndl_t i_pErr,
+                                 const GardSeverity i_severity);
+    
+    /**
+     * @brief Clears the specified GARD Records.
+     *
+     * @param[in] i_recordId RecordId to clear. If zero then all GARD Records
+     *                       are cleared.
+     *
+     * @return errlHndl_t. Error log handle.
+     */
+    errlHndl_t _clearGardRecords(const uint32_t i_recordId);
+    
+    /**
+     * @brief Clears all GARD Records for the specified Target.
+     *
+     * @param[in] i_targetId Reference to Target ID to clear GARD Records for.
+     *
+     * @return errlHndl_t. Error log handle.
+     */
+    errlHndl_t _clearGardRecords(const TARGETING::EntityPath & i_targetId);
+
+    /**
+     * @brief Gets the specified GARD Records.
+     *
+     * @param[in]  i_recordId RecordId to get. If zero then all GARD Records are
+     *                        retrieved.
+     * @param[out] o_records  Reference to vector of GardRecords that is cleared
+     *                        then filled in with records.
+     *
+     * @return errlHndl_t. Error log handle.
+     */
+    errlHndl_t _getGardRecords(const uint32_t i_recordId,
+                               GardRecords_t & o_records);
+    
+    /**
+     * @brief Gets all GARD Records for the specified Target.
+     *
+     *
+     * @param[in]  i_targetId Reference to Target ID to get GARD Records for.
+     * @param[out] o_records  Reference to vector of GardRecords that is cleared
+     *                        then filled in with records.
+     *
+     * @return errlHndl_t. Error log handle.
+     */
+    errlHndl_t _getGardRecords(const TARGETING::EntityPath & i_targetId,
+                               GardRecords_t & o_records);
+    
+    /**
+     * @brief Ensures that the GARD Record data is setup
+     * 
+     * @return errlHndl_t. Error log handle.
+     */
+    errlHndl_t _ensureGardRecordDataSetup();
+    
+    // Mutex for thread safety
+    mutable mutex_t iv_mutex;
+    
+    // GARD Record Data
+    uint32_t iv_nextGardRecordId;   // Next GARD Record ID to use
+    uint32_t iv_maxGardRecords;     // Maximum number of GARD Records
+    GardRecord * iv_pGardRecords;   // Pointer to the GARD Records in PNOR
+
+    // The Deconfigure Records
+    DeconfigureRecords_t iv_deconfigureRecords;
+};
+
+}
+
+#endif
diff --git a/src/include/usr/hwas/hwas_reasoncodes.H b/src/include/usr/hwas/hwas_reasoncodes.H
new file mode 100644
index 000000000..6e2b34858
--- /dev/null
+++ b/src/include/usr/hwas/hwas_reasoncodes.H
@@ -0,0 +1,43 @@
+//  IBM_PROLOG_BEGIN_TAG
+//  This is an automatically generated prolog.
+//
+//  $Source: src/include/usr/hwas/hwas_reasoncodes.H $
+//
+//  IBM CONFIDENTIAL
+//
+//  COPYRIGHT International Business Machines Corp. 2011
+//
+//  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 other-
+//  wise divested of its trade secrets, irrespective of what has
+//  been deposited with the U.S. Copyright Office.
+//
+//  Origin: 30
+//
+//  IBM_PROLOG_END
+#ifndef HWAS_REASONCODES_H
+#define HWAS_REASONCODES_H
+
+#include <hbotcompid.H>
+
+namespace HWAS
+{
+    enum HwasModuleID
+    {
+        MOD_DECONFIG_GARD    = 0x01,
+    };
+
+    enum HwasReasonCode
+    {
+        RC_TARGET_NOT_DECONFIGURABLE = HWAS_COMP_ID | 0x01,
+        RC_TARGET_NOT_GARDABLE       = HWAS_COMP_ID | 0x02,
+        RC_GARD_REPOSITORY_FULL      = HWAS_COMP_ID | 0x03,
+    };
+};
+
+#endif