IxNpeDlImageMgr_p.h 9.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339
  1. /**
  2. * @file IxNpeDlImageMgr_p.h
  3. *
  4. * @author Intel Corporation
  5. * @date 14 December 2001
  6. * @brief This file contains the private API for the ImageMgr module
  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 IxNpeDlImageMgr_p IxNpeDlImageMgr_p
  25. *
  26. * @brief The private API for the IxNpeDl ImageMgr module
  27. *
  28. * @{
  29. */
  30. #ifndef IXNPEDLIMAGEMGR_P_H
  31. #define IXNPEDLIMAGEMGR_P_H
  32. /*
  33. * Put the user defined include files required.
  34. */
  35. #include "IxNpeDl.h"
  36. #include "IxOsalTypes.h"
  37. /*
  38. * #defines and macros
  39. */
  40. /**
  41. * @def IX_NPEDL_IMAGEMGR_SIGNATURE
  42. *
  43. * @brief Signature found as 1st word in a microcode image library
  44. */
  45. #define IX_NPEDL_IMAGEMGR_SIGNATURE 0xDEADBEEF
  46. /**
  47. * @def IX_NPEDL_IMAGEMGR_END_OF_HEADER
  48. *
  49. * @brief Marks end of header in a microcode image library
  50. */
  51. #define IX_NPEDL_IMAGEMGR_END_OF_HEADER 0xFFFFFFFF
  52. /**
  53. * @def IX_NPEDL_IMAGEID_NPEID_OFFSET
  54. *
  55. * @brief Offset from LSB of NPE ID field in Image ID
  56. */
  57. #define IX_NPEDL_IMAGEID_NPEID_OFFSET 24
  58. /**
  59. * @def IX_NPEDL_IMAGEID_DEVICEID_OFFSET
  60. *
  61. * @brief Offset from LSB of Device ID field in Image ID
  62. */
  63. #define IX_NPEDL_IMAGEID_DEVICEID_OFFSET 28
  64. /**
  65. * @def IX_NPEDL_IMAGEID_FUNCTIONID_OFFSET
  66. *
  67. * @brief Offset from LSB of Functionality ID field in Image ID
  68. */
  69. #define IX_NPEDL_IMAGEID_FUNCTIONID_OFFSET 16
  70. /**
  71. * @def IX_NPEDL_IMAGEID_MAJOR_OFFSET
  72. *
  73. * @brief Offset from LSB of Major revision field in Image ID
  74. */
  75. #define IX_NPEDL_IMAGEID_MAJOR_OFFSET 8
  76. /**
  77. * @def IX_NPEDL_IMAGEID_MINOR_OFFSET
  78. *
  79. * @brief Offset from LSB of Minor revision field in Image ID
  80. */
  81. #define IX_NPEDL_IMAGEID_MINOR_OFFSET 0
  82. /**
  83. * @def IX_NPEDL_NPEID_FROM_IMAGEID_GET
  84. *
  85. * @brief Macro to extract NPE ID field from Image ID
  86. */
  87. #define IX_NPEDL_NPEID_FROM_IMAGEID_GET(imageId) \
  88. (((imageId) >> IX_NPEDL_IMAGEID_NPEID_OFFSET) & \
  89. IX_NPEDL_NPEIMAGE_NPEID_MASK)
  90. /**
  91. * @def IX_NPEDL_DEVICEID_FROM_IMAGEID_GET
  92. *
  93. * @brief Macro to extract NPE ID field from Image ID
  94. */
  95. #define IX_NPEDL_DEVICEID_FROM_IMAGEID_GET(imageId) \
  96. (((imageId) >> IX_NPEDL_IMAGEID_DEVICEID_OFFSET) & \
  97. IX_NPEDL_NPEIMAGE_DEVICEID_MASK)
  98. /**
  99. * @def IX_NPEDL_FUNCTIONID_FROM_IMAGEID_GET
  100. *
  101. * @brief Macro to extract Functionality ID field from Image ID
  102. */
  103. #define IX_NPEDL_FUNCTIONID_FROM_IMAGEID_GET(imageId) \
  104. (((imageId) >> IX_NPEDL_IMAGEID_FUNCTIONID_OFFSET) & \
  105. IX_NPEDL_NPEIMAGE_FIELD_MASK)
  106. /**
  107. * @def IX_NPEDL_MAJOR_FROM_IMAGEID_GET
  108. *
  109. * @brief Macro to extract Major revision field from Image ID
  110. */
  111. #define IX_NPEDL_MAJOR_FROM_IMAGEID_GET(imageId) \
  112. (((imageId) >> IX_NPEDL_IMAGEID_MAJOR_OFFSET) & \
  113. IX_NPEDL_NPEIMAGE_FIELD_MASK)
  114. /**
  115. * @def IX_NPEDL_MINOR_FROM_IMAGEID_GET
  116. *
  117. * @brief Macro to extract Minor revision field from Image ID
  118. */
  119. #define IX_NPEDL_MINOR_FROM_IMAGEID_GET(imageId) \
  120. (((imageId) >> IX_NPEDL_IMAGEID_MINOR_OFFSET) & \
  121. IX_NPEDL_NPEIMAGE_FIELD_MASK)
  122. /*
  123. * Prototypes for interface functions
  124. */
  125. /**
  126. * @fn IX_STATUS ixNpeDlImageMgrMicrocodeImageLibraryOverride (UINT32 *clientImageLibrary)
  127. *
  128. * @brief This instructs NPE Downloader to use client-supplied microcode image library.
  129. *
  130. * This function sets NPE Downloader to use a client-supplied microcode image library
  131. * instead of the standard image library which is included by the NPE Downloader.
  132. *
  133. * @note THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.
  134. * It will be removed in a future release.
  135. * See API header file IxNpeDl.h for more information.
  136. *
  137. * @pre
  138. * - <i>clientImageLibrary</i> should point to a microcode image library valid for use
  139. * by the NPE Downloader component.
  140. *
  141. * @post
  142. * - the client-supplied image uibrary will be used for all subsequent operations
  143. * performed by the NPE Downloader
  144. *
  145. * @return
  146. * - IX_SUCCESS if the operation was successful
  147. * - IX_FAIL if the client-supplied image library did not contain a valid signature
  148. */
  149. IX_STATUS
  150. ixNpeDlImageMgrMicrocodeImageLibraryOverride (UINT32 *clientImageLibrary);
  151. /**
  152. * @fn IX_STATUS ixNpeDlImageMgrImageListExtract (IxNpeDlImageId *imageListPtr,
  153. UINT32 *numImages)
  154. *
  155. * @brief Extracts a list of images available in the NPE microcode image library.
  156. *
  157. * @param IxNpeDlImageId* [out] imageListPtr - pointer to array to contain
  158. * a list of images. If NULL,
  159. * only the number of images
  160. * is returned (in
  161. * <i>numImages</i>)
  162. * @param UINT32* [inout] numImages - As input, it points to a variable
  163. * containing the number of images which
  164. * can be stored in the
  165. * <i>imageListPtr</i> array. Its value
  166. * is ignored as input if
  167. * <i>imageListPtr</i> is NULL. As an
  168. * output, it will contain number of
  169. * images in the image library.
  170. *
  171. * This function reads the header of the microcode image library and extracts a list of the
  172. * images available in the image library. It can also be used to find the number of
  173. * images in the image library.
  174. *
  175. * @note THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.
  176. * It will be removed in a future release.
  177. * See API header file IxNpeDl.h for more information.
  178. *
  179. * @pre
  180. * - if <i>imageListPtr</i> != NULL, <i>numImages</i> should reflect the
  181. * number of image Id elements the <i>imageListPtr</i> can contain.
  182. *
  183. * @post
  184. * - <i>numImages</i> will reflect the number of image Id's found in the
  185. * microcode image library.
  186. *
  187. * @return
  188. * - IX_SUCCESS if the operation was successful
  189. * - IX_FAIL otherwise
  190. */
  191. IX_STATUS
  192. ixNpeDlImageMgrImageListExtract (IxNpeDlImageId *imageListPtr,
  193. UINT32 *numImages);
  194. /**
  195. * @fn IX_STATUS ixNpeDlImageMgrImageLocate (IxNpeDlImageId *imageId,
  196. UINT32 **imagePtr,
  197. UINT32 *imageSize)
  198. *
  199. * @brief Finds a image block in the NPE microcode image library.
  200. *
  201. * @param IxNpeDlImageId* [in] imageId - the id of the image to locate
  202. * @param UINT32** [out] imagePtr - pointer to the image in memory
  203. * @param UINT32* [out] imageSize - size (in 32-bit words) of image
  204. *
  205. * This function examines the header of the microcode image library for the location
  206. * and size of the specified image.
  207. *
  208. * @note THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.
  209. * It will be removed in a future release.
  210. * See API header file IxNpeDl.h for more information.
  211. *
  212. * @pre
  213. *
  214. * @post
  215. *
  216. * @return
  217. * - IX_SUCCESS if the operation was successful
  218. * - IX_FAIL otherwise
  219. */
  220. IX_STATUS
  221. ixNpeDlImageMgrImageLocate (IxNpeDlImageId *imageId,
  222. UINT32 **imagePtr,
  223. UINT32 *imageSize);
  224. /**
  225. * @fn IX_STATUS ixNpeDlImageMgrLatestImageExtract (IxNpeDlImageId *imageId)
  226. *
  227. * @brief Finds the most recent version of an image in the NPE image library.
  228. *
  229. * @param IxNpeDlImageId* [inout] imageId - the id of the image
  230. *
  231. * This function determines the most recent version of a specified image by its
  232. * higest major release and minor revision numbers
  233. *
  234. * @note THIS FUNCTION HAS BEEN DEPRECATED AND SHOULD NOT BE USED.
  235. * It will be removed in a future release.
  236. * See API header file IxNpeDl.h for more information.
  237. *
  238. * @pre
  239. *
  240. * @post
  241. *
  242. * @return
  243. * - IX_SUCCESS if the operation was successful
  244. * - IX_FAIL otherwise
  245. */
  246. IX_STATUS
  247. ixNpeDlImageMgrLatestImageExtract (IxNpeDlImageId *imageId);
  248. /**
  249. * @fn void ixNpeDlImageMgrStatsShow (void)
  250. *
  251. * @brief This function will display the statistics of the IxNpeDl ImageMgr
  252. * module
  253. *
  254. * @return none
  255. */
  256. void
  257. ixNpeDlImageMgrStatsShow (void);
  258. /**
  259. * @fn void ixNpeDlImageMgrStatsReset (void)
  260. *
  261. * @brief This function will reset the statistics of the IxNpeDl ImageMgr
  262. * module
  263. *
  264. * @return none
  265. */
  266. void
  267. ixNpeDlImageMgrStatsReset (void);
  268. /**
  269. * @fn IX_STATUS ixNpeDlImageMgrImageGet (UINT32 *imageLibrary,
  270. UINT32 imageId,
  271. UINT32 **imagePtr,
  272. UINT32 *imageSize)
  273. *
  274. * @brief Finds a image block in the NPE microcode image library.
  275. *
  276. * @param UINT32* [in] imageLibrary - the image library to use
  277. * @param UINT32 [in] imageId - the id of the image to locate
  278. * @param UINT32** [out] imagePtr - pointer to the image in memory
  279. * @param UINT32* [out] imageSize - size (in 32-bit words) of image
  280. *
  281. * This function examines the header of the specified microcode image library
  282. * for the location and size of the specified image. It returns a pointer to
  283. * the image in the <i>imagePtr</i> parameter.
  284. * If no image library is specified (imageLibrary == NULL), then the default
  285. * built-in image library will be used.
  286. *
  287. * @pre
  288. *
  289. * @post
  290. *
  291. * @return
  292. * - IX_SUCCESS if the operation was successful
  293. * - IX_FAIL otherwise
  294. */
  295. IX_STATUS
  296. ixNpeDlImageMgrImageFind (UINT32 *imageLibrary,
  297. UINT32 imageId,
  298. UINT32 **imagePtr,
  299. UINT32 *imageSize);
  300. #endif /* IXNPEDLIMAGEMGR_P_H */
  301. /**
  302. * @} defgroup IxNpeDlImageMgr_p
  303. */