drivers/net/npe/include/IxNpeDl.h

   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  */
 373 typedef 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  */
 383 typedef 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  */
 393 typedef 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  */
 407 typedef 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  */
 426 typedef 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  */
 489 PUBLIC IX_STATUS
 490 ixNpeDlNpeInitAndStart (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  */
 552 PUBLIC IX_STATUS
 553 ixNpeDlCustomImageNpeInitAndStart (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  */
 587 PUBLIC IX_STATUS
 588 ixNpeDlLoadedImageFunctionalityGet (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  */
 626 PUBLIC IX_STATUS
 627 ixNpeDlMicrocodeImageLibraryOverride (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  */
 671 PUBLIC IX_STATUS
 672 ixNpeDlImageDownload (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  */
 702 PUBLIC IX_STATUS
 703 ixNpeDlAvailableImagesCountGet (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  */
 743 PUBLIC IX_STATUS
 744 ixNpeDlAvailableImagesListGet (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  */
 773 PUBLIC IX_STATUS
 774 ixNpeDlLoadedImageGet (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  */
 804 PUBLIC IX_STATUS
 805 ixNpeDlLatestImageGet (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  */
 843 PUBLIC IX_STATUS
 844 ixNpeDlNpeStopAndReset (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  */
 881 PUBLIC IX_STATUS
 882 ixNpeDlNpeExecutionStart (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  */
 915 PUBLIC IX_STATUS
 916 ixNpeDlNpeExecutionStop (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
 946 PUBLIC IX_STATUS
 947 ixNpeDlUnload (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  */
 959 PUBLIC void
 960 ixNpeDlStatsShow (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  */
 971 PUBLIC void
 972 ixNpeDlStatsReset (void);
 973
 974 #endif /* IXNPEDL_H */
 975
 976 /**
 977  * @} defgroup IxNpeDl
 978  */
 979
 980