diff options
Diffstat (limited to 'cpu/ixp/npe/include/IxNpeMh.h')
| -rw-r--r-- | cpu/ixp/npe/include/IxNpeMh.h | 497 |
1 files changed, 497 insertions, 0 deletions
diff --git a/cpu/ixp/npe/include/IxNpeMh.h b/cpu/ixp/npe/include/IxNpeMh.h new file mode 100644 index 0000000000..20ee38b062 --- /dev/null +++ b/cpu/ixp/npe/include/IxNpeMh.h @@ -0,0 +1,497 @@ +/** + * @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 + */ |