/* IBM_PROLOG_BEGIN_TAG */ /* This is an automatically generated prolog. */ /* */ /* $Source: src/include/usr/util/utillidmgr.H $ */ /* */ /* IBM CONFIDENTIAL */ /* */ /* COPYRIGHT International Business Machines Corp. 2013 */ /* */ /* 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 _UTILLIDMGR_H #define _UTILLIDMGR_H /** * @file util/utillidmgr.H * * @brief Interface to support loading lids into memory. The utilities are * smart enough to determine if a lid is available in PNOR. If not, * it will attempt to get the LID from the FSP via mailbox messages. */ #include #include #include #include class UtilLidMgr { private: /** * @brief Default constructor. * * @par Detailed Description * Forcing user to use constructor with input parm/ */ UtilLidMgr(); public: /** * @brief Initialize Lid Manager object. * * @par Detailed Description * Ensures member variables are initialized to sane values. * Sets the initial LID ID. * * @param[in] i_lidId * LID ID. * */ explicit UtilLidMgr(uint32_t i_lidId); /** * @brief Destroy the Lid Manager object resources * * @par Detailed Description: * Frees any allocated memory * */ ~UtilLidMgr(); /** * @brief Sets the desired LID ID in an instance variable. * * @par Detailed Description: * This is how the user declares which LID they want * to work with. It can also be used to reset the * object to a different LID Id.. * * @param[in] i_lidId * LID ID. * * @return errlHndl_t * return errl == NULL -> success * return errl != NULL -> failure */ errlHndl_t setLidId(uint32_t i_lidId); /** * @brief Get LID Size * * @par Detailed Description: * Returns useful LID metrics to the user. Currently * this is only the size of the LID in bytes. * * @param[out] o_lidSize * Size of the LID in bytes. * * @return errlHndl_t * return errl == NULL -> success * return errl != NULL -> failure */ errlHndl_t getLidSize(size_t& o_lidSize); /** * @brief Get LID * * @par Detailed Description: * Gets lid and puts it into space allocated * by the caller. The caller is required to * allocate the indicated memory space before * calling this function. * * @param[in] i_dest * Pointer to where LID should be stored in * hostboot memory * * @param[in] i_destSeze * Reserved space in bytes at destintion address * for LID. * * @return errlHndl_t * return errl == NULL -> success * return errl != NULL -> failure */ errlHndl_t getLid(void* i_dest, size_t i_destSize); protected: /** * @brief Get LID Size PNOR * * @par Detailed Description: * Checks if LID is in Hostboot Ext image and * gets the size from there if available. * This function assumes the lid name is of the format * .lidbin * The file is not technically a lid, thus the slightly * different name * * @param[out] o_lidSize * Size of the LID in bytes. * * @param[out] o_imgInPnor * Indicates image was found in PNOR * * @return errlHndl_t * return errl == NULL -> success * return errl != NULL -> failure */ errlHndl_t getLidSizePnor(size_t& o_lidSize, bool& o_imgInPnor); /** * @brief Get LID PNOR * * @par Detailed Description: * Gets the LID from the PNOR extended image * if it exists. The caller is required to * allocate the indicated memory space before * calling this function. * This function assumes the lid name is of the format * .lidbin * The file is not technically a lid, thus the slightly * different name * * @param[in] i_dest * pointer where LID should be stored in * hostboot memory * * @param[in] i_destSeze * Reserved space in bytes at destintion address * for LID. * * @param[out] o_imgInPnor * Indicates image was found in PNOR * * @return errlHndl_t * return errl == NULL -> success * return errl != NULL -> failure */ errlHndl_t getLidPnor(void* i_dest, size_t i_destSize, bool& o_imgInPnor); /** * @brief performs object cleanup when a new lidId is set * Function is also called by the destructor. */ errlHndl_t cleanup(); /** * @brief Updates the lidId in the object * * @par Detailed Description: * Updates the lidId in the object * Also composes the LID filename * This function assumes the lid name is of the format * .lidbin * The file is not technically a lid, thus the slightly * different name * * @param[in] i_lidId * LID ID. */ void updateLid(uint32_t i_lidId); /** * @enum UtilLidMgr::MBOX_MSG_TYPE * * @brief Message enum to determine if msg should be sent * asynchronously or if the call should be synchronous * */ enum MBOX_MSG_TYPE { ASYNCHRONOUS, SYNCHRONOUS }; /** * @brief Create message queue * * @par Detailed Description: * Creates LID message queue and registers with mbox. * It also locks the cv_mutex. This ensures only the * current instance will listen for response messages * from FSP. * Any function that calls this function must also call * unregisterMsgQueue() to free the queue and unlock * the mutex. * * @return errlHndl_t * return errl == NULL -> success * return errl != NULL -> failure */ errlHndl_t createMsgQueue(); /** * @brief Unregister Msg Queue * * @par Detailed Description: * Unregisters LID msg queue with mbox */ void unregisterMsgQueue(); /** * @brief Uses the internal mailbox to send a message to the FSP * * * @par Detailed Description: * This funciton will call into mailboxsp code using the * UtilLidMgr as a target message queue.. * * @param[in] i_type * ::MBOX_MSG_TYPE passed in to define the * message sending policy. * * @param[in/out] i_msg * This parameter is used as both input and an * output parameter. If the message is sent * synchronusly the response will be populated * in an object pointed to by this pointer. If * the message is asynchronus the object * pointed to by this paramter will be sent to * the fsp. * * @return errlHndl_t * return errl == NULL -> success * return errl != NULL -> failure */ errlHndl_t sendMboxMessage( MBOX_MSG_TYPE i_type, msg_t * i_msg ); /** * @brief Mutex to prevent concurrent LID operations. * This needs to be static so we can mutex across multiple instances */ static mutex_t cv_mutex; /** * @brief Keep track of mutex state */ bool iv_needUnlock; /** * @brief Keep track of Msg queue registered state */ bool iv_queueRegistered; /** * @brief Pointer to message queue */ msg_q_t iv_HbMsgQ; /** * @brief LID fileName */ char iv_lidFileName[16]; /** * @brief current LID ID */ uint32_t iv_lidId; /** * @brief reported size of current LID */ size_t iv_lidSize; }; #endif /* _UTILLIDMGR_H */