IxNpeDl.h 32 KB

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