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