summaryrefslogtreecommitdiff
path: root/drivers/net/npe/include/IxNpeDl.h
blob: 86f69f414428adad919bbd49b82e52cfb55ecaf1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
/**
 * @file IxNpeDl.h
 *
 * @date 14 December 2001

 * @brief This file contains the public API of the IXP400 NPE Downloader
 *        component.
 *
 * 
 * @par
 * IXP400 SW Release version 2.0
 * 
 * -- Copyright Notice --
 * 
 * @par
 * Copyright 2001-2005, Intel Corporation.
 * All rights reserved.
 * 
 * @par
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of the Intel Corporation nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 * 
 * @par
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * 
 * @par
 * -- End of Copyright Notice --
*/

/**
 * @defgroup IxNpeDl IXP400 NPE-Downloader (IxNpeDl) API
 *
 * @brief The Public API for the IXP400 NPE Downloader
 *
 * @{
 */

#ifndef IXNPEDL_H
#define IXNPEDL_H

/*
 * Put the user defined include files required
 */
#include "IxOsalTypes.h"
#include "IxNpeMicrocode.h"

/*
 * #defines for function return types, etc.
 */

/**
 * @def IX_NPEDL_PARAM_ERR
 *
 * @brief NpeDl function return value for a parameter error
 */
#define IX_NPEDL_PARAM_ERR               2

/**
 * @def IX_NPEDL_RESOURCE_ERR
 *
 * @brief NpeDl function return value for a resource error
 */
#define IX_NPEDL_RESOURCE_ERR            3

/**
 * @def IX_NPEDL_CRITICAL_NPE_ERR
 *
 * @brief NpeDl function return value for a Critical NPE error occuring during
          download. Assume NPE is left in unstable condition if this value is
          returned or NPE is hang / halt.
 */
#define IX_NPEDL_CRITICAL_NPE_ERR        4

/**
 * @def IX_NPEDL_CRITICAL_MICROCODE_ERR
 *
 * @brief NpeDl function return value for a Critical Microcode error
 *        discovered during download. Assume NPE is left in unstable condition
 *        if this value is returned.
 */
#define IX_NPEDL_CRITICAL_MICROCODE_ERR  5

/**
 * @def IX_NPEDL_DEVICE_ERR
 *
 * @brief NpeDl function return value when image being downloaded
 *        is not meant for the device in use
 */
#define IX_NPEDL_DEVICE_ERR 6 

/**
 * @defgroup NPEImageID IXP400 NPE Image ID Definition
 *
 * @ingroup IxNpeDl
 *
 * @brief Definition of NPE Image ID to be passed to ixNpeDlNpeInitAndStart()
 *        as input of type UINT32 which has the following fields format:
 *
 *               Field [Bit Location] <BR>
 *               -------------------- <BR>
 *               Device ID [31 - 28] <BR>
 *               NPE ID [27 - 24] <BR>
 *               NPE Functionality ID [23 - 16] <BR>
 *               Major Release Number [15 -  8] <BR>
 *               Minor Release Number [7 - 0] <BR>
 *
 *
 * @{
 */

/**
 * @def IX_NPEDL_NPEIMAGE_FIELD_MASK
 *
 * @brief Mask for NPE Image ID's Field
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define IX_NPEDL_NPEIMAGE_FIELD_MASK  0xff

/**
 * @def IX_NPEDL_NPEIMAGE_NPEID_MASK
 *
 * @brief Mask for NPE Image NPE ID's Field
 *
 */
#define IX_NPEDL_NPEIMAGE_NPEID_MASK  0xf

/**
 * @def IX_NPEDL_NPEIMAGE_DEVICEID_MASK
 *
 * @brief Mask for NPE Image Device ID's Field
 *
 */
#define IX_NPEDL_NPEIMAGE_DEVICEID_MASK  0xf

/**
 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_NPEID
 *
 * @brief Location of NPE ID field in term of bit.
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define IX_NPEDL_NPEIMAGE_BIT_LOC_NPEID  24

/**
 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_FUNCTIONALITYID
 *
 * @brief Location of Functionality ID field in term of bit.
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define IX_NPEDL_NPEIMAGE_BIT_LOC_FUNCTIONALITYID  16

/**
 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_MAJOR
 *
 * @brief Location of Major Release Number field in term of bit.
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define IX_NPEDL_NPEIMAGE_BIT_LOC_MAJOR  8

/**
 * @def IX_NPEDL_NPEIMAGE_BIT_LOC_MINOR
 *
 * @brief Location of Minor Release Number field in term of bit.
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define IX_NPEDL_NPEIMAGE_BIT_LOC_MINOR  0

/**
 * @} addtogroup NPEImageID
 */

/**
 * @def ixNpeDlMicrocodeImageOverride(x)
 *
 * @brief  Map old terminology that uses term "image" to new term
 *        "image library"
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define ixNpeDlMicrocodeImageOverride(x) ixNpeDlMicrocodeImageLibraryOverride(x)

/**
 * @def IxNpeDlVersionId
 *
 * @brief  Map old terminology that uses term "version" to new term
 *        "image"
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define IxNpeDlVersionId IxNpeDlImageId

/**
 * @def ixNpeDlVersionDownload
 *
 * @brief  Map old terminology that uses term "version" to new term
 *        "image"
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define ixNpeDlVersionDownload(x,y) ixNpeDlImageDownload(x,y)

/**
 * @def ixNpeDlAvailableVersionsCountGet
 *
 * @brief  Map old terminology that uses term "version" to new term
 *        "image"
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define ixNpeDlAvailableVersionsCountGet(x) ixNpeDlAvailableImagesCountGet(x)

/**
 * @def ixNpeDlAvailableVersionsListGet
 *
 * @brief  Map old terminology that uses term "version" to new term
 *        "image"
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define ixNpeDlAvailableVersionsListGet(x,y) ixNpeDlAvailableImagesListGet(x,y)

 /**
 * @def ixNpeDlLoadedVersionGet
 *
 * @brief  Map old terminology that uses term "version" to new term
 *        "image"
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define ixNpeDlLoadedVersionGet(x,y) ixNpeDlLoadedImageGet(x,y)

 /**
 * @def clientImage
 *
 * @brief  Map old terminology that uses term "image" to new term
 *        "image library"
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define clientImage clientImageLibrary

 /**
 * @def versionIdPtr
 *
 * @brief  Map old terminology that uses term "version" to new term
 *        "image"
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define versionIdPtr imageIdPtr

 /**
 * @def numVersionsPtr
 *
 * @brief  Map old terminology that uses term "version" to new term
 *        "image"
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define numVersionsPtr numImagesPtr

/**
 * @def versionIdListPtr
 *
 * @brief  Map old terminology that uses term "version" to new term
 *        "image"
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define versionIdListPtr imageIdListPtr

/**
 * @def IxNpeDlBuildId
 *
 * @brief  Map old terminology that uses term "buildId" to new term
 *        "functionalityId"
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define IxNpeDlBuildId IxNpeDlFunctionalityId

/**
 * @def buildId
 *
 * @brief  Map old terminology that uses term "buildId" to new term
 *        "functionalityId"
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define buildId functionalityId

/**
 * @def IX_NPEDL_MicrocodeImage
 *
 * @brief  Map old terminology that uses term "image" to new term
 *        "image library"
 *
 * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
#define IX_NPEDL_MicrocodeImage IX_NPEDL_MicrocodeImageLibrary

/*
 * Typedefs
 */

/**
 * @typedef IxNpeDlFunctionalityId
 * @brief Used to make up Functionality ID field of Image Id
 *
 * @warning <b>THIS typedef HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
typedef UINT8 IxNpeDlFunctionalityId;

/**
 * @typedef IxNpeDlMajor
 * @brief Used to make up Major Release field of Image Id
 *
 * @warning <b>THIS typedef HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
typedef UINT8 IxNpeDlMajor;

/**
 * @typedef IxNpeDlMinor
 * @brief Used to make up Minor Revision field of Image Id
 *
 * @warning <b>THIS typedef HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
typedef UINT8 IxNpeDlMinor;

/*
 * Enums
 */

/**
 * @brief NpeId numbers to identify NPE A, B or C
 * @note In this context, for IXP425 Silicon (B0):<br>
 *      - NPE-A has HDLC, HSS, AAL and UTOPIA Coprocessors.<br>
 *      - NPE-B has Ethernet Coprocessor.<br>
 *      - NPE-C has Ethernet, AES, DES and HASH Coprocessors.<br>
 *      - IXP400 Product Line have different combinations of coprocessors.
 */
typedef enum
{
  IX_NPEDL_NPEID_NPEA = 0,    /**< Identifies NPE A */
  IX_NPEDL_NPEID_NPEB,        /**< Identifies NPE B */
  IX_NPEDL_NPEID_NPEC,        /**< Identifies NPE C */
  IX_NPEDL_NPEID_MAX          /**< Total Number of NPEs */
} IxNpeDlNpeId;

/*
 * Structs
 */

/**
 * @brief Image Id to identify each image contained in an image library
 *
 * @warning <b>THIS struct HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart for more information.
 */
typedef struct
{
    IxNpeDlNpeId   npeId;   /**< NPE ID */
    IxNpeDlFunctionalityId functionalityId; /**< Build ID indicates functionality of image */
    IxNpeDlMajor   major;   /**< Major Release Number */
    IxNpeDlMinor   minor;   /**< Minor Revision Number */
} IxNpeDlImageId;

/*
 * Prototypes for interface functions
 */

/**
 * @ingroup IxNpeDl
 *
 * @fn PUBLIC IX_STATUS ixNpeDlNpeInitAndStart (UINT32 imageId)
 *
 * @brief Stop, reset, download microcode (firmware) and finally start NPE.
 *
 * @param imageId UINT32 [in] - Id of the microcode image to download.
 *
 * This function locates the image specified by the <i>imageId</i> parameter
 * from the default microcode image library which is included internally by
 * this component.
 * It then stops and resets the NPE, loads the firmware image onto the NPE,
 * and then restarts the NPE.
 *
 * @note A list of valid image IDs is included in this header file.
 *       See #defines with prefix IX_NPEDL_NPEIMAGE_...
 *
 * @note This function, along with @ref ixNpeDlCustomImageNpeInitAndStart
 *       and @ref ixNpeDlLoadedImageFunctionalityGet, supercedes the following
 *       functions which are deprecated and will be removed completely in a
 *       future release:
 *       - @ref ixNpeDlImageDownload
 *       - @ref ixNpeDlAvailableImagesCountGet
 *       - @ref ixNpeDlAvailableImagesListGet
 *       - @ref ixNpeDlLatestImageGet
 *       - @ref ixNpeDlLoadedImageGet
 *       - @ref ixNpeDlMicrocodeImageLibraryOverride
 *       - @ref ixNpeDlNpeExecutionStop
 *       - @ref ixNpeDlNpeStopAndReset
 *       - @ref ixNpeDlNpeExecutionStart
 *
 * @pre
 *         - The Client is responsible for ensuring mutual access to the NPE.
 * @post
 *         - The NPE Instruction Pipeline will be cleared if State Information
 *           has been downloaded.
 *         - If the download fails with a critical error, the NPE may
 *           be left in an ususable state.
 * @return
 *         - IX_SUCCESS if the download was successful;
 *         - IX_NPEDL_PARAM_ERR if a parameter error occured
 *         - IX_NPEDL_CRITICAL_NPE_ERR if a critical NPE error occured during
 *           download
 *         - IX_NPEDL_CRITICAL_MICROCODE_ERR if a critical microcode error
 *           occured during download
 *         - IX_NPEDL_DEVICE_ERR if the image being loaded is not meant for 
 *           the device currently running.
 *         - IX_FAIL if NPE is not available or image is failed to be located.
 *           A warning is issued if the NPE is not present.
 */
PUBLIC IX_STATUS
ixNpeDlNpeInitAndStart (UINT32 npeImageId);

/**
 * @ingroup IxNpeDl
 *
 * @fn PUBLIC IX_STATUS ixNpeDlCustomImageNpeInitAndStart (UINT32 *imageLibrary,
                                                           UINT32 imageId)
 *
 * @brief Stop, reset, download microcode (firmware) and finally start NPE
 *
 * @param imageId UINT32 [in] - Id of the microcode image to download.
 *
 * This function locates the image specified by the <i>imageId</i> parameter
 * from the specified microcode image library which is pointed to by the
 * <i>imageLibrary</i> parameter.
 * It then stops and resets the NPE, loads the firmware image onto the NPE,
 * and then restarts the NPE.
 *
 * This is a facility for users who wish to use an image from an external
 * library of NPE firmware images.  To use a standard image from the
 * built-in library, see @ref ixNpeDlNpeInitAndStart instead.
 *
 * @note A list of valid image IDs is included in this header file.
 *       See #defines with prefix IX_NPEDL_NPEIMAGE_...
 *
 * @note This function, along with @ref ixNpeDlNpeInitAndStart
 *       and @ref ixNpeDlLoadedImageFunctionalityGet, supercedes the following
 *       functions which are deprecated and will be removed completely in a
 *       future release:
 *       - @ref ixNpeDlImageDownload
 *       - @ref ixNpeDlAvailableImagesCountGet
 *       - @ref ixNpeDlAvailableImagesListGet
 *       - @ref ixNpeDlLatestImageGet
 *       - @ref ixNpeDlLoadedImageGet
 *       - @ref ixNpeDlMicrocodeImageLibraryOverride
 *       - @ref ixNpeDlNpeExecutionStop
 *       - @ref ixNpeDlNpeStopAndReset
 *       - @ref ixNpeDlNpeExecutionStart
 *
 * @pre
 *         - The Client is responsible for ensuring mutual access to the NPE.
 *         - The image library supplied must be in the correct format for use
 *           by the NPE Downloader (IxNpeDl) component.  Details of the library
 *           format are contained in the Functional Specification document for
 *           IxNpeDl.
 * @post
 *         - The NPE Instruction Pipeline will be cleared if State Information
 *           has been downloaded.
 *         - If the download fails with a critical error, the NPE may
 *           be left in an ususable state.
 * @return
 *         - IX_SUCCESS if the download was successful;
 *         - IX_NPEDL_PARAM_ERR if a parameter error occured
 *         - IX_NPEDL_CRITICAL_NPE_ERR if a critical NPE error occured during
 *           download
 *         - IX_NPEDL_CRITICAL_MICROCODE_ERR if a critical microcode error
 *           occured during download
 *         - IX_NPEDL_DEVICE_ERR if the image being loaded is not meant for 
 *           the device currently running.
 *         - IX_FAIL if NPE is not available or image is failed to be located.
 *           A warning is issued if the NPE is not present.
 */
PUBLIC IX_STATUS
ixNpeDlCustomImageNpeInitAndStart (UINT32 *imageLibrary,
                    UINT32 npeImageId);


/**
 * @ingroup IxNpeDl
 *
 * @fn PUBLIC IX_STATUS ixNpeDlLoadedImageFunctionalityGet (IxNpeDlNpeId npeId,
                                                        UINT8 *functionalityId)
 *
 * @brief Gets the functionality of the image last loaded on a particular NPE
 *
 * @param npeId  @ref IxNpeDlNpeId [in]      - Id of the target NPE.
 * @param functionalityId UINT8* [out] - the functionality ID of the image
 *                                       last loaded on the NPE.
 *
 * This function retrieves the functionality ID of the image most recently
 * downloaded successfully to the specified NPE.  If the NPE does not contain
 * a valid image, this function returns a FAIL status.
 *
 * @warning This function is not intended for general use, as a knowledge of
 * how to interpret the functionality ID is required.  As such, this function
 * should only be used by other Access Layer components of the IXP400 Software
 * Release.
 *
 * @pre
 *
 * @post
 *
 * @return
 *     -  IX_SUCCESS if the operation was successful
 *     -  IX_NPEDL_PARAM_ERR if a parameter error occured
 *     -  IX_FAIL if the NPE does not have a valid image loaded
 */
PUBLIC IX_STATUS
ixNpeDlLoadedImageFunctionalityGet (IxNpeDlNpeId npeId,
                                    UINT8 *functionalityId);


/**
 * @ingroup IxNpeDl
 *
 * @fn IX_STATUS ixNpeDlMicrocodeImageLibraryOverride (UINT32 *clientImageLibrary)
 *
 * @brief This instructs NPE Downloader to use client-supplied microcode image library.
 *
 * @param clientImageLibrary UINT32* [in]  - Pointer to the client-supplied
 *                                   NPE microcode image library
 *
 * This function sets NPE Downloader to use a client-supplied microcode image library
 * instead of the standard image library which is included by the NPE Downloader.
 * <b>This function is provided mainly for increased testability and should not
 * be used in normal circumstances.</b> When not used, NPE Downloader will use
 * a "built-in" image library, local to this component, which should always contain the
 * latest microcode for the NPEs.
 *
 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlCustomImageNpeInitAndStart.
 *
 * @pre
 *      - <i>clientImageLibrary</i> should point to a microcode image library valid for use
 *        by the NPE Downloader component.
 *
 * @post
 *      - the client-supplied image library will be used for all subsequent operations
 *        performed by the NPE Downloader
 *
 * @return
 *      - IX_SUCCESS if the operation was successful
 *      - IX_NPEDL_PARAM_ERR if a parameter error occured
 *      - IX_FAIL if the client-supplied image library did not contain a valid signature
 */
PUBLIC IX_STATUS
ixNpeDlMicrocodeImageLibraryOverride (UINT32 *clientImageLibrary);

/**
 * @ingroup IxNpeDl
 *
 * @fn PUBLIC IX_STATUS ixNpeDlImageDownload (IxNpeDlImageId *imageIdPtr,
                                                BOOL verify)
 *
 * @brief Stop, reset, download microcode and finally start NPE.
 *
 * @param imageIdPtr @ref IxNpeDlImageId* [in] - Pointer to Id of the microcode
 *                                              image to download.
 * @param verify BOOL [in]     - ON/OFF option to verify the download. If ON
 *                               (verify == TRUE), the Downloader will read back
 *                               each word written to the NPE registers to
 *                               ensure the download operation was successful.
 *
 * Using the <i>imageIdPtr</i>, this function locates a particular image of
 * microcode in the microcode image library in memory, and downloads the microcode
 * to a particular NPE.
 *
 * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 *       It will be removed in a future release.
 *       See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
 *
 * @pre
 *         - The Client is responsible for ensuring mutual access to the NPE.
 *       - The Client should use ixNpeDlLatestImageGet() to obtain the latest
 *         version of the image before attempting download.
 * @post
 *         - The NPE Instruction Pipeline will be cleared if State Information
 *           has been downloaded.
 *         - If the download fails with a critical error, the NPE may
 *           be left in an ususable state.
 * @return
 *         - IX_SUCCESS if the download was successful;
 *         - IX_NPEDL_PARAM_ERR if a parameter error occured
 *         - IX_NPEDL_CRITICAL_NPE_ERR if a critical NPE error occured during
 *           download
 *         - IX_PARAM_CRITICAL_MICROCODE_ERR if a critical microcode error
 *           occured during download
 *         - IX_FAIL if NPE is not available or image is failed to be located.
 *           A warning is issued if the NPE is not present.
 */
PUBLIC IX_STATUS
ixNpeDlImageDownload (IxNpeDlImageId *imageIdPtr,
            BOOL verify);

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

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

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

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

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

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

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

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

PUBLIC IX_STATUS 
ixNpeDlUnload (void);

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

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

#endif /* IXNPEDL_H */

/**
 * @} defgroup IxNpeDl
 */