flags.rs

  1// SPDX-License-Identifier: GPL-2.0
  2// SPDX-FileCopyrightText: Copyright 2025 Collabora ltd.
  3
  4use crate::bindings;
  5use crate::prelude::*;
  6
  7/// Flags to be used when registering IRQ handlers.
  8///
  9/// Flags can be used to request specific behaviors when registering an IRQ
 10/// handler, and can be combined using the `|`, `&`, and `!` operators to
 11/// further control the system's behavior.
 12///
 13/// A common use case is to register a shared interrupt, as sharing the line
 14/// between devices is increasingly common in modern systems and is even
 15/// required for some buses. This requires setting [`Flags::SHARED`] when
 16/// requesting the interrupt. Other use cases include setting the trigger type
 17/// through `Flags::TRIGGER_*`, which determines when the interrupt fires, or
 18/// controlling whether the interrupt is masked after the handler runs by using
 19/// [`Flags::ONESHOT`].
 20///
 21/// If an invalid combination of flags is provided, the system will refuse to
 22/// register the handler, and lower layers will enforce certain flags when
 23/// necessary. This means, for example, that all the
 24/// [`crate::irq::Registration`] for a shared interrupt have to agree on
 25/// [`Flags::SHARED`] and on the same trigger type, if set.
 26#[derive(Clone, Copy, PartialEq, Eq)]
 27pub struct Flags(c_ulong);
 28
 29impl Flags {
 30    /// Use the interrupt line as already configured.
 31    pub const TRIGGER_NONE: Flags = Flags::new(bindings::IRQF_TRIGGER_NONE);
 32
 33    /// The interrupt is triggered when the signal goes from low to high.
 34    pub const TRIGGER_RISING: Flags = Flags::new(bindings::IRQF_TRIGGER_RISING);
 35
 36    /// The interrupt is triggered when the signal goes from high to low.
 37    pub const TRIGGER_FALLING: Flags = Flags::new(bindings::IRQF_TRIGGER_FALLING);
 38
 39    /// The interrupt is triggered while the signal is held high.
 40    pub const TRIGGER_HIGH: Flags = Flags::new(bindings::IRQF_TRIGGER_HIGH);
 41
 42    /// The interrupt is triggered while the signal is held low.
 43    pub const TRIGGER_LOW: Flags = Flags::new(bindings::IRQF_TRIGGER_LOW);
 44
 45    /// Allow sharing the IRQ among several devices.
 46    pub const SHARED: Flags = Flags::new(bindings::IRQF_SHARED);
 47
 48    /// Set by callers when they expect sharing mismatches to occur.
 49    pub const PROBE_SHARED: Flags = Flags::new(bindings::IRQF_PROBE_SHARED);
 50
 51    /// Flag to mark this interrupt as timer interrupt.
 52    pub const TIMER: Flags = Flags::new(bindings::IRQF_TIMER);
 53
 54    /// Interrupt is per CPU.
 55    pub const PERCPU: Flags = Flags::new(bindings::IRQF_PERCPU);
 56
 57    /// Flag to exclude this interrupt from irq balancing.
 58    pub const NOBALANCING: Flags = Flags::new(bindings::IRQF_NOBALANCING);
 59
 60    /// Interrupt is used for polling (only the interrupt that is registered
 61    /// first in a shared interrupt is considered for performance reasons).
 62    pub const IRQPOLL: Flags = Flags::new(bindings::IRQF_IRQPOLL);
 63
 64    /// Interrupt is not re-enabled after the hardirq handler finished. Used by
 65    /// threaded interrupts which need to keep the irq line disabled until the
 66    /// threaded handler has been run.
 67    pub const ONESHOT: Flags = Flags::new(bindings::IRQF_ONESHOT);
 68
 69    /// Do not disable this IRQ during suspend. Does not guarantee that this
 70    /// interrupt will wake the system from a suspended state.
 71    pub const NO_SUSPEND: Flags = Flags::new(bindings::IRQF_NO_SUSPEND);
 72
 73    /// Force enable it on resume even if [`Flags::NO_SUSPEND`] is set.
 74    pub const FORCE_RESUME: Flags = Flags::new(bindings::IRQF_FORCE_RESUME);
 75
 76    /// Interrupt cannot be threaded.
 77    pub const NO_THREAD: Flags = Flags::new(bindings::IRQF_NO_THREAD);
 78
 79    /// Resume IRQ early during syscore instead of at device resume time.
 80    pub const EARLY_RESUME: Flags = Flags::new(bindings::IRQF_EARLY_RESUME);
 81
 82    /// If the IRQ is shared with a [`Flags::NO_SUSPEND`] user, execute this
 83    /// interrupt handler after suspending interrupts. For system wakeup devices
 84    /// users need to implement wakeup detection in their interrupt handlers.
 85    pub const COND_SUSPEND: Flags = Flags::new(bindings::IRQF_COND_SUSPEND);
 86
 87    /// Don't enable IRQ or NMI automatically when users request it. Users will
 88    /// enable it explicitly by `enable_irq` or `enable_nmi` later.
 89    pub const NO_AUTOEN: Flags = Flags::new(bindings::IRQF_NO_AUTOEN);
 90
 91    /// Exclude from runnaway detection for IPI and similar handlers, depends on
 92    /// `PERCPU`.
 93    pub const NO_DEBUG: Flags = Flags::new(bindings::IRQF_NO_DEBUG);
 94
 95    pub(crate) fn into_inner(self) -> c_ulong {
 96        self.0
 97    }
 98
 99    // Always inline to optimize out error path of `build_assert`.
100    #[inline(always)]
101    const fn new(value: u32) -> Self {
102        build_assert!(value as u64 <= c_ulong::MAX as u64);
103        Self(value as c_ulong)
104    }
105}
106
107impl core::ops::BitOr for Flags {
108    type Output = Self;
109    fn bitor(self, rhs: Self) -> Self::Output {
110        Self(self.0 | rhs.0)
111    }
112}
113
114impl core::ops::BitAnd for Flags {
115    type Output = Self;
116    fn bitand(self, rhs: Self) -> Self::Output {
117        Self(self.0 & rhs.0)
118    }
119}
120
121impl core::ops::Not for Flags {
122    type Output = Self;
123    fn not(self) -> Self::Output {
124        Self(!self.0)
125    }
126}