Linux中断子系统移植指南：从irq_chip到irq_domain的适配与调试

1. 中断子系统到底在解决什么问题

做Linux驱动移植的人，早晚都会撞上中断这块硬骨头。你从一颗芯片换到另一颗芯片，GPIO、时钟、引脚复用这些改改寄存器还能对付，但一旦涉及中断控制器换了型号，或者从ARM Cortex-A切到RISC-V，中断子系统的适配就会变成整个移植工作中最耗时的部分。我做过几次不同平台的驱动移植，每次中断这块都要花掉将近三分之一的时间去调试。

中断子系统的本质，是让外设能在事件发生时主动通知CPU，而不是让CPU傻等着轮询。举个生活化的例子：你寄快递，可以选择每隔十分钟下楼看快递到没到（轮询），也可以留个电话让快递员到了打给你（中断）。显然打电话更高效，但问题在于——你只有一个手机号，如果同时有快递、外卖、物业都打这个号码，你就需要一套规则来决定先接谁、谁可以稍后、谁直接挂断。Linux中断子系统干的就是这个事。

这套框架要解决的核心问题包括：中断号的统一管理、中断控制器的抽象、中断服务程序的注册与调用、中断上下文的限制、中断嵌套与优先级、以及多核环境下的中断亲和性。对于做驱动移植的人来说，你不需要从头实现这些，但你必须理解框架的分层逻辑，否则遇到request_irq返回失败、中断触发不了、或者中断风暴的时候，你连从哪一层开始排查都不知道。

这篇文章适合两类人：一是正在做Linux驱动移植、需要适配新平台中断控制器的工程师；二是已经写过字符设备驱动、但对中断子系统只有模糊认识的开发者。我会从整体框架讲起，然后逐层拆解关键数据结构和移植时需要改动的部分，最后给出实际调试中踩过的坑和排查方法。

2. 中断子系统的整体分层设计

2.1 从硬件到软件的三层抽象

Linux中断子系统在设计上采用了典型的分层思想，从下往上大致可以分为三层：

最底层是硬件层，也就是具体的SoC中断控制器，比如GIC（Generic Interrupt Controller）、NVIC、或者各种GPIO中断控制器。这一层的差异最大，也是驱动移植时主要改动的部分。

中间层是中断控制器抽象层，Linux用irq_chip和irq_domain这两个结构体来抽象不同中断控制器的行为。irq_chip定义了中断控制器的操作函数集，比如使能、禁用、应答、设置触发方式等；irq_domain则负责硬件中断号到Linux虚拟中断号的映射。

最上层是通用中断处理层，包括irq_desc、irqaction、generic_handle_irq等，这一层对所有平台都是通用的，驱动开发者调用request_irq注册中断处理函数，就是和这一层打交道。

这种分层的意义在于：驱动开发者只需要关心最上层，用统一的API注册中断；而做平台移植的人只需要实现中间层的irq_chip和irq_domain，不需要改动通用代码。我第一次理解这个分层的时候，感觉就像USB子系统的设计思路——HCD负责硬件差异，USB Core负责通用逻辑，设备驱动只管调API。

2.2 为什么不用一个结构体搞定所有事

有人可能会问，为什么不直接用一个大的结构体把中断控制器和中断描述都塞进去，非要拆成irq_chip、irq_domain、irq_desc、irqaction这么多层？

原因在于关注点分离。irq_chip只关心“怎么操作这个中断控制器硬件”，irq_domain只关心“硬件中断号怎么映射到虚拟中断号”，irq_desc只关心“这个中断线上挂了哪些处理函数”，irqaction只关心“某个具体的处理函数及其上下文”。如果混在一起，当你要支持中断控制器级联（比如GPIO中断控制器挂在GIC的某条中断线上）时，代码会变得极其混乱。

我实际移植过一个级联中断控制器的平台，父控制器是GIC，子控制器是一个自定义的GPIO中断聚合器。正是因为有了irq_domain的层级映射机制，子控制器的中断号可以通过irq_domain_add_hierarchy挂到父domain下面，整个映射关系清晰可控。如果当初设计成一个扁平结构，这种级联场景几乎没法优雅处理。

2.3 移植时你需要关注哪些层

对于驱动移植来说，你的工作范围通常落在中间层。具体来说：

• 如果新平台的中断控制器和已有驱动兼容（比如都是标准GICv3），那你可能什么都不用改，只需要在设备树里填对interrupt-parent和interrupts属性。
• 如果是自定义中断控制器，你需要实现一个irq_chip，定义irq_mask、irq_unmask、irq_ack、irq_set_type等回调。
• 如果中断控制器有级联关系，你还需要创建irq_domain并建立映射。
• 通用中断处理层和驱动API层基本不需要动，除非你要支持一些特殊的中断类型（比如NMI）。

理解这个分工之后，你在移植时就能快速定位：中断触发不了，先看设备树的中断号对不对；中断号映射失败，看irq_domain的xlate回调；中断处理函数没被调用，看irq_chip的irq_ack和irq_unmask是否实现正确。

3. 核心数据结构拆解与移植关键点

3.1 irq_desc：中断线的全局描述符

irq_desc是中断子系统的核心数据结构，每条中断线对应一个irq_desc。它里面最关键的成员是irqaction链表和irq_chip指针。

struct irq_desc { struct irq_common_data irq_common_data; struct irq_data irq_data; struct irqaction *action; /* 中断处理函数链表 */ unsigned int status_use_accessors; unsigned int core_internal_state__do_not_mess_with_it; unsigned int depth; /* 禁用嵌套深度 */ unsigned int wake_depth; unsigned int tot_count; unsigned int irq_count; unsigned long last_unhandled; unsigned int irqs_unhandled; raw_spinlock_t lock; struct cpumask *percpu_enabled; ... };

depth这个字段值得单独说。它记录了中断被禁用的嵌套层数，每次调用disable_irq会加一，enable_irq会减一，只有减到零才真正使能中断。我踩过一个坑：在中断处理函数里调用了disable_irq，结果导致死锁，因为disable_irq会等待当前正在执行的中断处理完成，而在中断上下文里等自己完成就是死锁。正确做法是用disable_irq_nosync。

移植时你一般不需要直接操作irq_desc，但调试时可以通过/proc/irq/<num>/下的文件查看它的状态，比如/proc/irq/45/spurious可以看到该中断线上未处理中断的统计。

3.2 irq_chip：中断控制器的操作集

irq_chip是移植时最需要关注的结构体，它定义了中断控制器的所有操作：

struct irq_chip { const char *name; unsigned int (*irq_startup)(struct irq_data *data); void (*irq_shutdown)(struct irq_data *data); void (*irq_enable)(struct irq_data *data); void (*irq_disable)(struct irq_data *data); void (*irq_ack)(struct irq_data *data); void (*irq_mask)(struct irq_data *data); void (*irq_unmask)(struct irq_data *data); void (*irq_eoi)(struct irq_data *data); int (*irq_set_type)(struct irq_data *data, unsigned int type); int (*irq_set_affinity)(struct irq_data *data, const struct cpumask *dest, bool force); ... };

其中irq_ack、irq_mask、irq_unmask、irq_eoi是最核心的四个回调。irq_ack用于应答中断控制器，告诉它“这个中断我已经收到了”；irq_mask和irq_unmask用于屏蔽和解除屏蔽中断；irq_eoi用于中断结束通知，在GIC中通常是写EOI寄存器。

移植时的关键决策是：你的中断控制器需不需要irq_ack。有些中断控制器在进入中断处理函数时会自动应答，有些则需要软件显式应答。如果该应答的没应答，中断会一直触发，形成中断风暴；如果不该应答的乱应答，可能会丢失中断。我移植过一个自定义中断控制器，硬件手册上写的是“中断状态寄存器在读取时自动清除”，所以irq_ack实现为空函数，但irq_mask和irq_unmask必须正确实现，否则无法屏蔽中断。

3.3 irq_domain：硬件中断号到虚拟中断号的桥梁

irq_domain解决的是中断号映射问题。硬件中断号（hwirq）是中断控制器视角的编号，虚拟中断号（virq）是Linux全局视角的编号。两者之间的映射关系由irq_domain维护。

struct irq_domain { struct list_head link; const char *name; const struct irq_domain_ops *ops; void *host_data; unsigned int flags; struct fwnode_handle *fwnode; struct irq_domain *parent; ... };

irq_domain_ops中的xlate回调负责解析设备树中的interrupts属性，map回调负责建立映射，alloc回调负责分配虚拟中断号。

移植时最常见的场景是：设备树里写了interrupts = <0 45 4>，但驱动里request_irq拿到的中断号不对。这时候就要检查xlate回调是否正确解析了设备树参数。GIC的xlate会解析三个cell：中断类型（SPI/PPI/SGI）、中断号、触发方式。如果你的中断控制器设备树绑定是自定义的，xlate的实现必须和绑定文档一致。

3.4 irqaction：中断处理函数的载体

irqaction是每次request_irq调用时创建的结构体，它记录了处理函数指针、设备ID、中断标志等：

struct irqaction { irq_handler_t handler; void *dev_id; void __percpu *percpu_dev_id; struct irqaction *next; irq_handler_t thread_fn; struct task_struct *thread; unsigned int irq; unsigned int flags; ... };

flags字段决定了中断的行为：IRQF_SHARED表示共享中断线，IRQF_TRIGGER_RISING表示上升沿触发，IRQF_ONESHOT表示中断处理函数执行期间保持屏蔽。移植时如果设备树里配置的触发方式和驱动里request_irq的flags不一致，中断可能触发不了或者反复触发。我遇到过设备树写的是下降沿触发，但驱动里传了IRQF_TRIGGER_RISING，结果中断死活不来，改成一致后立刻正常。

4. 中断注册与处理的完整流程

4.1 从设备树到request_irq的调用链

当驱动调用request_irq时，内核内部经历了一系列转换。以设备树平台为例：

1. 驱动调用platform_get_irq或irq_of_parse_and_map，从设备树节点中解析interrupts属性。
2. irq_of_parse_and_map调用irq_create_of_mapping，进而调用irq_find_mapping查找或创建虚拟中断号。
3. 如果虚拟中断号不存在，调用irq_domain_alloc_irqs分配一个，并通过irq_domain_ops.map回调建立hwirq到virq的映射。
4. 驱动拿到virq后调用request_irq，内核创建irqaction并挂到对应irq_desc的action链表上。
5. 如果中断控制器还没使能该中断线，调用irq_chip.irq_startup或irq_enable使能。

这个流程中，第3步的map回调是移植时最可能出问题的地方。如果map回调没有正确设置irq_data中的hwirq和chip，后续的中断使能和应答都会失败。

4.2 中断触发后的处理路径

当硬件中断触发后，CPU会跳转到中断向量表，最终调用到handle_irq。以ARM64为例，流程大致是：

1. CPU保存现场，读取中断控制器寄存器获取hwirq。
2. 调用irq_find_mapping将hwirq转换为virq。
3. 调用generic_handle_irq(virq)，进而调用generic_handle_irq_desc。
4. generic_handle_irq_desc调用irq_desc->handle_irq，对于电平触发中断通常是handle_level_irq，对于边沿触发是handle_edge_irq。
5. handle_level_irq会先调用irq_chip.irq_ack应答中断，然后调用irq_chip.irq_mask屏蔽中断，接着遍历action链表调用每个handler，最后调用irq_chip.irq_unmask解除屏蔽。
6. 如果是线程化中断（IRQF_ONESHOT或thread_fn），还会唤醒中断线程。

这里的关键点是：handle_level_irq和handle_edge_irq的行为不同。电平触发中断在屏蔽后如果硬件仍然保持电平，解除屏蔽后会再次触发；边沿触发中断则不会。移植时如果触发方式配错，会导致中断丢失或重复。

4.3 中断上下文的限制与注意事项

中断处理函数运行在中断上下文，这意味着：

• 不能调用可能睡眠的函数，比如kmalloc(GFP_KERNEL)、mutex_lock、copy_to_user。
• 不能调用disable_irq，只能用disable_irq_nosync。
• 栈空间有限，不能做大量局部变量分配。
• 执行时间要尽可能短，否则会影响系统响应。

我移植过一个触摸屏驱动，中断处理函数里做了I2C读取，结果系统卡顿严重。后来改成中断里只做标记，实际读取放到工作队列里，问题解决。这就是典型的中断上下文限制导致的性能问题。

5. 移植实操：从零适配一个中断控制器

5.1 硬件手册需要看哪些寄存器

拿到一个新的中断控制器，硬件手册里必须确认以下信息：

• 中断使能寄存器：每个中断线的使能位在哪里，是分开的还是分组的。
• 中断屏蔽寄存器：和使能寄存器是同一个还是分开的。
• 中断状态寄存器：如何读取当前pending的中断，读取后是否自动清除。
• 中断应答寄存器：是否需要显式写应答，还是读取状态即应答。
• 触发方式配置寄存器：如何配置上升沿、下降沿、高电平、低电平。
• 优先级寄存器：是否支持优先级，如何配置。
• 中断号范围：支持多少条中断线，编号从几开始。

这些信息决定了irq_chip中各个回调的实现方式。比如如果状态寄存器读取后自动清除，irq_ack就可以是空函数；如果需要写应答寄存器，irq_ack就必须实现。

5.2 实现一个最小可用的irq_chip

假设我们有一个简单的中断控制器，寄存器基地址为base，支持32条中断线，每条线有独立的使能位和状态位，状态位读取后自动清除，触发方式固定为高电平。

struct my_intc { void __iomem *base; struct irq_domain *domain; raw_spinlock_t lock; }; static void my_intc_irq_mask(struct irq_data *d) { struct my_intc *intc = irq_data_get_irq_chip_data(d); u32 offset = d->hwirq / 32; u32 bit = d->hwirq % 32; u32 val; raw_spin_lock(&intc->lock); val = readl(intc->base + ENABLE_REG + offset * 4); val &= ~(1 << bit); writel(val, intc->base + ENABLE_REG + offset * 4); raw_spin_unlock(&intc->lock); } static void my_intc_irq_unmask(struct irq_data *d) { struct my_intc *intc = irq_data_get_irq_chip_data(d); u32 offset = d->hwirq / 32; u32 bit = d->hwirq % 32; u32 val; raw_spin_lock(&intc->lock); val = readl(intc->base + ENABLE_REG + offset * 4); val |= (1 << bit); writel(val, intc->base + ENABLE_REG + offset * 4); raw_spin_unlock(&intc->lock); } static void my_intc_irq_ack(struct irq_data *d) { /* 状态寄存器读取后自动清除，无需额外操作 */ } static struct irq_chip my_intc_chip = { .name = "my-intc", .irq_mask = my_intc_irq_mask, .irq_unmask = my_intc_irq_unmask, .irq_ack = my_intc_irq_ack, };

这个最小实现里，irq_mask和irq_unmask操作使能寄存器，irq_ack为空。注意加锁保护，因为多核环境下可能同时有多个CPU操作同一个寄存器。

5.3 建立irq_domain和中断映射

有了irq_chip之后，需要创建irq_domain并建立映射：

static int my_intc_domain_map(struct irq_domain *d, unsigned int virq, irq_hw_number_t hwirq) { struct my_intc *intc = d->host_data; irq_set_chip_data(virq, intc); irq_set_chip_and_handler(virq, &my_intc_chip, handle_level_irq); irq_set_status_flags(virq, IRQ_LEVEL); return 0; } static const struct irq_domain_ops my_intc_domain_ops = { .map = my_intc_domain_map, .xlate = irq_domain_xlate_twocell, }; static int my_intc_probe(struct platform_device *pdev) { struct my_intc *intc; struct resource *res; int irq, ret; intc = devm_kzalloc(&pdev->dev, sizeof(*intc), GFP_KERNEL); if (!intc) return -ENOMEM; res = platform_get_resource(pdev, IORESOURCE_MEM, 0); intc->base = devm_ioremap_resource(&pdev->dev, res); if (IS_ERR(intc->base)) return PTR_ERR(intc->base); raw_spin_lock_init(&intc->lock); intc->domain = irq_domain_add_linear(pdev->dev.of_node, 32, &my_intc_domain_ops, intc); if (!intc->domain) return -ENOMEM; /* 初始化硬件：禁用所有中断 */ writel(0, intc->base + ENABLE_REG); writel(0, intc->base + ENABLE_REG + 4); platform_set_drvdata(pdev, intc); return 0; }

这里用irq_domain_add_linear创建线性映射domain，支持32条中断线。xlate用irq_domain_xlate_twocell，表示设备树中每个中断用两个cell描述：中断号和触发方式。

5.4 设备树节点的编写要点

对应的设备树节点：

my_intc: interrupt-controller@10000000 { compatible = "myvendor,my-intc"; reg = <0x10000000 0x1000>; interrupt-controller; #interrupt-cells = <2>; interrupt-parent = <&gic>; interrupts = <0 45 4>; /* 挂在GIC的SPI 45上，高电平触发 */ }; device@20000000 { compatible = "myvendor,my-device"; reg = <0x20000000 0x1000>; interrupt-parent = <&my_intc>; interrupts = <5 4>; /* 使用my_intc的第5号中断，高电平触发 */ };

关键点：#interrupt-cells = <2>要和xlate的cell数量一致；interrupt-parent指向父控制器；interrupts属性的格式要和xlate解析逻辑匹配。

6. 常见问题与排查技巧实录

6.1 中断触发不了怎么办

这是移植时最常见的问题。排查顺序建议如下：

我遇到过一次中断触发不了，查了两天，最后发现是设备树里interrupt-parent写成了另一个控制器。这种低级错误在移植时特别容易犯，因为设备树是手写的，没有编译器帮你检查。

6.2 中断风暴怎么定位

中断风暴的表现是系统卡死，top看到某个CPU的si（软中断）占用率100%。原因通常是中断应答没有正确执行，硬件一直认为中断未被处理。

排查方法：

• 检查irq_chip.irq_ack是否实现，是否需要写应答寄存器。
• 检查handle_level_irq和handle_edge_irq是否选对。电平触发中断如果硬件电平一直保持，屏蔽后解除屏蔽会再次触发，这是正常的；但如果应答没做，就会无限触发。
• 用cat /proc/interrupts观察中断计数，如果某个中断号计数飞涨，就是它的问题。

我移植过一个GPIO中断控制器，硬件手册说“读取状态寄存器自动清除”，但实际上只有读取特定偏移的状态寄存器才清除，读错了偏移就不会清除。这种硬件手册的坑只能靠实测发现。

6.3 中断号映射失败的排查

如果request_irq返回-EINVAL，很可能是中断号映射失败。排查步骤：

1. 确认设备树interrupts属性的cell数量和#interrupt-cells一致。
2. 确认xlate回调能正确解析设备树参数。
3. 确认irq_domain的map回调被调用，可以在map里加pr_info打印。
4. 确认父控制器的irq_domain已经创建。

有个技巧：在irq_create_of_mapping里加打印，可以看到每次映射的hwirq和virq，非常直观。

6.4 共享中断的注意事项

共享中断（IRQF_SHARED）要求所有共享同一中断线的驱动都传入了非NULL的dev_id，且dev_id必须唯一。如果两个驱动传了相同的dev_id，第二个request_irq会失败。

另外，共享中断的处理函数必须能判断中断是否来自自己的设备，如果不是就返回IRQ_NONE。如果所有处理函数都返回IRQ_NONE，内核会认为这个中断是spurious的，累计到一定次数后会禁用该中断线。

6.5 中断亲和性设置

多核平台上，可以通过/proc/irq/<num>/smp_affinity设置中断亲和性，让特定中断只在指定CPU上处理。移植时如果发现某个中断总是落在CPU0上导致负载不均，可以调整亲和性。

在代码里可以用irq_set_affinity_hint设置建议亲和性：

irq_set_affinity_hint(irq, cpumask_of(cpu));

注意这只是hint，实际亲和性还受irq_chip.irq_set_affinity是否实现影响。如果中断控制器不支持亲和性设置，这个hint会被忽略。

7. 移植后的验证与性能调优

7.1 验证中断是否正常工作

移植完成后，最基本的验证方法是：

# 查看中断统计 cat /proc/interrupts # 查看某个中断的详细信息 cat /proc/irq/45/spurious ls /proc/irq/45/ # 查看中断控制器的domain信息 cat /sys/kernel/debug/irq/domains/

/proc/interrupts会列出每个中断号的中断计数、中断控制器名称、以及注册的处理函数名。如果中断触发后计数增加，说明中断路径是通的。

7.2 中断延迟的测量

对于实时性要求高的场景，需要测量中断延迟。可以用ftrace的irqsofftracer：

echo irqsoff > /sys/kernel/debug/tracing/current_tracer echo 1 > /sys/kernel/debug/tracing/tracing_on # 触发中断 cat /sys/kernel/debug/tracing/trace

irqsoff会记录中断被关闭的最长时间，帮助定位延迟热点。

7.3 中断线程化的取舍

对于处理时间较长的中断，可以用request_threaded_irq将处理函数线程化。线程化后，硬中断处理函数只做最少的应答和屏蔽，实际处理放到内核线程里，可以睡眠、可以调度。

但线程化也有代价：中断延迟会增加，因为需要唤醒线程。对于GPIO按键这种对延迟不敏感的场景，线程化很合适；对于网络收包这种对延迟敏感的场景，还是用传统中断处理更好。

我移植过一个音频驱动，DMA完成中断里需要做较多处理，线程化后系统响应明显改善，但音频延迟略有增加。最终通过调整线程优先级找到了平衡点。

7.4 中断嵌套与优先级

Linux中断子系统默认不支持中断嵌套，即一个中断处理函数执行期间，同类型中断会被屏蔽。如果硬件支持优先级，可以通过IRQF_NO_THREAD和IRQF_PERCPU等标志做更细粒度的控制。

移植时如果发现高优先级中断被低优先级中断阻塞，需要检查中断控制器的优先级配置和irq_chip是否实现了irq_set_priority（如果有这个回调的话）。

8. 几个容易忽略的移植细节

8.1 中断控制器的初始化顺序

中断控制器的初始化必须在设备驱动之前完成，否则设备驱动request_irq时会找不到中断控制器。Linux通过IRQCHIP_DECLARE宏和of_irq_init机制保证初始化顺序。

移植时如果用IRQCHIP_DECLARE，需要确保compatible字符串和设备树一致。如果用platform_driver，需要设置合适的initcall级别，通常用postcore_initcall。

8.2 中断控制器的电源管理

如果中断控制器支持电源管理，需要在irq_chip中实现irq_set_wake回调，并在系统休眠时保存和恢复寄存器状态。移植时如果忽略这一点，系统休眠唤醒后中断可能失效。

8.3 多核启动时的中断分发

多核平台上，CPU启动过程中中断的分发需要特别注意。从CPU启动时，中断控制器需要正确配置，否则从CPU可能收不到中断。GIC通过gic_starting_cpu和gic_dying_cpu回调处理这个问题，自定义中断控制器也需要类似的机制。

8.4 中断号空间的分配

irq_domain_add_linear适合中断号连续且数量固定的场景；irq_domain_add_tree适合中断号稀疏的场景；irq_domain_add_nomap适合不需要映射的场景。移植时根据中断控制器的特点选择合适的domain类型，可以节省内存并提高查找效率。

我在一个支持动态中断号的控制器上用了irq_domain_add_linear，结果中断号范围很大但实际用的很少，浪费了不少内存。后来改成irq_domain_add_tree，内存占用明显下降。

8.5 调试中断子系统的常用手段

除了/proc/interrupts和ftrace，还有几个实用手段：

• CONFIG_GENERIC_IRQ_DEBUGFS打开后，/sys/kernel/debug/irq/下会有每个中断的详细信息。
• CONFIG_IRQ_DOMAIN_DEBUG打开后，可以看到domain的映射关系。
• 在generic_handle_irq里加打印，可以看到每次中断的virq和hwirq。
• 用irq_set_chip_and_handler时传入不同的handler，可以观察行为差异。

这些手段在排查疑难问题时非常有用，尤其是当硬件手册和实际行为不一致的时候。

中断子系统的移植工作，说到底是对硬件行为的精确建模。你对硬件理解得越透彻，irq_chip的实现就越准确，调试时间就越短。我个人的经验是，拿到新硬件后先别急着写代码，把中断相关的寄存器手册反复读三遍，把中断触发、应答、屏蔽的时序图搞清楚，后面写代码就是水到渠成的事。