Migrate headers to support platform specializations

  Add plat_target.H, fapi2_target.H
  Add plat_error_scope.H, fapi2_error_scope.H
  Update documentation to reflect platform support
  Wrap buffer print() API to remove from platforms
  Move target operators to platform specific files
  Move target states to target_states.H
  Add plat_hw_access, fapi2_hw_access.H
  Make op mode and pib error platform specific

Change-Id: If376f656b2b8a8f207332d42494dd3ce099790c6
Reviewed-on: http://gfw160.aus.stglabs.ibm.com:8080/gerrit/16970
Reviewed-by: Matt K. Light <mklight@us.ibm.com>
Reviewed-by: Thi N. Tran <thi@us.ibm.com>
Reviewed-by: Brian Silver <bsilver@us.ibm.com>
Tested-by: Brian Silver <bsilver@us.ibm.com>

5 files changed, 214 insertions, 74 deletions

diff --git a/import/hwpf/fapi2/include/buffer_traits.H b/import/hwpf/fapi2/include/buffer_traits.H
index 2b98019c..7585d135 100644
--- a/import/hwpf/fapi2/include/buffer_traits.H
+++ b/import/hwpf/fapi2/include/buffer_traits.H
@@ -35,8 +35,10 @@
 #include <algorithm>
 #include <buffer_parameters.H>
 
-// for debug printing ... can be removed for flight
+#ifdef FAPI2_DEBUG
 #include <iostream>
+#endif
+
 #include <iterator>
 
 namespace fapi2
@@ -60,7 +62,8 @@ namespace fapi2
     class bufferTraits
     {
     public:
-#ifndef DOXYGEN
+
+#if !defined(DOXYGEN) && defined(FAPI2_DEBUG)
         ///
         /// @brief Print a container of bits
         /// @param[in] i_data the container of bits
@@ -153,7 +156,7 @@ namespace fapi2
     class bufferTraits<bits_container, uint32_t>
     {
     public:
-#ifndef DOXYGEN
+#if !defined(DOXYGEN) && defined(FAPI2_DEBUG)
         ///
         /// @brief Print a container of bits
         /// @param[in] i_data the container of bits
diff --git a/import/hwpf/fapi2/include/error_scope.H b/import/hwpf/fapi2/include/error_scope.H
index 4e4bc485..91b7c380 100644
--- a/import/hwpf/fapi2/include/error_scope.H
+++ b/import/hwpf/fapi2/include/error_scope.H
@@ -24,82 +24,14 @@
 /* IBM_PROLOG_END_TAG                                                     */
 /**
  * @file error_scope.H
- * @brief definitions which create a scope for automatic error handling
+ * @brief platform specializations which create a scope for automatic error handling
  */
 
 #ifndef __FAPI2_ERROR_SCOPE__
 #define __FAPI2_ERROR_SCOPE__
 
-#include <stdint.h>
-#include <thread>
-#include <stdio.h>
-#include <return_code.H>
-#include <hwp_ffdc_classes.H>
-
-/// @cond
-#define FAPI_VA_NARGS_IMPL(_1, _2, _3, _4, _5, N, ...) N
-#define FAPI_VA_NARGS(...) FAPI_VA_NARGS_IMPL(__VA_ARGS__, 5, 4, 3, 2, 1)
-
-#define FAPI_TRY_IMPL2(count, ...) FAPI_TRY ## count (__VA_ARGS__)
-#define FAPI_TRY_IMPL(count, ...) FAPI_TRY_IMPL2(count, __VA_ARGS__)
-
-#define FAPI_TRY_NO_TRACE( __operation__ )                              \
-    if ((fapi2::current_err = (__operation__)) != fapi2::FAPI2_RC_SUCCESS) \
-    {                                                                   \
-        goto fapi_try_exit;                                             \
-    }
-
-// Why debug? Because this isn't a mechanism to gather FFDC
-// one should be using FAPI_ASSERT. However, it is nice to
-// have a conditional trace in the event of a failure in the
-// operation, so that's why this is here.
-#define FAPI_TRY_TRACE( __operation__, ... )                            \
-    if ((fapi2::current_err = (__operation__)) != fapi2::FAPI2_RC_SUCCESS) \
-    {                                                                   \
-        FAPI_DBG(__VA_ARGS__);                                          \
-        goto fapi_try_exit;                                             \
-    }
-
-#define FAPI_TRY1 FAPI_TRY_NO_TRACE
-#define FAPI_TRY2 FAPI_TRY_TRACE
-#define FAPI_TRY3 FAPI_TRY_TRACE
-#define FAPI_TRY4 FAPI_TRY_TRACE
-#define FAPI_TRY5 FAPI_TRY_TRACE
-/// @endcond
-
-///
-/// @brief Wrapper to check an operation for an error state
-/// and jump to the label cleam_up if there is an error.
-/// @param[in] __operation__ an operation which returns a fapi::ReturnCode
-/// @param[in] ... vararg format/agruments for trace output (optional)
-/// @note This implementation does not support PIB error masks or
-/// FSP operational states.
-/// @warning The trace information is only going to be seen during
-/// debug, it's not an error or informational trace. This is because
-/// traces might not be seen in the field. If you want information
-/// you will see on a field error, use FAPI_ASSERT.
-///
-#ifdef DOXYGEN
-#define FAPI_TRY(__operation__, ...) FAPI_TRY_IMPL
-#else
-#define FAPI_TRY(...) FAPI_TRY_IMPL(FAPI_VA_NARGS(__VA_ARGS__), __VA_ARGS__)
-#endif
-
-///
-/// @brief Assert a conditional is true.
-/// If it is not, the FFDC gathering function is called and the
-/// trace is output as a FAPI error trace.
-/// @param[in] __conditional__ the condition to assert
-/// @param[in] __ffdc__ the FFDC gathering function
-/// @param[in] ... varargs, as input to FAPI_ERR
-///
-#define FAPI_ASSERT( __conditional__, __ffdc__, ... )   \
-    if (! (__conditional__))                            \
-    {                                                   \
-        (__ffdc__).execute();                           \
-        FAPI_ERR(__VA_ARGS__);                          \
-        goto fapi_try_exit;                             \
-    }
+#include <plat_error_scope.H>
+#include <fapi2_error_scope.H>
 
 
 #endif
diff --git a/import/hwpf/fapi2/include/fapi2_error_scope.H b/import/hwpf/fapi2/include/fapi2_error_scope.H
new file mode 100644
index 00000000..d865a5d7
--- /dev/null
+++ b/import/hwpf/fapi2/include/fapi2_error_scope.H
@@ -0,0 +1,83 @@
+/* IBM_PROLOG_BEGIN_TAG                                                   */
+/* This is an automatically generated prolog.                             */
+/*                                                                        */
+/* $Source: import/hwpf/fapi2/include/fapi2_error_scope.H $               */
+/*                                                                        */
+/* OpenPOWER HCODE Project                                                */
+/*                                                                        */
+/* COPYRIGHT 2012,2017                                                    */
+/* [+] International Business Machines Corp.                              */
+/*                                                                        */
+/*                                                                        */
+/* Licensed under the Apache License, Version 2.0 (the "License");        */
+/* you may not use this file except in compliance with the License.       */
+/* You may obtain a copy of the License at                                */
+/*                                                                        */
+/*     http://www.apache.org/licenses/LICENSE-2.0                         */
+/*                                                                        */
+/* Unless required by applicable law or agreed to in writing, software    */
+/* distributed under the License is distributed on an "AS IS" BASIS,      */
+/* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or        */
+/* implied. See the License for the specific language governing           */
+/* permissions and limitations under the License.                         */
+/*                                                                        */
+/* IBM_PROLOG_END_TAG                                                     */
+/**
+ * @file fapi2_error_scope.H
+ * @brief common definitions which create a scope for automatic error handling
+ */
+
+#ifndef __FAPI2_COMMON_ERROR_SCOPE__
+#define __FAPI2_COMMON_ERROR_SCOPE__
+
+#include <stdint.h>
+#include <plat_error_scope.H>
+#include <return_code.H>
+#include <hwp_ffdc_classes.H>
+
+/// @cond
+#define FAPI_VA_NARGS_IMPL(_1, _2, _3, _4, _5, N, ...) N
+#define FAPI_VA_NARGS(...) FAPI_VA_NARGS_IMPL(__VA_ARGS__, 5, 4, 3, 2, 1)
+
+#define FAPI_TRY_IMPL2(count, ...) FAPI_TRY ## count (__VA_ARGS__)
+#define FAPI_TRY_IMPL(count, ...) FAPI_TRY_IMPL2(count, __VA_ARGS__)
+
+#define FAPI_TRY_NO_TRACE( __operation__ ) PLAT_FAPI_TRY_NO_TRACE( __operation__ )
+#define FAPI_TRY_TRACE( __operation__, ... ) PLAT_FAPI_TRY_TRACE( __operation__, __VA_ARGS__ )
+
+#define FAPI_TRY1 FAPI_TRY_NO_TRACE
+#define FAPI_TRY2 FAPI_TRY_TRACE
+#define FAPI_TRY3 FAPI_TRY_TRACE
+#define FAPI_TRY4 FAPI_TRY_TRACE
+#define FAPI_TRY5 FAPI_TRY_TRACE
+/// @endcond
+
+///
+/// @brief Wrapper to check an operation for an error state
+/// and jump to the label cleam_up if there is an error.
+/// @param[in] __operation__ an operation which returns a fapi::ReturnCode
+/// @param[in] ... vararg format/agruments for trace output (optional)
+/// @note This implementation does not support PIB error masks or
+/// FSP operational states.
+/// @warning The trace information is only going to be seen during
+/// debug, it's not an error or informational trace. This is because
+/// traces might not be seen in the field. If you want information
+/// you will see on a field error, use FAPI_ASSERT.
+///
+#ifdef DOXYGEN
+#define FAPI_TRY(__operation__, ...) FAPI_TRY_IMPL
+#else
+#define FAPI_TRY(...) FAPI_TRY_IMPL(FAPI_VA_NARGS(__VA_ARGS__), __VA_ARGS__)
+#endif
+
+///
+/// @brief Assert a conditional is true.
+/// If it is not, the FFDC gathering function is called and the
+/// trace is output as a FAPI error trace.
+/// @param[in] __conditional__ the condition to assert
+/// @param[in] __ffdc__ the FFDC gathering function
+/// @param[in] ... varargs, as input to FAPI_ERR
+///
+#define FAPI_ASSERT( __conditional__, __ffdc__, ... ) PLAT_FAPI_ASSERT( __conditional__, __ffdc__, __VA_ARGS__ )
+
+#endif
diff --git a/import/hwpf/fapi2/include/hw_access_def.H b/import/hwpf/fapi2/include/hw_access_def.H
new file mode 100644
index 00000000..84beafe3
--- /dev/null
+++ b/import/hwpf/fapi2/include/hw_access_def.H
@@ -0,0 +1,77 @@
+/* IBM_PROLOG_BEGIN_TAG                                                   */
+/* This is an automatically generated prolog.                             */
+/*                                                                        */
+/* $Source: import/hwpf/fapi2/include/hw_access_def.H $                   */
+/*                                                                        */
+/* OpenPOWER HCODE Project                                                */
+/*                                                                        */
+/* COPYRIGHT 2012,2017                                                    */
+/* [+] International Business Machines Corp.                              */
+/*                                                                        */
+/*                                                                        */
+/* Licensed under the Apache License, Version 2.0 (the "License");        */
+/* you may not use this file except in compliance with the License.       */
+/* You may obtain a copy of the License at                                */
+/*                                                                        */
+/*     http://www.apache.org/licenses/LICENSE-2.0                         */
+/*                                                                        */
+/* Unless required by applicable law or agreed to in writing, software    */
+/* distributed under the License is distributed on an "AS IS" BASIS,      */
+/* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or        */
+/* implied. See the License for the specific language governing           */
+/* permissions and limitations under the License.                         */
+/*                                                                        */
+/* IBM_PROLOG_END_TAG                                                     */
+///
+/// @file hw_access_def.H
+/// @brief Hardware access definitions
+///
+
+#ifndef FAPI2_HWACCESSDEF_H_
+#define FAPI2_HWACCESSDEF_H_
+
+#include <stdint.h>
+
+/// @cond
+typedef uint64_t spyId_t;
+typedef uint64_t scanRingId_t;
+/// @endcond
+
+namespace fapi2
+{
+    ///
+    /// @enum fapi2::ChipOpModifyMode
+    /// @brief Enumeration of modify modes used in HW access modify operations
+    ///
+    enum ChipOpModifyMode
+    {
+        CHIP_OP_MODIFY_MODE_OR = 1,  ///< Modify or mode
+        CHIP_OP_MODIFY_MODE_AND = 2, ///< Modify and mode
+        CHIP_OP_MODIFY_MODE_XOR = 3, ///< Modify xor mode
+    };
+
+    ///
+    /// @enum fapi2::RingMode
+    /// @brief Enumeration of Ring access operation modes
+    ///        This is a bitmap to allow the user to specify multiple modes.
+    ///
+    enum RingMode
+    {
+        RING_MODE_SET_PULSE       = 0x00000001, ///< Set pulse
+        RING_MODE_NO_HEADER_CHECK = 0x00000002, ///< Dont' check header
+        // FUTURE_MODE            = 0x00000004,
+        // FUTURE_MODE            = 0x00000008,
+    };
+
+    /// @enum OpModes operational Mode Error Functions
+    enum OpModes
+    {
+        // These are bit-masks in case they need to be or'd together
+        NORMAL           = 0x00,
+        IGNORE_HW_ERROR  = 0x01,
+        DO_NOT_DO_WAKEUP = 0x02,
+    };
+
+}
+
+#endif
diff --git a/import/hwpf/fapi2/include/target_states.H b/import/hwpf/fapi2/include/target_states.H
new file mode 100644
index 00000000..03849dca
--- /dev/null
+++ b/import/hwpf/fapi2/include/target_states.H
@@ -0,0 +1,45 @@
+/* IBM_PROLOG_BEGIN_TAG                                                   */
+/* This is an automatically generated prolog.                             */
+/*                                                                        */
+/* $Source: import/hwpf/fapi2/include/target_states.H $                   */
+/*                                                                        */
+/* OpenPOWER HCODE Project                                                */
+/*                                                                        */
+/* COPYRIGHT 2012,2017                                                    */
+/* [+] International Business Machines Corp.                              */
+/*                                                                        */
+/*                                                                        */
+/* Licensed under the Apache License, Version 2.0 (the "License");        */
+/* you may not use this file except in compliance with the License.       */
+/* You may obtain a copy of the License at                                */
+/*                                                                        */
+/*     http://www.apache.org/licenses/LICENSE-2.0                         */
+/*                                                                        */
+/* Unless required by applicable law or agreed to in writing, software    */
+/* distributed under the License is distributed on an "AS IS" BASIS,      */
+/* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or        */
+/* implied. See the License for the specific language governing           */
+/* permissions and limitations under the License.                         */
+/*                                                                        */
+/* IBM_PROLOG_END_TAG                                                     */
+/**
+ * @file target_states.H
+ * @brief common state for fapi2 targets
+ */
+
+#ifndef __FAPI2_TARGET_STATES__
+#define __FAPI2_TARGET_STATES__
+
+namespace fapi2
+{
+    ///
+    /// @brief Enumeration of target state values (bitmask values)
+    ///
+    enum TargetState
+    {
+        TARGET_STATE_PRESENT    = 0x00000001,
+        TARGET_STATE_FUNCTIONAL = 0x00000002,
+    };
+}
+
+#endif