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