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  * SPDX-License-Identifier:     BSD-3-Clause
  21  * @par
  22  * -- End of Copyright Notice --
  23 */
  24
  25 /**
  26  * @defgroup IxNpeDl IXP400 NPE-Downloader (IxNpeDl) API
  27  *
  28  * @brief The Public API for the IXP400 NPE Downloader
  29  *
  30  * @{
  31  */
  32
  33 #ifndef IXNPEDL_H
  34 #define IXNPEDL_H
  35
  36 /*
  37  * Put the user defined include files required
  38  */
  39 #include "IxOsalTypes.h"
  40 #include "IxNpeMicrocode.h"
  41
  42 /*
  43  * #defines for function return types, etc.
  44  */
  45
  46 /**
  47  * @def IX_NPEDL_PARAM_ERR
  48  *
  49  * @brief NpeDl function return value for a parameter error
  50  */
  51 #define IX_NPEDL_PARAM_ERR               2
  52
  53 /**
  54  * @def IX_NPEDL_RESOURCE_ERR
  55  *
  56  * @brief NpeDl function return value for a resource error
  57  */
  58 #define IX_NPEDL_RESOURCE_ERR            3
  59
  60 /**
  61  * @def IX_NPEDL_CRITICAL_NPE_ERR
  62  *
  63  * @brief NpeDl function return value for a Critical NPE error occuring during
  64           download. Assume NPE is left in unstable condition if this value is
  65           returned or NPE is hang / halt.
  66  */
  67 #define IX_NPEDL_CRITICAL_NPE_ERR        4
  68
  69 /**
  70  * @def IX_NPEDL_CRITICAL_MICROCODE_ERR
  71  *
  72  * @brief NpeDl function return value for a Critical Microcode error
  73  *        discovered during download. Assume NPE is left in unstable condition
  74  *        if this value is returned.
  75  */
  76 #define IX_NPEDL_CRITICAL_MICROCODE_ERR  5
  77
  78 /**
  79  * @def IX_NPEDL_DEVICE_ERR
  80  *
  81  * @brief NpeDl function return value when image being downloaded
  82  *        is not meant for the device in use
  83  */
  84 #define IX_NPEDL_DEVICE_ERR 6
  85
  86 /**
  87  * @defgroup NPEImageID IXP400 NPE Image ID Definition
  88  *
  89  * @ingroup IxNpeDl
  90  *
  91  * @brief Definition of NPE Image ID to be passed to ixNpeDlNpeInitAndStart()
  92  *        as input of type UINT32 which has the following fields format:
  93  *
  94  *               Field [Bit Location] <BR>
  95  *               -------------------- <BR>
  96  *               Device ID [31 - 28] <BR>
  97  *               NPE ID [27 - 24] <BR>
  98  *               NPE Functionality ID [23 - 16] <BR>
  99  *               Major Release Number [15 -  8] <BR>
 100  *               Minor Release Number [7 - 0] <BR>
 101  *
 102  *
 103  * @{
 104  */
 105
 106 /**
 107  * @def IX_NPEDL_NPEIMAGE_FIELD_MASK
 108  *
 109  * @brief Mask for NPE Image ID's Field
 110  *
 111  * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 112  *       It will be removed in a future release.
 113  *       See @ref ixNpeDlNpeInitAndStart for more information.
 114  */
 115 #define IX_NPEDL_NPEIMAGE_FIELD_MASK  0xff
 116
 117 /**
 118  * @def IX_NPEDL_NPEIMAGE_NPEID_MASK
 119  *
 120  * @brief Mask for NPE Image NPE ID's Field
 121  *
 122  */
 123 #define IX_NPEDL_NPEIMAGE_NPEID_MASK  0xf
 124
 125 /**
 126  * @def IX_NPEDL_NPEIMAGE_DEVICEID_MASK
 127  *
 128  * @brief Mask for NPE Image Device ID's Field
 129  *
 130  */
 131 #define IX_NPEDL_NPEIMAGE_DEVICEID_MASK  0xf
 132
 133 /**
 134  * @def IX_NPEDL_NPEIMAGE_BIT_LOC_NPEID
 135  *
 136  * @brief Location of NPE ID field in term of bit.
 137  *
 138  * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 139  *       It will be removed in a future release.
 140  *       See @ref ixNpeDlNpeInitAndStart for more information.
 141  */
 142 #define IX_NPEDL_NPEIMAGE_BIT_LOC_NPEID  24
 143
 144 /**
 145  * @def IX_NPEDL_NPEIMAGE_BIT_LOC_FUNCTIONALITYID
 146  *
 147  * @brief Location of Functionality ID field in term of bit.
 148  *
 149  * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 150  *       It will be removed in a future release.
 151  *       See @ref ixNpeDlNpeInitAndStart for more information.
 152  */
 153 #define IX_NPEDL_NPEIMAGE_BIT_LOC_FUNCTIONALITYID  16
 154
 155 /**
 156  * @def IX_NPEDL_NPEIMAGE_BIT_LOC_MAJOR
 157  *
 158  * @brief Location of Major Release Number field in term of bit.
 159  *
 160  * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 161  *       It will be removed in a future release.
 162  *       See @ref ixNpeDlNpeInitAndStart for more information.
 163  */
 164 #define IX_NPEDL_NPEIMAGE_BIT_LOC_MAJOR  8
 165
 166 /**
 167  * @def IX_NPEDL_NPEIMAGE_BIT_LOC_MINOR
 168  *
 169  * @brief Location of Minor Release Number field in term of bit.
 170  *
 171  * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 172  *       It will be removed in a future release.
 173  *       See @ref ixNpeDlNpeInitAndStart for more information.
 174  */
 175 #define IX_NPEDL_NPEIMAGE_BIT_LOC_MINOR  0
 176
 177 /**
 178  * @} addtogroup NPEImageID
 179  */
 180
 181 /**
 182  * @def ixNpeDlMicrocodeImageOverride(x)
 183  *
 184  * @brief  Map old terminology that uses term "image" to new term
 185  *        "image library"
 186  *
 187  * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 188  *       It will be removed in a future release.
 189  *       See @ref ixNpeDlNpeInitAndStart for more information.
 190  */
 191 #define ixNpeDlMicrocodeImageOverride(x) ixNpeDlMicrocodeImageLibraryOverride(x)
 192
 193 /**
 194  * @def IxNpeDlVersionId
 195  *
 196  * @brief  Map old terminology that uses term "version" to new term
 197  *        "image"
 198  *
 199  * @warning <b>THIS #define HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 200  *       It will be removed in a future release.
 201  *       See @ref ixNpeDlNpeInitAndStart for more information.
 202  */
 203 #define IxNpeDlVersionId IxNpeDlImageId
 204
 205 /**
 206  * @def ixNpeDlVersionDownload
 207  *
 208  * @brief  Map old terminology that uses term "version" to new term
 209  *        "image"
 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 ixNpeDlVersionDownload(x,y) ixNpeDlImageDownload(x,y)
 216
 217 /**
 218  * @def ixNpeDlAvailableVersionsCountGet
 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 ixNpeDlAvailableVersionsCountGet(x) ixNpeDlAvailableImagesCountGet(x)
 228
 229 /**
 230  * @def ixNpeDlAvailableVersionsListGet
 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 ixNpeDlAvailableVersionsListGet(x,y) ixNpeDlAvailableImagesListGet(x,y)
 240
 241  /**
 242  * @def ixNpeDlLoadedVersionGet
 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 ixNpeDlLoadedVersionGet(x,y) ixNpeDlLoadedImageGet(x,y)
 252
 253  /**
 254  * @def clientImage
 255  *
 256  * @brief  Map old terminology that uses term "image" to new term
 257  *        "image library"
 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 clientImage clientImageLibrary
 264
 265  /**
 266  * @def versionIdPtr
 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 versionIdPtr imageIdPtr
 276
 277  /**
 278  * @def numVersionsPtr
 279  *
 280  * @brief  Map old terminology that uses term "version" to new term
 281  *        "image"
 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 numVersionsPtr numImagesPtr
 288
 289 /**
 290  * @def versionIdListPtr
 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 versionIdListPtr imageIdListPtr
 300
 301 /**
 302  * @def IxNpeDlBuildId
 303  *
 304  * @brief  Map old terminology that uses term "buildId" to new term
 305  *        "functionalityId"
 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 IxNpeDlBuildId IxNpeDlFunctionalityId
 312
 313 /**
 314  * @def buildId
 315  *
 316  * @brief  Map old terminology that uses term "buildId" to new term
 317  *        "functionalityId"
 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 buildId functionalityId
 324
 325 /**
 326  * @def IX_NPEDL_MicrocodeImage
 327  *
 328  * @brief  Map old terminology that uses term "image" to new term
 329  *        "image library"
 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 IX_NPEDL_MicrocodeImage IX_NPEDL_MicrocodeImageLibrary
 336
 337 /*
 338  * Typedefs
 339  */
 340
 341 /**
 342  * @typedef IxNpeDlFunctionalityId
 343  * @brief Used to make up Functionality ID field of Image Id
 344  *
 345  * @warning <b>THIS typedef HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 346  *       It will be removed in a future release.
 347  *       See @ref ixNpeDlNpeInitAndStart for more information.
 348  */
 349 typedef UINT8 IxNpeDlFunctionalityId;
 350
 351 /**
 352  * @typedef IxNpeDlMajor
 353  * @brief Used to make up Major Release field of Image Id
 354  *
 355  * @warning <b>THIS typedef HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 356  *       It will be removed in a future release.
 357  *       See @ref ixNpeDlNpeInitAndStart for more information.
 358  */
 359 typedef UINT8 IxNpeDlMajor;
 360
 361 /**
 362  * @typedef IxNpeDlMinor
 363  * @brief Used to make up Minor Revision field of Image Id
 364  *
 365  * @warning <b>THIS typedef HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 366  *       It will be removed in a future release.
 367  *       See @ref ixNpeDlNpeInitAndStart for more information.
 368  */
 369 typedef UINT8 IxNpeDlMinor;
 370
 371 /*
 372  * Enums
 373  */
 374
 375 /**
 376  * @brief NpeId numbers to identify NPE A, B or C
 377  * @note In this context, for IXP425 Silicon (B0):<br>
 378  *      - NPE-A has HDLC, HSS, AAL and UTOPIA Coprocessors.<br>
 379  *      - NPE-B has Ethernet Coprocessor.<br>
 380  *      - NPE-C has Ethernet, AES, DES and HASH Coprocessors.<br>
 381  *      - IXP400 Product Line have different combinations of coprocessors.
 382  */
 383 typedef enum
 384 {
 385   IX_NPEDL_NPEID_NPEA = 0,    /**< Identifies NPE A */
 386   IX_NPEDL_NPEID_NPEB,        /**< Identifies NPE B */
 387   IX_NPEDL_NPEID_NPEC,        /**< Identifies NPE C */
 388   IX_NPEDL_NPEID_MAX          /**< Total Number of NPEs */
 389 } IxNpeDlNpeId;
 390
 391 /*
 392  * Structs
 393  */
 394
 395 /**
 396  * @brief Image Id to identify each image contained in an image library
 397  *
 398  * @warning <b>THIS struct HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 399  *       It will be removed in a future release.
 400  *       See @ref ixNpeDlNpeInitAndStart for more information.
 401  */
 402 typedef struct
 403 {
 404     IxNpeDlNpeId   npeId;   /**< NPE ID */
 405     IxNpeDlFunctionalityId functionalityId; /**< Build ID indicates functionality of image */
 406     IxNpeDlMajor   major;   /**< Major Release Number */
 407     IxNpeDlMinor   minor;   /**< Minor Revision Number */
 408 } IxNpeDlImageId;
 409
 410 /*
 411  * Prototypes for interface functions
 412  */
 413
 414 /**
 415  * @ingroup IxNpeDl
 416  *
 417  * @fn PUBLIC IX_STATUS ixNpeDlNpeInitAndStart (UINT32 imageId)
 418  *
 419  * @brief Stop, reset, download microcode (firmware) and finally start NPE.
 420  *
 421  * @param imageId UINT32 [in] - Id of the microcode image to download.
 422  *
 423  * This function locates the image specified by the <i>imageId</i> parameter
 424  * from the default microcode image library which is included internally by
 425  * this component.
 426  * It then stops and resets the NPE, loads the firmware image onto the NPE,
 427  * and then restarts the NPE.
 428  *
 429  * @note A list of valid image IDs is included in this header file.
 430  *       See #defines with prefix IX_NPEDL_NPEIMAGE_...
 431  *
 432  * @note This function, along with @ref ixNpeDlCustomImageNpeInitAndStart
 433  *       and @ref ixNpeDlLoadedImageFunctionalityGet, supercedes the following
 434  *       functions which are deprecated and will be removed completely in a
 435  *       future release:
 436  *       - @ref ixNpeDlImageDownload
 437  *       - @ref ixNpeDlAvailableImagesCountGet
 438  *       - @ref ixNpeDlAvailableImagesListGet
 439  *       - @ref ixNpeDlLatestImageGet
 440  *       - @ref ixNpeDlLoadedImageGet
 441  *       - @ref ixNpeDlMicrocodeImageLibraryOverride
 442  *       - @ref ixNpeDlNpeExecutionStop
 443  *       - @ref ixNpeDlNpeStopAndReset
 444  *       - @ref ixNpeDlNpeExecutionStart
 445  *
 446  * @pre
 447  *         - The Client is responsible for ensuring mutual access to the NPE.
 448  * @post
 449  *         - The NPE Instruction Pipeline will be cleared if State Information
 450  *           has been downloaded.
 451  *         - If the download fails with a critical error, the NPE may
 452  *           be left in an ususable state.
 453  * @return
 454  *         - IX_SUCCESS if the download was successful;
 455  *         - IX_NPEDL_PARAM_ERR if a parameter error occured
 456  *         - IX_NPEDL_CRITICAL_NPE_ERR if a critical NPE error occured during
 457  *           download
 458  *         - IX_NPEDL_CRITICAL_MICROCODE_ERR if a critical microcode error
 459  *           occured during download
 460  *         - IX_NPEDL_DEVICE_ERR if the image being loaded is not meant for
 461  *           the device currently running.
 462  *         - IX_FAIL if NPE is not available or image is failed to be located.
 463  *           A warning is issued if the NPE is not present.
 464  */
 465 PUBLIC IX_STATUS
 466 ixNpeDlNpeInitAndStart (UINT32 npeImageId);
 467
 468 /**
 469  * @ingroup IxNpeDl
 470  *
 471  * @fn PUBLIC IX_STATUS ixNpeDlCustomImageNpeInitAndStart (UINT32 *imageLibrary,
 472                                                            UINT32 imageId)
 473  *
 474  * @brief Stop, reset, download microcode (firmware) and finally start NPE
 475  *
 476  * @param imageId UINT32 [in] - Id of the microcode image to download.
 477  *
 478  * This function locates the image specified by the <i>imageId</i> parameter
 479  * from the specified microcode image library which is pointed to by the
 480  * <i>imageLibrary</i> parameter.
 481  * It then stops and resets the NPE, loads the firmware image onto the NPE,
 482  * and then restarts the NPE.
 483  *
 484  * This is a facility for users who wish to use an image from an external
 485  * library of NPE firmware images.  To use a standard image from the
 486  * built-in library, see @ref ixNpeDlNpeInitAndStart instead.
 487  *
 488  * @note A list of valid image IDs is included in this header file.
 489  *       See #defines with prefix IX_NPEDL_NPEIMAGE_...
 490  *
 491  * @note This function, along with @ref ixNpeDlNpeInitAndStart
 492  *       and @ref ixNpeDlLoadedImageFunctionalityGet, supercedes the following
 493  *       functions which are deprecated and will be removed completely in a
 494  *       future release:
 495  *       - @ref ixNpeDlImageDownload
 496  *       - @ref ixNpeDlAvailableImagesCountGet
 497  *       - @ref ixNpeDlAvailableImagesListGet
 498  *       - @ref ixNpeDlLatestImageGet
 499  *       - @ref ixNpeDlLoadedImageGet
 500  *       - @ref ixNpeDlMicrocodeImageLibraryOverride
 501  *       - @ref ixNpeDlNpeExecutionStop
 502  *       - @ref ixNpeDlNpeStopAndReset
 503  *       - @ref ixNpeDlNpeExecutionStart
 504  *
 505  * @pre
 506  *         - The Client is responsible for ensuring mutual access to the NPE.
 507  *         - The image library supplied must be in the correct format for use
 508  *           by the NPE Downloader (IxNpeDl) component.  Details of the library
 509  *           format are contained in the Functional Specification document for
 510  *           IxNpeDl.
 511  * @post
 512  *         - The NPE Instruction Pipeline will be cleared if State Information
 513  *           has been downloaded.
 514  *         - If the download fails with a critical error, the NPE may
 515  *           be left in an ususable state.
 516  * @return
 517  *         - IX_SUCCESS if the download was successful;
 518  *         - IX_NPEDL_PARAM_ERR if a parameter error occured
 519  *         - IX_NPEDL_CRITICAL_NPE_ERR if a critical NPE error occured during
 520  *           download
 521  *         - IX_NPEDL_CRITICAL_MICROCODE_ERR if a critical microcode error
 522  *           occured during download
 523  *         - IX_NPEDL_DEVICE_ERR if the image being loaded is not meant for
 524  *           the device currently running.
 525  *         - IX_FAIL if NPE is not available or image is failed to be located.
 526  *           A warning is issued if the NPE is not present.
 527  */
 528 PUBLIC IX_STATUS
 529 ixNpeDlCustomImageNpeInitAndStart (UINT32 *imageLibrary,
 530                     UINT32 npeImageId);
 531
 532
 533 /**
 534  * @ingroup IxNpeDl
 535  *
 536  * @fn PUBLIC IX_STATUS ixNpeDlLoadedImageFunctionalityGet (IxNpeDlNpeId npeId,
 537                                                         UINT8 *functionalityId)
 538  *
 539  * @brief Gets the functionality of the image last loaded on a particular NPE
 540  *
 541  * @param npeId  @ref IxNpeDlNpeId [in]      - Id of the target NPE.
 542  * @param functionalityId UINT8* [out] - the functionality ID of the image
 543  *                                       last loaded on the NPE.
 544  *
 545  * This function retrieves the functionality ID of the image most recently
 546  * downloaded successfully to the specified NPE.  If the NPE does not contain
 547  * a valid image, this function returns a FAIL status.
 548  *
 549  * @warning This function is not intended for general use, as a knowledge of
 550  * how to interpret the functionality ID is required.  As such, this function
 551  * should only be used by other Access Layer components of the IXP400 Software
 552  * Release.
 553  *
 554  * @pre
 555  *
 556  * @post
 557  *
 558  * @return
 559  *     -  IX_SUCCESS if the operation was successful
 560  *     -  IX_NPEDL_PARAM_ERR if a parameter error occured
 561  *     -  IX_FAIL if the NPE does not have a valid image loaded
 562  */
 563 PUBLIC IX_STATUS
 564 ixNpeDlLoadedImageFunctionalityGet (IxNpeDlNpeId npeId,
 565                                     UINT8 *functionalityId);
 566
 567
 568 /**
 569  * @ingroup IxNpeDl
 570  *
 571  * @fn IX_STATUS ixNpeDlMicrocodeImageLibraryOverride (UINT32 *clientImageLibrary)
 572  *
 573  * @brief This instructs NPE Downloader to use client-supplied microcode image library.
 574  *
 575  * @param clientImageLibrary UINT32* [in]  - Pointer to the client-supplied
 576  *                                   NPE microcode image library
 577  *
 578  * This function sets NPE Downloader to use a client-supplied microcode image library
 579  * instead of the standard image library which is included by the NPE Downloader.
 580  * <b>This function is provided mainly for increased testability and should not
 581  * be used in normal circumstances.</b> When not used, NPE Downloader will use
 582  * a "built-in" image library, local to this component, which should always contain the
 583  * latest microcode for the NPEs.
 584  *
 585  * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 586  *       It will be removed in a future release.
 587  *       See @ref ixNpeDlCustomImageNpeInitAndStart.
 588  *
 589  * @pre
 590  *      - <i>clientImageLibrary</i> should point to a microcode image library valid for use
 591  *        by the NPE Downloader component.
 592  *
 593  * @post
 594  *      - the client-supplied image library will be used for all subsequent operations
 595  *        performed by the NPE Downloader
 596  *
 597  * @return
 598  *      - IX_SUCCESS if the operation was successful
 599  *      - IX_NPEDL_PARAM_ERR if a parameter error occured
 600  *      - IX_FAIL if the client-supplied image library did not contain a valid signature
 601  */
 602 PUBLIC IX_STATUS
 603 ixNpeDlMicrocodeImageLibraryOverride (UINT32 *clientImageLibrary);
 604
 605 /**
 606  * @ingroup IxNpeDl
 607  *
 608  * @fn PUBLIC IX_STATUS ixNpeDlImageDownload (IxNpeDlImageId *imageIdPtr,
 609                                                 BOOL verify)
 610  *
 611  * @brief Stop, reset, download microcode and finally start NPE.
 612  *
 613  * @param imageIdPtr @ref IxNpeDlImageId* [in] - Pointer to Id of the microcode
 614  *                                              image to download.
 615  * @param verify BOOL [in]     - ON/OFF option to verify the download. If ON
 616  *                               (verify == true), the Downloader will read back
 617  *                               each word written to the NPE registers to
 618  *                               ensure the download operation was successful.
 619  *
 620  * Using the <i>imageIdPtr</i>, this function locates a particular image of
 621  * microcode in the microcode image library in memory, and downloads the microcode
 622  * to a particular NPE.
 623  *
 624  * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 625  *       It will be removed in a future release.
 626  *       See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
 627  *
 628  * @pre
 629  *         - The Client is responsible for ensuring mutual access to the NPE.
 630  *       - The Client should use ixNpeDlLatestImageGet() to obtain the latest
 631  *         version of the image before attempting download.
 632  * @post
 633  *         - The NPE Instruction Pipeline will be cleared if State Information
 634  *           has been downloaded.
 635  *         - If the download fails with a critical error, the NPE may
 636  *           be left in an ususable state.
 637  * @return
 638  *         - IX_SUCCESS if the download was successful;
 639  *         - IX_NPEDL_PARAM_ERR if a parameter error occured
 640  *         - IX_NPEDL_CRITICAL_NPE_ERR if a critical NPE error occured during
 641  *           download
 642  *         - IX_PARAM_CRITICAL_MICROCODE_ERR if a critical microcode error
 643  *           occured during download
 644  *         - IX_FAIL if NPE is not available or image is failed to be located.
 645  *           A warning is issued if the NPE is not present.
 646  */
 647 PUBLIC IX_STATUS
 648 ixNpeDlImageDownload (IxNpeDlImageId *imageIdPtr,
 649             BOOL verify);
 650
 651 /**
 652  * @ingroup IxNpeDl
 653  *
 654  * @fn PUBLIC IX_STATUS ixNpeDlAvailableImagesCountGet (UINT32 *numImagesPtr)
 655  *
 656  * @brief Get the number of Images available in a microcode image library
 657  *
 658  * @param numImagesPtr UINT32* [out] - A pointer to the number of images in
 659  *                                       the image library.
 660  *
 661  * Gets the number of images available in the microcode image library.
 662  * Then returns this in a variable pointed to by <i>numImagesPtr</i>.
 663  *
 664  * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 665  *       It will be removed in a future release.
 666  *       See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
 667  *
 668  * @pre
 669  *     - The Client should declare the variable to which numImagesPtr points
 670  *
 671  * @post
 672  *
 673  * @return
 674  *     - IX_SUCCESS if the operation was successful
 675  *     - IX_NPEDL_PARAM_ERR if a parameter error occured
 676  *     - IX_FAIL otherwise
 677  */
 678 PUBLIC IX_STATUS
 679 ixNpeDlAvailableImagesCountGet (UINT32 *numImagesPtr);
 680
 681 /**
 682  * @ingroup IxNpeDl
 683  *
 684  * @fn PUBLIC IX_STATUS ixNpeDlAvailableImagesListGet (IxNpeDlImageId *imageIdListPtr,
 685                                                          UINT32 *listSizePtr)
 686  *
 687  * @brief Get a list of the images available in a microcode image library
 688  *
 689  * @param imageIdListPtr @ref IxNpeDlImageId* [out] - Array to contain list of
 690  *                                                   image Ids (memory
 691  *                                                   allocated by Client).
 692  * @param listSizePtr UINT32* [inout]  - As an input, this param should point
 693  *                                       to the max number of Ids the
 694  *                                       <i>imageIdListPtr</i> array can
 695  *                                       hold. NpeDl will replace the input
 696  *                                       value of this parameter with the
 697  *                                       number of image Ids actually filled
 698  *                                       into the array before returning.
 699  *
 700  * Finds list of images available in the microcode image library.
 701  * Fills these into the array pointed to by <i>imageIdListPtr</i>
 702  *
 703  * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 704  *       It will be removed in a future release.
 705  *       See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
 706  *
 707  * @pre
 708  *     - The Client should declare the variable to which numImagesPtr points
 709  *     - The Client should create an array (<i>imageIdListPtr</i>) large
 710  *       enough to contain all the image Ids in the image library
 711  *
 712  * @post
 713  *
 714  * @return
 715  *     - IX_SUCCESS if the operation was successful
 716  *     - IX_NPEDL_PARAM_ERR if a parameter error occured
 717  *     - IX_FAIL otherwise
 718  */
 719 PUBLIC IX_STATUS
 720 ixNpeDlAvailableImagesListGet (IxNpeDlImageId *imageIdListPtr,
 721                  UINT32 *listSizePtr);
 722
 723 /**
 724  * @ingroup IxNpeDl
 725  *
 726  * @fn PUBLIC IX_STATUS ixNpeDlLoadedImageGet (IxNpeDlNpeId npeId,
 727                                                 IxNpeDlImageId *imageIdPtr)
 728  *
 729  * @brief Gets the Id of the image currently loaded on a particular NPE
 730  *
 731  * @param npeId @ref IxNpeDlNpeId [in]              - Id of the target NPE.
 732  * @param imageIdPtr @ref IxNpeDlImageId* [out]     - Pointer to the where the
 733  *                                               image id should be stored.
 734  *
 735  * If an image of microcode was previously downloaded successfully to the NPE
 736  * by NPE Downloader, this function returns in <i>imageIdPtr</i> the image
 737  * Id of that image loaded on the NPE.
 738  *
 739  * @pre
 740  *     - The Client has allocated memory to the <i>imageIdPtr</i> pointer.
 741  *
 742  * @post
 743  *
 744  * @return
 745  *     -  IX_SUCCESS if the operation was successful
 746  *     -  IX_NPEDL_PARAM_ERR if a parameter error occured
 747  *     -  IX_FAIL if the NPE doesn't currently have a image loaded
 748  */
 749 PUBLIC IX_STATUS
 750 ixNpeDlLoadedImageGet (IxNpeDlNpeId npeId,
 751              IxNpeDlImageId *imageIdPtr);
 752
 753 /**
 754  * @fn PUBLIC IX_STATUS ixNpeDlLatestImageGet (IxNpeDlNpeId npeId, IxNpeDlFunctionalityId
 755                                         functionalityId, IxNpeDlImageId *imageIdPtr)
 756  *
 757  * @brief This instructs NPE Downloader to get Id of the latest version for an
 758  * image that is specified by the client.
 759  *
 760  * @param npeId @ref IxNpeDlNpeId [in]                    - Id of the target NPE.
 761  * @param functionalityId @ref IxNpeDlFunctionalityId [in]    - functionality of the image
 762  * @param imageIdPtr @ref IxNpeDlImageId* [out]               - Pointer to the where the
 763  *                                                         image id should be stored.
 764  *
 765  * This function sets NPE Downloader to return the id of the latest version for
 766  * image.  The user will select the image by providing a particular NPE
 767  * (specifying <i>npeId</i>) with particular functionality (specifying
 768  * <i>FunctionalityId</i>). The most recent version available as determined by the
 769  * highest Major and Minor revision numbers is returned in <i>imageIdPtr</i>.
 770  *
 771  * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 772  *       It will be removed in a future release.
 773  *       See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
 774  *
 775  * @return
 776  *      - IX_SUCCESS if the operation was successful
 777  *      - IX_NPEDL_PARAM_ERR if a parameter error occured
 778  *      - IX_FAIL otherwise
 779  */
 780 PUBLIC IX_STATUS
 781 ixNpeDlLatestImageGet (IxNpeDlNpeId npeId,
 782              IxNpeDlFunctionalityId functionalityId,
 783                     IxNpeDlImageId *imageIdPtr);
 784
 785 /**
 786  * @ingroup IxNpeDl
 787  *
 788  * @fn PUBLIC IX_STATUS ixNpeDlNpeStopAndReset (IxNpeDlNpeId npeId)
 789  *
 790  * @brief Stops and Resets an NPE
 791  *
 792  * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE.
 793  *
 794  * This function performs a soft NPE reset by writing reset values to
 795  * particular NPE registers. Note that this does not reset NPE co-processors.
 796  * This implicitly stops NPE code execution before resetting the NPE.
 797  *
 798  * @note It is no longer necessary to call this function before downloading
 799  * a new image to the NPE.  It is left on the API only to allow greater control
 800  * of NPE execution if required.  Where appropriate, use @ref ixNpeDlNpeInitAndStart
 801  * or @ref ixNpeDlCustomImageNpeInitAndStart instead.
 802  *
 803  * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 804  *       It will be removed in a future release.
 805  *       See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
 806  *
 807  * @pre
 808  *     - The Client is responsible for ensuring mutual access to the NPE.
 809  *
 810  * @post
 811  *
 812  * @return
 813  *      - IX_SUCCESS if the operation was successful
 814  *      - IX_NPEDL_PARAM_ERR if a parameter error occured
 815  *      - IX_FAIL otherwise
 816  *      - IX_NPEDL_CRITICAL_NPE_ERR failed to reset NPE due to timeout error.
 817  *        Timeout error could happen if NPE hang
 818  */
 819 PUBLIC IX_STATUS
 820 ixNpeDlNpeStopAndReset (IxNpeDlNpeId npeId);
 821
 822 /**
 823  * @ingroup IxNpeDl
 824  *
 825  * @fn PUBLIC IX_STATUS ixNpeDlNpeExecutionStart (IxNpeDlNpeId npeId)
 826  *
 827  * @brief Starts code execution on a NPE
 828  *
 829  * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE
 830  *
 831  * Starts execution of code on a particular NPE.  A client would typically use
 832  * this after a download to NPE is performed, to start/restart code execution
 833  * on the NPE.
 834  *
 835  * @note It is no longer necessary to call this function after downloading
 836  * a new image to the NPE.  It is left on the API only to allow greater control
 837  * of NPE execution if required.  Where appropriate, use @ref ixNpeDlNpeInitAndStart
 838  * or @ref ixNpeDlCustomImageNpeInitAndStart instead.
 839  *
 840  * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 841  *       It will be removed in a future release.
 842  *       See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
 843  *
 844  * @pre
 845  *     - The Client is responsible for ensuring mutual access to the NPE.
 846  *     - Note that this function does not set the NPE Next Program Counter
 847  *       (NextPC), so it should be set beforehand if required by downloading
 848  *       appropriate State Information (using ixNpeDlVersionDownload()).
 849  *
 850  * @post
 851  *
 852  * @return
 853  *      - IX_SUCCESS if the operation was successful
 854  *      - IX_NPEDL_PARAM_ERR if a parameter error occured
 855  *      - IX_FAIL otherwise
 856  */
 857 PUBLIC IX_STATUS
 858 ixNpeDlNpeExecutionStart (IxNpeDlNpeId npeId);
 859
 860 /**
 861  * @ingroup IxNpeDl
 862  *
 863  * @fn PUBLIC IX_STATUS ixNpeDlNpeExecutionStop (IxNpeDlNpeId npeId)
 864  *
 865  * @brief Stops code execution on a NPE
 866  *
 867  * @param npeId @ref IxNpeDlNpeId [in] - Id of the target NPE
 868  *
 869  * Stops execution of code on a particular NPE.  This would typically be used
 870  * by a client before a download to NPE is performed, to stop code execution on
 871  * an NPE, unless ixNpeDlNpeStopAndReset() is used instead.  Unlike
 872  * ixNpeDlNpeStopAndReset(), this function only halts the NPE and leaves
 873  * all registers and settings intact. This is useful, for example, between
 874  * stages of a multi-stage download, to stop the NPE prior to downloading the
 875  * next image while leaving the current state of the NPE intact..
 876  *
 877  * @warning <b>THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.</b>
 878  *       It will be removed in a future release.
 879  *       See @ref ixNpeDlNpeInitAndStart and @ref ixNpeDlCustomImageNpeInitAndStart.
 880  *
 881  * @pre
 882  *     - The Client is responsible for ensuring mutual access to the NPE.
 883  *
 884  * @post
 885  *
 886  * @return
 887  *      - IX_SUCCESS if the operation was successful
 888  *      - IX_NPEDL_PARAM_ERR if a parameter error occured
 889  *      - IX_FAIL otherwise
 890  */
 891 PUBLIC IX_STATUS
 892 ixNpeDlNpeExecutionStop (IxNpeDlNpeId npeId);
 893
 894 /**
 895  * @ingroup IxNpeDl
 896  *
 897  * @fn PUBLIC IX_STATUS ixNpeDlUnload (void)
 898  *
 899  * @brief This function will uninitialise the IxNpeDl component.
 900  *
 901  * This function will uninitialise the IxNpeDl component.  It should only be
 902  * called once, and only if the IxNpeDl component has already been initialised by
 903  * calling any of the following functions:
 904  * - @ref ixNpeDlNpeInitAndStart
 905  * - @ref ixNpeDlCustomImageNpeInitAndStart
 906  * - @ref ixNpeDlImageDownload     (deprecated)
 907  * - @ref ixNpeDlNpeStopAndReset   (deprecated)
 908  * - @ref ixNpeDlNpeExecutionStop  (deprecated)
 909  * - @ref ixNpeDlNpeExecutionStart (deprecated)
 910  *
 911  * If possible, this function should be called before a soft reboot or unloading
 912  * a kernel module to perform any clean up operations required for IxNpeDl.
 913  *
 914  * The following actions will be performed by this function:
 915  * - Unmapping of any kernel memory mapped by IxNpeDl
 916  *
 917  * @return
 918  *      - IX_SUCCESS if the operation was successful
 919  *      - IX_FAIL otherwise
 920  */
 921
 922 PUBLIC IX_STATUS
 923 ixNpeDlUnload (void);
 924
 925 /**
 926  * @ingroup IxNpeDl
 927  *
 928  * @fn PUBLIC void ixNpeDlStatsShow (void)
 929  *
 930  * @brief This function will display run-time statistics from the IxNpeDl
 931  *        component
 932  *
 933  * @return none
 934  */
 935 PUBLIC void
 936 ixNpeDlStatsShow (void);
 937
 938 /**
 939  * @ingroup IxNpeDl
 940  *
 941  * @fn PUBLIC void ixNpeDlStatsReset (void)
 942  *
 943  * @brief This function will reset the statistics of the IxNpeDl component
 944  *
 945  * @return none
 946  */
 947 PUBLIC void
 948 ixNpeDlStatsReset (void);
 949
 950 #endif /* IXNPEDL_H */
 951
 952 /**
 953  * @} defgroup IxNpeDl
 954  */
 955
 956