HWPF: Enforce correct fapi::ReturnCode usage

Change-Id: Id5f2c7c4ebef5fa880133dd8ba353d69def10bbc
Reviewed-on: http://gfw160.austin.ibm.com:8080/gerrit/628
Tested-by: Jenkins Server
Reviewed-by: Van H. Lee <vanlee@us.ibm.com>
Reviewed-by: MIKE J. JONES <mjjones@us.ibm.com>

2 files changed, 68 insertions, 27 deletions

diff --git a/src/include/usr/hwpf/fapi/fapiReturnCode.H b/src/include/usr/hwpf/fapi/fapiReturnCode.H
index 34c060ca6..bd19c40e8 100644
--- a/src/include/usr/hwpf/fapi/fapiReturnCode.H
+++ b/src/include/usr/hwpf/fapi/fapiReturnCode.H
@@ -38,6 +38,7 @@
  *                                                  setHwpFfdc
  *                          mjjones     09/22/2011  Added ErrorInfo Support
  *                          mjjones     11/10/2011  Use ecmdDataBufferBase
+ *                          mjjones     01/12/2012  Enforce correct usage
  */
 
 #ifndef FAPIRETURNCODE_H_
@@ -51,6 +52,7 @@
 #include <fapiErrorInfo.H>
 #include <fapiHwpErrorInfo.H>
 #include <fapiPlatTrace.H>
+#include <fapiHwpReturnCodes.H>
 
 /**
  * @brief Set HWP Error macro
@@ -60,7 +62,7 @@
  * needs to be processed
  */
 #define FAPI_SET_HWP_ERROR(RC, ERROR) \
-    RC.resetError(fapi::ERROR); \
+    RC._setHwpError(fapi::ERROR); \
     ERROR##_CALL_FUNC_TO_ANALYZE_ERROR(RC); \
     ERROR##_CALL_FUNCS_TO_COLLECT_FFDC(RC); \
     ERROR##_ADD_ERROR_INFO(RC)
@@ -75,13 +77,17 @@ class ReturnCodeDataRef;
  * @class ReturnCode
  *
  * This class provides a generic return code. It contains the rcValue (return
- * code value) which is of type uint32_t. A user can treat a ReturnCode just
- * as if it were a uint32_t.
+ * code value) which is of type uint32_t.
  *
- * FAPI, PLAT and HWP code can all create a ReturnCode.
- * PLAT can associate PlatData to it (use-case is an error log).
- * HWPs can add ErrorInfo to it (via FAPI_SET_HWP_ERROR macro).
- * FFDC HWPs can add FFDC ErrorInfo to it (via addEIFfdc member function)
+ * FAPI can set an error in the ReturnCode by calling setFapiError.
+ * PLAT can set an error in the ReturnCode by calling setPlatError, this
+ *      function associates heap based PlatData to the ReturnCode (use-case is
+ *      an error log).
+ * HWP  can set an error in the ReturnCode by calling FAPI_SET_HWP_ERROR, this
+ *      macro adds any error information associated with the HWP error to the
+ *      ReturnCode (error information is documented in an error XML file).
+ * FAPI/PLAT/HWP can set an ecmdDataBufferBase error in the ReturnCode by
+ *               calling setEcmdError
  *
  * A ReturnCode is copyable and assignable. Therefore, it cannot be subclassed.
  *
@@ -104,15 +110,13 @@ public:
     /**
      * @brief Constructor. Sets rcValue to the specified value
      *
-     * @note This allows an implicit conversion between a uint32_t and a
-     *       ReturnCode. A user is allowed to return a uint32_t from a function
-     *       that returns a ReturnCode or is allowed to pass a uint32_t to a
-     *       function that expects a ReturnCode and in both cases, the uint32_t
-     *       will be automatically converted to a ReturnCode.
+     * @note This allows an implicit conversion from a value from the
+     *       ReturnCodes enumeration and a ReturnCode. This is provided so that
+     *       a function can do "return FAPI_RC_SUCCESS;"
      *
      * @param[in] i_rcValue The rcValue to set
      */
-    ReturnCode(const uint32_t i_rcValue);
+    ReturnCode(const ReturnCodes i_rcValue);
 
     /**
      * @brief Copy Constructor
@@ -136,7 +140,11 @@ public:
     ReturnCode & operator=(const ReturnCode & i_right);
 
     /**
-     * @brief Assignment Operator.
+     * @brief ***DEPRECATED*** Assignment Operator.
+     *
+     * TODO
+     * This function will be deleted to prevent invalid usage of ReturnCode
+     * Use setFapiError, setPlatError, setEcmdError or FAPI_SET_HWP_ERROR
      *
      * @param[in] i_rc rcValue to assign
      *
@@ -147,13 +155,6 @@ public:
     ReturnCode & operator=(const uint32_t i_rcValue);
 
     /**
-     * @brief Any associated data is deleted and the specified rcValue is set
-     *
-     * @param[in] i_rc rcValue to set
-     */
-    void resetError(const uint32_t i_rcValue);
-
-    /**
      * @brief Returns if the return code indicates success
      *
      * @return bool. True if ok, else false
@@ -166,21 +167,57 @@ public:
      * @note This allows a user to directly compare:
      *       1/ ReturnCode to uint32_t (ReturnCode converted to uint32_t)
      *       2/ ReturnCode to ReturnCode (Both ReturnCode converted to uint32_t)
+     *       This allows a user to test if a ReturnCode is bad (if (l_rc){})
      */
     operator uint32_t() const;
 
     /**
-     * @brief Associates heap based PlatData with the ReturnCode. The ReturnCode
-     *        object takes responsibility for deleting the data (platform code
-     *        actually implements the delete function and must know the type and
-     *        how to delete it). Any existing PlatData is deleted.
+     * @brief Sets a FAPI error. Sets the rcValue to the supplied value (from
+     *        the ReturnCodes enumeration) and deletes any associated data.
+     *
+     * This is called by FAPI code to generate an error.
+     *
+     * @param[in] i_rcValue Error value to set
+     */
+    void setFapiError(const ReturnCodes i_rcValue);
+
+    /**
+     * @brief Sets an ecmd error. Sets the rcValue to the supplied value and
+     *        deletes any associated data.
+     *
+     * This is called by FAPI/PLAT/HWP code to generate an error when an
+     * ecmdDataBufferBase call returns non zero. This can also be used by PLAT
+     * code that reports errors with ecmd return codes.
+     *
+     * @param[in] i_rcValue ecmdDataBufferBase error value to set
+     */
+    void setEcmdError(const uint32_t i_rcValue);
+
+    /**
+     * @brief Sets a PLAT error. Sets the rcValue to FAPI_RC_PLAT_ERR_SEE_DATA,
+     *        deletes any associated data and associates the supplied heap based
+     *        PlatData with the ReturnCode. The ReturnCode object takes
+     *        responsibility for deleting the data (platform code implements the
+     *        delete function and must know the type and how to delete it).
      *
      * This is called by PLAT. The expected use-case is to associate a platform
      * error log with the ReturnCode.
      *
      * @param[in] i_pData Pointer to PlatData (on the heap)
      */
-    void setPlatData(void * i_pData);
+    void setPlatError(void * i_pData);
+
+    /**
+     * @brief Sets a HWP error. Sets the rcValue to the supplied value (from
+     *        the HwpReturnCode enumeration) and deletes any associated data.
+     *
+     * HWP code must call the FAPI_SET_HWP_ERROR macro rather than this function
+     * directly to generate an error so that any error information is
+     * automatically added to the ReturnCode
+     *
+     * @param[in] i_rcValue Error value to set
+     */
+    void _setHwpError(const HwpReturnCode i_rcValue);
 
     /**
      * @brief Get a pointer to any PlatData. ReturnCode is still responsible for
diff --git a/src/include/usr/hwpf/fapi/fapiReturnCodes.H b/src/include/usr/hwpf/fapi/fapiReturnCodes.H
index 2f0592f27..011b8e814 100644
--- a/src/include/usr/hwpf/fapi/fapiReturnCodes.H
+++ b/src/include/usr/hwpf/fapi/fapiReturnCodes.H
@@ -38,6 +38,7 @@
  *                          mjjones     10/07/2011  Add FAPI_RC_INVALID_ATTR_GET
  *                          mjjones     10/28/2011  Trim FAPI/PLAT errors
  *                          mjjones     11/10/2011  Use ecmdDataBufferBase
+ *                          mjjones     01/13/2012  Name enumeration
  */
 
 #ifndef FAPIRETURNCODES_H_
@@ -50,8 +51,11 @@ namespace fapi
 
 /**
  * @brief Enumeration of return codes
+ *
+ * @note HWP return codes are in the HwpReturnCode enumeration in the
+ *       generated fapiHwpReturnCodes.H file
  */
-enum
+enum ReturnCodes
 {
     FAPI_RC_SUCCESS = 0,