FAPI2: Multicast API 2/2: Introduce the actual multicast functions

Chip targets gain a getMulticast() method to generate MC sub-targets.
The meaning of getParent()/getChildren() is updated to reflect MC
specialties.
Add an API call to update the multicast group mapping table per chip.

For details, please see hwpf/fapi2/docs/topics/multicast_doc.C

Change-Id: I4cea561fd14324b1accedf4ffaae9943159caf71
Reviewed-on: http://rchgit01.rchland.ibm.com/gerrit1/69457
Tested-by: Jenkins Server <pfd-jenkins+hostboot@us.ibm.com>
Tested-by: FSP CI Jenkins <fsp-CI-jenkins+hostboot@us.ibm.com>
Tested-by: HWSV CI <hwsv-ci+hostboot@us.ibm.com>
Reviewed-by: Daniel M. Crowell <dcrowell@us.ibm.com>
Reviewed-by: Matt K. Light <mklight@us.ibm.com>
Tested-by: Hostboot CI <hostboot-ci+hostboot@us.ibm.com>
Tested-by: PPE CI <ppe-ci+hostboot@us.ibm.com>
Reviewed-by: Jennifer A. Stofer <stofer@us.ibm.com>
Reviewed-on: http://rchgit01.rchland.ibm.com/gerrit1/70946

src/import/hwpf/fapi2/docs/topics/multicast_doc.C

@@ -0,0 +1,148 @@
+/* IBM_PROLOG_BEGIN_TAG                                                   */
+/* This is an automatically generated prolog.                             */
+/*                                                                        */
+/* $Source: src/import/hwpf/fapi2/docs/topics/multicast_doc.C $           */
+/*                                                                        */
+/* OpenPOWER HostBoot Project                                             */
+/*                                                                        */
+/* Contributors Listed Below - COPYRIGHT 2018,2019                        */
+/* [+] 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                                                     */
+#include <fapi2.H>
+#include <fapi2_target.H>
+
+using namespace fapi2;
+
+void multicast_doc(uint8_t i_core_select)
+{
+    Target<TARGET_TYPE_PROC_CHIP> l_chip_target;
+    Target<TARGET_TYPE_CORE> l_single_core;
+
+    /*
+    Multicast Targets: Target type
+    ==============================
+
+      # Additional TARGET_TYPE_MULTICAST
+      # MC targets are composite targets, e.g. */
+
+    Target < TARGET_TYPE_CORE | TARGET_TYPE_MULTICAST > l_mc_cores;
+
+    /*  # IMPORTANT: Composite type means "this _could_ be multicast" - a specific target may still be unicast!
+        # SCOM ops work on UC and MC targets alike
+        # Attribute ops work on UC only
+        # FAPI2 type-casting rules work in our favor here:
+          # Procedures that accept XYZ | MULTICAST targets will implicitly accept XYZ targets
+          # XYZ | MULTICAST can't be casted down to XYZ, so we can't accidentally getAttribute() on it */
+
+    l_mc_cores = l_single_core;   // works - these are compatible
+    l_single_core = l_mc_cores;   // compile error!
+
+    /*
+    Multicast Targets: Multicast type
+    =================================
+
+      # Targets gain a MulticastType template parameter, defaults to MULTICAST_OR
+        # Don't care for unicast targets
+        # No change to existing unicast procedures needed
+          # Platform code must be adapted
+          # Example SBE implementation in progress
+        # No extra binary code generated for unicast targets
+      # To change the MC type, use another target and simply assign: */
+
+    Target < TARGET_TYPE_CORE | TARGET_TYPE_MULTICAST, MULTICAST_AND > l_mc_cores_and = l_mc_cores;
+
+    /*  # Type casting / construction takes care of the icky bits
+      # Procedures can specify which MC type they require in their header
+        # Implicit type cast if necessary
+        # Suggest not specifying unless OR type not needed */
+
+    extern ReturnCode p9_hcd_core_chiplet_reset(
+        Target < TARGET_TYPE_CORE | TARGET_TYPE_MULTICAST, MULTICAST_AND > i_targets);
+    p9_hcd_core_chiplet_reset(l_mc_cores);
+
+    /*
+    Getting a multicast target
+    ==========================
+
+      # Option A: Your procedure takes an MC target
+        # Platform responsible for generating the correct target
+      # Option B: Your procedure takes a chip target
+        # Derive MC targets yourself */
+
+    auto l_all_mcs = l_chip_target.getMulticast<TARGET_TYPE_PERV>(MCGROUP_GOOD_MEMCTL);
+
+    /*# Abstract MC groups
+        # FAPI code never handles numeric group IDs but abstract role descriptors, such as
+          "all good except TP", "all good PCI", "all good MCs", "all existing OBUS"
+        # More such roles than group IDs in hardware
+          # Different groups available during different system phases
+        # Platform maps to hardware group IDs, fails if abstract group not mapped
+    */
+
+    /*
+    Transforming multicast targets
+    ============================== */
+
+    auto l_mc_eqs = l_mc_cores.getParent < TARGET_TYPE_EQ | TARGET_TYPE_MULTICAST > ();
+
+    /*  # Will map upwards to a multicast target of parent type
+          # Only for CORE -> EQ right now
+          # Also we can go back to the chip from anywhere like we're used to */
+
+    std::vector<Target<TARGET_TYPE_EQ> > l_uc_eqs = l_mc_eqs.getChildren<TARGET_TYPE_EQ>();
+
+    /*  # Will expand a multicast target into constituent unicast targets
+        # Will return a vector of length one if the target is unicast
+    */
+
+    /*
+    Special case: Multi-region targets
+    ==================================
+
+      # CORE | MULTICAST targets have an extra "core select" value that's got 1 or more bits set. */
+
+    l_mc_cores = l_chip_target.getMulticast(MCGROUP_GOOD_EQ, MCCORE_ALL);
+
+    /*# MulticastCoreSelect is an enum, but you're free to do bitops on it:  */
+
+    uint8_t l_my_core_select = i_core_select & 0xA;
+    l_my_core_select = i_core_select & (MCCORE_0 | MCCORE_2); // does the same but avoids magic values
+    l_mc_cores = l_chip_target.getMulticast(MCGROUP_GOOD_EQ,
+                                            static_cast<MulticastCoreSelect>(l_my_core_select));
+
+    /*# Falling back to unicast will iterate over EQs in the MC group as well as selected cores:  */
+
+    for (auto l_core : l_mc_cores.getChildren<TARGET_TYPE_CORE>())
+    {
+        // do something to the core
+    }
+
+    /*
+    Error Handling
+    ==============
+
+      # Handling PIB/PCB errors (PIB timeout, parity error, ...) is platform responsibility
+        # Gather FFDC from PCB master: Which slaves responded and how?
+          # HW will have individual FFDC regs for each PIB master
+        # Return to caller
+      # Handling unexpected data (ABIST_DONE not on etc.) is procedure responsibility
+        # Fall back to unicast and iterate over constituent targets
+        # FAPI to provide helper functions to minimize boilerplate
+          # Anything more than getChildren needed?
+    */
+
+}

src/import/hwpf/fapi2/include/error_info.H

@@ -5,7 +5,7 @@
 /*                                                                        */
 /* OpenPOWER HostBoot Project                                             */
 /*                                                                        */
-/* Contributors Listed Below - COPYRIGHT 2015,2016                        */
+/* Contributors Listed Below - COPYRIGHT 2015,2019                        */
 /* [+] International Business Machines Corp.                              */
 /*                                                                        */
 /*                                                                        */
@@ -53,14 +53,16 @@ inline uint64_t convertType( T& i_value )
 };
 
 // convert platform target handle to a uint64_t
-template<fapi2::TargetType T>
-inline uint64_t convertType( const fapi2::Target<T>& i_value)
+template<fapi2::TargetType T, fapi2::MulticastType M>
+inline uint64_t convertType( const fapi2::Target<T, M>& i_value)
 {
     // send the target type and instance as ffdc they will be used
     // to instantiate a target before logging the ffdc data
-    return static_cast<uint64_t>((static_cast<uint64_t>(
-                                      (i_value.get().getFapiTargetType())) << 32) |
-                                 i_value.get().getTargetInstance());
+    return static_cast<uint64_t>(
+               (static_cast<uint64_t>(
+                    (i_value.get().getFapiTargetType() |
+                     (i_value.get().fields.is_multicast << 31))
+                ) << 32) | i_value.get().getTargetInstance());
 };
 #endif
 

src/import/hwpf/fapi2/include/fapi2_hw_access.H

@@ -75,6 +75,26 @@ inline void setOpMode(const OpModes i_mode);
 /// @return the operational mode
 inline OpModes getOpMode(void);
 
+//--------------------------------------------------------------------------
+// Multicast mapping functions
+//--------------------------------------------------------------------------
+
+/// @brief Set up or replace the multicast group mapping for a given chip
+/// @param[in] i_chip     The chip whose multicast map is to be replaced
+/// @param[in] i_mappings A list of multicast group mappings
+/// @return FAPI2_RC_SUCCESS if the map was updated, otherwise error code.
+///
+/// This replaces the given chip's map of abstract multicast groups to chip
+/// specific hardware values with a new map. Any abstract group not explicitly
+/// mapped via i_mappings will be unmapped after this call returns success,
+/// and attempting to create multicast targets targeting unmapped groups will
+/// result in error.
+/// i_mappings may contain an arbitrary amount of abstract/HW pairs, but the
+/// function may return an error if too many mappings are specified.
+template< MulticastType M, typename V >
+inline ReturnCode setMulticastGroupMap(const Target<TARGET_TYPE_PROC_CHIP, M, V>& i_chip,
+                                       const std::vector< MulticastGroupMapping >& i_mappings);
+
 //--------------------------------------------------------------------------
 // HW Communication Functions
 //--------------------------------------------------------------------------

src/import/hwpf/fapi2/include/fapi2_target.H

@@ -139,8 +139,16 @@ class Target
             iv_handle(Value)
         {
             plat_apply_target_limits<K, M, V>();
-        };
 
+            /* Iff this is a potential mcast target, update the handle.
+             * We can't know the mcast op of the V handed in, so we have
+             * to incur the cost of the update even if unnecessary.
+             */
+            if (K & TARGET_TYPE_MULTICAST)
+            {
+                mcUpdateHandle();
+            }
+        };
 
         ///
         /// @brief Assignment Operator.
@@ -308,6 +316,36 @@ class Target
         getChildren(const TargetFilter i_filter,
                     const TargetState i_state = TARGET_STATE_FUNCTIONAL) const;
 
+        ///
+        /// @brief Get a multicast target for a given chip
+        /// @tparam T The type of target to return; TARGET_TYPE_MULTICAST is added automatically
+        /// @tparam O The type of multicast read operation for the target; defaults to OR
+        /// @param[in] i_group The abstract multicast group the target should point to
+        /// @return The multicast target
+        ///
+        /// This method is only applicable to chip-level targets.
+        /// If the requested multicast group cannot be mapped to an available HW multicast
+        /// group, a platform specific error will be thrown.
+        ///
+        template< TargetType T, MulticastType O = MULTICAST_OR >
+        inline Target < T | TARGET_TYPE_MULTICAST, O, V >
+        getMulticast(const MulticastGroup i_group) const;
+
+        ///
+        /// @brief Get a multicast core target for a given chip
+        /// @tparam O The type of multicast read operation for the target; defaults to OR
+        /// @param[in] i_group The abstract multicast group (selecting EQs) the target should point to
+        /// @param[in] i_cores Which cores inside the selected EQ should be targeted
+        /// @return The multicast target
+        ///
+        /// This method is only applicable to chip-level targets.
+        /// If the requested multicast group cannot be mapped to an available HW multicast
+        /// group, a platform specific error will be thrown.
+        ///
+        template< MulticastType O = MULTICAST_OR >
+        inline Target < TARGET_TYPE_CORE | TARGET_TYPE_MULTICAST, O, V >
+        getMulticast(const MulticastGroup i_group, const MulticastCoreSelect i_cores) const;
+
         ///
         /// @brief Get the target at the other end of a bus
         /// @tparam T The type of the target on the other end
@@ -326,7 +364,6 @@ class Target
         /// @brief Is the target functional?
         /// @return true if target is functional, false if non-functional
         ///
-
         inline bool
         isFunctional(void) const;
 
@@ -335,18 +372,20 @@ class Target
         /// @return The chiplet number for the Target. 0 is returned if the
         /// Target does not have a chiplet number (for ex, the PROC_CHIP Target)
         /// @note For logical targets such as the EX, the chiplet number of
-        /// their immediate parent chiplet is returned
+        /// their immediate parent chiplet is returned. For multicast targets
+        /// getChipletNumber() is not supported.
         ///
         inline uint8_t
         getChipletNumber(void) const;
 
         ///
-        /// @brief Copy from a Target<O> to a Target<K>
+        /// @brief Copy from a Target<O, MO> to a Target<K, M>
         /// @tparam O the target type of the other
+        /// @tparam MO the multicast type of the other
         ///
-        template<TargetType O, MulticastType MO, typename VO>
-        inline Target( const Target<O, MO, VO>& Other ):
-            Target<K, M, V>(Other.get())
+        template<TargetType O, MulticastType MO>
+        inline Target( const Target<O, MO, V>& Other ):
+            iv_handle(Other.get())
         {
             plat_apply_target_limits<K, M, V>();
 
@@ -356,6 +395,12 @@ class Target
 
             static_assert( bitCount<K>::count >= bitCount<O>::count,
                            "unable to cast to specialized Target");
+
+            // Only need to update the handle if we're coming from a target that's already MULTICAST
+            if ((O & TARGET_TYPE_MULTICAST) && (MO != M))
+            {
+                mcUpdateHandle();
+            }
         }
 
     private:

src/import/hwpf/fapi2/include/multicast_defs.H

@@ -36,7 +36,50 @@ enum MulticastType
     MULTICAST_COMPARE = 4,
 };
 
-typedef uint32_t MulticastGroup;
+/**
+ * @brief Abstract multicast group definitions
+ *
+ * These are abstract multicast groups that a procedure may want to talk to.
+ * They are being mapped to hardware MC group IDs by the platform layer.
+ * Due to the limited amount of hardware MC groups, the availability of
+ * certain abstract groups will be dependent on system state, for example
+ * the currently executing istep.
+ *
+ * The actual multicast group enumerations will be defined in a project specific header.
+ */
+enum MulticastGroup : uint32_t;
+
+    /**
+     * @brief Single FAPI->HW multicast group mapping
+     *
+     * This is used to provide a mapping of an abstract MulticastGroup to a hardware dependent
+     * value. The calling HWP and platform layer must have the same understanding of the HW
+     * value (e.g. PCB multicast group ID), FAPI2 is only the conduit and imposes no restriction
+     * on hwValue.
+     */
+    struct MulticastGroupMapping
+{
+    MulticastGroup abstractGroup;
+    uint32_t       hwValue;
+};
+
+/**
+ * @brief Bit mask for selecting cores out of an EQ.
+ */
+enum MulticastCoreSelect
+{
+    MCCORE_0   = 0x8,
+    MCCORE_1   = 0x4,
+    MCCORE_2   = 0x2,
+    MCCORE_3   = 0x1,
+    MCCORE_ALL = 0xF,
+};
+
+inline MulticastCoreSelect operator|(const MulticastCoreSelect a, const MulticastCoreSelect b)
+{
+    return static_cast<MulticastCoreSelect>(a | b);
+}
+
 }
 
 #endif

src/import/hwpf/fapi2/include/target_types.H

@@ -123,6 +123,13 @@ enum TargetType : uint64_t
                                 TARGET_TYPE_IOHS          |
                                 TARGET_TYPE_FC,
 
+    TARGET_TYPE_MULTICASTABLE = TARGET_TYPE_CORE   |
+                                TARGET_TYPE_EQ     |
+                                TARGET_TYPE_MCBIST |
+                                TARGET_TYPE_OBUS   |
+                                TARGET_TYPE_PERV   |
+                                TARGET_TYPE_PEC,
+
     // Mappings to target types found in the error xml files
     TARGET_TYPE_EX_CHIPLET    = TARGET_TYPE_EX,
     TARGET_TYPE_MBA_CHIPLET   = TARGET_TYPE_MBA,