FAPI2: Multicast API 1/2: Platform-breaking changes

The Target gains a new template parameter, M, that specifies
the multicast type. This is propagated through all affected
header files.

A new target type is introduced, TARGET_TYPE_MULTICAST, and
platform specific assertions put in place to prevent users
from creating such targets before the platform supports it.

Target also grows a new inline function for updating MC targets.
Platforms not supporting MC can provide a dummy implementation.

The example platform code in fapi2/include/plat/plat_target.H
is updated with minimal example code for platform implementers.

Change-Id: Ia0990f26890dc5c719caca608cd134a4964a3acf
Reviewed-on: http://rchgit01.rchland.ibm.com/gerrit1/69456
Tested-by: Jenkins Server <pfd-jenkins+hostboot@us.ibm.com>
Tested-by: HWSV CI <hwsv-ci+hostboot@us.ibm.com>
Tested-by: FSP CI Jenkins <fsp-CI-jenkins+hostboot@us.ibm.com>
Reviewed-by: Matt K. Light <mklight@us.ibm.com>
Tested-by: PPE CI <ppe-ci+hostboot@us.ibm.com>
Tested-by: Hostboot CI <hostboot-ci+hostboot@us.ibm.com>
Reviewed-by: Daniel M. Crowell <dcrowell@us.ibm.com>
Reviewed-by: RAJA DAS <rajadas2@in.ibm.com>
Reviewed-by: Jennifer A. Stofer <stofer@us.ibm.com>
Reviewed-on: http://rchgit01.rchland.ibm.com/gerrit1/70866
Reviewed-by: Sachin Gupta <sgupta2m@in.ibm.com>

1 files changed, 39 insertions, 39 deletions

diff --git a/src/import/hwpf/fapi2/include/fapi2_target.H b/src/import/hwpf/fapi2/include/fapi2_target.H
index 6f2c6793..4d9f6963 100644
--- a/src/import/hwpf/fapi2/include/fapi2_target.H
+++ b/src/import/hwpf/fapi2/include/fapi2_target.H
@@ -5,7 +5,7 @@
 /*                                                                        */
 /* OpenPOWER sbe Project                                                  */
 /*                                                                        */
-/* Contributors Listed Below - COPYRIGHT 2015,2016                        */
+/* Contributors Listed Below - COPYRIGHT 2015,2019                        */
 /* [+] International Business Machines Corp.                              */
 /*                                                                        */
 /*                                                                        */
@@ -37,6 +37,7 @@
 #include <vector>
 #include <target_types.H>
 #include <target_states.H>
+#include <multicast_defs.H>
 #include <plat_target.H>
 #include <return_code_defs.H>
 
@@ -44,8 +45,18 @@ namespace fapi2
 {
 
 ///
+/// @brief Apply any platform specific static assertions to target construction
+/// @tparam K the type of target to be constructed
+/// @tparam M the multicast type of the target to be constructed
+/// @tparam V the value type of the target to be constructed
+///
+template<TargetType K, MulticastType M, typename V>
+static constexpr void plat_apply_target_limits(void);
+
+///
 /// @brief Class representing a FAPI2 Target
 /// @tparam K the type (Kind) of target
+/// @tparam M the type of multicast operation if it's a multicast target
 /// @tparam V the type of the target's Value
 /// @remark TargetLite targets are uint64_t, Targets
 /// are uintptr_t (void*).
@@ -102,7 +113,7 @@ namespace fapi2
 /// fapi2::Target<fapi2::TARGET_TYPE_ABUS_ENDPOINT> E;
 /// takesProcOrMembuf( E );
 /// @endcode
-template<TargetType K, typename V = plat_target_handle_t>
+template<TargetType K, MulticastType M = MULTICAST_OR, typename V = plat_target_handle_t>
 class Target
 {
     public:
@@ -112,7 +123,9 @@ class Target
         ///        that takes in a value as a param
         ///
         Target(): Target(V())
-        {};
+        {
+            plat_apply_target_limits<K, M, V>();
+        };
 
         ///
         /// @brief Create a Target, with a value
@@ -124,7 +137,9 @@ class Target
         ///
         Target(const V& Value):
             iv_handle(Value)
-        {};
+        {
+            plat_apply_target_limits<K, M, V>();
+        };
 
 
         ///
@@ -203,7 +218,7 @@ class Target
         /// @return Target<T> a target representing the parent
         ///
         template< TargetType T >
-        inline Target<T, V> getParent(void) const;
+        inline Target<T, M, V> getParent(void) const;
 
         ///
         /// @brief Is this target a chip?
@@ -277,7 +292,7 @@ class Target
         /// in order. That is, core 0 is std::vector[0].
         ///
         template< TargetType T>
-        inline std::vector<Target<T, V> >
+        inline std::vector<Target<T, M, V> >
         getChildren(const TargetState i_state = TARGET_STATE_FUNCTIONAL) const;
 
         ///
@@ -289,7 +304,7 @@ class Target
         /// children
         ///
         template< TargetType T>
-        inline std::vector<Target<T, V> >
+        inline std::vector<Target<T, M, V> >
         getChildren(const TargetFilter i_filter,
                     const TargetState i_state = TARGET_STATE_FUNCTIONAL) const;
 
@@ -305,7 +320,7 @@ class Target
 
         template<TargetType T>
         inline fapi2::ReturnCodes
-        getOtherEnd(Target<T, V>& o_target, const TargetState i_state = TARGET_STATE_FUNCTIONAL) const;
+        getOtherEnd(Target<T, M, V>& o_target, const TargetState i_state = TARGET_STATE_FUNCTIONAL) const;
 
         ///
         /// @brief Is the target functional?
@@ -329,10 +344,12 @@ class Target
         /// @brief Copy from a Target<O> to a Target<K>
         /// @tparam O the target type of the other
         ///
-        template<TargetType O, typename VO>
-        inline Target( const Target<O, VO>& Other ):
-            Target<K, V>(Other.get())
+        template<TargetType O, MulticastType MO, typename VO>
+        inline Target( const Target<O, MO, VO>& Other ):
+            Target<K, M, V>(Other.get())
         {
+            plat_apply_target_limits<K, M, V>();
+
             // In case of recursion depth failure, use -ftemplate-depth=
             static_assert( (K & O) != 0,
                            "unable to cast Target, no shared types");
@@ -347,6 +364,8 @@ class Target
         static const TargetType iv_type = K;
         V iv_handle;
 
+        /// @brief if iv_handle is a multicast target, update its multicast type to M
+        inline void mcUpdateHandle();
 };
 
 // EX threads map to CORE threads:
@@ -475,8 +494,8 @@ inline uint8_t thread_bitset_f2n(const uint8_t i_ordinal, const uint8_t i_thread
 /// @post The contents of the buffer is replaced with the string
 /// representation of the target
 ///
-template< TargetType T, typename V >
-inline void toString(const Target<T, V>& i_target, char* i_buffer, size_t i_bsize);
+template< TargetType T, MulticastType M, typename V >
+inline void toString(const Target<T, M, V>& i_target, char* i_buffer, size_t i_bsize);
 
 ///
 /// @brief Return the string interpretation of this target
@@ -489,8 +508,8 @@ inline void toString(const Target<T, V>& i_target, char* i_buffer, size_t i_bsiz
 /// @post The contents of the buffer is replaced with the string
 /// representation of the target
 ///
-template< TargetType T, typename V >
-inline void toString(const Target<T, V>* i_target, char* i_buffer, size_t i_bsize);
+template< TargetType T, MulticastType M, typename V >
+inline void toString(const Target<T, M, V>* i_target, char* i_buffer, size_t i_bsize);
 
 ///
 /// @brief Get an enumerated target of a specific type
@@ -499,28 +518,8 @@ inline void toString(const Target<T, V>* i_target, char* i_buffer, size_t i_bsiz
 /// the desired target
 /// @return Target<T> the target requested
 ///
-template<TargetType T, typename V = plat_target_handle_t>
-inline Target<T, V> getTarget(uint64_t Ordinal);
-
-// Why has the been removed? For starters, the API name
-// is probably wrong as it's already been confused with
-// Target::getChildren(). And if I'm going to change it
-// I really want to see if we need it. I'm still not
-// clear on whether we're alloing this traversal or not.
-#if 0
-///
-/// @brief Get the base target's children
-/// @tparam T The type of the target
-/// @return std::vector<Target<T,V>> a vector of present/functional
-/// children
-///
-template<TargetType T, typename V>
-inline std::vector<Target<T, V>> getChildren()
-{
-    // For testing
-    return {Target<T, V>(), Target<T, V>()};
-}
-#endif
+template<TargetType T, MulticastType M = MULTICAST_OR, typename V = plat_target_handle_t>
+inline Target<T, M, V> getTarget(uint64_t Ordinal);
 
 ///
 /// @brief Return the string interpretation of this target
@@ -532,8 +531,8 @@ inline std::vector<Target<T, V>> getChildren()
 /// @post The contents of the buffer is replaced with the string
 /// representation of the target
 ///
-template<TargetType T, typename V, typename B>
-inline void toString(const Target<T, V>& i_target, B& i_buffer);
+template<TargetType T, MulticastType M, typename V, typename B>
+inline void toString(const Target<T, M, V>& i_target, B& i_buffer);
 
 ///
 /// @brief Check if the target is of a type, or in a type subset.
@@ -546,6 +545,7 @@ inline constexpr bool is_same(void)
 {
     return (K & T) != 0;
 }
+
 }
 
 #endif