arch/arm/cpu/ixp/npe/IxNpeMh.c

   1 /**
   2  * @file IxNpeMh.c
   3  *
   4  * @author Intel Corporation
   5  * @date 18 Jan 2002
   6  *
   7  * @brief This file contains the implementation of the public API for the
   8  * IXP425 NPE Message Handler component.
   9  *
  10  *
  11  * @par
  12  * IXP400 SW Release version 2.0
  13  *
  14  * -- Copyright Notice --
  15  *
  16  * @par
  17  * Copyright 2001-2005, Intel Corporation.
  18  * All rights reserved.
  19  *
  20  * @par
  21  * Redistribution and use in source and binary forms, with or without
  22  * modification, are permitted provided that the following conditions
  23  * are met:
  24  * 1. Redistributions of source code must retain the above copyright
  25  *    notice, this list of conditions and the following disclaimer.
  26  * 2. Redistributions in binary form must reproduce the above copyright
  27  *    notice, this list of conditions and the following disclaimer in the
  28  *    documentation and/or other materials provided with the distribution.
  29  * 3. Neither the name of the Intel Corporation nor the names of its contributors
  30  *    may be used to endorse or promote products derived from this software
  31  *    without specific prior written permission.
  32  *
  33  * @par
  34  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
  35  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  36  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  37  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
  38  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  39  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  40  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  41  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  42  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  43  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  44  * SUCH DAMAGE.
  45  *
  46  * @par
  47  * -- End of Copyright Notice --
  48 */
  49
  50 /*
  51  * Put the system defined include files required.
  52  */
  53
  54 /*
  55  * Put the user defined include files required.
  56  */
  57
  58 #include "IxOsal.h"
  59 #include "IxNpeMhMacros_p.h"
  60
  61 #include "IxNpeMh.h"
  62
  63 #include "IxNpeMhConfig_p.h"
  64 #include "IxNpeMhReceive_p.h"
  65 #include "IxNpeMhSend_p.h"
  66 #include "IxNpeMhSolicitedCbMgr_p.h"
  67 #include "IxNpeMhUnsolicitedCbMgr_p.h"
  68
  69 /*
  70  * #defines and macros used in this file.
  71  */
  72
  73 /*
  74  * Typedefs whose scope is limited to this file.
  75  */
  76
  77 /*
  78  * Variable declarations global to this file only.  Externs are followed by
  79  * static variables.
  80  */
  81
  82 PRIVATE BOOL ixNpeMhInitialized = FALSE;
  83
  84 /*
  85  * Extern function prototypes.
  86  */
  87
  88 /*
  89  * Static function prototypes.
  90  */
  91
  92 /*
  93  * Function definition: ixNpeMhInitialize
  94  */
  95
  96 PUBLIC IX_STATUS ixNpeMhInitialize (
  97     IxNpeMhNpeInterrupts npeInterrupts)
  98 {
  99     IX_NPEMH_TRACE0 (IX_NPEMH_FN_ENTRY_EXIT, "Entering "
 100                      "ixNpeMhInitialize\n");
 101
 102     /* check the npeInterrupts parameter */
 103     if ((npeInterrupts != IX_NPEMH_NPEINTERRUPTS_NO) &&
 104         (npeInterrupts != IX_NPEMH_NPEINTERRUPTS_YES))
 105     {
 106         IX_NPEMH_ERROR_REPORT ("Illegal npeInterrupts parameter value\n");
 107         return IX_FAIL;
 108     }
 109
 110     /* parameters are ok ... */
 111
 112     /* initialize the Receive module */
 113     ixNpeMhReceiveInitialize ();
 114
 115     /* initialize the Solicited Callback Manager module */
 116     ixNpeMhSolicitedCbMgrInitialize ();
 117
 118     /* initialize the Unsolicited Callback Manager module */
 119     ixNpeMhUnsolicitedCbMgrInitialize ();
 120
 121     /* initialize the Configuration module
 122      *
 123      * NOTE: This module was originally configured before the
 124      * others, but the sequence was changed so that interrupts
 125      * would only be enabled after the handler functions were
 126      * set up.  The above modules need to be initialised to
 127      * handle the NPE interrupts.  See SCR #2231.
 128      */
 129     ixNpeMhConfigInitialize (npeInterrupts);
 130
 131     ixNpeMhInitialized = TRUE;
 132
 133     IX_NPEMH_TRACE0 (IX_NPEMH_FN_ENTRY_EXIT, "Exiting "
 134                      "ixNpeMhInitialize\n");
 135
 136     return IX_SUCCESS;
 137 }
 138
 139 /*
 140  * Function definition: ixNpeMhUnload
 141  */
 142
 143 PUBLIC IX_STATUS ixNpeMhUnload (void)
 144 {
 145     IX_NPEMH_TRACE0 (IX_NPEMH_FN_ENTRY_EXIT, "Entering "
 146                      "ixNpeMhUnload\n");
 147
 148     if (!ixNpeMhInitialized)
 149     {
 150         return IX_FAIL;
 151     }
 152
 153     /* Uninitialize the Configuration module */
 154     ixNpeMhConfigUninit ();
 155
 156     ixNpeMhInitialized = FALSE;
 157
 158     IX_NPEMH_TRACE0 (IX_NPEMH_FN_ENTRY_EXIT, "Exiting "
 159                      "ixNpeMhUnload\n");
 160
 161     return IX_SUCCESS;
 162 }
 163
 164
 165 /*
 166  * Function definition: ixNpeMhUnsolicitedCallbackRegister
 167  */
 168
 169 PUBLIC IX_STATUS ixNpeMhUnsolicitedCallbackRegister (
 170     IxNpeMhNpeId npeId,
 171     IxNpeMhMessageId messageId,
 172     IxNpeMhCallback unsolicitedCallback)
 173 {
 174     IX_NPEMH_TRACE0 (IX_NPEMH_FN_ENTRY_EXIT, "Entering "
 175                      "ixNpeMhUnsolicitedCallbackRegister\n");
 176
 177     /* check that we are initialized */
 178     if (!ixNpeMhInitialized)
 179     {
 180         IX_NPEMH_ERROR_REPORT ("IxNpeMh component is not initialized\n");
 181         return IX_FAIL;
 182     }
 183
 184     /* check the npeId parameter */
 185     if (!ixNpeMhConfigNpeIdIsValid (npeId))
 186     {
 187         IX_NPEMH_ERROR_REPORT ("NPE ID invalid\n");
 188         return IX_FAIL;
 189     }
 190
 191     /* check the messageId parameter */
 192     if ((messageId < IX_NPEMH_MIN_MESSAGE_ID)
 193         || (messageId > IX_NPEMH_MAX_MESSAGE_ID))
 194     {
 195         IX_NPEMH_ERROR_REPORT ("Message ID is out of range\n");
 196         return IX_FAIL;
 197     }
 198
 199     /* the unsolicitedCallback parameter is allowed to be NULL */
 200
 201     /* parameters are ok ... */
 202
 203     /* get the lock to prevent other clients from entering */
 204     ixNpeMhConfigLockGet (npeId);
 205
 206     /* save the unsolicited callback for the message ID */
 207     ixNpeMhUnsolicitedCbMgrCallbackSave (
 208         npeId, messageId, unsolicitedCallback);
 209
 210     /* release the lock to allow other clients back in */
 211     ixNpeMhConfigLockRelease (npeId);
 212
 213     IX_NPEMH_TRACE0 (IX_NPEMH_FN_ENTRY_EXIT, "Exiting "
 214                      "ixNpeMhUnsolicitedCallbackRegister\n");
 215
 216     return IX_SUCCESS;
 217 }
 218
 219 /*
 220  * Function definition: ixNpeMhUnsolicitedCallbackForRangeRegister
 221  */
 222
 223 PUBLIC IX_STATUS ixNpeMhUnsolicitedCallbackForRangeRegister (
 224     IxNpeMhNpeId npeId,
 225     IxNpeMhMessageId minMessageId,
 226     IxNpeMhMessageId maxMessageId,
 227     IxNpeMhCallback unsolicitedCallback)
 228 {
 229     IxNpeMhMessageId messageId;
 230
 231     IX_NPEMH_TRACE0 (IX_NPEMH_FN_ENTRY_EXIT, "Entering "
 232                      "ixNpeMhUnsolicitedCallbackForRangeRegister\n");
 233
 234     /* check that we are initialized */
 235     if (!ixNpeMhInitialized)
 236     {
 237         IX_NPEMH_ERROR_REPORT ("IxNpeMh component is not initialized\n");
 238         return IX_FAIL;
 239     }
 240
 241     /* check the npeId parameter */
 242     if (!ixNpeMhConfigNpeIdIsValid (npeId))
 243     {
 244         IX_NPEMH_ERROR_REPORT ("NPE ID invalid\n");
 245         return IX_FAIL;
 246     }
 247
 248     /* check the minMessageId parameter */
 249     if ((minMessageId < IX_NPEMH_MIN_MESSAGE_ID)
 250         || (minMessageId > IX_NPEMH_MAX_MESSAGE_ID))
 251     {
 252         IX_NPEMH_ERROR_REPORT ("Min message ID is out of range\n");
 253         return IX_FAIL;
 254     }
 255
 256     /* check the maxMessageId parameter */
 257     if ((maxMessageId < IX_NPEMH_MIN_MESSAGE_ID)
 258         || (maxMessageId > IX_NPEMH_MAX_MESSAGE_ID))
 259     {
 260         IX_NPEMH_ERROR_REPORT ("Max message ID is out of range\n");
 261         return IX_FAIL;
 262     }
 263
 264     /* check the semantics of the message range parameters */
 265     if (minMessageId > maxMessageId)
 266     {
 267         IX_NPEMH_ERROR_REPORT ("Min message ID greater than max message "
 268                                "ID\n");
 269         return IX_FAIL;
 270     }
 271
 272     /* the unsolicitedCallback parameter is allowed to be NULL */
 273
 274     /* parameters are ok ... */
 275
 276     /* get the lock to prevent other clients from entering */
 277     ixNpeMhConfigLockGet (npeId);
 278
 279     /* for each message ID in the range ... */
 280     for (messageId = minMessageId; messageId <= maxMessageId; messageId++)
 281     {
 282         /* save the unsolicited callback for the message ID */
 283         ixNpeMhUnsolicitedCbMgrCallbackSave (
 284             npeId, messageId, unsolicitedCallback);
 285     }
 286
 287     /* release the lock to allow other clients back in */
 288     ixNpeMhConfigLockRelease (npeId);
 289
 290     IX_NPEMH_TRACE0 (IX_NPEMH_FN_ENTRY_EXIT, "Exiting "
 291                      "ixNpeMhUnsolicitedCallbackForRangeRegister\n");
 292
 293     return IX_SUCCESS;
 294 }
 295
 296 /*
 297  * Function definition: ixNpeMhMessageSend
 298  */
 299
 300 PUBLIC IX_STATUS ixNpeMhMessageSend (
 301     IxNpeMhNpeId npeId,
 302     IxNpeMhMessage message,
 303     UINT32 maxSendRetries)
 304 {
 305     IX_STATUS status = IX_SUCCESS;
 306
 307     IX_NPEMH_TRACE0 (IX_NPEMH_FN_ENTRY_EXIT, "Entering "
 308                      "ixNpeMhMessageSend\n");
 309
 310     /* check that we are initialized */
 311     if (!ixNpeMhInitialized)
 312     {
 313         IX_NPEMH_ERROR_REPORT ("IxNpeMh component is not initialized\n");
 314         return IX_FAIL;
 315     }
 316
 317     /* check the npeId parameter */
 318     if (!ixNpeMhConfigNpeIdIsValid (npeId))
 319     {
 320         IX_NPEMH_ERROR_REPORT ("NPE ID invalid\n");
 321         return IX_FAIL;
 322     }
 323
 324     /* parameters are ok ... */
 325
 326     /* get the lock to prevent other clients from entering */
 327     ixNpeMhConfigLockGet (npeId);
 328
 329     /* send the message */
 330     status = ixNpeMhSendMessageSend (npeId, message, maxSendRetries);
 331     if (status != IX_SUCCESS)
 332     {
 333         IX_NPEMH_ERROR_REPORT ("Failed to send message\n");
 334     }
 335
 336     /* release the lock to allow other clients back in */
 337     ixNpeMhConfigLockRelease (npeId);
 338
 339     IX_NPEMH_TRACE1 (IX_NPEMH_FN_ENTRY_EXIT, "Exiting "
 340                      "ixNpeMhMessageSend"
 341                      " : status = %d\n", status);
 342
 343     return status;
 344 }
 345
 346 /*
 347  * Function definition: ixNpeMhMessageWithResponseSend
 348  */
 349
 350 PUBLIC IX_STATUS ixNpeMhMessageWithResponseSend (
 351     IxNpeMhNpeId npeId,
 352     IxNpeMhMessage message,
 353     IxNpeMhMessageId solicitedMessageId,
 354     IxNpeMhCallback solicitedCallback,
 355     UINT32 maxSendRetries)
 356 {
 357     IX_STATUS status = IX_SUCCESS;
 358     IxNpeMhCallback unsolicitedCallback = NULL;
 359
 360     IX_NPEMH_TRACE0 (IX_NPEMH_FN_ENTRY_EXIT, "Entering "
 361                      "ixNpeMhMessageWithResponseSend\n");
 362
 363     /* check that we are initialized */
 364     if (!ixNpeMhInitialized)
 365     {
 366         IX_NPEMH_ERROR_REPORT ("IxNpeMh component is not initialized\n");
 367         return IX_FAIL;
 368     }
 369
 370     /* the solicitecCallback parameter is allowed to be NULL.  this */
 371     /* signifies the client is not interested in the response message */
 372
 373     /* check the npeId parameter */
 374     if (!ixNpeMhConfigNpeIdIsValid (npeId))
 375     {
 376         IX_NPEMH_ERROR_REPORT ("NPE ID invalid\n");
 377         return IX_FAIL;
 378     }
 379
 380     /* check the solicitedMessageId parameter */
 381     if ((solicitedMessageId < IX_NPEMH_MIN_MESSAGE_ID)
 382         || (solicitedMessageId > IX_NPEMH_MAX_MESSAGE_ID))
 383     {
 384         IX_NPEMH_ERROR_REPORT ("Solicited message ID is out of range\n");
 385         return IX_FAIL;
 386     }
 387
 388     /* check the solicitedMessageId parameter.  if an unsolicited */
 389     /* callback has been registered for the specified message ID then */
 390     /* report an error and return failure */
 391     ixNpeMhUnsolicitedCbMgrCallbackRetrieve (
 392         npeId, solicitedMessageId, &unsolicitedCallback);
 393     if (unsolicitedCallback != NULL)
 394     {
 395         IX_NPEMH_ERROR_REPORT ("Solicited message ID conflicts with "
 396                                "unsolicited message ID\n");
 397         return IX_FAIL;
 398     }
 399
 400     /* parameters are ok ... */
 401
 402     /* get the lock to prevent other clients from entering */
 403     ixNpeMhConfigLockGet (npeId);
 404
 405     /* send the message */
 406     status = ixNpeMhSendMessageWithResponseSend (
 407         npeId, message, solicitedMessageId, solicitedCallback,
 408         maxSendRetries);
 409     if (status != IX_SUCCESS)
 410     {
 411         IX_NPEMH_ERROR_REPORT ("Failed to send message\n");
 412     }
 413
 414     /* release the lock to allow other clients back in */
 415     ixNpeMhConfigLockRelease (npeId);
 416
 417     IX_NPEMH_TRACE1 (IX_NPEMH_FN_ENTRY_EXIT, "Exiting "
 418                      "ixNpeMhMessageWithResponseSend"
 419                      " : status = %d\n", status);
 420
 421     return status;
 422 }
 423
 424 /*
 425  * Function definition: ixNpeMhMessagesReceive
 426  */
 427
 428 PUBLIC IX_STATUS ixNpeMhMessagesReceive (
 429     IxNpeMhNpeId npeId)
 430 {
 431     IX_STATUS status = IX_SUCCESS;
 432
 433     IX_NPEMH_TRACE0 (IX_NPEMH_FN_ENTRY_EXIT, "Entering "
 434                      "ixNpeMhMessagesReceive\n");
 435
 436     /* check that we are initialized */
 437     if (!ixNpeMhInitialized)
 438     {
 439         IX_NPEMH_ERROR_REPORT ("IxNpeMh component is not initialized\n");
 440         return IX_FAIL;
 441     }
 442
 443     /* check the npeId parameter */
 444     if (!ixNpeMhConfigNpeIdIsValid (npeId))
 445     {
 446         IX_NPEMH_ERROR_REPORT ("NPE ID invalid\n");
 447         return IX_FAIL;
 448     }
 449
 450     /* parameters are ok ... */
 451
 452     /* get the lock to prevent other clients from entering */
 453     ixNpeMhConfigLockGet (npeId);
 454
 455     /* receive messages from the NPE */
 456     status = ixNpeMhReceiveMessagesReceive (npeId);
 457
 458     if (status != IX_SUCCESS)
 459     {
 460         IX_NPEMH_ERROR_REPORT ("Failed to receive message\n");
 461     }
 462
 463     /* release the lock to allow other clients back in */
 464     ixNpeMhConfigLockRelease (npeId);
 465
 466     IX_NPEMH_TRACE1 (IX_NPEMH_FN_ENTRY_EXIT, "Exiting "
 467                      "ixNpeMhMessagesReceive"
 468                      " : status = %d\n", status);
 469
 470     return status;
 471 }
 472
 473 /*
 474  * Function definition: ixNpeMhShow
 475  */
 476
 477 PUBLIC IX_STATUS ixNpeMhShow (
 478     IxNpeMhNpeId npeId)
 479 {
 480     IX_NPEMH_TRACE0 (IX_NPEMH_FN_ENTRY_EXIT, "Entering "
 481                      "ixNpeMhShow\n");
 482
 483     /* check that we are initialized */
 484     if (!ixNpeMhInitialized)
 485     {
 486         IX_NPEMH_ERROR_REPORT ("IxNpeMh component is not initialized\n");
 487         return IX_FAIL;
 488     }
 489
 490     /* check the npeId parameter */
 491     if (!ixNpeMhConfigNpeIdIsValid (npeId))
 492     {
 493         IX_NPEMH_ERROR_REPORT ("NPE ID invalid\n");
 494         return IX_FAIL;
 495     }
 496
 497     /* parameters are ok ... */
 498
 499     /* note we don't get the lock here as printing the statistics */
 500     /* to a console may take some time and we don't want to impact */
 501     /* system performance.  this means that the statistics displayed */
 502     /* may be in a state of flux and make not represent a consistent */
 503     /* snapshot. */
 504
 505     /* display a header */
 506     ixOsalLog (IX_OSAL_LOG_LVL_USER, IX_OSAL_LOG_DEV_STDOUT,
 507                "Current state of NPE ID %d:\n\n", npeId, 0, 0, 0, 0, 0);
 508
 509     /* show the current state of each module */
 510
 511     /* show the current state of the Configuration module */
 512     ixNpeMhConfigShow (npeId);
 513
 514     /* show the current state of the Receive module */
 515     ixNpeMhReceiveShow (npeId);
 516
 517     /* show the current state of the Send module */
 518     ixNpeMhSendShow (npeId);
 519
 520     /* show the current state of the Solicited Callback Manager module */
 521     ixNpeMhSolicitedCbMgrShow (npeId);
 522
 523     /* show the current state of the Unsolicited Callback Manager module */
 524     ixNpeMhUnsolicitedCbMgrShow (npeId);
 525
 526     IX_NPEMH_TRACE0 (IX_NPEMH_FN_ENTRY_EXIT, "Exiting "
 527                      "ixNpeMhShow\n");
 528
 529     return IX_SUCCESS;
 530 }
 531
 532 /*
 533  * Function definition: ixNpeMhShowReset
 534  */
 535
 536 PUBLIC IX_STATUS ixNpeMhShowReset (
 537     IxNpeMhNpeId npeId)
 538 {
 539     IX_NPEMH_TRACE0 (IX_NPEMH_FN_ENTRY_EXIT, "Entering "
 540                      "ixNpeMhShowReset\n");
 541
 542     /* check that we are initialized */
 543     if (!ixNpeMhInitialized)
 544     {
 545         IX_NPEMH_ERROR_REPORT ("IxNpeMh component is not initialized\n");
 546         return IX_FAIL;
 547     }
 548
 549     /* check the npeId parameter */
 550     if (!ixNpeMhConfigNpeIdIsValid (npeId))
 551     {
 552         IX_NPEMH_ERROR_REPORT ("NPE ID invalid\n");
 553         return IX_FAIL;
 554     }
 555
 556     /* parameters are ok ... */
 557
 558     /* note we don't get the lock here as resetting the statistics */
 559     /* shouldn't impact system performance. */
 560
 561     /* reset the current state of each module */
 562
 563     /* reset the current state of the Configuration module */
 564     ixNpeMhConfigShowReset (npeId);
 565
 566     /* reset the current state of the Receive module */
 567     ixNpeMhReceiveShowReset (npeId);
 568
 569     /* reset the current state of the Send module */
 570     ixNpeMhSendShowReset (npeId);
 571
 572     /* reset the current state of the Solicited Callback Manager module */
 573     ixNpeMhSolicitedCbMgrShowReset (npeId);
 574
 575     /* reset the current state of the Unsolicited Callback Manager module */
 576     ixNpeMhUnsolicitedCbMgrShowReset (npeId);
 577
 578     IX_NPEMH_TRACE0 (IX_NPEMH_FN_ENTRY_EXIT, "Exiting "
 579                      "ixNpeMhShowReset\n");
 580
 581     return IX_SUCCESS;
 582 }