path: root/Acceleration/library/icp_telephony/tdm_infrastructure_message_handler/IxPiuMhReceive.c

/**
 * @file IxPiuMhReceive.c
 *
 * @author Intel Corporation
 * @date 18 Jan 2002
 *
 * @description Contents are the implementation of the private API for
 * the Receive module.
 *
 *
 * @par
 * This file is provided under a dual BSD/GPLv2 license.  When using or 
 *   redistributing this file, you may do so under either license.
 * 
 *   GPL LICENSE SUMMARY
 * 
 *   Copyright(c) 2007,2008,2009 Intel Corporation. All rights reserved.
 * 
 *   This program is free software; you can redistribute it and/or modify 
 *   it under the terms of version 2 of the GNU General Public License as
 *   published by the Free Software Foundation.
 * 
 *   This program is distributed in the hope that it will be useful, but 
 *   WITHOUT ANY WARRANTY; without even the implied warranty of 
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU 
 *   General Public License for more details.
 * 
 *   You should have received a copy of the GNU General Public License 
 *   along with this program; if not, write to the Free Software 
 *   Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.
 *   The full GNU General Public License is included in this distribution 
 *   in the file called LICENSE.GPL.
 * 
 *   Contact Information:
 *   Intel Corporation
 * 
 *   BSD LICENSE 
 * 
 *   Copyright(c) 2007,2008,2009 Intel Corporation. All rights reserved.
 *   All rights reserved.
 * 
 *   Redistribution and use in source and binary forms, with or without 
 *   modification, are permitted provided that the following conditions 
 *   are met:
 * 
 *     * Redistributions of source code must retain the above copyright 
 *       notice, this list of conditions and the following disclaimer.
 *     * 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.
 *     * Neither the name of 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.
 * 
 *   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.
 * 
 * 
 *
*/

/*
 * Put the system defined include files required.
 */


/*
 * Put the user defined include files required.
 */
#include "IxOsal.h"
#include "IxPiuMhMacros_p.h"
#include "IxPiuMhConfig_p.h"
#include "IxPiuMhReceive_p.h"
#include "IxPiuMhSolicitedCbMgr_p.h"
#include "IxPiuMhUnsolicitedCbMgr_p.h"

/*
 * #defines and macros used in this file.
 */

/*
 * Typedefs whose scope is limited to this file.
 */

/**
 * @struct IxPiuMhReceiveStats
 *
 * @brief This structure is used to maintain statistics for the Receive
 * module.
 */

typedef struct
{
    UINT32 isrs;        /**< receive ISR invocations */
    UINT32 receives;    /**< receive messages invocations */
    UINT32 messages;    /**< messages received */
    UINT32 solicited;   /**< solicited messages received */
    UINT32 unsolicited; /**< unsolicited messages received */
    UINT32 callbacks;   /**< callbacks invoked */
} IxPiuMhReceiveStats;

/*
 * Variable declarations global to this file only.  Externs are followed by
 * static variables.
 */

PRIVATE IxPiuMhReceiveStats ixPiuMhReceiveStats[IX_PIUMH_NUM_PIUS];

/*
 * Extern function prototypes.
 */

/*
 * Static function prototypes.
 */
PRIVATE
void ixPiuMhReceiveIsr (int piuId);

PRIVATE
void ixPiuMhReceiveIsr (int piuId)
{
    int lockKey;

    IX_PIUMH_TRACE0 (IX_PIUMH_FN_ENTRY_EXIT, "Entering "
                     "ixPiuMhReceiveIsr\n");

    lockKey = ixOsalIrqLock ();

    /* invoke the message receive routine to get messages from the PIU */
    ixPiuMhReceiveMessagesReceive (piuId);

    /* update statistical info */
    ixPiuMhReceiveStats[piuId].isrs++;

    ixOsalIrqUnlock (lockKey);

    IX_PIUMH_TRACE0 (IX_PIUMH_FN_ENTRY_EXIT, "Exiting "
                     "ixPiuMhReceiveIsr\n");
}

/*
 * Function definition: ixPiuMhReceiveInitialize
 */

void ixPiuMhReceiveInitialize (void)
{
    IxPiuMhPiuId piuId = 0;

    IX_PIUMH_TRACE0 (IX_PIUMH_FN_ENTRY_EXIT, "Entering "
                     "ixPiuMhReceiveInitialize\n");

    /* for each PIU ... */
    for (piuId = 0; piuId < IX_PIUMH_NUM_PIUS; piuId++)
    {
        /* register our internal ISR for the PIU to handle "outFIFO not */
        /* empty" interrupts */
        ixPiuMhConfigIsrRegister (piuId, ixPiuMhReceiveIsr);
    }

    IX_PIUMH_TRACE0 (IX_PIUMH_FN_ENTRY_EXIT, "Exiting "
                     "ixPiuMhReceiveInitialize\n");
}

/*
 * Function definition: ixPiuMhReceiveUninitialize
 */
void ixPiuMhReceiveUninitialize (void)
{
    IxPiuMhPiuId piuId;

    IX_PIUMH_TRACE0 (IX_PIUMH_FN_ENTRY_EXIT, "Entering "
                     "ixPiuMhReceiveUninitialize\n");

    /* for each PIU ... */
    for (piuId = 0; piuId < IX_PIUMH_NUM_PIUS; piuId++)
    {
        /* unregister and set ISR to NULL */
        ixPiuMhConfigIsrUnregister (piuId);
    }

    IX_PIUMH_TRACE0 (IX_PIUMH_FN_ENTRY_EXIT, "Exiting "
                     "ixPiuMhReceiveUninitialize\n");

}

/*
 * Function definition: ixPiuMhReceiveMessagesReceive
 */

IX_STATUS ixPiuMhReceiveMessagesReceive (
    IxPiuMhPiuId piuId)
{
    IxPiuMhMessage message = { { 0, 0 } };
    IxPiuMhMessageId messageId = 0;
    IxPiuMhCallback callback = NULL;
    IX_STATUS status;

    IX_PIUMH_TRACE0 (IX_PIUMH_FN_ENTRY_EXIT, "Entering "
                     "ixPiuMhReceiveMessagesReceive\n");

    /* update statistical info */
    ixPiuMhReceiveStats[piuId].receives++;

    /* while the PIU has messages in its outFIFO */
    while (!ixPiuMhConfigOutFifoIsEmpty (piuId))
    {
        /* read a message from the PIU's outFIFO */
        status = ixPiuMhConfigOutFifoRead (piuId, &message);

        if (IX_SUCCESS != status)
        {
            return status;
        }

        /* get the ID of the message */
        messageId = ixPiuMhConfigMessageIdGet (message);

        IX_PIUMH_TRACE2 (IX_PIUMH_DEBUG,
             "Received message from PIU %d with ID 0x%02X\n",
             piuId, messageId);

        /* update statistical info */
        ixPiuMhReceiveStats[piuId].messages++;

        /* try to find a matching unsolicited callback for this message. */

        /* we assume the message is unsolicited.  only if there is no */
        /* unsolicited callback for this message type do we assume the */
        /* message is solicited.  it is much faster to check for an */
        /* unsolicited callback, so doing this check first should result */
        /* in better performance. */

        ixPiuMhUnsolicitedCbMgrCallbackRetrieve (
            piuId, messageId, &callback);

        if (callback != NULL)
        {
        IX_PIUMH_TRACE0 (IX_PIUMH_DEBUG,
                 "Found matching unsolicited callback\n");

            /* update statistical info */
            ixPiuMhReceiveStats[piuId].unsolicited++;
        }

        /* if no unsolicited callback was found try to find a matching */
        /* solicited callback for this message */
        if (callback == NULL)
        {
            ixPiuMhSolicitedCbMgrCallbackRetrieve (
                piuId, messageId, &callback);

            if (callback != NULL)
            {
        IX_PIUMH_TRACE0 (IX_PIUMH_DEBUG,
                 "Found matching solicited callback\n");

                /* update statistical info */
                ixPiuMhReceiveStats[piuId].solicited++;
            }
        }

        /* if a callback (either unsolicited or solicited) was found */
        if (callback != NULL)
        {
            /* invoke the callback to pass the message back to the client */
            callback (piuId, message);

            /* update statistical info */
            ixPiuMhReceiveStats[piuId].callbacks++;
        }
        else /* no callback (neither unsolicited nor solicited) was found */
        {
        IX_PIUMH_TRACE2 (IX_PIUMH_WARNING,
                 "No matching callback for PIU %d"
                 " and ID 0x%02X, discarding message\n",
                 piuId, messageId);

            /* the message will be discarded.  this is normal behaviour */
            /* if the client passes a NULL solicited callback when */
            /* sending a message.  this indicates that the client is not */
            /* interested in receiving the response.  alternatively a */
            /* NULL callback here may signify an unsolicited message */
            /* with no appropriate registered callback. */
        }
    }

    IX_PIUMH_TRACE0 (IX_PIUMH_FN_ENTRY_EXIT, "Exiting "
                     "ixPiuMhReceiveMessagesReceive\n");

    return IX_SUCCESS;
}

/*
 * Function definition: ixPiuMhReceiveShow
 */

void ixPiuMhReceiveShow (
    IxPiuMhPiuId piuId)
{
    /* show the ISR invocation counter */
    IX_PIUMH_SHOW ("Receive ISR invocations",
                   ixPiuMhReceiveStats[piuId].isrs);

    /* show the receive message invocation counter */
    IX_PIUMH_SHOW ("Receive messages invocations",
                   ixPiuMhReceiveStats[piuId].receives);

    /* show the message received counter */
    IX_PIUMH_SHOW ("Messages received",
                   ixPiuMhReceiveStats[piuId].messages);

    /* show the solicited message counter */
    IX_PIUMH_SHOW ("Solicited messages received",
                   ixPiuMhReceiveStats[piuId].solicited);

    /* show the unsolicited message counter */
    IX_PIUMH_SHOW ("Unsolicited messages received",
                   ixPiuMhReceiveStats[piuId].unsolicited);

    /* show the callback invoked counter */
    IX_PIUMH_SHOW ("Callbacks invoked",
                   ixPiuMhReceiveStats[piuId].callbacks);

    /* show the message discarded counter */
    IX_PIUMH_SHOW ("Received messages discarded",
                   (ixPiuMhReceiveStats[piuId].messages -
                    ixPiuMhReceiveStats[piuId].callbacks));
}

/*
 * Function definition: ixPiuMhReceiveShowReset
 */

void ixPiuMhReceiveShowReset (
    IxPiuMhPiuId piuId)
{
    /* reset the ISR invocation counter */
    ixPiuMhReceiveStats[piuId].isrs = 0;

    /* reset the receive message invocation counter */
    ixPiuMhReceiveStats[piuId].receives = 0;

    /* reset the message received counter */
    ixPiuMhReceiveStats[piuId].messages = 0;

    /* reset the solicited message counter */
    ixPiuMhReceiveStats[piuId].solicited = 0;

    /* reset the unsolicited message counter */
    ixPiuMhReceiveStats[piuId].unsolicited = 0;

    /* reset the callback invoked counter */
    ixPiuMhReceiveStats[piuId].callbacks = 0;
}