/*
 * Copyright (c) 2006 NVIDIA Corporation.  All rights reserved.
 *
 * NVIDIA Corporation and its licensors retain all intellectual property
 * and proprietary rights in and to this software, related documentation
 * and any modifications thereto.  Any use, reproduction, disclosure or
 * distribution of this software and related documentation without an express
 * license agreement from NVIDIA Corporation is strictly prohibited.
 */

#ifndef NVIRQ_H
#define NVIRQ_H

/** NvIrq - Interrupt abstraction layer:

    This provides a simple interface for querying and masking abstract interrupt
    events. The interface is designed to be used inside of the OEM's ISR or IST.

    NvIrq needs NvOsPhysicalMemMap and NvOsPhysicalMemUnmap (Only uncached 
    write-through functionality is used). NvOsSharedMem* is needed if NvIrq
    isn't initialized as a singleton.

    NvIrq is not thread-safe.
 */

#include "nvcommon.h"
#include "nverror.h"
#include "nvboard.h"

/** NvIrqChannel enum defines available I/O channels. No two I/O operations can
    safely occur at the same time on a channel. (This is only important in 
    indirect addressing. In direct address I/O operators are atomic and there 
    is no concept of channels).
 */
typedef enum
{
    /* Channel used while not in ISR. This channel is used by all user-mode code. */
    NvIrqChannel_Normal,

    /* Channel used in ISR context */
    NvIrqChannel_Isr
} NvIrqChannel;

/* NvIrqInterruptPortInfo struct describes the MMIO layout of the interrupt 
   status registers */
typedef struct NvIrqInterruptPortInfo_t
{
    /* Offset of status register */
    NvU32 statusOffset;

    /* Offset of mask register */
    NvU32 maskOffset;
} NvIrqInterruptPortInfo;

/** NvIrqInit - Method to initialize the NvIrq API. 

    This method is to be called before any other NvIrq methods can be used.     

    If NvIrq is not initialized as a singleton, NvIrq will put its state in
    shared memory.
 */
NvError 
NvIrqInit( const NvBoardMode *pMode, const NvBoardApertures *pApertures, 
    NvBool singleton );

/** NvIrqDeInit - Method to deinitialize the NvIrq API.
 */
void 
NvIrqDeInit( void );

/** NvIrqPostChipInit - To be called after the chip is intialized.
   
    This method should be called during NvBoardPostChipInit. If NvIrqInit succeeds 
    NvIrqEnableInterrupt() should be used to unmask the global interrupt line.
 */
NvError 
NvIrqPostChipInit( NvIrqChannel channel );

/** NvIrqPreChipDeInit - To be called before chip is shutdown.

    This method should be called during NvBoardPreChipDeInit. NvIrqDisableInterrupt() 
    should be called before invoking this method.
 */
void 
NvIrqPreChipDeInit( NvIrqChannel channel );

/** NvIrqFastScan - Method to quickly check if interrupt is pending

    This method is faster than NvIrqScanForEvent. It only checks whether an 
    interrupt is pending or not. NvIrqScanForEvent should be called from an 
    IST to do the actual decoding. This is useful when ISR latency is 
    important.

    If an interrupt is pending the global SCxx interrupt line is masked 
    and should reenabled using NvIrqEnableInterrupt after NvIrqScanForEvent 
    is called.
 */
NvBool 
NvIrqFastScan( NvIrqChannel channel );

/** NvIrqScanForEvent - Method to check SCxx for pending events. 

    This method should be called from an ISR or IST. If a pending event is 
    found, the event is masked. Once an upper layer clears the source of  
    the event in hardware, the event can be reenabled.

    @retval NvSuccess - on success
            NvErrorEventNotFound - no event found
 */
NvError 
NvIrqScanForEvent( NvIrqChannel channel, NvDeviceEvent *event );

/** NvIrqIsEventPending - Check whether the event is pending
 */
NvBool 
NvIrqIsEventPending( NvIrqChannel channel, NvDeviceEvent event );

/** NvIrqEnableInterrupt - Method to unmask global interrupt line
 */
void 
NvIrqEnableInterrupt( NvIrqChannel channel );

/** NvIrqDisableInterrupt - Method to mask global interrupt line
 */
void 
NvIrqDisableInterrupt( NvIrqChannel channel );

/** NvIrqEnableEvent - Method to unmask an event
 */
void 
NvIrqEnableEvent( NvIrqChannel channel, NvDeviceEvent event );

/** NvIrqDisableEvent - Method to mask an event
 */
void 
NvIrqDisableEvent( NvIrqChannel channel, NvDeviceEvent event );

/** NvIrqQueryInterruptPortInfo - Method to query interrupt port info. Calling 
        this method should be strongly avoided.
 */
NvError 
NvIrqQueryInterruptPortInfo( NvIrqInterruptPortInfo *pPortInfo );

#endif // NVIRQ_H