cpu/ixp/npe/include/IxNpeMh.h

/**
 * @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);

/**
 * @ingroup IxNpeMh
 *
 * @fn IX_STATUS ixNpeMhUnsolicitedCallbackForRangeRegister (
           IxNpeMhNpeId npeId,
           IxNpeMhMessageId minMessageId,
           IxNpeMhMessageId maxMessageId,
           IxNpeMhCallback unsolicitedCallback)
 *
 * @brief This function will register an unsolicited callback for a
 * particular NPE and range of message IDs.
 *
 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE whose messages the
 * unsolicited callback will handle.
 * @param minMessageId @ref IxNpeMhMessageId [in] - The minimum message ID in
 * the range of message IDs the unsolicited callback will handle.
 * @param maxMessageId @ref IxNpeMhMessageId [in] - The maximum message ID in
 * the range of message IDs the unsolicited callback will handle.
 * @param unsolicitedCallback @ref IxNpeMhCallback [in] - The unsolicited
 * callback function.  A value of NULL will deregister any previously
 * registered callback(s) for this NPE and range of message IDs.
 *
 * This function will register an unsolicited callback for a particular NPE
 * and range of message IDs.  It is a convenience function that is
 * effectively the same as calling ixNpeMhUnsolicitedCallbackRegister() for
 * each ID in the specified range.  See
 * ixNpeMhUnsolicitedCallbackRegister() for more
 * information.<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 ixNpeMhUnsolicitedCallbackForRangeRegister (
    IxNpeMhNpeId npeId,
    IxNpeMhMessageId minMessageId,
    IxNpeMhMessageId maxMessageId,
    IxNpeMhCallback unsolicitedCallback);

/**
 * @ingroup IxNpeMh
 *
 * @fn IX_STATUS ixNpeMhMessageSend (
           IxNpeMhNpeId npeId,
           IxNpeMhMessage message,
           UINT32 maxSendRetries)
 *
 * @brief This function will send a message to a particular NPE.
 *
 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to send the message
 * to.
 * @param message @ref IxNpeMhMessage [in] - The message to send.
 * @param maxSendRetries UINT32 [in] - Max num. of retries to perform
 * if the NPE's inFIFO is full.
 *
 * This function will send a message to a particular NPE.  It will be the
 * client's responsibility to ensure that the message is properly formed.
 * The return status will signify to the client if the message was
 * successfully sent or not.<P>If the message is sent to the NPE then this
 * function will return a status of success.  Note that this will only mean
 * the message has been placed in the NPE's inFIFO.  There will be no way
 * of knowing that the NPE has actually read the message, but once in the
 * incoming message queue it will be safe to assume that the NPE will
 * process it.
 * <P>The inFIFO may fill up sometimes if the Xscale is sending messages
 * faster than the NPE can handle them. This forces us to retry attempts 
 * to send the message until the NPE services the inFIFO. The client should
 * specify a ceiling value for the number of retries suitable to their
 * needs. IX_NPEMH_SEND_RETRIES_DEFAULT can be used as a default value for
 * the <i>maxSendRetries</i> parameter for this function. Each retry
 * exceeding this default number will incur a blocking delay of 1 microsecond,
 * to avoid consuming too much AHB bus bandwidth while performing retries.
 * <P>Note this function <B>must</B> only be used for messages.
 * that do not solicit responses. If the message being sent will solicit a
 * response then the ixNpeMhMessageWithResponseSend() function <B>must</B>
 * be used to ensure that the response is correctly
 * handled. <P> This function will return timeout status if NPE hang / halt 
 * while sending message. The timeout error is not related to the 
 * <i>maxSendRetries</i> as mentioned above. The timeout error will only occur 
 * if the first word of the message has been sent to NPE (not exceeding 
 * <i>maxSendRetries</i> when sending 1st message word), but the second word of
 * the message can't be written to NPE's inFIFO due to NPE hang / halt after 
 * maximum waiting time (IX_NPE_MH_MAX_NUM_OF_RETRIES). 
 * <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, failure or timeout.
 */

PUBLIC IX_STATUS ixNpeMhMessageSend (
    IxNpeMhNpeId npeId,
    IxNpeMhMessage message,
    UINT32 maxSendRetries);

/**
 * @ingroup IxNpeMh
 *
 * @fn IX_STATUS ixNpeMhMessageWithResponseSend (
           IxNpeMhNpeId npeId,
           IxNpeMhMessage message,
           IxNpeMhMessageId solicitedMessageId,
           IxNpeMhCallback solicitedCallback,
           UINT32 maxSendRetries)
 *
 * @brief This function is equivalent to the ixNpeMhMessageSend() function,
 * but must be used when the message being sent will solicited a response.
 *
 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to send the message
 * to.
 * @param message @ref IxNpeMhMessage [in] - The message to send.
 * @param solicitedMessageId @ref IxNpeMhMessageId [in] - The ID of the
 * solicited response message.
 * @param solicitedCallback @ref IxNpeMhCallback [in] - The function to use to
 * pass the response message back to the client.  A value of NULL will
 * cause the response message to be discarded.
 * @param maxSendRetries UINT32 [in] - Max num. of retries to perform
 * if the NPE's inFIFO is full.
 *
 * This function is equivalent to the ixNpeMhMessageSend() function, but
 * must be used when the message being sent will solicited a
 * response.<P>The client must specify the ID of the solicited response
 * message to allow the response to be recognised when it is received.  The
 * client must also specify a callback function to handle the received
 * response.  The IxNpeMh component will not offer the facility to send a
 * message to a NPE and receive a response within the same context.<P>Note
 * if the client is not interested in the response, specifying a NULL
 * callback will cause the response message to be discarded.<P>The
 * solicited callback will be stored and called some time later from an ISR
 * that will be triggered by the NPE's "outFIFO not empty" interrupt (see
 * ixNpeMhInitialize()) to handle the response message corresponding to the
 * message sent.  Response messages will be handled in the order they are
 * received.<P>
 * <P>The inFIFO may fill up sometimes if the Xscale is sending messages
 * faster than the NPE can handle them. This forces us to retry attempts 
 * to send the message until the NPE services the inFIFO. The client should
 * specify a ceiling value for the number of retries suitable to their
 * needs. IX_NPEMH_SEND_RETRIES_DEFAULT can be used as a default value for
 * the <i>maxSendRetries</i> parameter for this function. Each retry
 * exceeding this default number will incur a blocking delay of 1 microsecond,
 * to avoid consuming too much AHB bus bandwidth while performing retries.
 * <P> This function will return timeout status if NPE hang / halt 
 * while sending message. The timeout error is not related to the 
 * <i>maxSendRetries</i> as mentioned above. The timeout error will only occur 
 * if the first word of the message has been sent to NPE (not exceeding 
 * <i>maxSendRetries</i> when sending 1st message word), but the second word of
 * the message can't be written to NPE's inFIFO due to NPE hang / halt after 
 * maximum waiting time (IX_NPE_MH_MAX_NUM_OF_RETRIES). 
 * <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 ixNpeMhMessageWithResponseSend (
    IxNpeMhNpeId npeId,
    IxNpeMhMessage message,
    IxNpeMhMessageId solicitedMessageId,
    IxNpeMhCallback solicitedCallback,
    UINT32 maxSendRetries);

/**
 * @ingroup IxNpeMh
 *
 * @fn IX_STATUS ixNpeMhMessagesReceive (
           IxNpeMhNpeId npeId)
 *
 * @brief This function will receive messages from a particular NPE and
 * pass each message to the client via a solicited callback (for solicited
 * messages) or an unsolicited callback (for unsolicited messages).
 *
 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to receive and
 * process messages from.
 *
 * This function will receive messages from a particular NPE and pass each
 * message to the client via a solicited callback (for solicited messages)
 * or an unsolicited callback (for unsolicited messages).<P>If the IxNpeMh
 * component is initialised to service NPE "outFIFO not empty" interrupts
 * (see ixNpeMhInitialize()) then there is no need to call this function.
 * This function is only provided as an alternative mechanism to control
 * the receiving and processing of messages from the NPEs.<P> This function
 * will return timeout status if NPE hang / halt while receiving message. The
 * timeout error will only occur if this function has read the first word of
 * the message and can't read second word of the message from NPE's outFIFO
 * after maximum retries (IX_NPE_MH_MAX_NUM_OF_RETRIES). 
 * <P>Note this function cannot be called from within 
 * an ISR as it will use resource protection mechanisms.<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, failure or timeout.
 */

PUBLIC IX_STATUS ixNpeMhMessagesReceive (
    IxNpeMhNpeId npeId);

/**
 * @ingroup IxNpeMh
 *
 * @fn IX_STATUS ixNpeMhShow (
           IxNpeMhNpeId npeId)
 *
 * @brief This function will display the current state of the IxNpeMh
 * component.
 *
 * <B>Re-entrancy:</B> This function will be callable from
 * any thread at any time.  However, no resource protection will be used
 * so as not to impact system performance.  As this function is only
 * reading statistical information then this is acceptable.
 *
 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to display state
 * information for.
 *
 * @return The function returns a status indicating success or failure.
 */

PUBLIC IX_STATUS ixNpeMhShow (
    IxNpeMhNpeId npeId);

/**
 * @ingroup IxNpeMh
 *
 * @fn IX_STATUS ixNpeMhShowReset (
           IxNpeMhNpeId npeId)
 *
 * @brief This function will reset the current state of the IxNpeMh
 * component.
 *
 * <B>Re-entrancy:</B> This function will be callable from
 * any thread at any time.  However, no resource protection will be used
 * so as not to impact system performance.  As this function is only
 * writing statistical information then this is acceptable.
 *
 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to reset state
 * information for.
 *
 * @return The function returns a status indicating success or failure.
 */

PUBLIC IX_STATUS ixNpeMhShowReset (
    IxNpeMhNpeId npeId);

#endif /* IXNPEMH_H */

/**
 * @} defgroup IxNpeMh
 */