ixnpedl.h

AMCC POWERPC 44X系列的U-BOOT文件

 *         version of the image before attempting download.
 * @post
 *         - The NPE Instruction Pipeline will be cleared if State Information
 *           has been downloaded.
 *         - If the download fails with a critical error, the NPE may
 *           be left in an ususable state.
 * @return
 *         - IX_SUCCESS if the download was successful;
 *         - IX_NPEDL_PARAM_ERR if a parameter error occured
 *         - IX_NPEDL_CRITICAL_NPE_ERR if a critical NPE error occured during
 *           download
 *         - IX_PARAM_CRITICAL_MICROCODE_ERR if a critical microcode error
 *           occured during download
 *         - IX_FAIL if NPE is not available or image is failed to be located.
 *           A warning is issued if the NPE is not present.
 */
PUBLIC IX_STATUS
ixNpeDlImageDownload (IxNpeDlImageId *imageIdPtr,
            BOOL verify);

/**
 * @ingroup IxNpeDl
 *
 * @fn PUBLIC IX_STATUS ixNpeDlAvailableImagesCountGet (UINT32 *numImagesPtr)
 *
 * @brief Get the number of Images available in a microcode image library
 *
 * @param numImagesPtr UINT32* [out] - A pointer to the number of images in
 *                                       the image library.
 *
 * Gets the number of images available in the microcode image library.
 * Then returns this in a variable pointed to by <i>numImagesPtr</i>.
 *
 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
 *
 * @pre
 *     - The Client should declare the variable to which numImagesPtr points
 *
 * @post
 *
 * @return
 *     - IX_SUCCESS if the operation was successful
 *     - IX_NPEDL_PARAM_ERR if a parameter error occured
 *     - IX_FAIL otherwise
 */
PUBLIC IX_STATUS
ixNpeDlAvailableImagesCountGet (UINT32 *numImagesPtr);

/**
 * @ingroup IxNpeDl
 *
 * @fn PUBLIC IX_STATUS ixNpeDlAvailableImagesListGet (IxNpeDlImageId *imageIdListPtr,
                                                         UINT32 *listSizePtr)
 *
 * @brief Get a list of the images available in a microcode image library
 *
 * @param imageIdListPtr @ref IxNpeDlImageId* [out] - Array to contain list of
 *                                                   image Ids (memory
 *                                                   allocated by Client).
 * @param listSizePtr UINT32* [inout]  - As an input, this param should point
 *                                       to the max number of Ids the
 *                                       <i>imageIdListPtr</i> array can
 *                                       hold. NpeDl will replace the input
 *                                       value of this parameter with the
 *                                       number of image Ids actually filled
 *                                       into the array before returning.
 *
 * Finds list of images available in the microcode image library.
 * Fills these into the array pointed to by <i>imageIdListPtr</i>
 *
 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
 *
 * @pre
 *     - The Client should declare the variable to which numImagesPtr points
 *     - The Client should create an array (<i>imageIdListPtr</i>) large
 *       enough to contain all the image Ids in the image library
 *
 * @post
 *
 * @return
 *     - IX_SUCCESS if the operation was successful
 *     - IX_NPEDL_PARAM_ERR if a parameter error occured
 *     - IX_FAIL otherwise
 */
PUBLIC IX_STATUS
ixNpeDlAvailableImagesListGet (IxNpeDlImageId *imageIdListPtr,
                 UINT32 *listSizePtr);

/**
 * @ingroup IxNpeDl
 *
 * @fn PUBLIC IX_STATUS ixNpeDlLoadedImageGet (IxNpeDlNpeId npeId,
                                                IxNpeDlImageId *imageIdPtr)
 *
 * @brief Gets the Id of the image currently loaded on a particular NPE
 *
 * @param npeId @ref IxNpeDlNpeId [in]              - Id of the target NPE.
 * @param imageIdPtr @ref IxNpeDlImageId* [out]     - Pointer to the where the
 *                                               image id should be stored.
 *
 * If an image of microcode was previously downloaded successfully to the NPE
 * by NPE Downloader, this function returns in <i>imageIdPtr</i> the image
 * Id of that image loaded on the NPE.
 *
 * @pre
 *     - The Client has allocated memory to the <i>imageIdPtr</i> pointer.
 *
 * @post
 *
 * @return
 *     -  IX_SUCCESS if the operation was successful
 *     -  IX_NPEDL_PARAM_ERR if a parameter error occured
 *     -  IX_FAIL if the NPE doesn't currently have a image loaded
 */
PUBLIC IX_STATUS
ixNpeDlLoadedImageGet (IxNpeDlNpeId npeId,
             IxNpeDlImageId *imageIdPtr);

/**
 * @fn PUBLIC IX_STATUS ixNpeDlLatestImageGet (IxNpeDlNpeId npeId, IxNpeDlFunctionalityId
                                        functionalityId, IxNpeDlImageId *imageIdPtr)
 *
 * @brief This instructs NPE Downloader to get Id of the latest version for an
 * image that is specified by the client.
 *
 * @param npeId @ref IxNpeDlNpeId [in]                    - Id of the target NPE.
 * @param functionalityId @ref IxNpeDlFunctionalityId [in]    - functionality of the image
 * @param imageIdPtr @ref IxNpeDlImageId* [out]               - Pointer to the where the
 *                                                         image id should be stored.
 *
 * This function sets NPE Downloader to return the id of the latest version for
 * image.  The user will select the image by providing a particular NPE
 * (specifying <i>npeId</i>) with particular functionality (specifying
 * <i>FunctionalityId</i>). The most recent version available as determined by the
 * highest Major and Minor revision numbers is returned in <i>imageIdPtr</i>.
 *
 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
 *
 * @return
 *      - IX_SUCCESS if the operation was successful
 *      - IX_NPEDL_PARAM_ERR if a parameter error occured
 *      - IX_FAIL otherwise
 */
PUBLIC IX_STATUS
ixNpeDlLatestImageGet (IxNpeDlNpeId npeId,
             IxNpeDlFunctionalityId functionalityId,
                    IxNpeDlImageId *imageIdPtr);

/**
 * @ingroup IxNpeDl
 *
 * @fn PUBLIC IX_STATUS ixNpeDlNpeStopAndReset (IxNpeDlNpeId npeId)
 *
 * @brief Stops and Resets an NPE
 *
 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE.
 *
 * This function performs a soft NPE reset by writing reset values to
 * particular NPE registers. Note that this does not reset NPE co-processors.
 * This implicitly stops NPE code execution before resetting the NPE.
 *
 * @note It is no longer necessary to call this function before downloading
 * a new image to the NPE.  It is left on the API only to allow greater control
 * of NPE execution if required.  Where appropriate, use @ref ixNpeDlNpeInitAndStart
 * or @ref ixNpeDlCustomImageNpeInitAndStart instead.
 *
 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
 *
 * @pre
 *     - The Client is responsible for ensuring mutual access to the NPE.
 *
 * @post
 *
 * @return
 *      - IX_SUCCESS if the operation was successful
 *      - IX_NPEDL_PARAM_ERR if a parameter error occured
 *      - IX_FAIL otherwise
 *      - IX_NPEDL_CRITICAL_NPE_ERR failed to reset NPE due to timeout error. 
 *        Timeout error could happen if NPE hang
 */
PUBLIC IX_STATUS
ixNpeDlNpeStopAndReset (IxNpeDlNpeId npeId);

/**
 * @ingroup IxNpeDl
 *
 * @fn PUBLIC IX_STATUS ixNpeDlNpeExecutionStart (IxNpeDlNpeId npeId)
 *
 * @brief Starts code execution on a NPE
 *
 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE
 *
 * Starts execution of code on a particular NPE.  A client would typically use
 * this after a download to NPE is performed, to start/restart code execution
 * on the NPE.
 *
 * @note It is no longer necessary to call this function after downloading
 * a new image to the NPE.  It is left on the API only to allow greater control
 * of NPE execution if required.  Where appropriate, use @ref ixNpeDlNpeInitAndStart
 * or @ref ixNpeDlCustomImageNpeInitAndStart instead.
 *
 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
 *
 * @pre
 *     - The Client is responsible for ensuring mutual access to the NPE.
 *     - Note that this function does not set the NPE Next Program Counter
 *       (NextPC), so it should be set beforehand if required by downloading
 *       appropriate State Information (using ixNpeDlVersionDownload()).
 *
 * @post
 *
 * @return
 *      - IX_SUCCESS if the operation was successful
 *      - IX_NPEDL_PARAM_ERR if a parameter error occured
 *      - IX_FAIL otherwise
 */
PUBLIC IX_STATUS
ixNpeDlNpeExecutionStart (IxNpeDlNpeId npeId);

/**
 * @ingroup IxNpeDl
 *
 * @fn PUBLIC IX_STATUS ixNpeDlNpeExecutionStop (IxNpeDlNpeId npeId)
 *
 * @brief Stops code execution on a NPE
 *
 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE
 *
 * Stops execution of code on a particular NPE.  This would typically be used
 * by a client before a download to NPE is performed, to stop code execution on
 * an NPE, unless ixNpeDlNpeStopAndReset() is used instead.  Unlike
 * ixNpeDlNpeStopAndReset(), this function only halts the NPE and leaves
 * all registers and settings intact. This is useful, for example, between
 * stages of a multi-stage download, to stop the NPE prior to downloading the
 * next image while leaving the current state of the NPE intact..
 *
 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
 *
 * @pre
 *     - The Client is responsible for ensuring mutual access to the NPE.
 *
 * @post
 *
 * @return
 *      - IX_SUCCESS if the operation was successful
 *      - IX_NPEDL_PARAM_ERR if a parameter error occured
 *      - IX_FAIL otherwise
 */
PUBLIC IX_STATUS
ixNpeDlNpeExecutionStop (IxNpeDlNpeId npeId);

/**
 * @ingroup IxNpeDl
 *
 * @fn PUBLIC IX_STATUS ixNpeDlUnload (void)
 *
 * @brief This function will uninitialise the IxNpeDl component.
 *
 * This function will uninitialise the IxNpeDl component.  It should only be
 * called once, and only if the IxNpeDl component has already been initialised by
 * calling any of the following functions:
 * - @ref ixNpeDlNpeInitAndStart
 * - @ref ixNpeDlCustomImageNpeInitAndStart
 * - @ref ixNpeDlImageDownload     (deprecated)
 * - @ref ixNpeDlNpeStopAndReset   (deprecated)
 * - @ref ixNpeDlNpeExecutionStop  (deprecated)
 * - @ref ixNpeDlNpeExecutionStart (deprecated)
 *
 * If possible, this function should be called before a soft reboot or unloading
 * a kernel module to perform any clean up operations required for IxNpeDl.
 *
 * The following actions will be performed by this function:
 * - Unmapping of any kernel memory mapped by IxNpeDl
 *
 * @return
 *      - IX_SUCCESS if the operation was successful
 *      - IX_FAIL otherwise
 */

PUBLIC IX_STATUS 
ixNpeDlUnload (void);

/**
 * @ingroup IxNpeDl
 *
 * @fn PUBLIC void ixNpeDlStatsShow (void)
 *
 * @brief This function will display run-time statistics from the IxNpeDl
 *        component
 *
 * @return none
 */
PUBLIC void
ixNpeDlStatsShow (void);

/**
 * @ingroup IxNpeDl
 *
 * @fn PUBLIC void ixNpeDlStatsReset (void)
 *
 * @brief This function will reset the statistics of the IxNpeDl component
 *
 * @return none
 */
PUBLIC void
ixNpeDlStatsReset (void);

#endif /* IXNPEDL_H */

/**
 * @} defgroup IxNpeDl
 */