cpu/ixp/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  * Redistribution and use in source and binary forms, with or without
  20  * modification, are permitted provided that the following conditions
  21  * are met:
  22  * 1. Redistributions of source code must retain the above copyright
  23  *    notice, this list of conditions and the following disclaimer.
  24  * 2. Redistributions in binary form must reproduce the above copyright
  25  *    notice, this list of conditions and the following disclaimer in the
  26  *    documentation and/or other materials provided with the distribution.
  27  * 3. Neither the name of the Intel Corporation nor the names of its contributors
  28  *    may be used to endorse or promote products derived from this software
  29  *    without specific prior written permission.
  30  *
  31  * @par
  32  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
  33  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  34  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  35  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
  36  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  37  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  38  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  39  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  40  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  41  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  42  * SUCH DAMAGE.
  43  *
  44  * @par
  45  * -- End of Copyright Notice --
  46 */
  47
  48
  49 /**
  50  * @defgroup IxNpeDlNpeMgrUtils_p IxNpeDlNpeMgrUtils_p
  51  *
  52  * @brief The private API for the IxNpeDl NpeMgr Utils module
  53  *
  54  * @{
  55  */
  56
  57 #ifndef IXNPEDLNPEMGRUTILS_P_H
  58 #define IXNPEDLNPEMGRUTILS_P_H
  59
  60
  61 /*
  62  * Put the user defined include files required.
  63  */
  64 #include "IxNpeDl.h"
  65 #include "IxOsalTypes.h"
  66 #include "IxNpeDlNpeMgrEcRegisters_p.h"
  67
  68
  69 /*
  70  * Function Prototypes
  71  */
  72
  73 /**
  74  * @fn IX_STATUS ixNpeDlNpeMgrInsMemWrite (UINT32 npeBaseAddress,
  75                                            UINT32 insMemAddress,
  76                                            UINT32 insMemData,
  77                                            BOOL verify)
  78  *
  79  * @brief Writes a word to NPE Instruction memory
  80  *
  81  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
  82  * @param UINT32 [in] insMemAddress  - NPE instruction memory address to write
  83  * @param UINT32 [in] insMemData     - data to write to instruction memory
  84  * @param BOOL   [in] verify         - if TRUE, verify the memory location is
  85  *                                     written successfully.
  86  *
  87  * This function is used to write a single word of data to a location in NPE
  88  * instruction memory.  If the <i>verify</i> option is ON, NpeDl will read back
  89  * from the memory location to verify that it was written successfully
  90  *
  91  * @pre
  92  *
  93  * @post
  94  *
  95  * @return
  96  *    - IX_FAIL if verify is TRUE and the memory location was not written
  97  *      successfully
  98  *    - IX_SUCCESS otherwise
  99  */
 100 IX_STATUS
 101 ixNpeDlNpeMgrInsMemWrite (UINT32 npeBaseAddress, UINT32 insMemAddress,
 102                           UINT32 insMemData, BOOL verify);
 103
 104
 105 /**
 106  * @fn IX_STATUS ixNpeDlNpeMgrDataMemWrite (UINT32 npeBaseAddress,
 107                                             UINT32 dataMemAddress,
 108                                             UINT32 dataMemData,
 109                                             BOOL verify)
 110  *
 111  * @brief Writes a word to NPE Data memory
 112  *
 113  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
 114  * @param UINT32 [in] dataMemAddress - NPE data memory address to write
 115  * @param UINT32 [in] dataMemData    - data to write to NPE data memory
 116  * @param BOOL   [in] verify         - if TRUE, verify the memory location is
 117  *                                     written successfully.
 118  *
 119  * This function is used to write a single word of data to a location in NPE
 120  * data memory.  If the <i>verify</i> option is ON, NpeDl will read back from
 121  * the memory location to verify that it was written successfully
 122  *
 123  * @pre
 124  *
 125  * @post
 126  *
 127  * @return
 128  *    - IX_FAIL if verify is TRUE and the memory location was not written
 129  *      successfully
 130  *    - IX_SUCCESS otherwise
 131  */
 132 IX_STATUS
 133 ixNpeDlNpeMgrDataMemWrite (UINT32 npeBaseAddress, UINT32 dataMemAddress,
 134                            UINT32 dataMemData, BOOL verify);
 135
 136
 137 /**
 138  * @fn void ixNpeDlNpeMgrExecAccRegWrite (UINT32 npeBaseAddress,
 139                                           UINT32 regAddress,
 140                                           UINT32 regData)
 141  *
 142  * @brief Writes a word to 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  * @param UINT32 [in] regData        - data to write to register
 147  *
 148  * This function is used to write a single word of data to an NPE Execution
 149  * Access register.
 150  *
 151  * @pre
 152  *
 153  * @post
 154  *
 155  * @return none
 156  */
 157 void
 158 ixNpeDlNpeMgrExecAccRegWrite (UINT32 npeBaseAddress, UINT32 regAddress,
 159                               UINT32 regData);
 160
 161
 162 /**
 163  * @fn UINT32 ixNpeDlNpeMgrExecAccRegRead (UINT32 npeBaseAddress,
 164                                            UINT32 regAddress)
 165  *
 166  * @brief Reads the contents of an NPE Execution Access register
 167  *
 168  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
 169  * @param UINT32 [in] regAddress     - NPE Execution Access register address
 170  *
 171  * This function is used to read the contents of an NPE Execution
 172  * Access register.
 173  *
 174  * @pre
 175  *
 176  * @post
 177  *
 178  * @return The value read from the Execution Access register
 179  */
 180 UINT32
 181 ixNpeDlNpeMgrExecAccRegRead (UINT32 npeBaseAddress, UINT32 regAddress);
 182
 183
 184 /**
 185  * @fn void ixNpeDlNpeMgrCommandIssue (UINT32 npeBaseAddress,
 186                                        UINT32 command)
 187  *
 188  * @brief Issues an NPE Execution Control command
 189  *
 190  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
 191  * @param UINT32 [in] command        - Command to issue
 192  *
 193  * This function is used to issue a stand-alone NPE Execution Control command
 194  * (e.g. command to Stop NPE execution)
 195  *
 196  * @pre
 197  *
 198  * @post
 199  *
 200  * @return none
 201  */
 202 void
 203 ixNpeDlNpeMgrCommandIssue (UINT32 npeBaseAddress, UINT32 command);
 204
 205
 206 /**
 207  * @fn void ixNpeDlNpeMgrDebugInstructionPreExec (UINT32 npeBaseAddress)
 208  *
 209  * @brief Prepare to executes one or more NPE instructions in the Debug
 210  *        Execution Stack level.
 211  *
 212  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
 213  *
 214  * This function should be called once before a sequence of calls to
 215  * ixNpeDlNpeMgrDebugInstructionExec().
 216  *
 217  * @pre
 218  *
 219  * @post
 220  *     - ixNpeDlNpeMgrDebugInstructionPostExec() should be called to restore
 221  *       registers values altered by this function
 222  *
 223  * @return none
 224  */
 225 void
 226 ixNpeDlNpeMgrDebugInstructionPreExec (UINT32 npeBaseAddress);
 227
 228
 229 /**
 230  * @fn IX_STATUS ixNpeDlNpeMgrDebugInstructionExec (UINT32 npeBaseAddress,
 231                                                UINT32 npeInstruction,
 232                                                UINT32 ctxtNum,
 233                                                UINT32 ldur)
 234  *
 235  * @brief Executes a single instruction on the NPE at the Debug Execution Stack
 236  *        level
 237  *
 238  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
 239  * @param UINT32 [in] npeInstruction - Value to write to INSTR (Instruction)
 240  *                                     register
 241  * @param UINT32 [in] ctxtNum        - context the instruction will be executed
 242  *                                     in and which context store it may access
 243  * @param UINT32 [in] ldur           - Long Immediate Duration, set to non-zero
 244  *                                     to use long-immediate mode instruction
 245  *
 246  * This function is used to execute a single instruction in the NPE pipeline at
 247  * the debug Execution Context Stack level. It won't disturb the state of other
 248  * executing contexts.  Its useful for performing NPE operations, such as
 249  * writing to NPE Context Store registers and physical registers, that cannot
 250  * be carried out directly using the Configuration Bus registers. This function
 251  * will return TIMEOUT status if NPE not responding due to NPS is hang / halt.
 252  *
 253  * @pre
 254  *     - The NPE should be stopped and in a clean state
 255  *     - ixNpeDlNpeMgrDebugInstructionPreExec() should be called once before
 256  *       a sequential of 1 or more calls to this function
 257  *
 258  * @post
 259  *     - ixNpeDlNpeMgrDebugInstructionPostExec() should be called after
 260  *       a sequence of calls to this function
 261  *
 262  * @return
 263  *    - IX_NPEDL_CRITICAL_NPE_ERR if execution of instruction failed / timeout
 264  *    - IX_SUCCESS otherwise
 265  */
 266 IX_STATUS
 267 ixNpeDlNpeMgrDebugInstructionExec (UINT32 npeBaseAddress,
 268                                    UINT32 npeInstruction,
 269                                    UINT32 ctxtNum, UINT32 ldur);
 270
 271
 272 /**
 273  * @fn void ixNpeDlNpeMgrDebugInstructionPostExec (UINT32 npeBaseAddress)
 274  *
 275  * @brief Clean up after executing one or more NPE instructions in the
 276  *        Debug Stack Level
 277  *
 278  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
 279  *
 280  * This function should be called once following a sequence of calls to
 281  * ixNpeDlNpeMgrDebugInstructionExec().
 282  *
 283  * @pre
 284  *    -  ixNpeDlNpeMgrDebugInstructionPreExec() was called earlier
 285  *
 286  * @post
 287  *    -  The Instruction Pipeline will cleared
 288  *
 289  * @return none
 290  */
 291 void
 292 ixNpeDlNpeMgrDebugInstructionPostExec (UINT32 npeBaseAddress);
 293
 294
 295 /**
 296  * @fn IX_STATUS ixNpeDlNpeMgrPhysicalRegWrite (UINT32 npeBaseAddress,
 297                                                 UINT32 regAddr,
 298                                                 UINT32 regValue,
 299                                                 BOOL verify)
 300  *
 301  * @brief Write one of the 32* 32-bit physical registers in the NPE data
 302  *        register file
 303  *
 304  * @param UINT32 [in] npeBaseAddress - Base Address of NPE
 305  * @param UINT32 [in] regAddr        - number of the physical register (0-31)*
 306  * @param UINT32 [in] regValue       - value to write to the physical register
 307  * @param BOOL   [in] verify         - if TRUE, verify the register is written
 308  *                                     successfully.
 309  *
 310  * This function writes a physical register in the NPE data register file.
 311  * If the <i>verify</i> option is ON, NpeDl will read back the register to
 312  * verify that it was written successfully
 313  * *Note that release 1.0 of this software supports 32 physical
 314  * registers, but 64 may be supported in future versions.
 315  *
 316  * @pre
 317  *    - The NPE should be stopped and in a clean state
 318  *    - ixNpeDlNpeMgrDebugInstructionPreExec() should be called once before
 319  *      a sequential of 1 or more calls to this function
 320  *
 321  * @post
 322  *    - Contents of REGMAP Context Store register for Context 0 will be altered
 323  *    - ixNpeDlNpeMgrDebugInstructionPostExec() should be called after
 324  *      a sequence of calls to this function
 325  *
 326  * @return
 327  *    - IX_FAIL if verify is TRUE and the Context Register was not written
 328  *      successfully
 329  *    - IX_SUCCESS if Context Register was written successfully
 330  *    - IX_NPEDL_CRITICAL_NPE_ERR if Context Register was not written
 331  *      successfully due to timeout error where NPE is not responding
 332  */
 333 IX_STATUS
 334 ixNpeDlNpeMgrPhysicalRegWrite (UINT32 npeBaseAddress, UINT32 regAddr,
 335                                UINT32 regValue, BOOL verify);
 336
 337
 338 /**
 339  * @fn IX_STATUS ixNpeDlNpeMgrCtxtRegWrite (UINT32 npeBaseAddress,
 340                                             UINT32 ctxtNum,
 341                                             IxNpeDlCtxtRegNum ctxtReg,
 342                                             UINT32 ctxtRegVal,
 343                                             BOOL verify)
 344  *
 345  * @brief Writes a value to a Context Store register on an NPE
 346  *
 347  * @param UINT32 [in] npeBaseAddress     - Base Address of NPE
 348  * @param UINT32 [in] ctxtNum            - context store to access
 349  * @param IxNpeDlCtxtRegNum [in] ctxtReg - which Context Store reg to write
 350  * @param UINT32 [in] ctxtRegVal         - value to write to the Context Store
 351  *                                         register
 352  * @param BOOL   [in] verify             - if TRUE, verify the register is
 353  *                                         written successfully.
 354  *
 355  * This function writes the contents of a Context Store register in the NPE
 356  * register file. If the <i>verify</i> option is ON, NpeDl will read back the
 357  * register to verify that it was written successfully
 358  *
 359  * @pre
 360  *    - The NPE should be stopped and in a clean state
 361  *    - ixNpeDlNpeMgrDebugInstructionPreExec() should be called once before
 362  *      a sequential of 1 or more calls to this function
 363  *
 364  * @post
 365  *    - ixNpeDlNpeMgrDebugInstructionPostExec() should be called after
 366  *      a sequence of calls to this function
 367  *
 368  * @return
 369  *    - IX_FAIL if verify is TRUE and the Context Register was not written
 370  *      successfully
 371  *    - IX_SUCCESS if Context Register was written successfully
 372  *    - IX_NPEDL_CRITICAL_NPE_ERR if Context Register was not written
 373  *      successfully due to timeout error where NPE is not responding
 374  */
 375 IX_STATUS
 376 ixNpeDlNpeMgrCtxtRegWrite (UINT32 npeBaseAddress, UINT32 ctxtNum,
 377                            IxNpeDlCtxtRegNum ctxtReg, UINT32 ctxtRegVal,
 378                            BOOL verify);
 379
 380
 381 /**
 382  * @fn void ixNpeDlNpeMgrUtilsStatsShow (void)
 383  *
 384  * @brief This function will display the statistics of the IxNpeDl NpeMgrUtils
 385  *        module
 386  *
 387  * @return none
 388  */
 389 void
 390 ixNpeDlNpeMgrUtilsStatsShow (void);
 391
 392
 393 /**
 394  * @fn void ixNpeDlNpeMgrUtilsStatsReset (void)
 395  *
 396  * @brief This function will reset the statistics of the IxNpeDl NpeMgrUtils
 397  *        module
 398  *
 399  * @return none
 400  */
 401 void
 402 ixNpeDlNpeMgrUtilsStatsReset (void);
 403
 404
 405 #endif  /* IXNPEDLNPEMGRUTILS_P_H */