4 * @date 14 December 2001
6 * @brief This file contains the public API of the IXP400 NPE Downloader
11 * IXP400 SW Release version 2.0
13 * -- Copyright Notice --
16 * Copyright 2001-2005, Intel Corporation.
17 * All rights reserved.
20 * SPDX-License-Identifier: BSD-3-Clause
22 * -- End of Copyright Notice --
26 * @defgroup IxNpeDl IXP400 NPE-Downloader (IxNpeDl) API
28 * @brief The Public API for the IXP400 NPE Downloader
37 * Put the user defined include files required
39 #include "IxOsalTypes.h"
40 #include "IxNpeMicrocode.h"
43 * #defines for function return types, etc.
47 * @def IX_NPEDL_PARAM_ERR
49 * @brief NpeDl function return value for a parameter error
51 #define IX_NPEDL_PARAM_ERR 2
54 * @def IX_NPEDL_RESOURCE_ERR
56 * @brief NpeDl function return value for a resource error
58 #define IX_NPEDL_RESOURCE_ERR 3
61 * @def IX_NPEDL_CRITICAL_NPE_ERR
63 * @brief NpeDl function return value for a Critical NPE error occuring during
64 download. Assume NPE is left in unstable condition if this value is
65 returned or NPE is hang / halt.
67 #define IX_NPEDL_CRITICAL_NPE_ERR 4
70 * @def IX_NPEDL_CRITICAL_MICROCODE_ERR
72 * @brief NpeDl function return value for a Critical Microcode error
73 * discovered during download. Assume NPE is left in unstable condition
74 * if this value is returned.
76 #define IX_NPEDL_CRITICAL_MICROCODE_ERR 5
79 * @def IX_NPEDL_DEVICE_ERR
81 * @brief NpeDl function return value when image being downloaded
82 * is not meant for the device in use
84 #define IX_NPEDL_DEVICE_ERR 6
87 * @defgroup NPEImageID IXP400 NPE Image ID Definition
91 * @brief Definition of NPE Image ID to be passed to ixNpeDlNpeInitAndStart()
92 * as input of type UINT32 which has the following fields format:
94 * Field [Bit Location] <BR>
95 * -------------------- <BR>
96 * Device ID [31 - 28] <BR>
97 * NPE ID [27 - 24] <BR>
98 * NPE Functionality ID [23 - 16] <BR>
99 * Major Release Number [15 - 8] <BR>
100 * Minor Release Number [7 - 0] <BR>
107 * @def IX_NPEDL_NPEIMAGE_FIELD_MASK
109 * @brief Mask for NPE Image ID's Field
111 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
112 * It will be removed in a future release.
113 * See @ref ixNpeDlNpeInitAndStart for more information.
115 #define IX_NPEDL_NPEIMAGE_FIELD_MASK 0xff
118 * @def IX_NPEDL_NPEIMAGE_NPEID_MASK
120 * @brief Mask for NPE Image NPE ID's Field
123 #define IX_NPEDL_NPEIMAGE_NPEID_MASK 0xf
126 * @def IX_NPEDL_NPEIMAGE_DEVICEID_MASK
128 * @brief Mask for NPE Image Device ID's Field
131 #define IX_NPEDL_NPEIMAGE_DEVICEID_MASK 0xf
134 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_NPEID
136 * @brief Location of NPE ID field in term of bit.
138 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
139 * It will be removed in a future release.
140 * See @ref ixNpeDlNpeInitAndStart for more information.
142 #define IX_NPEDL_NPEIMAGE_BIT_LOC_NPEID 24
145 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_FUNCTIONALITYID
147 * @brief Location of Functionality ID field in term of bit.
149 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
150 * It will be removed in a future release.
151 * See @ref ixNpeDlNpeInitAndStart for more information.
153 #define IX_NPEDL_NPEIMAGE_BIT_LOC_FUNCTIONALITYID 16
156 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_MAJOR
158 * @brief Location of Major Release Number field in term of bit.
160 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
161 * It will be removed in a future release.
162 * See @ref ixNpeDlNpeInitAndStart for more information.
164 #define IX_NPEDL_NPEIMAGE_BIT_LOC_MAJOR 8
167 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_MINOR
169 * @brief Location of Minor Release Number field in term of bit.
171 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
172 * It will be removed in a future release.
173 * See @ref ixNpeDlNpeInitAndStart for more information.
175 #define IX_NPEDL_NPEIMAGE_BIT_LOC_MINOR 0
178 * @} addtogroup NPEImageID
182 * @def ixNpeDlMicrocodeImageOverride(x)
184 * @brief Map old terminology that uses term "image" to new term
187 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
188 * It will be removed in a future release.
189 * See @ref ixNpeDlNpeInitAndStart for more information.
191 #define ixNpeDlMicrocodeImageOverride(x) ixNpeDlMicrocodeImageLibraryOverride(x)
194 * @def IxNpeDlVersionId
196 * @brief Map old terminology that uses term "version" to new term
199 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
200 * It will be removed in a future release.
201 * See @ref ixNpeDlNpeInitAndStart for more information.
203 #define IxNpeDlVersionId IxNpeDlImageId
206 * @def ixNpeDlVersionDownload
208 * @brief Map old terminology that uses term "version" to new term
211 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
212 * It will be removed in a future release.
213 * See @ref ixNpeDlNpeInitAndStart for more information.
215 #define ixNpeDlVersionDownload(x,y) ixNpeDlImageDownload(x,y)
218 * @def ixNpeDlAvailableVersionsCountGet
220 * @brief Map old terminology that uses term "version" to new term
223 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
224 * It will be removed in a future release.
225 * See @ref ixNpeDlNpeInitAndStart for more information.
227 #define ixNpeDlAvailableVersionsCountGet(x) ixNpeDlAvailableImagesCountGet(x)
230 * @def ixNpeDlAvailableVersionsListGet
232 * @brief Map old terminology that uses term "version" to new term
235 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
236 * It will be removed in a future release.
237 * See @ref ixNpeDlNpeInitAndStart for more information.
239 #define ixNpeDlAvailableVersionsListGet(x,y) ixNpeDlAvailableImagesListGet(x,y)
242 * @def ixNpeDlLoadedVersionGet
244 * @brief Map old terminology that uses term "version" to new term
247 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
248 * It will be removed in a future release.
249 * See @ref ixNpeDlNpeInitAndStart for more information.
251 #define ixNpeDlLoadedVersionGet(x,y) ixNpeDlLoadedImageGet(x,y)
256 * @brief Map old terminology that uses term "image" to new term
259 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
260 * It will be removed in a future release.
261 * See @ref ixNpeDlNpeInitAndStart for more information.
263 #define clientImage clientImageLibrary
268 * @brief Map old terminology that uses term "version" to new term
271 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
272 * It will be removed in a future release.
273 * See @ref ixNpeDlNpeInitAndStart for more information.
275 #define versionIdPtr imageIdPtr
278 * @def numVersionsPtr
280 * @brief Map old terminology that uses term "version" to new term
283 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
284 * It will be removed in a future release.
285 * See @ref ixNpeDlNpeInitAndStart for more information.
287 #define numVersionsPtr numImagesPtr
290 * @def versionIdListPtr
292 * @brief Map old terminology that uses term "version" to new term
295 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
296 * It will be removed in a future release.
297 * See @ref ixNpeDlNpeInitAndStart for more information.
299 #define versionIdListPtr imageIdListPtr
302 * @def IxNpeDlBuildId
304 * @brief Map old terminology that uses term "buildId" to new term
307 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
308 * It will be removed in a future release.
309 * See @ref ixNpeDlNpeInitAndStart for more information.
311 #define IxNpeDlBuildId IxNpeDlFunctionalityId
316 * @brief Map old terminology that uses term "buildId" to new term
319 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
320 * It will be removed in a future release.
321 * See @ref ixNpeDlNpeInitAndStart for more information.
323 #define buildId functionalityId
326 * @def IX_NPEDL_MicrocodeImage
328 * @brief Map old terminology that uses term "image" to new term
331 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
332 * It will be removed in a future release.
333 * See @ref ixNpeDlNpeInitAndStart for more information.
335 #define IX_NPEDL_MicrocodeImage IX_NPEDL_MicrocodeImageLibrary
342 * @typedef IxNpeDlFunctionalityId
343 * @brief Used to make up Functionality ID field of Image Id
345 * @warning <b>THIS typedef HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
346 * It will be removed in a future release.
347 * See @ref ixNpeDlNpeInitAndStart for more information.
349 typedef UINT8 IxNpeDlFunctionalityId;
352 * @typedef IxNpeDlMajor
353 * @brief Used to make up Major Release field of Image Id
355 * @warning <b>THIS typedef HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
356 * It will be removed in a future release.
357 * See @ref ixNpeDlNpeInitAndStart for more information.
359 typedef UINT8 IxNpeDlMajor;
362 * @typedef IxNpeDlMinor
363 * @brief Used to make up Minor Revision field of Image Id
365 * @warning <b>THIS typedef HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
366 * It will be removed in a future release.
367 * See @ref ixNpeDlNpeInitAndStart for more information.
369 typedef UINT8 IxNpeDlMinor;
376 * @brief NpeId numbers to identify NPE A, B or C
377 * @note In this context, for IXP425 Silicon (B0):<br>
378 * - NPE-A has HDLC, HSS, AAL and UTOPIA Coprocessors.<br>
379 * - NPE-B has Ethernet Coprocessor.<br>
380 * - NPE-C has Ethernet, AES, DES and HASH Coprocessors.<br>
381 * - IXP400 Product Line have different combinations of coprocessors.
385 IX_NPEDL_NPEID_NPEA = 0, /**< Identifies NPE A */
386 IX_NPEDL_NPEID_NPEB, /**< Identifies NPE B */
387 IX_NPEDL_NPEID_NPEC, /**< Identifies NPE C */
388 IX_NPEDL_NPEID_MAX /**< Total Number of NPEs */
396 * @brief Image Id to identify each image contained in an image library
398 * @warning <b>THIS struct HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
399 * It will be removed in a future release.
400 * See @ref ixNpeDlNpeInitAndStart for more information.
404 IxNpeDlNpeId npeId; /**< NPE ID */
405 IxNpeDlFunctionalityId functionalityId; /**< Build ID indicates functionality of image */
406 IxNpeDlMajor major; /**< Major Release Number */
407 IxNpeDlMinor minor; /**< Minor Revision Number */
411 * Prototypes for interface functions
417 * @fn PUBLIC IX_STATUS ixNpeDlNpeInitAndStart (UINT32 imageId)
419 * @brief Stop, reset, download microcode (firmware) and finally start NPE.
421 * @param imageId UINT32 [in] - Id of the microcode image to download.
423 * This function locates the image specified by the <i>imageId</i> parameter
424 * from the default microcode image library which is included internally by
426 * It then stops and resets the NPE, loads the firmware image onto the NPE,
427 * and then restarts the NPE.
429 * @note A list of valid image IDs is included in this header file.
430 * See #defines with prefix IX_NPEDL_NPEIMAGE_...
432 * @note This function, along with @ref ixNpeDlCustomImageNpeInitAndStart
433 * and @ref ixNpeDlLoadedImageFunctionalityGet, supercedes the following
434 * functions which are deprecated and will be removed completely in a
436 * - @ref ixNpeDlImageDownload
437 * - @ref ixNpeDlAvailableImagesCountGet
438 * - @ref ixNpeDlAvailableImagesListGet
439 * - @ref ixNpeDlLatestImageGet
440 * - @ref ixNpeDlLoadedImageGet
441 * - @ref ixNpeDlMicrocodeImageLibraryOverride
442 * - @ref ixNpeDlNpeExecutionStop
443 * - @ref ixNpeDlNpeStopAndReset
444 * - @ref ixNpeDlNpeExecutionStart
447 * - The Client is responsible for ensuring mutual access to the NPE.
449 * - The NPE Instruction Pipeline will be cleared if State Information
450 * has been downloaded.
451 * - If the download fails with a critical error, the NPE may
452 * be left in an ususable state.
454 * - IX_SUCCESS if the download was successful;
455 * - IX_NPEDL_PARAM_ERR if a parameter error occured
456 * - IX_NPEDL_CRITICAL_NPE_ERR if a critical NPE error occured during
458 * - IX_NPEDL_CRITICAL_MICROCODE_ERR if a critical microcode error
459 * occured during download
460 * - IX_NPEDL_DEVICE_ERR if the image being loaded is not meant for
461 * the device currently running.
462 * - IX_FAIL if NPE is not available or image is failed to be located.
463 * A warning is issued if the NPE is not present.
466 ixNpeDlNpeInitAndStart (UINT32 npeImageId);
471 * @fn PUBLIC IX_STATUS ixNpeDlCustomImageNpeInitAndStart (UINT32 *imageLibrary,
474 * @brief Stop, reset, download microcode (firmware) and finally start NPE
476 * @param imageId UINT32 [in] - Id of the microcode image to download.
478 * This function locates the image specified by the <i>imageId</i> parameter
479 * from the specified microcode image library which is pointed to by the
480 * <i>imageLibrary</i> parameter.
481 * It then stops and resets the NPE, loads the firmware image onto the NPE,
482 * and then restarts the NPE.
484 * This is a facility for users who wish to use an image from an external
485 * library of NPE firmware images. To use a standard image from the
486 * built-in library, see @ref ixNpeDlNpeInitAndStart instead.
488 * @note A list of valid image IDs is included in this header file.
489 * See #defines with prefix IX_NPEDL_NPEIMAGE_...
491 * @note This function, along with @ref ixNpeDlNpeInitAndStart
492 * and @ref ixNpeDlLoadedImageFunctionalityGet, supercedes the following
493 * functions which are deprecated and will be removed completely in a
495 * - @ref ixNpeDlImageDownload
496 * - @ref ixNpeDlAvailableImagesCountGet
497 * - @ref ixNpeDlAvailableImagesListGet
498 * - @ref ixNpeDlLatestImageGet
499 * - @ref ixNpeDlLoadedImageGet
500 * - @ref ixNpeDlMicrocodeImageLibraryOverride
501 * - @ref ixNpeDlNpeExecutionStop
502 * - @ref ixNpeDlNpeStopAndReset
503 * - @ref ixNpeDlNpeExecutionStart
506 * - The Client is responsible for ensuring mutual access to the NPE.
507 * - The image library supplied must be in the correct format for use
508 * by the NPE Downloader (IxNpeDl) component. Details of the library
509 * format are contained in the Functional Specification document for
512 * - The NPE Instruction Pipeline will be cleared if State Information
513 * has been downloaded.
514 * - If the download fails with a critical error, the NPE may
515 * be left in an ususable state.
517 * - IX_SUCCESS if the download was successful;
518 * - IX_NPEDL_PARAM_ERR if a parameter error occured
519 * - IX_NPEDL_CRITICAL_NPE_ERR if a critical NPE error occured during
521 * - IX_NPEDL_CRITICAL_MICROCODE_ERR if a critical microcode error
522 * occured during download
523 * - IX_NPEDL_DEVICE_ERR if the image being loaded is not meant for
524 * the device currently running.
525 * - IX_FAIL if NPE is not available or image is failed to be located.
526 * A warning is issued if the NPE is not present.
529 ixNpeDlCustomImageNpeInitAndStart (UINT32 *imageLibrary,
536 * @fn PUBLIC IX_STATUS ixNpeDlLoadedImageFunctionalityGet (IxNpeDlNpeId npeId,
537 UINT8 *functionalityId)
539 * @brief Gets the functionality of the image last loaded on a particular NPE
541 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE.
542 * @param functionalityId UINT8* [out] - the functionality ID of the image
543 * last loaded on the NPE.
545 * This function retrieves the functionality ID of the image most recently
546 * downloaded successfully to the specified NPE. If the NPE does not contain
547 * a valid image, this function returns a FAIL status.
549 * @warning This function is not intended for general use, as a knowledge of
550 * how to interpret the functionality ID is required. As such, this function
551 * should only be used by other Access Layer components of the IXP400 Software
559 * - IX_SUCCESS if the operation was successful
560 * - IX_NPEDL_PARAM_ERR if a parameter error occured
561 * - IX_FAIL if the NPE does not have a valid image loaded
564 ixNpeDlLoadedImageFunctionalityGet (IxNpeDlNpeId npeId,
565 UINT8 *functionalityId);
571 * @fn IX_STATUS ixNpeDlMicrocodeImageLibraryOverride (UINT32 *clientImageLibrary)
573 * @brief This instructs NPE Downloader to use client-supplied microcode image library.
575 * @param clientImageLibrary UINT32* [in] - Pointer to the client-supplied
576 * NPE microcode image library
578 * This function sets NPE Downloader to use a client-supplied microcode image library
579 * instead of the standard image library which is included by the NPE Downloader.
580 * <b>This function is provided mainly for increased testability and should not
581 * be used in normal circumstances.</b> When not used, NPE Downloader will use
582 * a "built-in" image library, local to this component, which should always contain the
583 * latest microcode for the NPEs.
585 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
586 * It will be removed in a future release.
587 * See @ref ixNpeDlCustomImageNpeInitAndStart.
590 * - <i>clientImageLibrary</i> should point to a microcode image library valid for use
591 * by the NPE Downloader component.
594 * - the client-supplied image library will be used for all subsequent operations
595 * performed by the NPE Downloader
598 * - IX_SUCCESS if the operation was successful
599 * - IX_NPEDL_PARAM_ERR if a parameter error occured
600 * - IX_FAIL if the client-supplied image library did not contain a valid signature
603 ixNpeDlMicrocodeImageLibraryOverride (UINT32 *clientImageLibrary);
608 * @fn PUBLIC IX_STATUS ixNpeDlImageDownload (IxNpeDlImageId *imageIdPtr,
611 * @brief Stop, reset, download microcode and finally start NPE.
613 * @param imageIdPtr @ref IxNpeDlImageId* [in] - Pointer to Id of the microcode
615 * @param verify BOOL [in] - ON/OFF option to verify the download. If ON
616 * (verify == true), the Downloader will read back
617 * each word written to the NPE registers to
618 * ensure the download operation was successful.
620 * Using the <i>imageIdPtr</i>, this function locates a particular image of
621 * microcode in the microcode image library in memory, and downloads the microcode
622 * to a particular NPE.
624 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
625 * It will be removed in a future release.
626 * See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
629 * - The Client is responsible for ensuring mutual access to the NPE.
630 * - The Client should use ixNpeDlLatestImageGet() to obtain the latest
631 * version of the image before attempting download.
633 * - The NPE Instruction Pipeline will be cleared if State Information
634 * has been downloaded.
635 * - If the download fails with a critical error, the NPE may
636 * be left in an ususable state.
638 * - IX_SUCCESS if the download was successful;
639 * - IX_NPEDL_PARAM_ERR if a parameter error occured
640 * - IX_NPEDL_CRITICAL_NPE_ERR if a critical NPE error occured during
642 * - IX_PARAM_CRITICAL_MICROCODE_ERR if a critical microcode error
643 * occured during download
644 * - IX_FAIL if NPE is not available or image is failed to be located.
645 * A warning is issued if the NPE is not present.
648 ixNpeDlImageDownload (IxNpeDlImageId *imageIdPtr,
654 * @fn PUBLIC IX_STATUS ixNpeDlAvailableImagesCountGet (UINT32 *numImagesPtr)
656 * @brief Get the number of Images available in a microcode image library
658 * @param numImagesPtr UINT32* [out] - A pointer to the number of images in
661 * Gets the number of images available in the microcode image library.
662 * Then returns this in a variable pointed to by <i>numImagesPtr</i>.
664 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
665 * It will be removed in a future release.
666 * See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
669 * - The Client should declare the variable to which numImagesPtr points
674 * - IX_SUCCESS if the operation was successful
675 * - IX_NPEDL_PARAM_ERR if a parameter error occured
676 * - IX_FAIL otherwise
679 ixNpeDlAvailableImagesCountGet (UINT32 *numImagesPtr);
684 * @fn PUBLIC IX_STATUS ixNpeDlAvailableImagesListGet (IxNpeDlImageId *imageIdListPtr,
687 * @brief Get a list of the images available in a microcode image library
689 * @param imageIdListPtr @ref IxNpeDlImageId* [out] - Array to contain list of
691 * allocated by Client).
692 * @param listSizePtr UINT32* [inout] - As an input, this param should point
693 * to the max number of Ids the
694 * <i>imageIdListPtr</i> array can
695 * hold. NpeDl will replace the input
696 * value of this parameter with the
697 * number of image Ids actually filled
698 * into the array before returning.
700 * Finds list of images available in the microcode image library.
701 * Fills these into the array pointed to by <i>imageIdListPtr</i>
703 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
704 * It will be removed in a future release.
705 * See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
708 * - The Client should declare the variable to which numImagesPtr points
709 * - The Client should create an array (<i>imageIdListPtr</i>) large
710 * enough to contain all the image Ids in the image library
715 * - IX_SUCCESS if the operation was successful
716 * - IX_NPEDL_PARAM_ERR if a parameter error occured
717 * - IX_FAIL otherwise
720 ixNpeDlAvailableImagesListGet (IxNpeDlImageId *imageIdListPtr,
721 UINT32 *listSizePtr);
726 * @fn PUBLIC IX_STATUS ixNpeDlLoadedImageGet (IxNpeDlNpeId npeId,
727 IxNpeDlImageId *imageIdPtr)
729 * @brief Gets the Id of the image currently loaded on a particular NPE
731 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE.
732 * @param imageIdPtr @ref IxNpeDlImageId* [out] - Pointer to the where the
733 * image id should be stored.
735 * If an image of microcode was previously downloaded successfully to the NPE
736 * by NPE Downloader, this function returns in <i>imageIdPtr</i> the image
737 * Id of that image loaded on the NPE.
740 * - The Client has allocated memory to the <i>imageIdPtr</i> pointer.
745 * - IX_SUCCESS if the operation was successful
746 * - IX_NPEDL_PARAM_ERR if a parameter error occured
747 * - IX_FAIL if the NPE doesn't currently have a image loaded
750 ixNpeDlLoadedImageGet (IxNpeDlNpeId npeId,
751 IxNpeDlImageId *imageIdPtr);
754 * @fn PUBLIC IX_STATUS ixNpeDlLatestImageGet (IxNpeDlNpeId npeId, IxNpeDlFunctionalityId
755 functionalityId, IxNpeDlImageId *imageIdPtr)
757 * @brief This instructs NPE Downloader to get Id of the latest version for an
758 * image that is specified by the client.
760 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE.
761 * @param functionalityId @ref IxNpeDlFunctionalityId [in] - functionality of the image
762 * @param imageIdPtr @ref IxNpeDlImageId* [out] - Pointer to the where the
763 * image id should be stored.
765 * This function sets NPE Downloader to return the id of the latest version for
766 * image. The user will select the image by providing a particular NPE
767 * (specifying <i>npeId</i>) with particular functionality (specifying
768 * <i>FunctionalityId</i>). The most recent version available as determined by the
769 * highest Major and Minor revision numbers is returned in <i>imageIdPtr</i>.
771 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
772 * It will be removed in a future release.
773 * See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
776 * - IX_SUCCESS if the operation was successful
777 * - IX_NPEDL_PARAM_ERR if a parameter error occured
778 * - IX_FAIL otherwise
781 ixNpeDlLatestImageGet (IxNpeDlNpeId npeId,
782 IxNpeDlFunctionalityId functionalityId,
783 IxNpeDlImageId *imageIdPtr);
788 * @fn PUBLIC IX_STATUS ixNpeDlNpeStopAndReset (IxNpeDlNpeId npeId)
790 * @brief Stops and Resets an NPE
792 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE.
794 * This function performs a soft NPE reset by writing reset values to
795 * particular NPE registers. Note that this does not reset NPE co-processors.
796 * This implicitly stops NPE code execution before resetting the NPE.
798 * @note It is no longer necessary to call this function before downloading
799 * a new image to the NPE. It is left on the API only to allow greater control
800 * of NPE execution if required. Where appropriate, use @ref ixNpeDlNpeInitAndStart
801 * or @ref ixNpeDlCustomImageNpeInitAndStart instead.
803 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
804 * It will be removed in a future release.
805 * See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
808 * - The Client is responsible for ensuring mutual access to the NPE.
813 * - IX_SUCCESS if the operation was successful
814 * - IX_NPEDL_PARAM_ERR if a parameter error occured
815 * - IX_FAIL otherwise
816 * - IX_NPEDL_CRITICAL_NPE_ERR failed to reset NPE due to timeout error.
817 * Timeout error could happen if NPE hang
820 ixNpeDlNpeStopAndReset (IxNpeDlNpeId npeId);
825 * @fn PUBLIC IX_STATUS ixNpeDlNpeExecutionStart (IxNpeDlNpeId npeId)
827 * @brief Starts code execution on a NPE
829 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE
831 * Starts execution of code on a particular NPE. A client would typically use
832 * this after a download to NPE is performed, to start/restart code execution
835 * @note It is no longer necessary to call this function after downloading
836 * a new image to the NPE. It is left on the API only to allow greater control
837 * of NPE execution if required. Where appropriate, use @ref ixNpeDlNpeInitAndStart
838 * or @ref ixNpeDlCustomImageNpeInitAndStart instead.
840 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
841 * It will be removed in a future release.
842 * See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
845 * - The Client is responsible for ensuring mutual access to the NPE.
846 * - Note that this function does not set the NPE Next Program Counter
847 * (NextPC), so it should be set beforehand if required by downloading
848 * appropriate State Information (using ixNpeDlVersionDownload()).
853 * - IX_SUCCESS if the operation was successful
854 * - IX_NPEDL_PARAM_ERR if a parameter error occured
855 * - IX_FAIL otherwise
858 ixNpeDlNpeExecutionStart (IxNpeDlNpeId npeId);
863 * @fn PUBLIC IX_STATUS ixNpeDlNpeExecutionStop (IxNpeDlNpeId npeId)
865 * @brief Stops code execution on a NPE
867 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE
869 * Stops execution of code on a particular NPE. This would typically be used
870 * by a client before a download to NPE is performed, to stop code execution on
871 * an NPE, unless ixNpeDlNpeStopAndReset() is used instead. Unlike
872 * ixNpeDlNpeStopAndReset(), this function only halts the NPE and leaves
873 * all registers and settings intact. This is useful, for example, between
874 * stages of a multi-stage download, to stop the NPE prior to downloading the
875 * next image while leaving the current state of the NPE intact..
877 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
878 * It will be removed in a future release.
879 * See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
882 * - The Client is responsible for ensuring mutual access to the NPE.
887 * - IX_SUCCESS if the operation was successful
888 * - IX_NPEDL_PARAM_ERR if a parameter error occured
889 * - IX_FAIL otherwise
892 ixNpeDlNpeExecutionStop (IxNpeDlNpeId npeId);
897 * @fn PUBLIC IX_STATUS ixNpeDlUnload (void)
899 * @brief This function will uninitialise the IxNpeDl component.
901 * This function will uninitialise the IxNpeDl component. It should only be
902 * called once, and only if the IxNpeDl component has already been initialised by
903 * calling any of the following functions:
904 * - @ref ixNpeDlNpeInitAndStart
905 * - @ref ixNpeDlCustomImageNpeInitAndStart
906 * - @ref ixNpeDlImageDownload (deprecated)
907 * - @ref ixNpeDlNpeStopAndReset (deprecated)
908 * - @ref ixNpeDlNpeExecutionStop (deprecated)
909 * - @ref ixNpeDlNpeExecutionStart (deprecated)
911 * If possible, this function should be called before a soft reboot or unloading
912 * a kernel module to perform any clean up operations required for IxNpeDl.
914 * The following actions will be performed by this function:
915 * - Unmapping of any kernel memory mapped by IxNpeDl
918 * - IX_SUCCESS if the operation was successful
919 * - IX_FAIL otherwise
923 ixNpeDlUnload (void);
928 * @fn PUBLIC void ixNpeDlStatsShow (void)
930 * @brief This function will display run-time statistics from the IxNpeDl
936 ixNpeDlStatsShow (void);
941 * @fn PUBLIC void ixNpeDlStatsReset (void)
943 * @brief This function will reset the statistics of the IxNpeDl component
948 ixNpeDlStatsReset (void);
950 #endif /* IXNPEDL_H */
953 * @} defgroup IxNpeDl