source: SVN/rincon/u-boot/cpu/ixp/npe/include/IxNpeDl.h @ 55

Last change on this file since 55 was 55, checked in by Tim Harvey, 22 months ago

rincon: added latest u-boot source

restored form server backup

Signed-off-by: Tim Harvey <tharvey@…>

File size: 33.5 KB
Line 
1/**
2 * @file IxNpeDl.h
3 *
4 * @date 14 December 2001
5
6 * @brief This file contains the public API of the IXP400 NPE Downloader
7 *        component.
8 *
9 *
10 * @par
11 * IXP400 SW Release version 2.0
12 *
13 * -- Copyright Notice --
14 *
15 * @par
16 * Copyright 2001-2005, Intel Corporation.
17 * All rights reserved.
18 *
19 * @par
20 * Redistribution and use in source and binary forms, with or without
21 * modification, are permitted provided that the following conditions
22 * are met:
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.
31 *
32 * @par
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
43 * SUCH DAMAGE.
44 *
45 * @par
46 * -- End of Copyright Notice --
47*/
48
49/**
50 * @defgroup IxNpeDl IXP400 NPE-Downloader (IxNpeDl) API
51 *
52 * @brief The Public API for the IXP400 NPE Downloader
53 *
54 * @{
55 */
56
57#ifndef IXNPEDL_H
58#define IXNPEDL_H
59
60/*
61 * Put the user defined include files required
62 */
63#include "IxOsalTypes.h"
64#include "IxNpeMicrocode.h"
65
66/*
67 * #defines for function return types, etc.
68 */
69
70/**
71 * @def IX_NPEDL_PARAM_ERR
72 *
73 * @brief NpeDl function return value for a parameter error
74 */
75#define IX_NPEDL_PARAM_ERR               2
76
77/**
78 * @def IX_NPEDL_RESOURCE_ERR
79 *
80 * @brief NpeDl function return value for a resource error
81 */
82#define IX_NPEDL_RESOURCE_ERR            3
83
84/**
85 * @def IX_NPEDL_CRITICAL_NPE_ERR
86 *
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.
90 */
91#define IX_NPEDL_CRITICAL_NPE_ERR        4
92
93/**
94 * @def IX_NPEDL_CRITICAL_MICROCODE_ERR
95 *
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.
99 */
100#define IX_NPEDL_CRITICAL_MICROCODE_ERR  5
101
102/**
103 * @def IX_NPEDL_DEVICE_ERR
104 *
105 * @brief NpeDl function return value when image being downloaded
106 *        is not meant for the device in use
107 */
108#define IX_NPEDL_DEVICE_ERR 6
109
110/**
111 * @defgroup NPEImageID IXP400 NPE Image ID Definition
112 *
113 * @ingroup IxNpeDl
114 *
115 * @brief Definition of NPE Image ID to be passed to ixNpeDlNpeInitAndStart()
116 *        as input of type UINT32 which has the following fields format:
117 *
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>
125 *
126 *
127 * @{
128 */
129
130/**
131 * @def IX_NPEDL_NPEIMAGE_FIELD_MASK
132 *
133 * @brief Mask for NPE Image ID's Field
134 *
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.
138 */
139#define IX_NPEDL_NPEIMAGE_FIELD_MASK  0xff
140
141/**
142 * @def IX_NPEDL_NPEIMAGE_NPEID_MASK
143 *
144 * @brief Mask for NPE Image NPE ID's Field
145 *
146 */
147#define IX_NPEDL_NPEIMAGE_NPEID_MASK  0xf
148
149/**
150 * @def IX_NPEDL_NPEIMAGE_DEVICEID_MASK
151 *
152 * @brief Mask for NPE Image Device ID's Field
153 *
154 */
155#define IX_NPEDL_NPEIMAGE_DEVICEID_MASK  0xf
156
157/**
158 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_NPEID
159 *
160 * @brief Location of NPE ID field in term of bit.
161 *
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.
165 */
166#define IX_NPEDL_NPEIMAGE_BIT_LOC_NPEID  24
167
168/**
169 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_FUNCTIONALITYID
170 *
171 * @brief Location of Functionality ID field in term of bit.
172 *
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.
176 */
177#define IX_NPEDL_NPEIMAGE_BIT_LOC_FUNCTIONALITYID  16
178
179/**
180 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_MAJOR
181 *
182 * @brief Location of Major Release Number field in term of bit.
183 *
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.
187 */
188#define IX_NPEDL_NPEIMAGE_BIT_LOC_MAJOR  8
189
190/**
191 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_MINOR
192 *
193 * @brief Location of Minor Release Number field in term of bit.
194 *
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.
198 */
199#define IX_NPEDL_NPEIMAGE_BIT_LOC_MINOR  0
200
201/**
202 * @} addtogroup NPEImageID
203 */
204
205/**
206 * @def ixNpeDlMicrocodeImageOverride(x)
207 *
208 * @brief  Map old terminology that uses term "image" to new term
209 *        "image library"
210 *
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.
214 */
215#define ixNpeDlMicrocodeImageOverride(x) ixNpeDlMicrocodeImageLibraryOverride(x)
216
217/**
218 * @def IxNpeDlVersionId
219 *
220 * @brief  Map old terminology that uses term "version" to new term
221 *        "image"
222 *
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.
226 */
227#define IxNpeDlVersionId IxNpeDlImageId
228
229/**
230 * @def ixNpeDlVersionDownload
231 *
232 * @brief  Map old terminology that uses term "version" to new term
233 *        "image"
234 *
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.
238 */
239#define ixNpeDlVersionDownload(x,y) ixNpeDlImageDownload(x,y)
240
241/**
242 * @def ixNpeDlAvailableVersionsCountGet
243 *
244 * @brief  Map old terminology that uses term "version" to new term
245 *        "image"
246 *
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.
250 */
251#define ixNpeDlAvailableVersionsCountGet(x) ixNpeDlAvailableImagesCountGet(x)
252
253/**
254 * @def ixNpeDlAvailableVersionsListGet
255 *
256 * @brief  Map old terminology that uses term "version" to new term
257 *        "image"
258 *
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.
262 */
263#define ixNpeDlAvailableVersionsListGet(x,y) ixNpeDlAvailableImagesListGet(x,y)
264
265 /**
266 * @def ixNpeDlLoadedVersionGet
267 *
268 * @brief  Map old terminology that uses term "version" to new term
269 *        "image"
270 *
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.
274 */
275#define ixNpeDlLoadedVersionGet(x,y) ixNpeDlLoadedImageGet(x,y)
276
277 /**
278 * @def clientImage
279 *
280 * @brief  Map old terminology that uses term "image" to new term
281 *        "image library"
282 *
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.
286 */
287#define clientImage clientImageLibrary
288
289 /**
290 * @def versionIdPtr
291 *
292 * @brief  Map old terminology that uses term "version" to new term
293 *        "image"
294 *
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.
298 */
299#define versionIdPtr imageIdPtr
300
301 /**
302 * @def numVersionsPtr
303 *
304 * @brief  Map old terminology that uses term "version" to new term
305 *        "image"
306 *
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.
310 */
311#define numVersionsPtr numImagesPtr
312
313/**
314 * @def versionIdListPtr
315 *
316 * @brief  Map old terminology that uses term "version" to new term
317 *        "image"
318 *
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.
322 */
323#define versionIdListPtr imageIdListPtr
324
325/**
326 * @def IxNpeDlBuildId
327 *
328 * @brief  Map old terminology that uses term "buildId" to new term
329 *        "functionalityId"
330 *
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.
334 */
335#define IxNpeDlBuildId IxNpeDlFunctionalityId
336
337/**
338 * @def buildId
339 *
340 * @brief  Map old terminology that uses term "buildId" to new term
341 *        "functionalityId"
342 *
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.
346 */
347#define buildId functionalityId
348
349/**
350 * @def IX_NPEDL_MicrocodeImage
351 *
352 * @brief  Map old terminology that uses term "image" to new term
353 *        "image library"
354 *
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.
358 */
359#define IX_NPEDL_MicrocodeImage IX_NPEDL_MicrocodeImageLibrary
360
361/*
362 * Typedefs
363 */
364
365/**
366 * @typedef IxNpeDlFunctionalityId
367 * @brief Used to make up Functionality ID field of Image Id
368 *
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.
372 */
373typedef UINT8 IxNpeDlFunctionalityId;
374
375/**
376 * @typedef IxNpeDlMajor
377 * @brief Used to make up Major Release field of Image Id
378 *
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.
382 */
383typedef UINT8 IxNpeDlMajor;
384
385/**
386 * @typedef IxNpeDlMinor
387 * @brief Used to make up Minor Revision field of Image Id
388 *
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.
392 */
393typedef UINT8 IxNpeDlMinor;
394
395/*
396 * Enums
397 */
398
399/**
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.
406 */
407typedef enum
408{
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 */
413} IxNpeDlNpeId;
414
415/*
416 * Structs
417 */
418
419/**
420 * @brief Image Id to identify each image contained in an image library
421 *
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.
425 */
426typedef struct
427{
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 */
432} IxNpeDlImageId;
433
434/*
435 * Prototypes for interface functions
436 */
437
438/**
439 * @ingroup IxNpeDl
440 *
441 * @fn PUBLIC IX_STATUS ixNpeDlNpeInitAndStart (UINT32 imageId)
442 *
443 * @brief Stop, reset, download microcode (firmware) and finally start NPE.
444 *
445 * @param imageId UINT32 [in] - Id of the microcode image to download.
446 *
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
449 * this component.
450 * It then stops and resets the NPE, loads the firmware image onto the NPE,
451 * and then restarts the NPE.
452 *
453 * @note A list of valid image IDs is included in this header file.
454 *       See #defines with prefix IX_NPEDL_NPEIMAGE_...
455 *
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
459 *       future release:
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
469 *
470 * @pre
471 *         - The Client is responsible for ensuring mutual access to the NPE.
472 * @post
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.
477 * @return
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
481 *           download
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.
488 */
489PUBLIC IX_STATUS
490ixNpeDlNpeInitAndStart (UINT32 npeImageId);
491
492/**
493 * @ingroup IxNpeDl
494 *
495 * @fn PUBLIC IX_STATUS ixNpeDlCustomImageNpeInitAndStart (UINT32 *imageLibrary,
496                                                           UINT32 imageId)
497 *
498 * @brief Stop, reset, download microcode (firmware) and finally start NPE
499 *
500 * @param imageId UINT32 [in] - Id of the microcode image to download.
501 *
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.
507 *
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.
511 *
512 * @note A list of valid image IDs is included in this header file.
513 *       See #defines with prefix IX_NPEDL_NPEIMAGE_...
514 *
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
518 *       future release:
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
528 *
529 * @pre
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
534 *           IxNpeDl.
535 * @post
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.
540 * @return
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
544 *           download
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.
551 */
552PUBLIC IX_STATUS
553ixNpeDlCustomImageNpeInitAndStart (UINT32 *imageLibrary,
554                    UINT32 npeImageId);
555
556
557/**
558 * @ingroup IxNpeDl
559 *
560 * @fn PUBLIC IX_STATUS ixNpeDlLoadedImageFunctionalityGet (IxNpeDlNpeId npeId,
561                                                        UINT8 *functionalityId)
562 *
563 * @brief Gets the functionality of the image last loaded on a particular NPE
564 *
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.
568 *
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.
572 *
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
576 * Release.
577 *
578 * @pre
579 *
580 * @post
581 *
582 * @return
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
586 */
587PUBLIC IX_STATUS
588ixNpeDlLoadedImageFunctionalityGet (IxNpeDlNpeId npeId,
589                                    UINT8 *functionalityId);
590
591
592/**
593 * @ingroup IxNpeDl
594 *
595 * @fn IX_STATUS ixNpeDlMicrocodeImageLibraryOverride (UINT32 *clientImageLibrary)
596 *
597 * @brief This instructs NPE Downloader to use client-supplied microcode image library.
598 *
599 * @param clientImageLibrary UINT32* [in]  - Pointer to the client-supplied
600 *                                   NPE microcode image library
601 *
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.
608 *
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.
612 *
613 * @pre
614 *      - <i>clientImageLibrary</i> should point to a microcode image library valid for use
615 *        by the NPE Downloader component.
616 *
617 * @post
618 *      - the client-supplied image library will be used for all subsequent operations
619 *        performed by the NPE Downloader
620 *
621 * @return
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
625 */
626PUBLIC IX_STATUS
627ixNpeDlMicrocodeImageLibraryOverride (UINT32 *clientImageLibrary);
628
629/**
630 * @ingroup IxNpeDl
631 *
632 * @fn PUBLIC IX_STATUS ixNpeDlImageDownload (IxNpeDlImageId *imageIdPtr,
633                                                BOOL verify)
634 *
635 * @brief Stop, reset, download microcode and finally start NPE.
636 *
637 * @param imageIdPtr @ref IxNpeDlImageId* [in] - Pointer to Id of the microcode
638 *                                              image to download.
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.
643 *
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.
647 *
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.
651 *
652 * @pre
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.
656 * @post
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.
661 * @return
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
665 *           download
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.
670 */
671PUBLIC IX_STATUS
672ixNpeDlImageDownload (IxNpeDlImageId *imageIdPtr,
673            BOOL verify);
674
675/**
676 * @ingroup IxNpeDl
677 *
678 * @fn PUBLIC IX_STATUS ixNpeDlAvailableImagesCountGet (UINT32 *numImagesPtr)
679 *
680 * @brief Get the number of Images available in a microcode image library
681 *
682 * @param numImagesPtr UINT32* [out] - A pointer to the number of images in
683 *                                       the image library.
684 *
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>.
687 *
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.
691 *
692 * @pre
693 *     - The Client should declare the variable to which numImagesPtr points
694 *
695 * @post
696 *
697 * @return
698 *     - IX_SUCCESS if the operation was successful
699 *     - IX_NPEDL_PARAM_ERR if a parameter error occured
700 *     - IX_FAIL otherwise
701 */
702PUBLIC IX_STATUS
703ixNpeDlAvailableImagesCountGet (UINT32 *numImagesPtr);
704
705/**
706 * @ingroup IxNpeDl
707 *
708 * @fn PUBLIC IX_STATUS ixNpeDlAvailableImagesListGet (IxNpeDlImageId *imageIdListPtr,
709                                                         UINT32 *listSizePtr)
710 *
711 * @brief Get a list of the images available in a microcode image library
712 *
713 * @param imageIdListPtr @ref IxNpeDlImageId* [out] - Array to contain list of
714 *                                                   image Ids (memory
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.
723 *
724 * Finds list of images available in the microcode image library.
725 * Fills these into the array pointed to by <i>imageIdListPtr</i>
726 *
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.
730 *
731 * @pre
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
735 *
736 * @post
737 *
738 * @return
739 *     - IX_SUCCESS if the operation was successful
740 *     - IX_NPEDL_PARAM_ERR if a parameter error occured
741 *     - IX_FAIL otherwise
742 */
743PUBLIC IX_STATUS
744ixNpeDlAvailableImagesListGet (IxNpeDlImageId *imageIdListPtr,
745                 UINT32 *listSizePtr);
746
747/**
748 * @ingroup IxNpeDl
749 *
750 * @fn PUBLIC IX_STATUS ixNpeDlLoadedImageGet (IxNpeDlNpeId npeId,
751                                                IxNpeDlImageId *imageIdPtr)
752 *
753 * @brief Gets the Id of the image currently loaded on a particular NPE
754 *
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.
758 *
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.
762 *
763 * @pre
764 *     - The Client has allocated memory to the <i>imageIdPtr</i> pointer.
765 *
766 * @post
767 *
768 * @return
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
772 */
773PUBLIC IX_STATUS
774ixNpeDlLoadedImageGet (IxNpeDlNpeId npeId,
775             IxNpeDlImageId *imageIdPtr);
776
777/**
778 * @fn PUBLIC IX_STATUS ixNpeDlLatestImageGet (IxNpeDlNpeId npeId, IxNpeDlFunctionalityId
779                                        functionalityId, IxNpeDlImageId *imageIdPtr)
780 *
781 * @brief This instructs NPE Downloader to get Id of the latest version for an
782 * image that is specified by the client.
783 *
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.
788 *
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>.
794 *
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.
798 *
799 * @return
800 *      - IX_SUCCESS if the operation was successful
801 *      - IX_NPEDL_PARAM_ERR if a parameter error occured
802 *      - IX_FAIL otherwise
803 */
804PUBLIC IX_STATUS
805ixNpeDlLatestImageGet (IxNpeDlNpeId npeId,
806             IxNpeDlFunctionalityId functionalityId,
807                    IxNpeDlImageId *imageIdPtr);
808
809/**
810 * @ingroup IxNpeDl
811 *
812 * @fn PUBLIC IX_STATUS ixNpeDlNpeStopAndReset (IxNpeDlNpeId npeId)
813 *
814 * @brief Stops and Resets an NPE
815 *
816 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE.
817 *
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.
821 *
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.
826 *
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.
830 *
831 * @pre
832 *     - The Client is responsible for ensuring mutual access to the NPE.
833 *
834 * @post
835 *
836 * @return
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
842 */
843PUBLIC IX_STATUS
844ixNpeDlNpeStopAndReset (IxNpeDlNpeId npeId);
845
846/**
847 * @ingroup IxNpeDl
848 *
849 * @fn PUBLIC IX_STATUS ixNpeDlNpeExecutionStart (IxNpeDlNpeId npeId)
850 *
851 * @brief Starts code execution on a NPE
852 *
853 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE
854 *
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
857 * on the NPE.
858 *
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.
863 *
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.
867 *
868 * @pre
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()).
873 *
874 * @post
875 *
876 * @return
877 *      - IX_SUCCESS if the operation was successful
878 *      - IX_NPEDL_PARAM_ERR if a parameter error occured
879 *      - IX_FAIL otherwise
880 */
881PUBLIC IX_STATUS
882ixNpeDlNpeExecutionStart (IxNpeDlNpeId npeId);
883
884/**
885 * @ingroup IxNpeDl
886 *
887 * @fn PUBLIC IX_STATUS ixNpeDlNpeExecutionStop (IxNpeDlNpeId npeId)
888 *
889 * @brief Stops code execution on a NPE
890 *
891 * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE
892 *
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..
900 *
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.
904 *
905 * @pre
906 *     - The Client is responsible for ensuring mutual access to the NPE.
907 *
908 * @post
909 *
910 * @return
911 *      - IX_SUCCESS if the operation was successful
912 *      - IX_NPEDL_PARAM_ERR if a parameter error occured
913 *      - IX_FAIL otherwise
914 */
915PUBLIC IX_STATUS
916ixNpeDlNpeExecutionStop (IxNpeDlNpeId npeId);
917
918/**
919 * @ingroup IxNpeDl
920 *
921 * @fn PUBLIC IX_STATUS ixNpeDlUnload (void)
922 *
923 * @brief This function will uninitialise the IxNpeDl component.
924 *
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)
934 *
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.
937 *
938 * The following actions will be performed by this function:
939 * - Unmapping of any kernel memory mapped by IxNpeDl
940 *
941 * @return
942 *      - IX_SUCCESS if the operation was successful
943 *      - IX_FAIL otherwise
944 */
945
946PUBLIC IX_STATUS
947ixNpeDlUnload (void);
948
949/**
950 * @ingroup IxNpeDl
951 *
952 * @fn PUBLIC void ixNpeDlStatsShow (void)
953 *
954 * @brief This function will display run-time statistics from the IxNpeDl
955 *        component
956 *
957 * @return none
958 */
959PUBLIC void
960ixNpeDlStatsShow (void);
961
962/**
963 * @ingroup IxNpeDl
964 *
965 * @fn PUBLIC void ixNpeDlStatsReset (void)
966 *
967 * @brief This function will reset the statistics of the IxNpeDl component
968 *
969 * @return none
970 */
971PUBLIC void
972ixNpeDlStatsReset (void);
973
974#endif /* IXNPEDL_H */
975
976/**
977 * @} defgroup IxNpeDl
978 */
979
980
Note: See TracBrowser for help on using the repository browser.