/*
 * Copyright (c) 2026, Chloe M.
 * Provided under the BSD-3 clause.
 *
 * Description: High-level interrupt management
 * Author:      Chloe M.
 */

#ifndef _HAL_INTR_H_
#define _HAL_INTR_H_ 1

#include <ptdef.h>
#include <ptapi/status.h>

/*
 * Represents value interrupt request levels that can be set within
 * the machine specific task priority store.
 */
#define IRQL_PASSIVE     0
#define IRQL_APC         1
#define IRQL_DISPATCH    2
#define IRQL_DEV_IRQ     3
#define IRQL_HIGH        4

/* Interrupt request level type */
typedef UCHAR IRQL;

/*
 * Represents an interrupt handler
 *
 * @Handler: Actual in-driver handler [@Data: driver specific data]
 * @Irql:    IRQL of this handler context
 * @Present: If true, entry is present
 *
 * XXX: This structured must be consistently ordered as it is
 *      read from assembly, always add to the bottom !!
 */
typedef struct _INTR_HANDLER {
    PT_STATUS(*Handler)(VOID *Data);
    IRQL Irql;
    BOOLEAN Present;
} INTR_HANDLER;

/*
 * Register an interrupt handler and obtain the interrupt
 * vector.
 *
 * @Handler:  Handler to register
 * @IsUser:   If set, is user-level interrupt
 *
 * Returned values of zero are invalid
 */
UCHAR HalIntrRegister(INTR_HANDLER *Handler, BOOLEAN IsUser);

/*
 * Returns the current IRQL
 */
IRQL HalGetIrql(VOID);

/*
 * Raise the IRQL level to a higher level
 *
 * @Irql: IRQL to raise to
 *
 * Returns the previous IRQL
 */
IRQL HalRaiseIrql(IRQL Irql);

/*
 * Lower the IRQL level to a lower level
 *
 * @Irql: IRQL to lower to
 *
 * Returns the previous IRQL
 */
IRQL HalLowerIrql(IRQL Irql);

#endif  /* !_HAL_INTR_H_ */
