// SPDX-License-Identifier: GPL-2.0
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.

//! The GSP event interrupt.
//!
//! The GSP posts messages to the GSP-to-CPU queue and raises SWGEN0, a software-generated cause
//! of its falcon. A threaded handler services it: the top half clears the tree and falcon state,
//! and the IRQ thread drains the queue.
//!
//! See "The GSP event" in `Documentation/gpu/nova/core/interrupts.rst`.

use kernel::{
    device,
    irq,
    pci,
    prelude::*, //
};

use super::interrupt_tree::{
    GinVector,
    LeafEnableGuard,
    Subtree,
    Tree, //
};
use crate::{
    falcon::{
        gsp::Gsp as GspFalcon,
        Falcon, //
    },
    gsp::cmdq::Cmdq,
    regs, //
};

/// The GSP event vector, which has the same number on every supported GPU.
const GSP_INTR_0_VECTOR: GinVector = GinVector::new::<155>();

/// The GSP event's subtree, the only one that nova-core services.
pub(crate) const GSP_SUBTREE: Subtree = GSP_INTR_0_VECTOR.subtree();

/// Clears the tree and falcon interrupt state that GSP boot leaves behind, and rearms PCI
/// interrupt delivery.
///
/// On return, no vector is enabled at its leaf, the serviced subtrees are disabled at `TOP`, and
/// the SWGEN0 latch is clear, so the next message that the GSP posts signals the tree.
pub(crate) fn quiesce(tree: &Tree<'_>, falcon: &Falcon<'_, GspFalcon>) {
    tree.reset();
    // The latch is cleared after the tree reset. The other order can leave the latch set with its
    // leaf bit cleared. See "Enabling the GSP event" in interrupts.rst.
    falcon.clear_swgen0_intr();
}

/// Threaded IRQ handler for the GSP event.
pub(crate) struct GspInterrupt<'a> {
    falcon: &'a Falcon<'a, GspFalcon>,
    cmdq: &'a Cmdq<'a>,
    tree: &'a Tree<'a>,
    /// For logging.
    dev: &'a device::Device,
}

impl GspInterrupt<'_> {
    /// Clears the latch of every host-routed cause in `status` other than SWGEN0, and logs them.
    ///
    /// Returns the causes still set after the clear. A cause driven from outside the falcon stays
    /// set, and only a device reset ends it.
    fn clear_faults(
        &self,
        status: regs::NV_PFALCON_FALCON_IRQSTAT,
    ) -> regs::NV_PFALCON_FALCON_IRQSTAT {
        let faults = status.with_swgen0(false);
        if faults.into_raw() == 0 {
            return faults;
        }

        dev_err!(
            &self.dev,
            "unserviceable GSP falcon interrupt, IRQSTAT {:#x}\n",
            status.into_raw()
        );
        self.falcon.clear_intr(faults);

        self.falcon.read_host_intr().with_swgen0(false)
    }
}

impl irq::ThreadedHandler for GspInterrupt<'_> {
    /// Top half, in hard interrupt context. Services the GSP vector only, so another vector
    /// pending in the same leaf stays pending.
    fn handle(&self) -> irq::ThreadedIrqReturn {
        let leaf = self.tree.read_pending(GSP_INTR_0_VECTOR.leaf_index());
        if !leaf.vectors().contains(GSP_INTR_0_VECTOR.leaf_mask()) {
            self.tree.rearm_pci_irq(GSP_SUBTREE);
            return irq::ThreadedIrqReturn::None;
        }
        leaf.clear_vectors(GSP_INTR_0_VECTOR.leaf_mask());

        let status = self.falcon.take_host_intr();

        let remaining_faults = self.clear_faults(status);
        if remaining_faults.into_raw() == 0 {
            self.falcon.retrigger_intr();
        } else {
            // Disabling the vector loses no notification: the falcon signals nothing further
            // while a cause stays set. See "Retriggering a falcon" in interrupts.rst.
            self.tree.disable_leaf(
                GSP_INTR_0_VECTOR.leaf_index(),
                GSP_INTR_0_VECTOR.leaf_mask(),
            );
            dev_err!(
                &self.dev,
                "GSP falcon cause {:#x} needs a device reset, GSP events are no longer serviced\n",
                remaining_faults.into_raw()
            );
        }

        self.tree.rearm_pci_irq(GSP_SUBTREE);

        if status.swgen0() {
            irq::ThreadedIrqReturn::WakeThread
        } else {
            irq::ThreadedIrqReturn::Handled
        }
    }

    /// IRQ thread. Drains the GSP-to-CPU queue, which may sleep.
    fn handle_threaded(&self) -> irq::IrqReturn {
        if let Err(e) = self.cmdq.drain() {
            // The failed message stays at the queue head, so every later drain fails the same way.
            self.tree.disable_leaf(
                GSP_INTR_0_VECTOR.leaf_index(),
                GSP_INTR_0_VECTOR.leaf_mask(),
            );
            dev_err!(
                &self.dev,
                "GSP event drain failed ({:?}), the message queue is no longer serviced\n",
                e
            );
        }
        irq::IrqReturn::Handled
    }
}

/// The registered GSP event handler and the enable of its vector.
///
/// The declaration order is the drop order, and it is required: the vector is disabled before
/// `free_irq` runs. See "Enabling the GSP event" in `Documentation/gpu/nova/core/interrupts.rst`.
#[pin_data]
pub(crate) struct GspIrq<'a> {
    _leaf_guard: LeafEnableGuard<'a>,
    #[pin]
    reg: irq::ThreadedRegistration<'a, GspInterrupt<'a>>,
}

impl<'a> GspIrq<'a> {
    /// Returns an initializer that registers the threaded handler and then enables the GSP
    /// vector at its leaf.
    ///
    /// An event that latched while the vector was disabled is delivered as soon as the GSP
    /// subtree is enabled at `TOP`.
    ///
    /// # Errors
    ///
    /// `EINVAL` if `tree` does not service the GSP subtree. Otherwise the error from
    /// `request_threaded_irq`.
    ///
    /// # Safety
    ///
    /// Callers must not `mem::forget()` the initialized `GspIrq` or otherwise prevent its [`Drop`]
    /// implementation, which runs `free_irq`, from running.
    pub(crate) unsafe fn new(
        pdev: &'a pci::Device<device::Bound>,
        tree: &'a Tree<'a>,
        falcon: &'a Falcon<'a, GspFalcon>,
        cmdq: &'a Cmdq<'a>,
    ) -> impl PinInit<Self, Error> + 'a {
        let dev = pdev.as_ref();

        try_pin_init!(Self {
            // SAFETY: this function's caller must not leak the `GspIrq` that owns this
            // registration, so the registration's `Drop` runs.
            reg <- unsafe {
                irq::ThreadedRegistration::new(
                    tree.request_for(GSP_SUBTREE)?,
                    irq::Flags::TRIGGER_NONE,
                    c"nova-core",
                    Ok(GspInterrupt { falcon, cmdq, tree, dev }),
                )
            },
            _leaf_guard: tree.enable_leaf_guarded(
                GSP_INTR_0_VECTOR.leaf_index(),
                GSP_INTR_0_VECTOR.leaf_mask(),
            ),
        })
    }
}