/** * @file IxNpeMh.h * * @date 14 Dec 2001 * * @brief This file contains the public API for the IXP400 NPE Message * Handler component. * *  * @par * IXP400 SW Release version 2.0 *  * -- Copyright Notice -- *  * @par * Copyright 2001-2005, Intel Corporation. * All rights reserved. *  * @par * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright *    notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright *    notice, this list of conditions and the following disclaimer in the *    documentation and/or other materials provided with the distribution. * 3. Neither the name of the Intel Corporation nor the names of its contributors *    may be used to endorse or promote products derived from this software *    without specific prior written permission. *  * @par * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. *  * @par * -- End of Copyright Notice --*//** * @defgroup IxNpeMh IXP400 NPE Message Handler (IxNpeMh) API * * @brief The public API for the IXP400 NPE Message Handler component. *  * @{ */#ifndef IXNPEMH_H#define IXNPEMH_H#include "IxOsalTypes.h"/* * #defines for function return types, etc. */#define IX_NPEMH_MIN_MESSAGE_ID (0x00) /**< minimum valid message ID */#define IX_NPEMH_MAX_MESSAGE_ID (0xFF) /**< maximum valid message ID */#define IX_NPEMH_SEND_RETRIES_DEFAULT (3) /**< default msg send retries *//** * @def IX_NPEMH_CRITICAL_NPE_ERR * * @brief NpeMH function return value for a Critical NPE error occuring during          sending/receiving message. Assume NPE hang / halt if this value is          returned. */#define IX_NPEMH_CRITICAL_NPE_ERR        2/** * @enum IxNpeMhNpeId * * @brief The ID of a particular NPE. * @note In this context, for IXP425 Silicon (B0):<br>  *      - NPE-A has HDLC, HSS, AAL and UTOPIA Coprocessors.<br>  *      - NPE-B has Ethernet Coprocessor.<br> *      - NPE-C has Ethernet, AES, DES and HASH Coprocessors.<br> *      - IXP400 Product Line have different combinations of coprocessors.  */typedef enum{    IX_NPEMH_NPEID_NPEA = 0, /**< ID for NPE-A */    IX_NPEMH_NPEID_NPEB,     /**< ID for NPE-B */    IX_NPEMH_NPEID_NPEC,     /**< ID for NPE-C */    IX_NPEMH_NUM_NPES        /**< Number of NPEs */} IxNpeMhNpeId;/** * @enum IxNpeMhNpeInterrupts * * @brief Indicator specifying whether or not NPE interrupts should drive * receiving of messages from the NPEs. */typedef enum{    IX_NPEMH_NPEINTERRUPTS_NO = 0, /**< Don't use NPE interrupts */    IX_NPEMH_NPEINTERRUPTS_YES     /**< Do use NPE interrupts */} IxNpeMhNpeInterrupts;/** * @brief The 2-word message structure to send to and receive from the * NPEs. */typedef struct{    UINT32 data[2]; /**< the actual data of the message */} IxNpeMhMessage;/** message ID */typedef UINT32 IxNpeMhMessageId;/** * @typedef IxNpeMhCallback * * @brief This prototype shows the format of a message callback function. * * This prototype shows the format of a message callback function.  The * message callback will be passed the message to be handled and will also * be told from which NPE the message was received.  The message callback * will either be registered by ixNpeMhUnsolicitedCallbackRegister() or * passed as a parameter to ixNpeMhMessageWithResponseSend().  It will be * called from within an ISR triggered by the NPE's "outFIFO not empty" * interrupt (see ixNpeMhInitialize()).  The parameters passed are the ID * of the NPE that the message was received from, and the message to be * handled.<P><B>Re-entrancy:</B> This function is only a prototype, and * will be implemented by the client.  It does not need to be re-entrant. */typedef void (*IxNpeMhCallback) (IxNpeMhNpeId, IxNpeMhMessage);/* * Prototypes for interface functions. *//** * @ingroup IxNpeMh * * @fn IX_STATUS ixNpeMhInitialize (           IxNpeMhNpeInterrupts npeInterrupts) * * @brief This function will initialise the IxNpeMh component. * * @param npeInterrupts @ref IxNpeMhNpeInterrupts [in] - This parameter * dictates whether or not the IxNpeMh component will service NPE "outFIFO * not empty" interrupts to trigger receiving and processing of messages * from the NPEs.  If not then the client must use ixNpeMhMessagesReceive() * to control message receiving and processing. * * This function will initialise the IxNpeMh component.  It should only be * called once, prior to using the IxNpeMh component.  The following * actions will be performed by this function:<OL><LI>Initialization of * internal data structures (e.g. solicited and unsolicited callback * tables).</LI><LI>Configuration of the interface with the NPEs (e.g. * enabling of NPE "outFIFO not empty" interrupts).</LI><LI>Registration of * ISRs that will receive and handle messages when the NPEs' "outFIFO not * empty" interrupts fire (if npeInterrupts equals * IX_NPEMH_NPEINTERRUPTS_YES).</LI></OL> * * @return The function returns a status indicating success or failure. */PUBLIC IX_STATUS ixNpeMhInitialize (    IxNpeMhNpeInterrupts npeInterrupts);/** * @ingroup IxNpeMh * * @fn IX_STATUS ixNpeMhUnload (void) * * @brief This function will uninitialise the IxNpeMh component. * * This function will uninitialise the IxNpeMh component.  It should only be * called once, and only if the IxNpeMh component has already been initialised. * No other IxNpeMh API functions should be called until @ref ixNpeMhInitialize * is called again. * If possible, this function should be called before a soft reboot or unloading * a kernel module to perform any clean up operations required for IxNpeMh. * * The following actions will be performed by this function: * <OL><LI>Unmapping of kernel memory mapped by the function * @ref ixNpeMhInitialize.</LI></OL> * * @return The function returns a status indicating success or failure. */PUBLIC IX_STATUS ixNpeMhUnload (void);/** * @ingroup IxNpeMh * * @fn IX_STATUS ixNpeMhUnsolicitedCallbackRegister (           IxNpeMhNpeId npeId,           IxNpeMhMessageId messageId,           IxNpeMhCallback unsolicitedCallback) * * @brief This function will register an unsolicited callback for a * particular NPE and message ID. * * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE whose messages * the unsolicited callback will handle. * @param messageId @ref IxNpeMhMessageId [in] - The ID of the messages the * unsolicited callback will handle. * @param unsolicitedCallback @ref IxNpeMhCallback [in] - The unsolicited * callback function.  A value of NULL will deregister any previously * registered callback for this NPE and message ID. * * This function will register an unsolicited message callback for a * particular NPE and message ID.<P>If an unsolicited callback is already * registered for the specified NPE and message ID then the callback will * be overwritten.  Only one client will be responsible for handling a * particular message ID associated with a NPE.  Registering a NULL * unsolicited callback will deregister any previously registered * callback.<P>The callback function will be called from an ISR that will * be triggered by the NPE's "outFIFO not empty" interrupt (see * ixNpeMhInitialize()) to handle any unsolicited messages of the specific * message ID received from the NPE.  Unsolicited messages will be handled * in the order they are received.<P>If no unsolicited callback can be * found for a received message then it is assumed that the message is * solicited.<P>If more than one client may be interested in a particular * unsolicited message then the suggested strategy is to register a * callback for the message that can itself distribute the message to * multiple clients as necessary.<P>See also * ixNpeMhUnsolicitedCallbackForRangeRegister().<P><B>Re-entrancy:</B> This * function will be callable from any thread at any time.  IxOsal * will be used for any necessary resource protection. * * @return The function returns a status indicating success or failure. */PUBLIC IX_STATUS ixNpeMhUnsolicitedCallbackRegister (    IxNpeMhNpeId npeId,    IxNpeMhMessageId messageId,    IxNpeMhCallback unsolicitedCallback);/**