dm: net: Move IXP NPE to drivers/net/

Signed-off-by: Marek Vasut <marex@denx.de>
Cc: Bryan Hundven <bryanhundven@gmail.com>
Cc: Michael Schwingen <rincewind@discworld.dascon.de>
Cc: Wolfgang Denk <wd@denx.de>
Cc: Albert Aribaud <albert.u.boot@aribaud.net>
Cc: U-Boot DM <u-boot-dm@lists.denx.de>
Cc: Joe Hershberger <joe.hershberger@ni.com>

1 files changed, 497 insertions, 0 deletions

diff --git a/drivers/net/npe/include/IxNpeMh.h b/drivers/net/npe/include/IxNpeMh.h
new file mode 100644
index 0000000000..20ee38b062
--- /dev/null
+++ b/drivers/net/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
+ */