1 /** 2 * @file IxNpeMh.h 3 * 4 * @date 14 Dec 2001 5 * 6 * @brief This file contains the public API for the IXP400 NPE Message 7 * Handler component. 8 * 9 * 10 * @par 11 * IXP400 SW Release version 2.0 12 * 13 * -- Copyright Notice -- 14 * 15 * @par 16 * Copyright 2001-2005, Intel Corporation. 17 * All rights reserved. 18 * 19 * @par 20 * Redistribution and use in source and binary forms, with or without 21 * modification, are permitted provided that the following conditions 22 * are met: 23 * 1. Redistributions of source code must retain the above copyright 24 * notice, this list of conditions and the following disclaimer. 25 * 2. Redistributions in binary form must reproduce the above copyright 26 * notice, this list of conditions and the following disclaimer in the 27 * documentation and/or other materials provided with the distribution. 28 * 3. Neither the name of the Intel Corporation nor the names of its contributors 29 * may be used to endorse or promote products derived from this software 30 * without specific prior written permission. 31 * 32 * @par 33 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' 34 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 35 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 36 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE 37 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 38 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 39 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 40 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 41 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 42 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 43 * SUCH DAMAGE. 44 * 45 * @par 46 * -- End of Copyright Notice -- 47 */ 48 49 /** 50 * @defgroup IxNpeMh IXP400 NPE Message Handler (IxNpeMh) API 51 * 52 * @brief The public API for the IXP400 NPE Message Handler component. 53 * 54 * @{ 55 */ 56 57 #ifndef IXNPEMH_H 58 #define IXNPEMH_H 59 60 #include "IxOsalTypes.h" 61 62 /* 63 * #defines for function return types, etc. 64 */ 65 66 #define IX_NPEMH_MIN_MESSAGE_ID (0x00) /**< minimum valid message ID */ 67 #define IX_NPEMH_MAX_MESSAGE_ID (0xFF) /**< maximum valid message ID */ 68 69 #define IX_NPEMH_SEND_RETRIES_DEFAULT (3) /**< default msg send retries */ 70 71 72 /** 73 * @def IX_NPEMH_CRITICAL_NPE_ERR 74 * 75 * @brief NpeMH function return value for a Critical NPE error occuring during 76 sending/receiving message. Assume NPE hang / halt if this value is 77 returned. 78 */ 79 #define IX_NPEMH_CRITICAL_NPE_ERR 2 80 81 /** 82 * @enum IxNpeMhNpeId 83 * 84 * @brief The ID of a particular NPE. 85 * @note In this context, for IXP425 Silicon (B0):<br> 86 * - NPE-A has HDLC, HSS, AAL and UTOPIA Coprocessors.<br> 87 * - NPE-B has Ethernet Coprocessor.<br> 88 * - NPE-C has Ethernet, AES, DES and HASH Coprocessors.<br> 89 * - IXP400 Product Line have different combinations of coprocessors. 90 */ 91 92 typedef enum 93 { 94 IX_NPEMH_NPEID_NPEA = 0, /**< ID for NPE-A */ 95 IX_NPEMH_NPEID_NPEB, /**< ID for NPE-B */ 96 IX_NPEMH_NPEID_NPEC, /**< ID for NPE-C */ 97 IX_NPEMH_NUM_NPES /**< Number of NPEs */ 98 } IxNpeMhNpeId; 99 100 /** 101 * @enum IxNpeMhNpeInterrupts 102 * 103 * @brief Indicator specifying whether or not NPE interrupts should drive 104 * receiving of messages from the NPEs. 105 */ 106 107 typedef enum 108 { 109 IX_NPEMH_NPEINTERRUPTS_NO = 0, /**< Don't use NPE interrupts */ 110 IX_NPEMH_NPEINTERRUPTS_YES /**< Do use NPE interrupts */ 111 } IxNpeMhNpeInterrupts; 112 113 /** 114 * @brief The 2-word message structure to send to and receive from the 115 * NPEs. 116 */ 117 118 typedef struct 119 { 120 UINT32 data[2]; /**< the actual data of the message */ 121 } IxNpeMhMessage; 122 123 /** message ID */ 124 typedef UINT32 IxNpeMhMessageId; 125 126 /** 127 * @typedef IxNpeMhCallback 128 * 129 * @brief This prototype shows the format of a message callback function. 130 * 131 * This prototype shows the format of a message callback function. The 132 * message callback will be passed the message to be handled and will also 133 * be told from which NPE the message was received. The message callback 134 * will either be registered by ixNpeMhUnsolicitedCallbackRegister() or 135 * passed as a parameter to ixNpeMhMessageWithResponseSend(). It will be 136 * called from within an ISR triggered by the NPE's "outFIFO not empty" 137 * interrupt (see ixNpeMhInitialize()). The parameters passed are the ID 138 * of the NPE that the message was received from, and the message to be 139 * handled.<P><B>Re-entrancy:</B> This function is only a prototype, and 140 * will be implemented by the client. It does not need to be re-entrant. 141 */ 142 143 typedef void (*IxNpeMhCallback) (IxNpeMhNpeId, IxNpeMhMessage); 144 145 /* 146 * Prototypes for interface functions. 147 */ 148 149 /** 150 * @ingroup IxNpeMh 151 * 152 * @fn IX_STATUS ixNpeMhInitialize ( 153 IxNpeMhNpeInterrupts npeInterrupts) 154 * 155 * @brief This function will initialise the IxNpeMh component. 156 * 157 * @param npeInterrupts @ref IxNpeMhNpeInterrupts [in] - This parameter 158 * dictates whether or not the IxNpeMh component will service NPE "outFIFO 159 * not empty" interrupts to trigger receiving and processing of messages 160 * from the NPEs. If not then the client must use ixNpeMhMessagesReceive() 161 * to control message receiving and processing. 162 * 163 * This function will initialise the IxNpeMh component. It should only be 164 * called once, prior to using the IxNpeMh component. The following 165 * actions will be performed by this function:<OL><LI>Initialization of 166 * internal data structures (e.g. solicited and unsolicited callback 167 * tables).</LI><LI>Configuration of the interface with the NPEs (e.g. 168 * enabling of NPE "outFIFO not empty" interrupts).</LI><LI>Registration of 169 * ISRs that will receive and handle messages when the NPEs' "outFIFO not 170 * empty" interrupts fire (if npeInterrupts equals 171 * IX_NPEMH_NPEINTERRUPTS_YES).</LI></OL> 172 * 173 * @return The function returns a status indicating success or failure. 174 */ 175 176 PUBLIC IX_STATUS ixNpeMhInitialize ( 177 IxNpeMhNpeInterrupts npeInterrupts); 178 179 /** 180 * @ingroup IxNpeMh 181 * 182 * @fn IX_STATUS ixNpeMhUnload (void) 183 * 184 * @brief This function will uninitialise the IxNpeMh component. 185 * 186 * This function will uninitialise the IxNpeMh component. It should only be 187 * called once, and only if the IxNpeMh component has already been initialised. 188 * No other IxNpeMh API functions should be called until @ref ixNpeMhInitialize 189 * is called again. 190 * If possible, this function should be called before a soft reboot or unloading 191 * a kernel module to perform any clean up operations required for IxNpeMh. 192 * 193 * The following actions will be performed by this function: 194 * <OL><LI>Unmapping of kernel memory mapped by the function 195 * @ref ixNpeMhInitialize.</LI></OL> 196 * 197 * @return The function returns a status indicating success or failure. 198 */ 199 200 PUBLIC IX_STATUS ixNpeMhUnload (void); 201 202 /** 203 * @ingroup IxNpeMh 204 * 205 * @fn IX_STATUS ixNpeMhUnsolicitedCallbackRegister ( 206 IxNpeMhNpeId npeId, 207 IxNpeMhMessageId messageId, 208 IxNpeMhCallback unsolicitedCallback) 209 * 210 * @brief This function will register an unsolicited callback for a 211 * particular NPE and message ID. 212 * 213 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE whose messages 214 * the unsolicited callback will handle. 215 * @param messageId @ref IxNpeMhMessageId [in] - The ID of the messages the 216 * unsolicited callback will handle. 217 * @param unsolicitedCallback @ref IxNpeMhCallback [in] - The unsolicited 218 * callback function. A value of NULL will deregister any previously 219 * registered callback for this NPE and message ID. 220 * 221 * This function will register an unsolicited message callback for a 222 * particular NPE and message ID.<P>If an unsolicited callback is already 223 * registered for the specified NPE and message ID then the callback will 224 * be overwritten. Only one client will be responsible for handling a 225 * particular message ID associated with a NPE. Registering a NULL 226 * unsolicited callback will deregister any previously registered 227 * callback.<P>The callback function will be called from an ISR that will 228 * be triggered by the NPE's "outFIFO not empty" interrupt (see 229 * ixNpeMhInitialize()) to handle any unsolicited messages of the specific 230 * message ID received from the NPE. Unsolicited messages will be handled 231 * in the order they are received.<P>If no unsolicited callback can be 232 * found for a received message then it is assumed that the message is 233 * solicited.<P>If more than one client may be interested in a particular 234 * unsolicited message then the suggested strategy is to register a 235 * callback for the message that can itself distribute the message to 236 * multiple clients as necessary.<P>See also 237 * ixNpeMhUnsolicitedCallbackForRangeRegister().<P><B>Re-entrancy:</B> This 238 * function will be callable from any thread at any time. IxOsal 239 * will be used for any necessary resource protection. 240 * 241 * @return The function returns a status indicating success or failure. 242 */ 243 244 PUBLIC IX_STATUS ixNpeMhUnsolicitedCallbackRegister ( 245 IxNpeMhNpeId npeId, 246 IxNpeMhMessageId messageId, 247 IxNpeMhCallback unsolicitedCallback); 248 249 /** 250 * @ingroup IxNpeMh 251 * 252 * @fn IX_STATUS ixNpeMhUnsolicitedCallbackForRangeRegister ( 253 IxNpeMhNpeId npeId, 254 IxNpeMhMessageId minMessageId, 255 IxNpeMhMessageId maxMessageId, 256 IxNpeMhCallback unsolicitedCallback) 257 * 258 * @brief This function will register an unsolicited callback for a 259 * particular NPE and range of message IDs. 260 * 261 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE whose messages the 262 * unsolicited callback will handle. 263 * @param minMessageId @ref IxNpeMhMessageId [in] - The minimum message ID in 264 * the range of message IDs the unsolicited callback will handle. 265 * @param maxMessageId @ref IxNpeMhMessageId [in] - The maximum message ID in 266 * the range of message IDs the unsolicited callback will handle. 267 * @param unsolicitedCallback @ref IxNpeMhCallback [in] - The unsolicited 268 * callback function. A value of NULL will deregister any previously 269 * registered callback(s) for this NPE and range of message IDs. 270 * 271 * This function will register an unsolicited callback for a particular NPE 272 * and range of message IDs. It is a convenience function that is 273 * effectively the same as calling ixNpeMhUnsolicitedCallbackRegister() for 274 * each ID in the specified range. See 275 * ixNpeMhUnsolicitedCallbackRegister() for more 276 * information.<P><B>Re-entrancy:</B> This function will be callable from 277 * any thread at any time. IxOsal will be used for any necessary 278 * resource protection. 279 * 280 * @return The function returns a status indicating success or failure. 281 */ 282 283 PUBLIC IX_STATUS ixNpeMhUnsolicitedCallbackForRangeRegister ( 284 IxNpeMhNpeId npeId, 285 IxNpeMhMessageId minMessageId, 286 IxNpeMhMessageId maxMessageId, 287 IxNpeMhCallback unsolicitedCallback); 288 289 /** 290 * @ingroup IxNpeMh 291 * 292 * @fn IX_STATUS ixNpeMhMessageSend ( 293 IxNpeMhNpeId npeId, 294 IxNpeMhMessage message, 295 UINT32 maxSendRetries) 296 * 297 * @brief This function will send a message to a particular NPE. 298 * 299 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to send the message 300 * to. 301 * @param message @ref IxNpeMhMessage [in] - The message to send. 302 * @param maxSendRetries UINT32 [in] - Max num. of retries to perform 303 * if the NPE's inFIFO is full. 304 * 305 * This function will send a message to a particular NPE. It will be the 306 * client's responsibility to ensure that the message is properly formed. 307 * The return status will signify to the client if the message was 308 * successfully sent or not.<P>If the message is sent to the NPE then this 309 * function will return a status of success. Note that this will only mean 310 * the message has been placed in the NPE's inFIFO. There will be no way 311 * of knowing that the NPE has actually read the message, but once in the 312 * incoming message queue it will be safe to assume that the NPE will 313 * process it. 314 * <P>The inFIFO may fill up sometimes if the Xscale is sending messages 315 * faster than the NPE can handle them. This forces us to retry attempts 316 * to send the message until the NPE services the inFIFO. The client should 317 * specify a ceiling value for the number of retries suitable to their 318 * needs. IX_NPEMH_SEND_RETRIES_DEFAULT can be used as a default value for 319 * the <i>maxSendRetries</i> parameter for this function. Each retry 320 * exceeding this default number will incur a blocking delay of 1 microsecond, 321 * to avoid consuming too much AHB bus bandwidth while performing retries. 322 * <P>Note this function <B>must</B> only be used for messages. 323 * that do not solicit responses. If the message being sent will solicit a 324 * response then the ixNpeMhMessageWithResponseSend() function <B>must</B> 325 * be used to ensure that the response is correctly 326 * handled. <P> This function will return timeout status if NPE hang / halt 327 * while sending message. The timeout error is not related to the 328 * <i>maxSendRetries</i> as mentioned above. The timeout error will only occur 329 * if the first word of the message has been sent to NPE (not exceeding 330 * <i>maxSendRetries</i> when sending 1st message word), but the second word of 331 * the message can't be written to NPE's inFIFO due to NPE hang / halt after 332 * maximum waiting time (IX_NPE_MH_MAX_NUM_OF_RETRIES). 333 * <P><B>Re-entrancy:</B> This function will be callable from any 334 * thread at any time. IxOsal will be used for any necessary 335 * resource protection. 336 * 337 * @return The function returns a status indicating success, failure or timeout. 338 */ 339 340 PUBLIC IX_STATUS ixNpeMhMessageSend ( 341 IxNpeMhNpeId npeId, 342 IxNpeMhMessage message, 343 UINT32 maxSendRetries); 344 345 /** 346 * @ingroup IxNpeMh 347 * 348 * @fn IX_STATUS ixNpeMhMessageWithResponseSend ( 349 IxNpeMhNpeId npeId, 350 IxNpeMhMessage message, 351 IxNpeMhMessageId solicitedMessageId, 352 IxNpeMhCallback solicitedCallback, 353 UINT32 maxSendRetries) 354 * 355 * @brief This function is equivalent to the ixNpeMhMessageSend() function, 356 * but must be used when the message being sent will solicited a response. 357 * 358 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to send the message 359 * to. 360 * @param message @ref IxNpeMhMessage [in] - The message to send. 361 * @param solicitedMessageId @ref IxNpeMhMessageId [in] - The ID of the 362 * solicited response message. 363 * @param solicitedCallback @ref IxNpeMhCallback [in] - The function to use to 364 * pass the response message back to the client. A value of NULL will 365 * cause the response message to be discarded. 366 * @param maxSendRetries UINT32 [in] - Max num. of retries to perform 367 * if the NPE's inFIFO is full. 368 * 369 * This function is equivalent to the ixNpeMhMessageSend() function, but 370 * must be used when the message being sent will solicited a 371 * response.<P>The client must specify the ID of the solicited response 372 * message to allow the response to be recognised when it is received. The 373 * client must also specify a callback function to handle the received 374 * response. The IxNpeMh component will not offer the facility to send a 375 * message to a NPE and receive a response within the same context.<P>Note 376 * if the client is not interested in the response, specifying a NULL 377 * callback will cause the response message to be discarded.<P>The 378 * solicited callback will be stored and called some time later from an ISR 379 * that will be triggered by the NPE's "outFIFO not empty" interrupt (see 380 * ixNpeMhInitialize()) to handle the response message corresponding to the 381 * message sent. Response messages will be handled in the order they are 382 * received.<P> 383 * <P>The inFIFO may fill up sometimes if the Xscale is sending messages 384 * faster than the NPE can handle them. This forces us to retry attempts 385 * to send the message until the NPE services the inFIFO. The client should 386 * specify a ceiling value for the number of retries suitable to their 387 * needs. IX_NPEMH_SEND_RETRIES_DEFAULT can be used as a default value for 388 * the <i>maxSendRetries</i> parameter for this function. Each retry 389 * exceeding this default number will incur a blocking delay of 1 microsecond, 390 * to avoid consuming too much AHB bus bandwidth while performing retries. 391 * <P> This function will return timeout status if NPE hang / halt 392 * while sending message. The timeout error is not related to the 393 * <i>maxSendRetries</i> as mentioned above. The timeout error will only occur 394 * if the first word of the message has been sent to NPE (not exceeding 395 * <i>maxSendRetries</i> when sending 1st message word), but the second word of 396 * the message can't be written to NPE's inFIFO due to NPE hang / halt after 397 * maximum waiting time (IX_NPE_MH_MAX_NUM_OF_RETRIES). 398 * <P><B>Re-entrancy:</B> This function will be callable from any 399 * thread at any time. IxOsal will be used for any necessary 400 * resource protection. 401 * 402 * @return The function returns a status indicating success or failure. 403 */ 404 405 PUBLIC IX_STATUS ixNpeMhMessageWithResponseSend ( 406 IxNpeMhNpeId npeId, 407 IxNpeMhMessage message, 408 IxNpeMhMessageId solicitedMessageId, 409 IxNpeMhCallback solicitedCallback, 410 UINT32 maxSendRetries); 411 412 /** 413 * @ingroup IxNpeMh 414 * 415 * @fn IX_STATUS ixNpeMhMessagesReceive ( 416 IxNpeMhNpeId npeId) 417 * 418 * @brief This function will receive messages from a particular NPE and 419 * pass each message to the client via a solicited callback (for solicited 420 * messages) or an unsolicited callback (for unsolicited messages). 421 * 422 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to receive and 423 * process messages from. 424 * 425 * This function will receive messages from a particular NPE and pass each 426 * message to the client via a solicited callback (for solicited messages) 427 * or an unsolicited callback (for unsolicited messages).<P>If the IxNpeMh 428 * component is initialised to service NPE "outFIFO not empty" interrupts 429 * (see ixNpeMhInitialize()) then there is no need to call this function. 430 * This function is only provided as an alternative mechanism to control 431 * the receiving and processing of messages from the NPEs.<P> This function 432 * will return timeout status if NPE hang / halt while receiving message. The 433 * timeout error will only occur if this function has read the first word of 434 * the message and can't read second word of the message from NPE's outFIFO 435 * after maximum retries (IX_NPE_MH_MAX_NUM_OF_RETRIES). 436 * <P>Note this function cannot be called from within 437 * an ISR as it will use resource protection mechanisms.<P><B>Re-entrancy:</B> 438 * This function will be callable from any thread at any time. IxOsal will be 439 * used for any necessary resource protection. 440 * 441 * @return The function returns a status indicating success, failure or timeout. 442 */ 443 444 PUBLIC IX_STATUS ixNpeMhMessagesReceive ( 445 IxNpeMhNpeId npeId); 446 447 /** 448 * @ingroup IxNpeMh 449 * 450 * @fn IX_STATUS ixNpeMhShow ( 451 IxNpeMhNpeId npeId) 452 * 453 * @brief This function will display the current state of the IxNpeMh 454 * component. 455 * 456 * <B>Re-entrancy:</B> This function will be callable from 457 * any thread at any time. However, no resource protection will be used 458 * so as not to impact system performance. As this function is only 459 * reading statistical information then this is acceptable. 460 * 461 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to display state 462 * information for. 463 * 464 * @return The function returns a status indicating success or failure. 465 */ 466 467 PUBLIC IX_STATUS ixNpeMhShow ( 468 IxNpeMhNpeId npeId); 469 470 /** 471 * @ingroup IxNpeMh 472 * 473 * @fn IX_STATUS ixNpeMhShowReset ( 474 IxNpeMhNpeId npeId) 475 * 476 * @brief This function will reset the current state of the IxNpeMh 477 * component. 478 * 479 * <B>Re-entrancy:</B> This function will be callable from 480 * any thread at any time. However, no resource protection will be used 481 * so as not to impact system performance. As this function is only 482 * writing statistical information then this is acceptable. 483 * 484 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to reset state 485 * information for. 486 * 487 * @return The function returns a status indicating success or failure. 488 */ 489 490 PUBLIC IX_STATUS ixNpeMhShowReset ( 491 IxNpeMhNpeId npeId); 492 493 #endif /* IXNPEMH_H */ 494 495 /** 496 * @} defgroup IxNpeMh 497 */ 498