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