drivers/net/npe/include/IxNpeMh.h

   1 /**
   2  * @file IxNpeMh.h
   3  *
   4  * @date 14 Dec 2001
   5  *
   6  * @brief This file contains the public API for the IXP400 NPE Message
   7  * Handler component.
   8  *
   9  *
  10  * @par
  11  * IXP400 SW Release version 2.0
  12  *
  13  * -- Copyright Notice --
  14  *
  15  * @par
  16  * Copyright 2001-2005, Intel Corporation.
  17  * All rights reserved.
  18  *
  19  * @par
  20  * SPDX-License-Identifier:     BSD-3-Clause
  21  * @par
  22  * -- End of Copyright Notice --
  23 */
  24
  25 /**
  26  * @defgroup IxNpeMh IXP400 NPE Message Handler (IxNpeMh) API
  27  *
  28  * @brief The public API for the IXP400 NPE Message Handler component.
  29  *
  30  * @{
  31  */
  32
  33 #ifndef IXNPEMH_H
  34 #define IXNPEMH_H
  35
  36 #include "IxOsalTypes.h"
  37
  38 /*
  39  * #defines for function return types, etc.
  40  */
  41
  42 #define IX_NPEMH_MIN_MESSAGE_ID (0x00) /**< minimum valid message ID */
  43 #define IX_NPEMH_MAX_MESSAGE_ID (0xFF) /**< maximum valid message ID */
  44
  45 #define IX_NPEMH_SEND_RETRIES_DEFAULT (3) /**< default msg send retries */
  46
  47
  48 /**
  49  * @def IX_NPEMH_CRITICAL_NPE_ERR
  50  *
  51  * @brief NpeMH function return value for a Critical NPE error occuring during
  52           sending/receiving message. Assume NPE hang / halt if this value is
  53           returned.
  54  */
  55 #define IX_NPEMH_CRITICAL_NPE_ERR        2
  56
  57 /**
  58  * @enum IxNpeMhNpeId
  59  *
  60  * @brief The ID of a particular NPE.
  61  * @note In this context, for IXP425 Silicon (B0):<br>
  62  *      - NPE-A has HDLC, HSS, AAL and UTOPIA Coprocessors.<br>
  63  *      - NPE-B has Ethernet Coprocessor.<br>
  64  *      - NPE-C has Ethernet, AES, DES and HASH Coprocessors.<br>
  65  *      - IXP400 Product Line have different combinations of coprocessors.
  66  */
  67
  68 typedef enum
  69 {
  70     IX_NPEMH_NPEID_NPEA = 0, /**< ID for NPE-A */
  71     IX_NPEMH_NPEID_NPEB,     /**< ID for NPE-B */
  72     IX_NPEMH_NPEID_NPEC,     /**< ID for NPE-C */
  73     IX_NPEMH_NUM_NPES        /**< Number of NPEs */
  74 } IxNpeMhNpeId;
  75
  76 /**
  77  * @enum IxNpeMhNpeInterrupts
  78  *
  79  * @brief Indicator specifying whether or not NPE interrupts should drive
  80  * receiving of messages from the NPEs.
  81  */
  82
  83 typedef enum
  84 {
  85     IX_NPEMH_NPEINTERRUPTS_NO = 0, /**< Don't use NPE interrupts */
  86     IX_NPEMH_NPEINTERRUPTS_YES     /**< Do use NPE interrupts */
  87 } IxNpeMhNpeInterrupts;
  88
  89 /**
  90  * @brief The 2-word message structure to send to and receive from the
  91  * NPEs.
  92  */
  93
  94 typedef struct
  95 {
  96     UINT32 data[2]; /**< the actual data of the message */
  97 } IxNpeMhMessage;
  98
  99 /** message ID */
 100 typedef UINT32 IxNpeMhMessageId;
 101
 102 /**
 103  * @typedef IxNpeMhCallback
 104  *
 105  * @brief This prototype shows the format of a message callback function.
 106  *
 107  * This prototype shows the format of a message callback function.  The
 108  * message callback will be passed the message to be handled and will also
 109  * be told from which NPE the message was received.  The message callback
 110  * will either be registered by ixNpeMhUnsolicitedCallbackRegister() or
 111  * passed as a parameter to ixNpeMhMessageWithResponseSend().  It will be
 112  * called from within an ISR triggered by the NPE's "outFIFO not empty"
 113  * interrupt (see ixNpeMhInitialize()).  The parameters passed are the ID
 114  * of the NPE that the message was received from, and the message to be
 115  * handled.<P><B>Re-entrancy:</B> This function is only a prototype, and
 116  * will be implemented by the client.  It does not need to be re-entrant.
 117  */
 118
 119 typedef void (*IxNpeMhCallback) (IxNpeMhNpeId, IxNpeMhMessage);
 120
 121 /*
 122  * Prototypes for interface functions.
 123  */
 124
 125 /**
 126  * @ingroup IxNpeMh
 127  *
 128  * @fn IX_STATUS ixNpeMhInitialize (
 129            IxNpeMhNpeInterrupts npeInterrupts)
 130  *
 131  * @brief This function will initialise the IxNpeMh component.
 132  *
 133  * @param npeInterrupts @ref IxNpeMhNpeInterrupts [in] - This parameter
 134  * dictates whether or not the IxNpeMh component will service NPE "outFIFO
 135  * not empty" interrupts to trigger receiving and processing of messages
 136  * from the NPEs.  If not then the client must use ixNpeMhMessagesReceive()
 137  * to control message receiving and processing.
 138  *
 139  * This function will initialise the IxNpeMh component.  It should only be
 140  * called once, prior to using the IxNpeMh component.  The following
 141  * actions will be performed by this function:<OL><LI>Initialization of
 142  * internal data structures (e.g. solicited and unsolicited callback
 143  * tables).</LI><LI>Configuration of the interface with the NPEs (e.g.
 144  * enabling of NPE "outFIFO not empty" interrupts).</LI><LI>Registration of
 145  * ISRs that will receive and handle messages when the NPEs' "outFIFO not
 146  * empty" interrupts fire (if npeInterrupts equals
 147  * IX_NPEMH_NPEINTERRUPTS_YES).</LI></OL>
 148  *
 149  * @return The function returns a status indicating success or failure.
 150  */
 151
 152 PUBLIC IX_STATUS ixNpeMhInitialize (
 153     IxNpeMhNpeInterrupts npeInterrupts);
 154
 155 /**
 156  * @ingroup IxNpeMh
 157  *
 158  * @fn IX_STATUS ixNpeMhUnload (void)
 159  *
 160  * @brief This function will uninitialise the IxNpeMh component.
 161  *
 162  * This function will uninitialise the IxNpeMh component.  It should only be
 163  * called once, and only if the IxNpeMh component has already been initialised.
 164  * No other IxNpeMh API functions should be called until @ref ixNpeMhInitialize
 165  * is called again.
 166  * If possible, this function should be called before a soft reboot or unloading
 167  * a kernel module to perform any clean up operations required for IxNpeMh.
 168  *
 169  * The following actions will be performed by this function:
 170  * <OL><LI>Unmapping of kernel memory mapped by the function
 171  * @ref ixNpeMhInitialize.</LI></OL>
 172  *
 173  * @return The function returns a status indicating success or failure.
 174  */
 175
 176 PUBLIC IX_STATUS ixNpeMhUnload (void);
 177
 178 /**
 179  * @ingroup IxNpeMh
 180  *
 181  * @fn IX_STATUS ixNpeMhUnsolicitedCallbackRegister (
 182            IxNpeMhNpeId npeId,
 183            IxNpeMhMessageId messageId,
 184            IxNpeMhCallback unsolicitedCallback)
 185  *
 186  * @brief This function will register an unsolicited callback for a
 187  * particular NPE and message ID.
 188  *
 189  * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE whose messages
 190  * the unsolicited callback will handle.
 191  * @param messageId @ref IxNpeMhMessageId [in] - The ID of the messages the
 192  * unsolicited callback will handle.
 193  * @param unsolicitedCallback @ref IxNpeMhCallback [in] - The unsolicited
 194  * callback function.  A value of NULL will deregister any previously
 195  * registered callback for this NPE and message ID.
 196  *
 197  * This function will register an unsolicited message callback for a
 198  * particular NPE and message ID.<P>If an unsolicited callback is already
 199  * registered for the specified NPE and message ID then the callback will
 200  * be overwritten.  Only one client will be responsible for handling a
 201  * particular message ID associated with a NPE.  Registering a NULL
 202  * unsolicited callback will deregister any previously registered
 203  * callback.<P>The callback function will be called from an ISR that will
 204  * be triggered by the NPE's "outFIFO not empty" interrupt (see
 205  * ixNpeMhInitialize()) to handle any unsolicited messages of the specific
 206  * message ID received from the NPE.  Unsolicited messages will be handled
 207  * in the order they are received.<P>If no unsolicited callback can be
 208  * found for a received message then it is assumed that the message is
 209  * solicited.<P>If more than one client may be interested in a particular
 210  * unsolicited message then the suggested strategy is to register a
 211  * callback for the message that can itself distribute the message to
 212  * multiple clients as necessary.<P>See also
 213  * ixNpeMhUnsolicitedCallbackForRangeRegister().<P><B>Re-entrancy:</B> This
 214  * function will be callable from any thread at any time.  IxOsal
 215  * will be used for any necessary resource protection.
 216  *
 217  * @return The function returns a status indicating success or failure.
 218  */
 219
 220 PUBLIC IX_STATUS ixNpeMhUnsolicitedCallbackRegister (
 221     IxNpeMhNpeId npeId,
 222     IxNpeMhMessageId messageId,
 223     IxNpeMhCallback unsolicitedCallback);
 224
 225 /**
 226  * @ingroup IxNpeMh
 227  *
 228  * @fn IX_STATUS ixNpeMhUnsolicitedCallbackForRangeRegister (
 229            IxNpeMhNpeId npeId,
 230            IxNpeMhMessageId minMessageId,
 231            IxNpeMhMessageId maxMessageId,
 232            IxNpeMhCallback unsolicitedCallback)
 233  *
 234  * @brief This function will register an unsolicited callback for a
 235  * particular NPE and range of message IDs.
 236  *
 237  * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE whose messages the
 238  * unsolicited callback will handle.
 239  * @param minMessageId @ref IxNpeMhMessageId [in] - The minimum message ID in
 240  * the range of message IDs the unsolicited callback will handle.
 241  * @param maxMessageId @ref IxNpeMhMessageId [in] - The maximum message ID in
 242  * the range of message IDs the unsolicited callback will handle.
 243  * @param unsolicitedCallback @ref IxNpeMhCallback [in] - The unsolicited
 244  * callback function.  A value of NULL will deregister any previously
 245  * registered callback(s) for this NPE and range of message IDs.
 246  *
 247  * This function will register an unsolicited callback for a particular NPE
 248  * and range of message IDs.  It is a convenience function that is
 249  * effectively the same as calling ixNpeMhUnsolicitedCallbackRegister() for
 250  * each ID in the specified range.  See
 251  * ixNpeMhUnsolicitedCallbackRegister() for more
 252  * information.<P><B>Re-entrancy:</B> This function will be callable from
 253  * any thread at any time.  IxOsal will be used for any necessary
 254  * resource protection.
 255  *
 256  * @return The function returns a status indicating success or failure.
 257  */
 258
 259 PUBLIC IX_STATUS ixNpeMhUnsolicitedCallbackForRangeRegister (
 260     IxNpeMhNpeId npeId,
 261     IxNpeMhMessageId minMessageId,
 262     IxNpeMhMessageId maxMessageId,
 263     IxNpeMhCallback unsolicitedCallback);
 264
 265 /**
 266  * @ingroup IxNpeMh
 267  *
 268  * @fn IX_STATUS ixNpeMhMessageSend (
 269            IxNpeMhNpeId npeId,
 270            IxNpeMhMessage message,
 271            UINT32 maxSendRetries)
 272  *
 273  * @brief This function will send a message to a particular NPE.
 274  *
 275  * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to send the message
 276  * to.
 277  * @param message @ref IxNpeMhMessage [in] - The message to send.
 278  * @param maxSendRetries UINT32 [in] - Max num. of retries to perform
 279  * if the NPE's inFIFO is full.
 280  *
 281  * This function will send a message to a particular NPE.  It will be the
 282  * client's responsibility to ensure that the message is properly formed.
 283  * The return status will signify to the client if the message was
 284  * successfully sent or not.<P>If the message is sent to the NPE then this
 285  * function will return a status of success.  Note that this will only mean
 286  * the message has been placed in the NPE's inFIFO.  There will be no way
 287  * of knowing that the NPE has actually read the message, but once in the
 288  * incoming message queue it will be safe to assume that the NPE will
 289  * process it.
 290  * <P>The inFIFO may fill up sometimes if the Xscale is sending messages
 291  * faster than the NPE can handle them. This forces us to retry attempts
 292  * to send the message until the NPE services the inFIFO. The client should
 293  * specify a ceiling value for the number of retries suitable to their
 294  * needs. IX_NPEMH_SEND_RETRIES_DEFAULT can be used as a default value for
 295  * the <i>maxSendRetries</i> parameter for this function. Each retry
 296  * exceeding this default number will incur a blocking delay of 1 microsecond,
 297  * to avoid consuming too much AHB bus bandwidth while performing retries.
 298  * <P>Note this function <B>must</B> only be used for messages.
 299  * that do not solicit responses. If the message being sent will solicit a
 300  * response then the ixNpeMhMessageWithResponseSend() function <B>must</B>
 301  * be used to ensure that the response is correctly
 302  * handled. <P> This function will return timeout status if NPE hang / halt
 303  * while sending message. The timeout error is not related to the
 304  * <i>maxSendRetries</i> as mentioned above. The timeout error will only occur
 305  * if the first word of the message has been sent to NPE (not exceeding
 306  * <i>maxSendRetries</i> when sending 1st message word), but the second word of
 307  * the message can't be written to NPE's inFIFO due to NPE hang / halt after
 308  * maximum waiting time (IX_NPE_MH_MAX_NUM_OF_RETRIES).
 309  * <P><B>Re-entrancy:</B> This function will be callable from any
 310  * thread at any time.  IxOsal will be used for any necessary
 311  * resource protection.
 312  *
 313  * @return The function returns a status indicating success, failure or timeout.
 314  */
 315
 316 PUBLIC IX_STATUS ixNpeMhMessageSend (
 317     IxNpeMhNpeId npeId,
 318     IxNpeMhMessage message,
 319     UINT32 maxSendRetries);
 320
 321 /**
 322  * @ingroup IxNpeMh
 323  *
 324  * @fn IX_STATUS ixNpeMhMessageWithResponseSend (
 325            IxNpeMhNpeId npeId,
 326            IxNpeMhMessage message,
 327            IxNpeMhMessageId solicitedMessageId,
 328            IxNpeMhCallback solicitedCallback,
 329            UINT32 maxSendRetries)
 330  *
 331  * @brief This function is equivalent to the ixNpeMhMessageSend() function,
 332  * but must be used when the message being sent will solicited a response.
 333  *
 334  * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to send the message
 335  * to.
 336  * @param message @ref IxNpeMhMessage [in] - The message to send.
 337  * @param solicitedMessageId @ref IxNpeMhMessageId [in] - The ID of the
 338  * solicited response message.
 339  * @param solicitedCallback @ref IxNpeMhCallback [in] - The function to use to
 340  * pass the response message back to the client.  A value of NULL will
 341  * cause the response message to be discarded.
 342  * @param maxSendRetries UINT32 [in] - Max num. of retries to perform
 343  * if the NPE's inFIFO is full.
 344  *
 345  * This function is equivalent to the ixNpeMhMessageSend() function, but
 346  * must be used when the message being sent will solicited a
 347  * response.<P>The client must specify the ID of the solicited response
 348  * message to allow the response to be recognised when it is received.  The
 349  * client must also specify a callback function to handle the received
 350  * response.  The IxNpeMh component will not offer the facility to send a
 351  * message to a NPE and receive a response within the same context.<P>Note
 352  * if the client is not interested in the response, specifying a NULL
 353  * callback will cause the response message to be discarded.<P>The
 354  * solicited callback will be stored and called some time later from an ISR
 355  * that will be triggered by the NPE's "outFIFO not empty" interrupt (see
 356  * ixNpeMhInitialize()) to handle the response message corresponding to the
 357  * message sent.  Response messages will be handled in the order they are
 358  * received.<P>
 359  * <P>The inFIFO may fill up sometimes if the Xscale is sending messages
 360  * faster than the NPE can handle them. This forces us to retry attempts
 361  * to send the message until the NPE services the inFIFO. The client should
 362  * specify a ceiling value for the number of retries suitable to their
 363  * needs. IX_NPEMH_SEND_RETRIES_DEFAULT can be used as a default value for
 364  * the <i>maxSendRetries</i> parameter for this function. Each retry
 365  * exceeding this default number will incur a blocking delay of 1 microsecond,
 366  * to avoid consuming too much AHB bus bandwidth while performing retries.
 367  * <P> This function will return timeout status if NPE hang / halt
 368  * while sending message. The timeout error is not related to the
 369  * <i>maxSendRetries</i> as mentioned above. The timeout error will only occur
 370  * if the first word of the message has been sent to NPE (not exceeding
 371  * <i>maxSendRetries</i> when sending 1st message word), but the second word of
 372  * the message can't be written to NPE's inFIFO due to NPE hang / halt after
 373  * maximum waiting time (IX_NPE_MH_MAX_NUM_OF_RETRIES).
 374  * <P><B>Re-entrancy:</B> This function will be callable from any
 375  * thread at any time.  IxOsal will be used for any necessary
 376  * resource protection.
 377  *
 378  * @return The function returns a status indicating success or failure.
 379  */
 380
 381 PUBLIC IX_STATUS ixNpeMhMessageWithResponseSend (
 382     IxNpeMhNpeId npeId,
 383     IxNpeMhMessage message,
 384     IxNpeMhMessageId solicitedMessageId,
 385     IxNpeMhCallback solicitedCallback,
 386     UINT32 maxSendRetries);
 387
 388 /**
 389  * @ingroup IxNpeMh
 390  *
 391  * @fn IX_STATUS ixNpeMhMessagesReceive (
 392            IxNpeMhNpeId npeId)
 393  *
 394  * @brief This function will receive messages from a particular NPE and
 395  * pass each message to the client via a solicited callback (for solicited
 396  * messages) or an unsolicited callback (for unsolicited messages).
 397  *
 398  * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to receive and
 399  * process messages from.
 400  *
 401  * This function will receive messages from a particular NPE and pass each
 402  * message to the client via a solicited callback (for solicited messages)
 403  * or an unsolicited callback (for unsolicited messages).<P>If the IxNpeMh
 404  * component is initialised to service NPE "outFIFO not empty" interrupts
 405  * (see ixNpeMhInitialize()) then there is no need to call this function.
 406  * This function is only provided as an alternative mechanism to control
 407  * the receiving and processing of messages from the NPEs.<P> This function
 408  * will return timeout status if NPE hang / halt while receiving message. The
 409  * timeout error will only occur if this function has read the first word of
 410  * the message and can't read second word of the message from NPE's outFIFO
 411  * after maximum retries (IX_NPE_MH_MAX_NUM_OF_RETRIES).
 412  * <P>Note this function cannot be called from within
 413  * an ISR as it will use resource protection mechanisms.<P><B>Re-entrancy:</B>
 414  * This function will be callable from any thread at any time.  IxOsal will be
 415  * used for any necessary resource protection.
 416  *
 417  * @return The function returns a status indicating success, failure or timeout.
 418  */
 419
 420 PUBLIC IX_STATUS ixNpeMhMessagesReceive (
 421     IxNpeMhNpeId npeId);
 422
 423 /**
 424  * @ingroup IxNpeMh
 425  *
 426  * @fn IX_STATUS ixNpeMhShow (
 427            IxNpeMhNpeId npeId)
 428  *
 429  * @brief This function will display the current state of the IxNpeMh
 430  * component.
 431  *
 432  * <B>Re-entrancy:</B> This function will be callable from
 433  * any thread at any time.  However, no resource protection will be used
 434  * so as not to impact system performance.  As this function is only
 435  * reading statistical information then this is acceptable.
 436  *
 437  * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to display state
 438  * information for.
 439  *
 440  * @return The function returns a status indicating success or failure.
 441  */
 442
 443 PUBLIC IX_STATUS ixNpeMhShow (
 444     IxNpeMhNpeId npeId);
 445
 446 /**
 447  * @ingroup IxNpeMh
 448  *
 449  * @fn IX_STATUS ixNpeMhShowReset (
 450            IxNpeMhNpeId npeId)
 451  *
 452  * @brief This function will reset the current state of the IxNpeMh
 453  * component.
 454  *
 455  * <B>Re-entrancy:</B> This function will be callable from
 456  * any thread at any time.  However, no resource protection will be used
 457  * so as not to impact system performance.  As this function is only
 458  * writing statistical information then this is acceptable.
 459  *
 460  * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to reset state
 461  * information for.
 462  *
 463  * @return The function returns a status indicating success or failure.
 464  */
 465
 466 PUBLIC IX_STATUS ixNpeMhShowReset (
 467     IxNpeMhNpeId npeId);
 468
 469 #endif /* IXNPEMH_H */
 470
 471 /**
 472  * @} defgroup IxNpeMh
 473  */