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 * Redistribution and use in source and binary forms, with or without
21 * modification, are permitted provided that the following conditions
23 * 1. Redistributions of source code must retain the above copyright
24 * notice, this list of conditions and the following disclaimer.
25 * 2. Redistributions in binary form must reproduce the above copyright
26 * notice, this list of conditions and the following disclaimer in the
27 * documentation and/or other materials provided with the distribution.
28 * 3. Neither the name of the Intel Corporation nor the names of its contributors
29 * may be used to endorse or promote products derived from this software
30 * without specific prior written permission.
33 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
34 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
35 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
36 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
37 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
38 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
39 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
40 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
41 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
42 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
46 * -- End of Copyright Notice --
50 * @defgroup IxNpeDl IXP400 NPE-Downloader (IxNpeDl) API
52 * @brief The Public API for the IXP400 NPE Downloader
61 * Put the user defined include files required
63 #include "IxOsalTypes.h"
64 #include "IxNpeMicrocode.h"
67 * #defines for function return types, etc.
71 * @def IX_NPEDL_PARAM_ERR
73 * @brief NpeDl function return value for a parameter error
75 #define IX_NPEDL_PARAM_ERR 2
78 * @def IX_NPEDL_RESOURCE_ERR
80 * @brief NpeDl function return value for a resource error
82 #define IX_NPEDL_RESOURCE_ERR 3
85 * @def IX_NPEDL_CRITICAL_NPE_ERR
87 * @brief NpeDl function return value for a Critical NPE error occuring during
88 download. Assume NPE is left in unstable condition if this value is
89 returned or NPE is hang / halt.
91 #define IX_NPEDL_CRITICAL_NPE_ERR 4
94 * @def IX_NPEDL_CRITICAL_MICROCODE_ERR
96 * @brief NpeDl function return value for a Critical Microcode error
97 * discovered during download. Assume NPE is left in unstable condition
98 * if this value is returned.
100 #define IX_NPEDL_CRITICAL_MICROCODE_ERR 5
103 * @def IX_NPEDL_DEVICE_ERR
105 * @brief NpeDl function return value when image being downloaded
106 * is not meant for the device in use
108 #define IX_NPEDL_DEVICE_ERR 6
111 * @defgroup NPEImageID IXP400 NPE Image ID Definition
115 * @brief Definition of NPE Image ID to be passed to ixNpeDlNpeInitAndStart()
116 * as input of type UINT32 which has the following fields format:
118 * Field [Bit Location] <BR>
119 * -------------------- <BR>
120 * Device ID [31 - 28] <BR>
121 * NPE ID [27 - 24] <BR>
122 * NPE Functionality ID [23 - 16] <BR>
123 * Major Release Number [15 - 8] <BR>
124 * Minor Release Number [7 - 0] <BR>
131 * @def IX_NPEDL_NPEIMAGE_FIELD_MASK
133 * @brief Mask for NPE Image ID's Field
135 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
136 * It will be removed in a future release.
137 * See @ref ixNpeDlNpeInitAndStart for more information.
139 #define IX_NPEDL_NPEIMAGE_FIELD_MASK 0xff
142 * @def IX_NPEDL_NPEIMAGE_NPEID_MASK
144 * @brief Mask for NPE Image NPE ID's Field
147 #define IX_NPEDL_NPEIMAGE_NPEID_MASK 0xf
150 * @def IX_NPEDL_NPEIMAGE_DEVICEID_MASK
152 * @brief Mask for NPE Image Device ID's Field
155 #define IX_NPEDL_NPEIMAGE_DEVICEID_MASK 0xf
158 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_NPEID
160 * @brief Location of NPE ID field in term of bit.
162 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
163 * It will be removed in a future release.
164 * See @ref ixNpeDlNpeInitAndStart for more information.
166 #define IX_NPEDL_NPEIMAGE_BIT_LOC_NPEID 24
169 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_FUNCTIONALITYID
171 * @brief Location of Functionality ID field in term of bit.
173 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
174 * It will be removed in a future release.
175 * See @ref ixNpeDlNpeInitAndStart for more information.
177 #define IX_NPEDL_NPEIMAGE_BIT_LOC_FUNCTIONALITYID 16
180 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_MAJOR
182 * @brief Location of Major Release Number field in term of bit.
184 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
185 * It will be removed in a future release.
186 * See @ref ixNpeDlNpeInitAndStart for more information.
188 #define IX_NPEDL_NPEIMAGE_BIT_LOC_MAJOR 8
191 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_MINOR
193 * @brief Location of Minor Release Number field in term of bit.
195 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
196 * It will be removed in a future release.
197 * See @ref ixNpeDlNpeInitAndStart for more information.
199 #define IX_NPEDL_NPEIMAGE_BIT_LOC_MINOR 0
202 * @} addtogroup NPEImageID
206 * @def ixNpeDlMicrocodeImageOverride(x)
208 * @brief Map old terminology that uses term "image" 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 ixNpeDlMicrocodeImageOverride(x) ixNpeDlMicrocodeImageLibraryOverride(x)
218 * @def IxNpeDlVersionId
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 IxNpeDlVersionId IxNpeDlImageId
230 * @def ixNpeDlVersionDownload
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 ixNpeDlVersionDownload(x,y) ixNpeDlImageDownload(x,y)
242 * @def ixNpeDlAvailableVersionsCountGet
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 ixNpeDlAvailableVersionsCountGet(x) ixNpeDlAvailableImagesCountGet(x)
254 * @def ixNpeDlAvailableVersionsListGet
256 * @brief Map old terminology that uses term "version" 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 ixNpeDlAvailableVersionsListGet(x,y) ixNpeDlAvailableImagesListGet(x,y)
266 * @def ixNpeDlLoadedVersionGet
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 ixNpeDlLoadedVersionGet(x,y) ixNpeDlLoadedImageGet(x,y)
280 * @brief Map old terminology that uses term "image" 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 clientImage clientImageLibrary
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 versionIdPtr imageIdPtr
302 * @def numVersionsPtr
304 * @brief Map old terminology that uses term "version" 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 numVersionsPtr numImagesPtr
314 * @def versionIdListPtr
316 * @brief Map old terminology that uses term "version" 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 versionIdListPtr imageIdListPtr
326 * @def IxNpeDlBuildId
328 * @brief Map old terminology that uses term "buildId" 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 IxNpeDlBuildId IxNpeDlFunctionalityId
340 * @brief Map old terminology that uses term "buildId" to new term
343 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
344 * It will be removed in a future release.
345 * See @ref ixNpeDlNpeInitAndStart for more information.
347 #define buildId functionalityId
350 * @def IX_NPEDL_MicrocodeImage
352 * @brief Map old terminology that uses term "image" to new term
355 * @warning <b>THIS #define 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 #define IX_NPEDL_MicrocodeImage IX_NPEDL_MicrocodeImageLibrary
366 * @typedef IxNpeDlFunctionalityId
367 * @brief Used to make up Functionality ID field of Image Id
369 * @warning <b>THIS typedef HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
370 * It will be removed in a future release.
371 * See @ref ixNpeDlNpeInitAndStart for more information.
373 typedef UINT8 IxNpeDlFunctionalityId;
376 * @typedef IxNpeDlMajor
377 * @brief Used to make up Major Release field of Image Id
379 * @warning <b>THIS typedef HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
380 * It will be removed in a future release.
381 * See @ref ixNpeDlNpeInitAndStart for more information.
383 typedef UINT8 IxNpeDlMajor;
386 * @typedef IxNpeDlMinor
387 * @brief Used to make up Minor Revision field of Image Id
389 * @warning <b>THIS typedef HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
390 * It will be removed in a future release.
391 * See @ref ixNpeDlNpeInitAndStart for more information.
393 typedef UINT8 IxNpeDlMinor;
400 * @brief NpeId numbers to identify NPE A, B or C
401 * @note In this context, for IXP425 Silicon (B0):<br>
402 * - NPE-A has HDLC, HSS, AAL and UTOPIA Coprocessors.<br>
403 * - NPE-B has Ethernet Coprocessor.<br>
404 * - NPE-C has Ethernet, AES, DES and HASH Coprocessors.<br>
405 * - IXP400 Product Line have different combinations of coprocessors.
409 IX_NPEDL_NPEID_NPEA = 0, /**< Identifies NPE A */
410 IX_NPEDL_NPEID_NPEB, /**< Identifies NPE B */
411 IX_NPEDL_NPEID_NPEC, /**< Identifies NPE C */
412 IX_NPEDL_NPEID_MAX /**< Total Number of NPEs */
420 * @brief Image Id to identify each image contained in an image library
422 * @warning <b>THIS struct HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
423 * It will be removed in a future release.
424 * See @ref ixNpeDlNpeInitAndStart for more information.
428 IxNpeDlNpeId npeId; /**< NPE ID */
429 IxNpeDlFunctionalityId functionalityId; /**< Build ID indicates functionality of image */
430 IxNpeDlMajor major; /**< Major Release Number */
431 IxNpeDlMinor minor; /**< Minor Revision Number */
435 * Prototypes for interface functions
441 * @fn PUBLIC IX_STATUS ixNpeDlNpeInitAndStart (UINT32 imageId)
443 * @brief Stop, reset, download microcode (firmware) and finally start NPE.
445 * @param imageId UINT32 [in] - Id of the microcode image to download.
447 * This function locates the image specified by the <i>imageId</i> parameter
448 * from the default microcode image library which is included internally by
450 * It then stops and resets the NPE, loads the firmware image onto the NPE,
451 * and then restarts the NPE.
453 * @note A list of valid image IDs is included in this header file.
454 * See #defines with prefix IX_NPEDL_NPEIMAGE_...
456 * @note This function, along with @ref ixNpeDlCustomImageNpeInitAndStart
457 * and @ref ixNpeDlLoadedImageFunctionalityGet, supercedes the following
458 * functions which are deprecated and will be removed completely in a
460 * - @ref ixNpeDlImageDownload
461 * - @ref ixNpeDlAvailableImagesCountGet
462 * - @ref ixNpeDlAvailableImagesListGet
463 * - @ref ixNpeDlLatestImageGet
464 * - @ref ixNpeDlLoadedImageGet
465 * - @ref ixNpeDlMicrocodeImageLibraryOverride
466 * - @ref ixNpeDlNpeExecutionStop
467 * - @ref ixNpeDlNpeStopAndReset
468 * - @ref ixNpeDlNpeExecutionStart
471 * - The Client is responsible for ensuring mutual access to the NPE.
473 * - The NPE Instruction Pipeline will be cleared if State Information
474 * has been downloaded.
475 * - If the download fails with a critical error, the NPE may
476 * be left in an ususable state.
478 * - IX_SUCCESS if the download was successful;
479 * - IX_NPEDL_PARAM_ERR if a parameter error occured
480 * - IX_NPEDL_CRITICAL_NPE_ERR if a critical NPE error occured during
482 * - IX_NPEDL_CRITICAL_MICROCODE_ERR if a critical microcode error
483 * occured during download
484 * - IX_NPEDL_DEVICE_ERR if the image being loaded is not meant for
485 * the device currently running.
486 * - IX_FAIL if NPE is not available or image is failed to be located.
487 * A warning is issued if the NPE is not present.
490 ixNpeDlNpeInitAndStart (UINT32 npeImageId);
495 * @fn PUBLIC IX_STATUS ixNpeDlCustomImageNpeInitAndStart (UINT32 *imageLibrary,
498 * @brief Stop, reset, download microcode (firmware) and finally start NPE
500 * @param imageId UINT32 [in] - Id of the microcode image to download.
502 * This function locates the image specified by the <i>imageId</i> parameter
503 * from the specified microcode image library which is pointed to by the
504 * <i>imageLibrary</i> parameter.
505 * It then stops and resets the NPE, loads the firmware image onto the NPE,
506 * and then restarts the NPE.
508 * This is a facility for users who wish to use an image from an external
509 * library of NPE firmware images. To use a standard image from the
510 * built-in library, see @ref ixNpeDlNpeInitAndStart instead.
512 * @note A list of valid image IDs is included in this header file.
513 * See #defines with prefix IX_NPEDL_NPEIMAGE_...
515 * @note This function, along with @ref ixNpeDlNpeInitAndStart
516 * and @ref ixNpeDlLoadedImageFunctionalityGet, supercedes the following
517 * functions which are deprecated and will be removed completely in a
519 * - @ref ixNpeDlImageDownload
520 * - @ref ixNpeDlAvailableImagesCountGet
521 * - @ref ixNpeDlAvailableImagesListGet
522 * - @ref ixNpeDlLatestImageGet
523 * - @ref ixNpeDlLoadedImageGet
524 * - @ref ixNpeDlMicrocodeImageLibraryOverride
525 * - @ref ixNpeDlNpeExecutionStop
526 * - @ref ixNpeDlNpeStopAndReset
527 * - @ref ixNpeDlNpeExecutionStart
530 * - The Client is responsible for ensuring mutual access to the NPE.
531 * - The image library supplied must be in the correct format for use
532 * by the NPE Downloader (IxNpeDl) component. Details of the library
533 * format are contained in the Functional Specification document for
536 * - The NPE Instruction Pipeline will be cleared if State Information
537 * has been downloaded.
538 * - If the download fails with a critical error, the NPE may
539 * be left in an ususable state.
541 * - IX_SUCCESS if the download was successful;
542 * - IX_NPEDL_PARAM_ERR if a parameter error occured
543 * - IX_NPEDL_CRITICAL_NPE_ERR if a critical NPE error occured during
545 * - IX_NPEDL_CRITICAL_MICROCODE_ERR if a critical microcode error
546 * occured during download
547 * - IX_NPEDL_DEVICE_ERR if the image being loaded is not meant for
548 * the device currently running.
549 * - IX_FAIL if NPE is not available or image is failed to be located.
550 * A warning is issued if the NPE is not present.
553 ixNpeDlCustomImageNpeInitAndStart (UINT32 *imageLibrary,
560 * @fn PUBLIC IX_STATUS ixNpeDlLoadedImageFunctionalityGet (IxNpeDlNpeId npeId,
561 UINT8 *functionalityId)
563 * @brief Gets the functionality of the image last loaded on a particular NPE
565 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE.
566 * @param functionalityId UINT8* [out] - the functionality ID of the image
567 * last loaded on the NPE.
569 * This function retrieves the functionality ID of the image most recently
570 * downloaded successfully to the specified NPE. If the NPE does not contain
571 * a valid image, this function returns a FAIL status.
573 * @warning This function is not intended for general use, as a knowledge of
574 * how to interpret the functionality ID is required. As such, this function
575 * should only be used by other Access Layer components of the IXP400 Software
583 * - IX_SUCCESS if the operation was successful
584 * - IX_NPEDL_PARAM_ERR if a parameter error occured
585 * - IX_FAIL if the NPE does not have a valid image loaded
588 ixNpeDlLoadedImageFunctionalityGet (IxNpeDlNpeId npeId,
589 UINT8 *functionalityId);
595 * @fn IX_STATUS ixNpeDlMicrocodeImageLibraryOverride (UINT32 *clientImageLibrary)
597 * @brief This instructs NPE Downloader to use client-supplied microcode image library.
599 * @param clientImageLibrary UINT32* [in] - Pointer to the client-supplied
600 * NPE microcode image library
602 * This function sets NPE Downloader to use a client-supplied microcode image library
603 * instead of the standard image library which is included by the NPE Downloader.
604 * <b>This function is provided mainly for increased testability and should not
605 * be used in normal circumstances.</b> When not used, NPE Downloader will use
606 * a "built-in" image library, local to this component, which should always contain the
607 * latest microcode for the NPEs.
609 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
610 * It will be removed in a future release.
611 * See @ref ixNpeDlCustomImageNpeInitAndStart.
614 * - <i>clientImageLibrary</i> should point to a microcode image library valid for use
615 * by the NPE Downloader component.
618 * - the client-supplied image library will be used for all subsequent operations
619 * performed by the NPE Downloader
622 * - IX_SUCCESS if the operation was successful
623 * - IX_NPEDL_PARAM_ERR if a parameter error occured
624 * - IX_FAIL if the client-supplied image library did not contain a valid signature
627 ixNpeDlMicrocodeImageLibraryOverride (UINT32 *clientImageLibrary);
632 * @fn PUBLIC IX_STATUS ixNpeDlImageDownload (IxNpeDlImageId *imageIdPtr,
635 * @brief Stop, reset, download microcode and finally start NPE.
637 * @param imageIdPtr @ref IxNpeDlImageId* [in] - Pointer to Id of the microcode
639 * @param verify BOOL [in] - ON/OFF option to verify the download. If ON
640 * (verify == TRUE), the Downloader will read back
641 * each word written to the NPE registers to
642 * ensure the download operation was successful.
644 * Using the <i>imageIdPtr</i>, this function locates a particular image of
645 * microcode in the microcode image library in memory, and downloads the microcode
646 * to a particular NPE.
648 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
649 * It will be removed in a future release.
650 * See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
653 * - The Client is responsible for ensuring mutual access to the NPE.
654 * - The Client should use ixNpeDlLatestImageGet() to obtain the latest
655 * version of the image before attempting download.
657 * - The NPE Instruction Pipeline will be cleared if State Information
658 * has been downloaded.
659 * - If the download fails with a critical error, the NPE may
660 * be left in an ususable state.
662 * - IX_SUCCESS if the download was successful;
663 * - IX_NPEDL_PARAM_ERR if a parameter error occured
664 * - IX_NPEDL_CRITICAL_NPE_ERR if a critical NPE error occured during
666 * - IX_PARAM_CRITICAL_MICROCODE_ERR if a critical microcode error
667 * occured during download
668 * - IX_FAIL if NPE is not available or image is failed to be located.
669 * A warning is issued if the NPE is not present.
672 ixNpeDlImageDownload (IxNpeDlImageId *imageIdPtr,
678 * @fn PUBLIC IX_STATUS ixNpeDlAvailableImagesCountGet (UINT32 *numImagesPtr)
680 * @brief Get the number of Images available in a microcode image library
682 * @param numImagesPtr UINT32* [out] - A pointer to the number of images in
685 * Gets the number of images available in the microcode image library.
686 * Then returns this in a variable pointed to by <i>numImagesPtr</i>.
688 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
689 * It will be removed in a future release.
690 * See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
693 * - The Client should declare the variable to which numImagesPtr points
698 * - IX_SUCCESS if the operation was successful
699 * - IX_NPEDL_PARAM_ERR if a parameter error occured
700 * - IX_FAIL otherwise
703 ixNpeDlAvailableImagesCountGet (UINT32 *numImagesPtr);
708 * @fn PUBLIC IX_STATUS ixNpeDlAvailableImagesListGet (IxNpeDlImageId *imageIdListPtr,
711 * @brief Get a list of the images available in a microcode image library
713 * @param imageIdListPtr @ref IxNpeDlImageId* [out] - Array to contain list of
715 * allocated by Client).
716 * @param listSizePtr UINT32* [inout] - As an input, this param should point
717 * to the max number of Ids the
718 * <i>imageIdListPtr</i> array can
719 * hold. NpeDl will replace the input
720 * value of this parameter with the
721 * number of image Ids actually filled
722 * into the array before returning.
724 * Finds list of images available in the microcode image library.
725 * Fills these into the array pointed to by <i>imageIdListPtr</i>
727 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
728 * It will be removed in a future release.
729 * See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
732 * - The Client should declare the variable to which numImagesPtr points
733 * - The Client should create an array (<i>imageIdListPtr</i>) large
734 * enough to contain all the image Ids in the image library
739 * - IX_SUCCESS if the operation was successful
740 * - IX_NPEDL_PARAM_ERR if a parameter error occured
741 * - IX_FAIL otherwise
744 ixNpeDlAvailableImagesListGet (IxNpeDlImageId *imageIdListPtr,
745 UINT32 *listSizePtr);
750 * @fn PUBLIC IX_STATUS ixNpeDlLoadedImageGet (IxNpeDlNpeId npeId,
751 IxNpeDlImageId *imageIdPtr)
753 * @brief Gets the Id of the image currently loaded on a particular NPE
755 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE.
756 * @param imageIdPtr @ref IxNpeDlImageId* [out] - Pointer to the where the
757 * image id should be stored.
759 * If an image of microcode was previously downloaded successfully to the NPE
760 * by NPE Downloader, this function returns in <i>imageIdPtr</i> the image
761 * Id of that image loaded on the NPE.
764 * - The Client has allocated memory to the <i>imageIdPtr</i> pointer.
769 * - IX_SUCCESS if the operation was successful
770 * - IX_NPEDL_PARAM_ERR if a parameter error occured
771 * - IX_FAIL if the NPE doesn't currently have a image loaded
774 ixNpeDlLoadedImageGet (IxNpeDlNpeId npeId,
775 IxNpeDlImageId *imageIdPtr);
778 * @fn PUBLIC IX_STATUS ixNpeDlLatestImageGet (IxNpeDlNpeId npeId, IxNpeDlFunctionalityId
779 functionalityId, IxNpeDlImageId *imageIdPtr)
781 * @brief This instructs NPE Downloader to get Id of the latest version for an
782 * image that is specified by the client.
784 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE.
785 * @param functionalityId @ref IxNpeDlFunctionalityId [in] - functionality of the image
786 * @param imageIdPtr @ref IxNpeDlImageId* [out] - Pointer to the where the
787 * image id should be stored.
789 * This function sets NPE Downloader to return the id of the latest version for
790 * image. The user will select the image by providing a particular NPE
791 * (specifying <i>npeId</i>) with particular functionality (specifying
792 * <i>FunctionalityId</i>). The most recent version available as determined by the
793 * highest Major and Minor revision numbers is returned in <i>imageIdPtr</i>.
795 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
796 * It will be removed in a future release.
797 * See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
800 * - IX_SUCCESS if the operation was successful
801 * - IX_NPEDL_PARAM_ERR if a parameter error occured
802 * - IX_FAIL otherwise
805 ixNpeDlLatestImageGet (IxNpeDlNpeId npeId,
806 IxNpeDlFunctionalityId functionalityId,
807 IxNpeDlImageId *imageIdPtr);
812 * @fn PUBLIC IX_STATUS ixNpeDlNpeStopAndReset (IxNpeDlNpeId npeId)
814 * @brief Stops and Resets an NPE
816 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE.
818 * This function performs a soft NPE reset by writing reset values to
819 * particular NPE registers. Note that this does not reset NPE co-processors.
820 * This implicitly stops NPE code execution before resetting the NPE.
822 * @note It is no longer necessary to call this function before downloading
823 * a new image to the NPE. It is left on the API only to allow greater control
824 * of NPE execution if required. Where appropriate, use @ref ixNpeDlNpeInitAndStart
825 * or @ref ixNpeDlCustomImageNpeInitAndStart instead.
827 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
828 * It will be removed in a future release.
829 * See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
832 * - The Client is responsible for ensuring mutual access to the NPE.
837 * - IX_SUCCESS if the operation was successful
838 * - IX_NPEDL_PARAM_ERR if a parameter error occured
839 * - IX_FAIL otherwise
840 * - IX_NPEDL_CRITICAL_NPE_ERR failed to reset NPE due to timeout error.
841 * Timeout error could happen if NPE hang
844 ixNpeDlNpeStopAndReset (IxNpeDlNpeId npeId);
849 * @fn PUBLIC IX_STATUS ixNpeDlNpeExecutionStart (IxNpeDlNpeId npeId)
851 * @brief Starts code execution on a NPE
853 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE
855 * Starts execution of code on a particular NPE. A client would typically use
856 * this after a download to NPE is performed, to start/restart code execution
859 * @note It is no longer necessary to call this function after downloading
860 * a new image to the NPE. It is left on the API only to allow greater control
861 * of NPE execution if required. Where appropriate, use @ref ixNpeDlNpeInitAndStart
862 * or @ref ixNpeDlCustomImageNpeInitAndStart instead.
864 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
865 * It will be removed in a future release.
866 * See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
869 * - The Client is responsible for ensuring mutual access to the NPE.
870 * - Note that this function does not set the NPE Next Program Counter
871 * (NextPC), so it should be set beforehand if required by downloading
872 * appropriate State Information (using ixNpeDlVersionDownload()).
877 * - IX_SUCCESS if the operation was successful
878 * - IX_NPEDL_PARAM_ERR if a parameter error occured
879 * - IX_FAIL otherwise
882 ixNpeDlNpeExecutionStart (IxNpeDlNpeId npeId);
887 * @fn PUBLIC IX_STATUS ixNpeDlNpeExecutionStop (IxNpeDlNpeId npeId)
889 * @brief Stops code execution on a NPE
891 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE
893 * Stops execution of code on a particular NPE. This would typically be used
894 * by a client before a download to NPE is performed, to stop code execution on
895 * an NPE, unless ixNpeDlNpeStopAndReset() is used instead. Unlike
896 * ixNpeDlNpeStopAndReset(), this function only halts the NPE and leaves
897 * all registers and settings intact. This is useful, for example, between
898 * stages of a multi-stage download, to stop the NPE prior to downloading the
899 * next image while leaving the current state of the NPE intact..
901 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
902 * It will be removed in a future release.
903 * See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
906 * - The Client is responsible for ensuring mutual access to the NPE.
911 * - IX_SUCCESS if the operation was successful
912 * - IX_NPEDL_PARAM_ERR if a parameter error occured
913 * - IX_FAIL otherwise
916 ixNpeDlNpeExecutionStop (IxNpeDlNpeId npeId);
921 * @fn PUBLIC IX_STATUS ixNpeDlUnload (void)
923 * @brief This function will uninitialise the IxNpeDl component.
925 * This function will uninitialise the IxNpeDl component. It should only be
926 * called once, and only if the IxNpeDl component has already been initialised by
927 * calling any of the following functions:
928 * - @ref ixNpeDlNpeInitAndStart
929 * - @ref ixNpeDlCustomImageNpeInitAndStart
930 * - @ref ixNpeDlImageDownload (deprecated)
931 * - @ref ixNpeDlNpeStopAndReset (deprecated)
932 * - @ref ixNpeDlNpeExecutionStop (deprecated)
933 * - @ref ixNpeDlNpeExecutionStart (deprecated)
935 * If possible, this function should be called before a soft reboot or unloading
936 * a kernel module to perform any clean up operations required for IxNpeDl.
938 * The following actions will be performed by this function:
939 * - Unmapping of any kernel memory mapped by IxNpeDl
942 * - IX_SUCCESS if the operation was successful
943 * - IX_FAIL otherwise
947 ixNpeDlUnload (void);
952 * @fn PUBLIC void ixNpeDlStatsShow (void)
954 * @brief This function will display run-time statistics from the IxNpeDl
960 ixNpeDlStatsShow (void);
965 * @fn PUBLIC void ixNpeDlStatsReset (void)
967 * @brief This function will reset the statistics of the IxNpeDl component
972 ixNpeDlStatsReset (void);
974 #endif /* IXNPEDL_H */
977 * @} defgroup IxNpeDl