drivers/net/npe/include/IxNpeDlNpeMgr_p.h

   1 /**
   2  * @file IxNpeDlNpeMgr_p.h
   3  *
   4  * @author Intel Corporation
   5  * @date 14 December 2001
   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 IxNpeDlNpeMgr_p IxNpeDlNpeMgr_p
  27  *
  28  * @brief The private API for the IxNpeDl NpeMgr module
  29  *
  30  * @{
  31  */
  32
  33 #ifndef IXNPEDLNPEMGR_P_H
  34 #define IXNPEDLNPEMGR_P_H
  35
  36
  37 /*
  38  * Put the user defined include files required.
  39  */
  40 #include "IxNpeDl.h"
  41 #include "IxOsalTypes.h"
  42
  43
  44 /*
  45  * Function Prototypes
  46  */
  47
  48
  49 /**
  50  * @fn void ixNpeDlNpeMgrInit (void)
  51  *
  52  * @brief Initialises the NpeMgr module
  53  *
  54  * @param none
  55  *
  56  * This function initialises the NpeMgr module.
  57  * It should be called before any other function in this module is called.
  58  * It only needs to be called once, but can be called multiple times safely.
  59  * The code will ASSERT on failure.
  60  *
  61  * @pre
  62  *     - It must be called before any other function in this module
  63  *
  64  * @post
  65  *     - NPE Configuration Register memory space will be mapped using
  66  *       IxOsal. This memory will not be unmapped by this module.
  67  *
  68  * @return none
  69  */
  70 void
  71 ixNpeDlNpeMgrInit (void);
  72
  73
  74 /**
  75  * @fn IX_STATUS ixNpeMhNpeMgrUninit (void)
  76  *
  77  * @brief This function will uninitialise the IxNpeDlNpeMgr sub-component.
  78  *
  79  * This function will uninitialise the IxNpeDlNpeMgr sub-component.
  80  * It should only be called once, and only if the IxNpeDlNpeMgr sub-component
  81  * has already been initialised by calling @ref ixNpeDlNpeMgrInit().
  82  * No other IxNpeDlNpeMgr sub-component API functions should be called
  83  * until @ref ixNpeDlNpeMgrInit() is called again.
  84  * If possible, this function should be called before a soft reboot or unloading
  85  * a kernel module to perform any clean up operations required for IxNpeMh.
  86  *
  87  * @return
  88  *      - IX_SUCCESS if the operation was successful
  89  *      - IX_FAIL otherwise
  90  */
  91
  92 IX_STATUS ixNpeDlNpeMgrUninit (void);
  93
  94
  95 /**
  96  * @fn IX_STATUS ixNpeDlNpeMgrImageLoad (IxNpeDlNpeId npeId,
  97                                            UINT32 *imageCodePtr,
  98                                            BOOL verify)
  99  *
 100  * @brief Loads a image of microcode onto an NPE
 101  *
 102  * @param IxNpeDlNpeId [in] npeId     - Id of target NPE
 103  * @param UINT32* [in] imageCodePtr - pointer to image code in image to be
 104  *                                      downloaded
 105  * @param BOOL [in] verify            - if true, verify each word written to
 106  *                                      NPE memory.
 107  *
 108  * This function loads a image containing blocks of microcode onto a
 109  * particular NPE. If the <i>verify</i> option is ON, NpeDl will read back each
 110  * word written and verify that it was written successfully
 111  *
 112  * @pre
 113  *     - The NPE should be stopped beforehand
 114  *
 115  * @post
 116  *     - The NPE Instruction Pipeline may be flushed clean
 117  *
 118  * @return
 119  *     - IX_SUCCESS if the download was successful
 120  *     - IX_FAIL if the download failed
 121  *     - IX_NPEDL_CRITICAL_NPE_ERR if the download failed due to timeout error
 122  *       where NPE is not responding
 123  */
 124 IX_STATUS
 125 ixNpeDlNpeMgrImageLoad (IxNpeDlNpeId npeId, UINT32 *imageCodePtr,
 126                           BOOL verify);
 127
 128
 129 /**
 130  * @fn IX_STATUS ixNpeDlNpeMgrNpeReset (IxNpeDlNpeId npeId)
 131  *
 132  * @brief sets a NPE to RESET state
 133  *
 134  * @param IxNpeDlNpeId [in] npeId - id of target NPE
 135  *
 136  * This function performs a soft NPE reset by writing reset values to the
 137  * Configuration Bus Execution Control registers, the Execution Context Stack
 138  * registers, the Physical Register file, and the Context Store registers for
 139  * each context number. It also clears inFIFO, outFIFO and Watchpoint FIFO.
 140  * It does not reset NPE Co-processors.
 141  *
 142  * @pre
 143  *     - The NPE should be stopped beforehand
 144  *
 145  * @post
 146  *     - NPE NextProgram Counter (NextPC) will be set to a fixed initial value,
 147  *       such as 0.  This should be explicitly set by downloading State
 148  *       Information before starting NPE Execution.
 149  *     - The NPE Instruction Pipeline will be in a clean state.
 150  *
 151  * @return
 152  *     - IX_SUCCESS if the operation was successful
 153  *     - IX_FAIL if the operation failed
 154  *     - IX_NPEDL_CRITICAL_NPE_ERR if the operation failed due to NPE hang
 155  */
 156 IX_STATUS
 157 ixNpeDlNpeMgrNpeReset (IxNpeDlNpeId npeId);
 158
 159
 160 /**
 161  * @fn IX_STATUS ixNpeDlNpeMgrNpeStart (IxNpeDlNpeId npeId)
 162  *
 163  * @brief Starts NPE Execution
 164  *
 165  * @param IxNpeDlNpeId [in] npeId - Id of target NPE
 166  *
 167  * Ensures only background Execution Stack Level is Active, clears instruction
 168  * pipeline, and starts Execution on a NPE by sending a Start NPE command to
 169  * the NPE. Checks the execution status of the NPE to verify that it is
 170  * running.
 171  *
 172  * @pre
 173  *     - The NPE should be stopped beforehand.
 174  *     - Note that this function does not set the NPE Next Program Counter
 175  *       (NextPC), so it should be set beforehand if required by downloading
 176  *       appropriate State Information.
 177  *
 178  * @post
 179  *
 180  * @return
 181  *     - IX_SUCCESS if the operation was successful
 182  *     - IX_FAIL otherwise
 183  */
 184 IX_STATUS
 185 ixNpeDlNpeMgrNpeStart (IxNpeDlNpeId npeId);
 186
 187
 188 /**
 189  * @fn IX_STATUS ixNpeDlNpeMgrNpeStop (IxNpeDlNpeId npeId)
 190  *
 191  * @brief Halts NPE Execution
 192  *
 193  * @param IxNpeDlNpeId [in] npeId - id of target NPE
 194  *
 195  * Stops execution on an NPE by sending a Stop NPE command to the NPE.
 196  * Checks the execution status of the NPE to verify that it has stopped.
 197  *
 198  * @pre
 199  *
 200  * @post
 201  *
 202  * @return
 203  *     - IX_SUCCESS if the operation was successful
 204  *     - IX_FAIL otherwise
 205  */
 206 IX_STATUS
 207 ixNpeDlNpeMgrNpeStop (IxNpeDlNpeId npeId);
 208
 209
 210 /**
 211  * @fn void ixNpeDlNpeMgrStatsShow (void)
 212  *
 213  * @brief This function will display statistics of the IxNpeDl NpeMgr module
 214  *
 215  * @return none
 216  */
 217 void
 218 ixNpeDlNpeMgrStatsShow (void);
 219
 220
 221 /**
 222  * @fn void ixNpeDlNpeMgrStatsReset (void)
 223  *
 224  * @brief This function will reset the statistics of the IxNpeDl NpeMgr module
 225  *
 226  * @return none
 227  */
 228 void
 229 ixNpeDlNpeMgrStatsReset (void);
 230
 231
 232 #endif /* IXNPEDLIMAGEMGR_P_H */
 233
 234 /**
 235  * @} defgroup IxNpeDlNpeMgr_p
 236  */