From 7d9e00e84843d669f115cb9f51ef587321dae39a Mon Sep 17 00:00:00 2001 From: Joachim Fenkes Date: Wed, 28 Nov 2018 10:25:41 +0100 Subject: 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 Tested-by: FSP CI Jenkins Tested-by: HWSV CI Reviewed-by: Daniel M. Crowell Reviewed-by: Matt K. Light Tested-by: Hostboot CI Tested-by: PPE CI Reviewed-by: Jennifer A. Stofer Reviewed-on: http://rchgit01.rchland.ibm.com/gerrit1/70946 --- src/import/hwpf/fapi2/docs/topics/multicast_doc.C | 148 ++++++++++++++++++++++ src/import/hwpf/fapi2/include/error_info.H | 14 +- src/import/hwpf/fapi2/include/fapi2_hw_access.H | 20 +++ src/import/hwpf/fapi2/include/fapi2_target.H | 59 ++++++++- src/import/hwpf/fapi2/include/multicast_defs.H | 45 ++++++- src/import/hwpf/fapi2/include/target_types.H | 7 + 6 files changed, 279 insertions(+), 14 deletions(-) create mode 100644 src/import/hwpf/fapi2/docs/topics/multicast_doc.C (limited to 'src/import/hwpf/fapi2') diff --git a/src/import/hwpf/fapi2/docs/topics/multicast_doc.C b/src/import/hwpf/fapi2/docs/topics/multicast_doc.C new file mode 100644 index 000000000..20234383e --- /dev/null +++ b/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 +#include + +using namespace fapi2; + +void multicast_doc(uint8_t i_core_select) +{ + Target l_chip_target; + Target 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(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 > l_uc_eqs = l_mc_eqs.getChildren(); + + /* # 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(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()) + { + // 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? + */ + +} diff --git a/src/import/hwpf/fapi2/include/error_info.H b/src/import/hwpf/fapi2/include/error_info.H index df38467c2..4fd1af8a1 100644 --- a/src/import/hwpf/fapi2/include/error_info.H +++ b/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 -inline uint64_t convertType( const fapi2::Target& i_value) +template +inline uint64_t convertType( const fapi2::Target& 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((static_cast( - (i_value.get().getFapiTargetType())) << 32) | - i_value.get().getTargetInstance()); + return static_cast( + (static_cast( + (i_value.get().getFapiTargetType() | + (i_value.get().fields.is_multicast << 31)) + ) << 32) | i_value.get().getTargetInstance()); }; #endif diff --git a/src/import/hwpf/fapi2/include/fapi2_hw_access.H b/src/import/hwpf/fapi2/include/fapi2_hw_access.H index d2a4d0191..4c7142369 100644 --- a/src/import/hwpf/fapi2/include/fapi2_hw_access.H +++ b/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& i_chip, + const std::vector< MulticastGroupMapping >& i_mappings); + //-------------------------------------------------------------------------- // HW Communication Functions //-------------------------------------------------------------------------- diff --git a/src/import/hwpf/fapi2/include/fapi2_target.H b/src/import/hwpf/fapi2/include/fapi2_target.H index fcfb8d12c..444fe3396 100644 --- a/src/import/hwpf/fapi2/include/fapi2_target.H +++ b/src/import/hwpf/fapi2/include/fapi2_target.H @@ -139,8 +139,16 @@ class Target iv_handle(Value) { plat_apply_target_limits(); - }; + /* 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 to a Target + /// @brief Copy from a Target to a Target /// @tparam O the target type of the other + /// @tparam MO the multicast type of the other /// - template - inline Target( const Target& Other ): - Target(Other.get()) + template + inline Target( const Target& Other ): + iv_handle(Other.get()) { plat_apply_target_limits(); @@ -356,6 +395,12 @@ class Target static_assert( bitCount::count >= bitCount::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: diff --git a/src/import/hwpf/fapi2/include/multicast_defs.H b/src/import/hwpf/fapi2/include/multicast_defs.H index 5ed6a1bbe..b0d67fc51 100644 --- a/src/import/hwpf/fapi2/include/multicast_defs.H +++ b/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(a | b); +} + } #endif diff --git a/src/import/hwpf/fapi2/include/target_types.H b/src/import/hwpf/fapi2/include/target_types.H index 7b96fa3d7..8da4c633d 100644 --- a/src/import/hwpf/fapi2/include/target_types.H +++ b/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, -- cgit v1.2.1