drivers/net/npe/include/IxNpeDlNpeMgrUtils_p.h

   1 /**
   2  * @file IxNpeDlNpeMgrUtils_p.h
   3  *
   4  * @author Intel Corporation
   5  * @date 18 February 2002
   6  * @brief This file contains the private API for the NpeMgr 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
  25 /**
  26  * @defgroup IxNpeDlNpeMgrUtils_p IxNpeDlNpeMgrUtils_p
  27  *
  28  * @brief The private API for the IxNpeDl NpeMgr Utils module
  29  *
  30  * @{
  31  */
  32
  33 #ifndef IXNPEDLNPEMGRUTILS_P_H
  34 #define IXNPEDLNPEMGRUTILS_P_H
  35
  36
  37 /*
  38  * Put the user defined include files required.
  39  */
  40 #include "IxNpeDl.h"
  41 #include "IxOsalTypes.h"
  42 #include "IxNpeDlNpeMgrEcRegisters_p.h"
  43
  44
  45 /*
  46  * Function Prototypes
  47  */
  48
  49 /**
  50  * @fn IX_STATUS ixNpeDlNpeMgrInsMemWrite (UINT32 npeBaseAddress,
  51                                            UINT32 insMemAddress,
  52                                            UINT32 insMemData,
  53                                            BOOL verify)
  54  *
  55  * @brief Writes a word to NPE Instruction memory
  56  *
  57  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
  58  * @param UINT32 [in] insMemAddress  - NPE instruction memory address to write
  59  * @param UINT32 [in] insMemData     - data to write to instruction memory
  60  * @param BOOL   [in] verify         - if true, verify the memory location is
  61  *                                     written successfully.
  62  *
  63  * This function is used to write a single word of data to a location in NPE
  64  * instruction memory.  If the <i>verify</i> option is ON, NpeDl will read back
  65  * from the memory location to verify that it was written successfully
  66  *
  67  * @pre
  68  *
  69  * @post
  70  *
  71  * @return
  72  *    - IX_FAIL if verify is true and the memory location was not written
  73  *      successfully
  74  *    - IX_SUCCESS otherwise
  75  */
  76 IX_STATUS
  77 ixNpeDlNpeMgrInsMemWrite (UINT32 npeBaseAddress, UINT32 insMemAddress,
  78                           UINT32 insMemData, BOOL verify);
  79
  80
  81 /**
  82  * @fn IX_STATUS ixNpeDlNpeMgrDataMemWrite (UINT32 npeBaseAddress,
  83                                             UINT32 dataMemAddress,
  84                                             UINT32 dataMemData,
  85                                             BOOL verify)
  86  *
  87  * @brief Writes a word to NPE Data memory
  88  *
  89  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
  90  * @param UINT32 [in] dataMemAddress - NPE data memory address to write
  91  * @param UINT32 [in] dataMemData    - data to write to NPE data memory
  92  * @param BOOL   [in] verify         - if true, verify the memory location is
  93  *                                     written successfully.
  94  *
  95  * This function is used to write a single word of data to a location in NPE
  96  * data memory.  If the <i>verify</i> option is ON, NpeDl will read back from
  97  * the memory location to verify that it was written successfully
  98  *
  99  * @pre
 100  *
 101  * @post
 102  *
 103  * @return
 104  *    - IX_FAIL if verify is true and the memory location was not written
 105  *      successfully
 106  *    - IX_SUCCESS otherwise
 107  */
 108 IX_STATUS
 109 ixNpeDlNpeMgrDataMemWrite (UINT32 npeBaseAddress, UINT32 dataMemAddress,
 110                            UINT32 dataMemData, BOOL verify);
 111
 112
 113 /**
 114  * @fn void ixNpeDlNpeMgrExecAccRegWrite (UINT32 npeBaseAddress,
 115                                           UINT32 regAddress,
 116                                           UINT32 regData)
 117  *
 118  * @brief Writes a word to an NPE Execution Access register
 119  *
 120  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
 121  * @param UINT32 [in] regAddress     - NPE Execution Access register address
 122  * @param UINT32 [in] regData        - data to write to register
 123  *
 124  * This function is used to write a single word of data to an NPE Execution
 125  * Access register.
 126  *
 127  * @pre
 128  *
 129  * @post
 130  *
 131  * @return none
 132  */
 133 void
 134 ixNpeDlNpeMgrExecAccRegWrite (UINT32 npeBaseAddress, UINT32 regAddress,
 135                               UINT32 regData);
 136
 137
 138 /**
 139  * @fn UINT32 ixNpeDlNpeMgrExecAccRegRead (UINT32 npeBaseAddress,
 140                                            UINT32 regAddress)
 141  *
 142  * @brief Reads the contents of an NPE Execution Access register
 143  *
 144  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
 145  * @param UINT32 [in] regAddress     - NPE Execution Access register address
 146  *
 147  * This function is used to read the contents of an NPE Execution
 148  * Access register.
 149  *
 150  * @pre
 151  *
 152  * @post
 153  *
 154  * @return The value read from the Execution Access register
 155  */
 156 UINT32
 157 ixNpeDlNpeMgrExecAccRegRead (UINT32 npeBaseAddress, UINT32 regAddress);
 158
 159
 160 /**
 161  * @fn void ixNpeDlNpeMgrCommandIssue (UINT32 npeBaseAddress,
 162                                        UINT32 command)
 163  *
 164  * @brief Issues an NPE Execution Control command
 165  *
 166  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
 167  * @param UINT32 [in] command        - Command to issue
 168  *
 169  * This function is used to issue a stand-alone NPE Execution Control command
 170  * (e.g. command to Stop NPE execution)
 171  *
 172  * @pre
 173  *
 174  * @post
 175  *
 176  * @return none
 177  */
 178 void
 179 ixNpeDlNpeMgrCommandIssue (UINT32 npeBaseAddress, UINT32 command);
 180
 181
 182 /**
 183  * @fn void ixNpeDlNpeMgrDebugInstructionPreExec (UINT32 npeBaseAddress)
 184  *
 185  * @brief Prepare to executes one or more NPE instructions in the Debug
 186  *        Execution Stack level.
 187  *
 188  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
 189  *
 190  * This function should be called once before a sequence of calls to
 191  * ixNpeDlNpeMgrDebugInstructionExec().
 192  *
 193  * @pre
 194  *
 195  * @post
 196  *     - ixNpeDlNpeMgrDebugInstructionPostExec() should be called to restore
 197  *       registers values altered by this function
 198  *
 199  * @return none
 200  */
 201 void
 202 ixNpeDlNpeMgrDebugInstructionPreExec (UINT32 npeBaseAddress);
 203
 204
 205 /**
 206  * @fn IX_STATUS ixNpeDlNpeMgrDebugInstructionExec (UINT32 npeBaseAddress,
 207                                                UINT32 npeInstruction,
 208                                                UINT32 ctxtNum,
 209                                                UINT32 ldur)
 210  *
 211  * @brief Executes a single instruction on the NPE at the Debug Execution Stack
 212  *        level
 213  *
 214  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
 215  * @param UINT32 [in] npeInstruction - Value to write to INSTR (Instruction)
 216  *                                     register
 217  * @param UINT32 [in] ctxtNum        - context the instruction will be executed
 218  *                                     in and which context store it may access
 219  * @param UINT32 [in] ldur           - Long Immediate Duration, set to non-zero
 220  *                                     to use long-immediate mode instruction
 221  *
 222  * This function is used to execute a single instruction in the NPE pipeline at
 223  * the debug Execution Context Stack level. It won't disturb the state of other
 224  * executing contexts.  Its useful for performing NPE operations, such as
 225  * writing to NPE Context Store registers and physical registers, that cannot
 226  * be carried out directly using the Configuration Bus registers. This function
 227  * will return TIMEOUT status if NPE not responding due to NPS is hang / halt.
 228  *
 229  * @pre
 230  *     - The NPE should be stopped and in a clean state
 231  *     - ixNpeDlNpeMgrDebugInstructionPreExec() should be called once before
 232  *       a sequential of 1 or more calls to this function
 233  *
 234  * @post
 235  *     - ixNpeDlNpeMgrDebugInstructionPostExec() should be called after
 236  *       a sequence of calls to this function
 237  *
 238  * @return
 239  *    - IX_NPEDL_CRITICAL_NPE_ERR if execution of instruction failed / timeout
 240  *    - IX_SUCCESS otherwise
 241  */
 242 IX_STATUS
 243 ixNpeDlNpeMgrDebugInstructionExec (UINT32 npeBaseAddress,
 244                                    UINT32 npeInstruction,
 245                                    UINT32 ctxtNum, UINT32 ldur);
 246
 247
 248 /**
 249  * @fn void ixNpeDlNpeMgrDebugInstructionPostExec (UINT32 npeBaseAddress)
 250  *
 251  * @brief Clean up after executing one or more NPE instructions in the
 252  *        Debug Stack Level
 253  *
 254  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
 255  *
 256  * This function should be called once following a sequence of calls to
 257  * ixNpeDlNpeMgrDebugInstructionExec().
 258  *
 259  * @pre
 260  *    -  ixNpeDlNpeMgrDebugInstructionPreExec() was called earlier
 261  *
 262  * @post
 263  *    -  The Instruction Pipeline will cleared
 264  *
 265  * @return none
 266  */
 267 void
 268 ixNpeDlNpeMgrDebugInstructionPostExec (UINT32 npeBaseAddress);
 269
 270
 271 /**
 272  * @fn IX_STATUS ixNpeDlNpeMgrPhysicalRegWrite (UINT32 npeBaseAddress,
 273                                                 UINT32 regAddr,
 274                                                 UINT32 regValue,
 275                                                 BOOL verify)
 276  *
 277  * @brief Write one of the 32* 32-bit physical registers in the NPE data
 278  *        register file
 279  *
 280  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
 281  * @param UINT32 [in] regAddr        - number of the physical register (0-31)*
 282  * @param UINT32 [in] regValue       - value to write to the physical register
 283  * @param BOOL   [in] verify         - if true, verify the register is written
 284  *                                     successfully.
 285  *
 286  * This function writes a physical register in the NPE data register file.
 287  * If the <i>verify</i> option is ON, NpeDl will read back the register to
 288  * verify that it was written successfully
 289  * *Note that release 1.0 of this software supports 32 physical
 290  * registers, but 64 may be supported in future versions.
 291  *
 292  * @pre
 293  *    - The NPE should be stopped and in a clean state
 294  *    - ixNpeDlNpeMgrDebugInstructionPreExec() should be called once before
 295  *      a sequential of 1 or more calls to this function
 296  *
 297  * @post
 298  *    - Contents of REGMAP Context Store register for Context 0 will be altered
 299  *    - ixNpeDlNpeMgrDebugInstructionPostExec() should be called after
 300  *      a sequence of calls to this function
 301  *
 302  * @return
 303  *    - IX_FAIL if verify is true and the Context Register was not written
 304  *      successfully
 305  *    - IX_SUCCESS if Context Register was written successfully
 306  *    - IX_NPEDL_CRITICAL_NPE_ERR if Context Register was not written
 307  *      successfully due to timeout error where NPE is not responding
 308  */
 309 IX_STATUS
 310 ixNpeDlNpeMgrPhysicalRegWrite (UINT32 npeBaseAddress, UINT32 regAddr,
 311                                UINT32 regValue, BOOL verify);
 312
 313
 314 /**
 315  * @fn IX_STATUS ixNpeDlNpeMgrCtxtRegWrite (UINT32 npeBaseAddress,
 316                                             UINT32 ctxtNum,
 317                                             IxNpeDlCtxtRegNum ctxtReg,
 318                                             UINT32 ctxtRegVal,
 319                                             BOOL verify)
 320  *
 321  * @brief Writes a value to a Context Store register on an NPE
 322  *
 323  * @param UINT32 [in] npeBaseAddress     - Base Address of NPE
 324  * @param UINT32 [in] ctxtNum            - context store to access
 325  * @param IxNpeDlCtxtRegNum [in] ctxtReg - which Context Store reg to write
 326  * @param UINT32 [in] ctxtRegVal         - value to write to the Context Store
 327  *                                         register
 328  * @param BOOL   [in] verify             - if true, verify the register is
 329  *                                         written successfully.
 330  *
 331  * This function writes the contents of a Context Store register in the NPE
 332  * register file. If the <i>verify</i> option is ON, NpeDl will read back the
 333  * register to verify that it was written successfully
 334  *
 335  * @pre
 336  *    - The NPE should be stopped and in a clean state
 337  *    - ixNpeDlNpeMgrDebugInstructionPreExec() should be called once before
 338  *      a sequential of 1 or more calls to this function
 339  *
 340  * @post
 341  *    - ixNpeDlNpeMgrDebugInstructionPostExec() should be called after
 342  *      a sequence of calls to this function
 343  *
 344  * @return
 345  *    - IX_FAIL if verify is true and the Context Register was not written
 346  *      successfully
 347  *    - IX_SUCCESS if Context Register was written successfully
 348  *    - IX_NPEDL_CRITICAL_NPE_ERR if Context Register was not written
 349  *      successfully due to timeout error where NPE is not responding
 350  */
 351 IX_STATUS
 352 ixNpeDlNpeMgrCtxtRegWrite (UINT32 npeBaseAddress, UINT32 ctxtNum,
 353                            IxNpeDlCtxtRegNum ctxtReg, UINT32 ctxtRegVal,
 354                            BOOL verify);
 355
 356
 357 /**
 358  * @fn void ixNpeDlNpeMgrUtilsStatsShow (void)
 359  *
 360  * @brief This function will display the statistics of the IxNpeDl NpeMgrUtils
 361  *        module
 362  *
 363  * @return none
 364  */
 365 void
 366 ixNpeDlNpeMgrUtilsStatsShow (void);
 367
 368
 369 /**
 370  * @fn void ixNpeDlNpeMgrUtilsStatsReset (void)
 371  *
 372  * @brief This function will reset the statistics of the IxNpeDl NpeMgrUtils
 373  *        module
 374  *
 375  * @return none
 376  */
 377 void
 378 ixNpeDlNpeMgrUtilsStatsReset (void);
 379
 380
 381 #endif  /* IXNPEDLNPEMGRUTILS_P_H */