path: root/src/usr/diag/prdf/framework/service/prdfTargetServices.H

/* IBM_PROLOG_BEGIN_TAG                                                   */
/* This is an automatically generated prolog.                             */
/*                                                                        */
/* $Source: src/usr/diag/prdf/framework/service/prdfTargetServices.H $    */
/*                                                                        */
/* IBM CONFIDENTIAL                                                       */
/*                                                                        */
/* COPYRIGHT International Business Machines Corp. 2012                   */
/*                                                                        */
/* p1                                                                     */
/*                                                                        */
/* Object Code Only (OCO) source materials                                */
/* Licensed Internal Code Source Materials                                */
/* IBM HostBoot Licensed Internal Code                                    */
/*                                                                        */
/* The source code for this program is not published or otherwise         */
/* divested of its trade secrets, irrespective of what has been           */
/* deposited with the U.S. Copyright Office.                              */
/*                                                                        */
/* Origin: 30                                                             */
/*                                                                        */
/* IBM_PROLOG_END_TAG                                                     */

#ifndef PRDFTARGETSERVICES_H
#define PRDFTARGETSERVICES_H

/**
 * @file  prdfTargetServices.H
 * @brief Wrapper code for things PRD needs from target services.
 */

//------------------------------------------------------------------------------
// Includes
//------------------------------------------------------------------------------

#include <iipconst.h>
#include <prdfTimer.H>
#include <algorithm>
#include <targeting/common/target.H>
#include <targeting/common/entitypath.H>
#include <errlentry.H>

#ifdef __HOSTBOOT_MODULE

#else

#endif

//------------------------------------------------------------------------------

namespace PRDF
{

enum PositionBounds
{
    MAX_NODE_PER_SYS    = 8,

    MAX_PROC_PER_NODE   = 8,

    MAX_EX_PER_PROC     = 16,
    MAX_CORE_PER_PROC   = MAX_EX_PER_PROC,
    MAX_L2_PER_PROC     = MAX_EX_PER_PROC,
    MAX_L3_PER_PROC     = MAX_EX_PER_PROC,

    MAX_XBUS_PER_PROC   = 4,
    MAX_ABUS_PER_PROC   = 3,

    MAX_MCS_PER_PROC    = 8,
    MAX_MEMBUF_PER_PROC = MAX_MCS_PER_PROC,

    MAX_MBA_PER_MEMBUF  = 2,
    MAX_PORT_PER_MBA    = 2,
    MAX_DIMM_PER_PORT   = 2,

    INVALID_POSITION_BOUND = 0xffffffff,
};

namespace PlatServices
{

//##############################################################################
//##
//##                 Target Manipulation Utility Functions
//##
//##############################################################################

/**
 * @brief   Returns the target for a given HUID.
 * @param   i_huid The HUID of a target.
 * @return  The target for the given HUID.
 * @post    Must check that the returned target is not NULL.
 */
TARGETING::TargetHandle_t getTarget( HUID i_huid );

/**
 * @brief   Returns the target for a given entity path.
 * @param   i_path The entity path of a target.
 * @return  The target for the given entity path.
 * @post    Must check that the returned target is not NULL.
 */
TARGETING::TargetHandle_t getTarget( const TARGETING::EntityPath & i_path );

/**
 * @brief   Returns the entity path for a given target.
 * @param   i_target   A target.
 * @param   o_path     The returned path.
 * @param   i_pathType The desired path type, optional.
 * @return  Non-SUCCESS if internal functions fail, SUCCESS otherwise.
 * @note    Will use the path type specified the EntityPath contructor unless
 *          a supported PATH_TYPE is given.
 */
int32_t getEntityPath( TARGETING::TargetHandle_t i_target,
                       TARGETING::EntityPath & o_path,
                       TARGETING::EntityPath::PATH_TYPE i_pathType
                                            = TARGETING::EntityPath::PATH_NA );

/**
 * @brief   Returns the HUID for a given target.
 * @param   i_target A target.
 * @return  The HUID for the given target.
 * @post    Must check that the returned target is not INVALID_HUID.
 */
HUID getHuid( TARGETING::TargetHandle_t i_target );

/**
 * @brief   Query functional state of a target.
 * @param   i_target Any target.
 * @return  TRUE if target is functional, FALSE otherwise.
 */
bool isFunctional( TARGETING::TargetHandle_t i_target );

/**
 * @brief   Returns the type of the given target.
 * @param   i_target Any target.
 * @return  The type for the given target.
 */
TARGETING::TYPE getTargetType( TARGETING::TargetHandle_t i_target );

/**
 * @brief   Returns the class of the given target.
 * @param   i_target Any target.
 * @return  The class for the given target.
 */
TARGETING::CLASS getTargetClass( TARGETING::TargetHandle_t i_target );

/**
 * @brief   Prints the HUID and dumps the entity path of the given target.
 * @param   i_target Any target.
 */
void printTargetInfo( TARGETING::TargetHandle_t i_target );

/**
 * @brief   Get the chip level (DD level) of this target.
 * @param   i_target Any chip or unit target.
 * @return  The chip level or 0 function failed.
 */
uint8_t getChipLevel( TARGETING::TargetHandle_t i_target );

/**
 * @brief   Get the chip ID (P7, P7+, etc.) of this target.
 * @param   i_target Any chip or unit target.
 * @return  The chip ID or 0 function failed.
 */
//TODO: See .C
//uint32_t getChipId( TARGETING::TargetHandle_t i_target );

//##############################################################################
//##
//##                       getConnected() support functions
//##
//##############################################################################

/**
 * @brief   Returns a list of functional targets of a given type that is
 *          associated with the given target.
 * @param   i_target    The given target.
 * @param   i_connType  Type of target(s) return in list
 * @return  The connected list of targets. On error, the list will be empty.
 * @note    This function does not support peer-to-peer connections.
 */
TARGETING::TargetHandleList getConnected( TARGETING::TargetHandle_t i_target,
                                          TARGETING::TYPE i_connType );

/**
 * @brief   Returns the target of a PROC that is connected via the given
 *          target's XBUS or ABUS.
 * @param   i_procTarget Target of TYPE_PROC.
 * @param   i_busType    Bus type of TYPE_XBUS or TYPE_ABUS.
 * @param   i_busPos     Position of bus (XBUS: 0-3, ABUS: 0-2).
 * @return  The connected PROC target. On error, the target will be NULL.
 */
TARGETING::TargetHandle_t getConnectedPeerProc(
                                         TARGETING::TargetHandle_t i_procTarget,
                                         TARGETING::TYPE i_busType,
                                         uint32_t i_busPos );

/**
 * @brief   Returns the system target.
 * @return  The system target.
 */
TARGETING::TargetHandle_t getSystemTarget();

/**
 * @brief   Get container chip target for the given target.
 * @param   i_target Any chip or unit target.
 * @return  The container chip target.
 * @post    Must check that the returned target is not NULL.
 */
TARGETING::TargetHandle_t getParentChip( TARGETING::TargetHandle_t i_target );

/**
 * @brief   Returns the list of functional targets of a given type.
 * @param   i_type Type of target requested.
 * @return  The list of functional targets.
 */
TARGETING::TargetHandleList getFunctionalTargetList( TARGETING::TYPE i_type );

/**
 * @brief   Determines if the given target is the last functional core.
 * @param   i_coreTarget A core target.
 * @return  TRUE if target is last functional core, FALSE otherwise.
 */
bool checkLastFuncCore( TARGETING::TargetHandle_t i_coreTarget );

//##############################################################################
//##
//##                       Target position support code
//##
//##############################################################################

/**
 * @brief   Returns the position of the given target.
 * @param   i_target Any target.
 * @return  The position or index of the given target relative to its container.
 *          Can compare against enums in PRDF::PositionBounds for validity.
 */
uint32_t getTargetPosition( TARGETING::TargetHandle_t i_target );

/**
 * @brief   Returns the position of a node in which the given target is
 *          contained.
 * @param   i_target Any target.
 * @return  The position of the connected node.
 */
uint32_t getNodePosition( TARGETING::TargetHandle_t i_target );

//##############################################################################
//##
//##                       DUMP and Runtime Deconfig support code
//##
//##############################################################################

/**
 * Interface to request a Hardware Unit dump collection.
 *
 * @param[in] i_errl input error log handle
 * @param[in] i_huid The HUID of Failing target to dump
 *
 * @return NULL on success, else error log
 */
errlHndl_t dumpHWURequest(errlHndl_t i_errl, HUID i_huid );

/**
* Change the state of the given HUID at runtime.
*
* @param   i_huid The HUID of a target
*
* @return NULL on success, else error log
*/
errlHndl_t runtimeDeconfig( HUID i_huid );


//##############################################################################
//##
//##                        Memory specific functions
//##
//##############################################################################

/**
 * @brief   Returns the list of master ranks for a logical DIMM.
 * @param   i_memTarget MBA target or child of MBA.
 * @param   i_portSlct  Port select (0-1).
 * @param   i_dimmSlct  DIMM select (0-1).
 * @param   o_ranks     List of master ranks for a logical DIMM.
 * @return  Non-SUCCESS if internal functions fail, SUCCESS otherwise.
 */
int32_t getMasterRanks( TARGETING::TargetHandle_t i_memTarget,
                        uint32_t i_portSlct, uint32_t i_dimmSlct,
                        std::vector<uint32_t> & o_ranks );

/**
 * @brief   Returns the DMI bus channel for the given memory target.
 * @param   i_memTarget MCS target or child of MCS.
 * @return  The DMI bus channel.
 * @note    Can check against MAX_MCS_PER_PROC for validity.
 */
uint32_t getMemChnl( TARGETING::TargetHandle_t i_memTarget );

/**
 * @brief   Determines if a given target is associated with a memory buffer that
 *          is located on the DIMM card.
 * @param   i_target Any memory target or parent.
 * @return  TRUE if target is associated with buffered DIMMs, FALSE otherwise.
 */
bool isMembufOnDimm( TARGETING::TargetHandle_t i_memTarget );

//##############################################################################
//##
//##                        Clock specific functions
//##
//##############################################################################

/**
 * @brief   Queries if this chip's clocks are on.
 * @param   i_pTargetHandle Handle of a chip or any logical entity.
 * @return  TRUE if this chip's clocks are on, FALSE otherwise.
 * @pre     None.
 * @post    None.
 */
bool areClocksOn( TARGETING::TargetHandle_t i_pTargetHandle );

/**
 * @brief   Gets handle of the clock card for the given target.
 * @param   i_pTargetHandle     Handle of a functional unit.
 * @param   i_targetType        Type of clock source  desired.
 * @return  Handle_t of clock source.
 * @pre     None.
 * @post    None.
 */
TARGETING::TargetHandle_t getClockId(TARGETING::TargetHandle_t
                             i_pTargetHandle,TARGETING::TYPE i_targetType);

/**
 * @brief   Get TargetHandle_t of clock mux.
 * @param   i_pFabricHandle Handle of a fabric.
 * @return  Handle of clock mux.
 * @pre     Fabric must be a handle of a functioning fabric.
 * @post    None.
 */
TARGETING::TargetHandle_t getClockMux(TARGETING::TargetHandle_t
                             i_pFabricHandle);

} // end namespace PlatServices

} // end namespace PRDF

#endif // PRDFTARGETSERVICES_H