FAPI2 Direct attribute access support

Change-Id: Icc127aa36d53cd18f9bf16414efcaa2cc35b8c14
Reviewed-on: http://gfw160.aus.stglabs.ibm.com:8080/gerrit/17400
Tested-by: Jenkins Server
Reviewed-by: Matt K. Light <mklight@us.ibm.com>
Reviewed-by: Brian Silver <bsilver@us.ibm.com>

7 files changed, 240 insertions, 91 deletions

diff --git a/src/import/hwpf/fapi2/include/fapi2.H b/src/import/hwpf/fapi2/include/fapi2.H
index 1efede789..12a428132 100644
--- a/src/import/hwpf/fapi2/include/fapi2.H
+++ b/src/import/hwpf/fapi2/include/fapi2.H
@@ -1,31 +1,7 @@
-/* IBM_PROLOG_BEGIN_TAG                                                   */
-/* This is an automatically generated prolog.                             */
-/*                                                                        */
-/* $Source: $                                                             */
-/*                                                                        */
-/* OpenPOWER HostBoot Project                                             */
-/*                                                                        */
-/* Contributors Listed Below - COPYRIGHT 2012,2014                        */
-/* [+] 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.H
- * @brief top level header for fapi2
- */
+///
+/// @file fapi2.H
+/// @brief top level header for fapi2
+///
 
 #ifndef __FAPI2_TOP_LEVEL__
 #define __FAPI2_TOP_LEVEL__
@@ -34,7 +10,6 @@
 #include <return_code.H>
 #include <buffer.H>
 #include <hw_access.H>
-
 #include <utils.H>
 #include <plat_trace.H>
 
@@ -45,16 +20,8 @@
 // Block of headers not currently in fapi2
 #ifdef FAPI2_MISSING_HEADERS
   #include <fapi2SystemConfig.H>
-  #include <fapi2HwpExecutor.H>
-  #include <fapi2AttributeService.H>
-  #include <fapi2MvpdAccess.H>
-  #include <fapi2MBvpdAccess.H>
-#endif
-
-// Block of auto generated headers not presently in fapi2
-#ifdef FAPI2_AUTOGEN_HEADERS
-  #include <fapi2AttributeIds.H>  // Generated file
-  #include <fapi2ChipEcFeature.H> // Generated file
+  #include <mvpdAccess.H>
+  #include <mbvpdAccess.H>
 #endif
 
 #endif // __FAPI2_TOP_LEVEL__
diff --git a/src/import/hwpf/fapi2/include/fapi2_attribute_service.H b/src/import/hwpf/fapi2/include/fapi2_attribute_service.H
new file mode 100644
index 000000000..b031f6e80
--- /dev/null
+++ b/src/import/hwpf/fapi2/include/fapi2_attribute_service.H
@@ -0,0 +1,127 @@
+///
+/// @file src/include/usr/hwpf/fapi2/fapi2_attribute_service.H
+///
+/// @brief Defines the FAPI_ATTR_GET and FAPI_ATTR_SET macros that a user
+/// calls to get/set attributes and a check function that the macros use to
+/// verify correct usage
+///
+
+#ifndef FAPI2ATTRIBUTESERVICE_H_
+#define FAPI2ATTRIBUTESERVICE_H_
+#include <stdint.h>
+#include <attribute_ids.H>
+#include <target.H>
+#include <target_types.H>
+#include <plat_attribute_service.H>
+
+/// @brief Macros called by user to get/set attributes for FAPI2 targets
+///
+/// Code must have a reference to a FAPI2 Target and an attribute ID (from
+/// XML file):
+///   fapi2::ReturnCode l_rc;
+///   fapi2::Target<target type>& l_target = ????;
+///          Ex: Target<TARGET_TYPE_PROC_CHIP>& l_target = ????;
+///
+/// To get a copy of an integer attribute and set the attribute
+///   uint64_t l_val = 0;
+///   l_rc = FAPI_ATTR_GET(<ID>, l_target, l_val);
+///   l_rc = FAPI_ATTR_SET(<ID>, l_target, l_val);
+///
+/// To get a copy of an integer array attribute and set the attribute
+///   uint32_t l_pVal[4] = {0};
+///   l_rc = FAPI_ATTR_GET(<ID>, l_target, l_pVal);
+///   l_rc = FAPI_ATTR_SET(<ID>, l_target, l_pVal);
+///
+/// A priveleged attribute is one that a HWP should not generally access,
+/// examples include ATTR_NAME and ATTR_EC, where usage can lead to a non
+/// data-driven design. A privileged attribute can be accessed with
+/// FAPI_ATTR_GET_PRIVILEGED and FAPI_ATTR_SET_PRIVILEGED
+///
+/// The non-PRIVILEGED macros first call a template function (compiler will
+/// optimize out) that will cause a compile failure if the attribute is
+/// privileged, they then call a PRIVILEGED macro to get/set the attribute
+///
+/// The PRIVILEGED macros call a template function (compiler will optimize out)
+/// that will cause a compile failure if the ID is not valid or VAL is not the
+/// correct type.
+//
+
+#define FAPI_ATTR_GET(ID, TARGET, VAL) \
+    (fapi2::failIfPrivileged<ID##_Privileged>(), \
+     fapi2::Target<ID##_TargetType>(TARGET), \
+     fapi2::checkIdType<ID##_Type>(ID, VAL), \
+     ID##_GETMACRO(ID, TARGET, VAL))
+
+#define FAPI_ATTR_SET(ID, TARGET, VAL) \
+    (fapi2::failIfPrivileged<ID##_Privileged>(), \
+     fapi2::Target<ID##_TargetType>(TARGET), \
+     fapi2::checkIdType<ID##_Type>(ID, VAL), \
+     ID##_SETMACRO(ID, TARGET, VAL))
+
+#define FAPI_ATTR_GET_PRIVILEGED(ID, TARGET, VAL) \
+    (fapi2::checkIdType<ID##_Type>(ID, VAL), \
+     ID##_GETMACRO(ID, TARGET, VAL))
+
+#define FAPI_ATTR_SET_PRIVILEGED(ID, TARGET, VAL) \
+    (fapi2::checkIdType<ID##_Type>(ID, VAL), \
+     ID##_SETMACRO(ID, TARGET, VAL))
+
+namespace fapi2
+{
+
+///
+/// @brief Get an InitFile attribute for FAPI2
+///
+/// This function gets a copy of an attribute. In the case of an array attribute,
+/// The value in the specified index is retrieved. This should be used by the
+/// InitFile HWP only, that HWP processes a binary InitFile and therefore needs
+/// to read a variable ID of a variable data type. Standard HWPs should use the
+/// FAPI2_ATTR_GET macro which automatically checks the type for correct usage.
+///
+/// If there are ever attributes with more than 4 dimensions then this function
+/// will need to be updated.
+///
+/// @Tparam K template parameter, passed in target.
+/// @param[in]  i_id          AttributeID
+/// @param[in]  i_target      Reference to fapi2::Target (can be NULL for system)
+/// @param[out] o_val         Reference to uint64_t where attribute value is set
+/// @param[in]  i_arrayIndex1 If array attribute then index1
+/// @param[in]  i_arrayIndex2 If at least 2D array attribute then index2
+/// @param[in]  i_arrayIndex3 If at least 3D array attribute then index3
+/// @param[in]  i_arrayIndex4 If at least 4D array attribute then index4
+///
+/// @return ReturnCode. Zero if success
+///
+template< TargetType K >
+ReturnCode getInitFileAttr(const AttributeId i_id,
+                           const Target<K>& i_target,
+                           uint64_t & o_val,
+                           const uint32_t i_arrayIndex1 = 0,
+                           const uint32_t i_arrayIndex2 = 0,
+                           const uint32_t i_arrayIndex3 = 0,
+                           const uint32_t i_arrayIndex4 = 0);
+
+/**
+ * @brief Check the ID and TYPE
+ *
+ * This is called by FAPI code to check at compile time that a FAPI attribute
+ * access is using the correct data type and a valid AttributeId
+ */
+template<typename T> inline void checkIdType(AttributeId, T &) {}
+
+/**
+ * @brief Fail if attribute privileged
+ *
+ * This is called by FAPI code to check at compile time that a standard FAPI
+ * attribute access (FAPI_ATTR_GET) is not accessing a privileged attribute
+ */
+class ErrorAccessingPrivilegedAttribute;
+template<const bool PRIVILEGED> void failIfPrivileged()
+{
+   ErrorAccessingPrivilegedAttribute();
+}
+template <> inline void failIfPrivileged<false>() {}
+
+}
+
+#endif // FAPI2ATTRIBUTESERVICE_H_
diff --git a/src/import/hwpf/fapi2/include/fapi2_chip_ec_feature.H b/src/import/hwpf/fapi2/include/fapi2_chip_ec_feature.H
new file mode 100644
index 000000000..2398b5dad
--- /dev/null
+++ b/src/import/hwpf/fapi2/include/fapi2_chip_ec_feature.H
@@ -0,0 +1,39 @@
+///
+/// @file src/include/usr/hwpf/fapi2/fapi2_chip_ec_feature.H
+///
+/// @brief Defines the queryChipEcFeature function that allows HWPs to
+///        query if a particular chip has a feature determined by its EC level.
+///        Chip EC features are specified in attribute XML files and the
+///        queryChipEcFeature function implementation is auto-generated.
+///        HWPs should not call this function directly, but should access the
+///        corresponding HWPF attribute using FAPI_ATTR_GET
+///
+
+#ifndef FAPI2CHIPECFEATURE_H_
+#define FAPI2CHIPECFEATURE_H_
+
+#include <stdint.h>
+#include <target.H>
+#include <return_code.H>
+
+namespace fapi2
+{
+
+///
+/// @brief Queries if a Chip has a particular feature
+///
+/// This should only be called by FAPI during the processing of a FAPI_ATTR_GET
+/// for a Chip EC Feature attribute
+///
+/// @param[in]  i_id         Attribute ID of the Chip EC Feature
+/// @param[in]  i_target     Reference to chip target
+/// @param[out] o_hasFeature Set to 1 if chip has feature else 0
+/// @return ReturnCode. Zero on success, else platform specified error
+///
+template< TargetType K >
+ReturnCode queryChipEcFeature(AttributeId i_id,
+                              const Target<K>& i_target,
+                              uint8_t & o_hasFeature);
+}
+
+#endif
diff --git a/src/import/hwpf/fapi2/include/fapi2_hwp_executor.H b/src/import/hwpf/fapi2/include/fapi2_hwp_executor.H
new file mode 100644
index 000000000..e92d14275
--- /dev/null
+++ b/src/import/hwpf/fapi2/include/fapi2_hwp_executor.H
@@ -0,0 +1,24 @@
+///
+/// @file fapi2_hwp_executor.H
+///
+/// @brief Defines the FAPI2 HWP Executor Macro.
+///
+/// The FAPI2 HWP Executor macro is called when a PLAT invoker function or a HWP
+/// wants to execute a HWP.
+///
+
+#ifndef FAPI2HWPEXECUTOR_H_
+#define FAPI2HWPEXECUTOR_H_
+
+#include <hwp_executor.H>
+
+/**
+ * @brief HWP Executor macro
+ *
+ * This macro calls a PLAT macro which will do any platform specific work to
+ * execute the HWP (e.g. dlopening a shared library)
+ */
+#define FAPI_EXEC_HWP(RC, FUNC, _args_...) \
+    FAPI_PLAT_EXEC_HWP(RC, FUNC, ##_args_)
+
+#endif // FAPI2HWPEXECUTOR_H_
diff --git a/src/import/hwpf/fapi2/include/fapi2_target.H b/src/import/hwpf/fapi2/include/fapi2_target.H
index ce0e950cc..b479fca77 100644
--- a/src/import/hwpf/fapi2/include/fapi2_target.H
+++ b/src/import/hwpf/fapi2/include/fapi2_target.H
@@ -1,31 +1,7 @@
-/* IBM_PROLOG_BEGIN_TAG                                                   */
-/* This is an automatically generated prolog.                             */
-/*                                                                        */
-/* $Source: $                                                             */
-/*                                                                        */
-/* OpenPOWER HostBoot Project                                             */
-/*                                                                        */
-/* Contributors Listed Below - COPYRIGHT 2012,2014                        */
-/* [+] 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_target.H
- * @brief common definitions for fapi2 targets
- */
+///
+/// @file fapi2_target.H
+/// @brief Common definitions for fapi2 targets
+///
 
 #ifndef __FAPI2_COMMON_TARGET__
 #define __FAPI2_COMMON_TARGET__
@@ -173,6 +149,43 @@ namespace fapi2
         inline Target<T> getParent(void) const;
 
         ///
+        /// @brief Is this target a chip?
+        /// @return Return true if this target is a chip, false otherwise
+        ///
+        inline constexpr bool isChip(void) const
+        {
+           return ( (K == TARGET_TYPE_PROC_CHIP) ||
+                    (K == TARGET_TYPE_MEMBUF_CHIP) );
+        }
+
+        ///
+        /// @brief Is this target a chiplet?
+        /// @return Return true if this target is a chiplet, false otherwise
+        ///
+        inline constexpr bool isChiplet(void) const
+        {
+           return ( (K == TARGET_TYPE_EX) ||
+                    (K == TARGET_TYPE_MBA) ||
+                    (K == TARGET_TYPE_MCS) ||
+                    (K == TARGET_TYPE_XBUS) ||
+                    (K == TARGET_TYPE_ABUS) ||
+                    (K == TARGET_TYPE_L4) ||
+                    (K == TARGET_TYPE_CORE) ||
+                    (K == TARGET_TYPE_EQ) ||
+                    (K == TARGET_TYPE_MCA) ||
+                    (K == TARGET_TYPE_MCBIST) ||
+                    (K == TARGET_TYPE_MI) ||
+                    (K == TARGET_TYPE_DMI) ||
+                    (K == TARGET_TYPE_OBUS) ||
+                    (K == TARGET_TYPE_NV) ||
+                    (K == TARGET_TYPE_SBE) ||
+                    (K == TARGET_TYPE_PPE) ||
+                    (K == TARGET_TYPE_PERV) ||
+                    (K == TARGET_TYPE_PEC) ||
+                    (K == TARGET_TYPE_PHB) );
+        }
+
+        ///
         /// @brief Get this target's children
         /// @tparam T The type of the parent
         /// @param[in] i_state The desired TargetState of the children
diff --git a/src/import/hwpf/fapi2/include/target_types.H b/src/import/hwpf/fapi2/include/target_types.H
index bdbb3d50b..561f45700 100644
--- a/src/import/hwpf/fapi2/include/target_types.H
+++ b/src/import/hwpf/fapi2/include/target_types.H
@@ -1,27 +1,3 @@
-/* IBM_PROLOG_BEGIN_TAG                                                   */
-/* This is an automatically generated prolog.                             */
-/*                                                                        */
-/* $Source: $                                                             */
-/*                                                                        */
-/* OpenPOWER HostBoot Project                                             */
-/*                                                                        */
-/* Contributors Listed Below - COPYRIGHT 2012,2014                        */
-/* [+] 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_types.H
  * @brief definitions for fapi2 target types
@@ -40,6 +16,7 @@ namespace fapi2
     /// or tables. TYPE_ALL is used to pass targets to methods which
     /// can act generally on any type of target
     ///
+
     /// Target Kind
     enum TargetType
     {
@@ -99,6 +76,7 @@ namespace fapi2
         static const uint8_t count = 0;
     };
     /// @endcond
+
 }
 
 #endif
diff --git a/src/import/hwpf/fapi2/include/utils.H b/src/import/hwpf/fapi2/include/utils.H
index 85f334b9a..0f10b32ee 100644
--- a/src/import/hwpf/fapi2/include/utils.H
+++ b/src/import/hwpf/fapi2/include/utils.H
@@ -82,6 +82,7 @@ namespace fapi2
     /// @return ReturnCode. Zero on success, else platform specified error.
     ///
     ReturnCode delay(uint64_t i_nanoSeconds, uint64_t i_simCycles);
+
 };
 
 #endif // FAPI2_UTILS_H_