Documentation/translations/zh_CN/core-api/irq/irq-domain.rst

   1 .. include:: ../../disclaimer-zh_CN.rst
   2
   3 :Original: Documentation/core-api/irq/irq-domain.rst
   4
   5 :翻译:
   6
   7  司延腾 Yanteng Si <siyanteng@loongson.cn>
   8  周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
   9
  10 .. _cn_irq-domain.rst:
  11
  12 =======================
  13 irq_domain 中断号映射库
  14 =======================
  15
  16 目前Linux内核的设计使用了一个巨大的数字空间，每个独立的IRQ源都被分配了一个不
  17 同的数字。
  18 当只有一个中断控制器时，这很简单，但在有多个中断控制器的系统中，内核必须确保每
  19 个中断控制器都能得到非重复的Linux IRQ号（数字）分配。
  20
  21 注册为唯一的irqchips的中断控制器编号呈现出上升的趋势：例如GPIO控制器等不同
  22 种类的子驱动程序通过将其中断处理程序建模为irqchips，即实际上是级联中断控制器，
  23 避免了重新实现与IRQ核心系统相同的回调机制。
  24
  25 在这里，中断号与硬件中断号离散了所有种类的对应关系：而在过去，IRQ号可以选择，
  26 使它们与硬件IRQ线进入根中断控制器（即实际向CPU发射中断线的组件）相匹配，现
  27 在这个编号仅仅是一个数字。
  28
  29 出于这个原因，我们需要一种机制将控制器本地中断号（即硬件irq编号）与Linux IRQ
  30 号分开。
  31
  32 irq_alloc_desc*() 和 irq_free_desc*() API 提供了对irq号的分配，但它们不
  33 提供任何对控制器本地IRQ(hwirq)号到Linux IRQ号空间的反向映射的支持。
  34
  35 irq_domain 库在 irq_alloc_desc*() API 的基础上增加了 hwirq 和 IRQ 号码
  36 之间的映射。 相比于中断控制器驱动开放编码自己的反向映射方案，我们更喜欢用
  37 irq_domain来管理映射。
  38
  39 irq_domain还实现了从抽象的irq_fwspec结构体到hwirq号的转换（到目前为止是
  40 Device Tree和ACPI GSI），并且可以很容易地扩展以支持其它IRQ拓扑数据源。
  41
  42 irq_domain的用法
  43 ================
  44
  45 中断控制器驱动程序通过以下方式创建并注册一个irq_domain。调用
  46 irq_domain_add_*() 或 irq_domain_create_*()函数之一（每个映射方法都有不
  47 同的分配器函数，后面会详细介绍）。 函数成功后会返回一个指向irq_domain的指针。
  48 调用者必须向分配器函数提供一个irq_domain_ops结构体。
  49
  50 在大多数情况下，irq_domain在开始时是空的，没有任何hwirq和IRQ号之间的映射。
  51 通过调用irq_create_mapping()将映射添加到irq_domain中，该函数接受
  52 irq_domain和一个hwirq号作为参数。 如果hwirq的映射还不存在，那么它将分配
  53 一个新的Linux irq_desc，将其与hwirq关联起来，并调用.map()回调，这样驱动
  54 程序就可以执行任何必要的硬件设置。
  55
  56 一旦建立了映射，可以通过多种方法检索或使用它：
  57
  58 - irq_resolve_mapping()返回一个指向给定域和hwirq号的irq_desc结构指针，
  59   如果没有映射则返回NULL。
  60
  61 - irq_find_mapping()返回给定域和hwirq的Linux IRQ号，如果没有映射则返回0。
  62
  63 - irq_linear_revmap()现与irq_find_mapping()相同，已被废弃。
  64
  65 - generic_handle_domain_irq()处理一个由域和hwirq号描述的中断。
  66
  67 请注意，irq域的查找必须发生在与RCU读临界区兼容的上下文中。
  68
  69 在调用irq_find_mapping()之前，至少要调用一次irq_create_mapping()函数，
  70 以免描述符不能被分配。
  71
  72 如果驱动程序有Linux的IRQ号或irq_data指针，并且需要知道相关的hwirq号（比
  73 如在irq_chip回调中），那么可以直接从irq_data->hwirq中获得。
  74
  75 irq_domain映射的类型
  76 ====================
  77
  78 从hwirq到Linux irq的反向映射有几种机制，每种机制使用不同的分配函数。应该
  79 使用哪种反向映射类型取决于用例。 下面介绍每一种反向映射类型：
  80
  81 线性映射
  82 --------
  83
  84 ::
  85
  86         irq_domain_add_linear()
  87         irq_domain_create_linear()
  88
  89 线性反向映射维护了一个固定大小的表，该表以hwirq号为索引。 当一个hwirq被映射
  90 时，会给hwirq分配一个irq_desc，并将irq号存储在表中。
  91
  92 当最大的hwirq号固定且数量相对较少时，线性图是一个很好的选择（~<256）。 这种
  93 映射的优点是固定时间查找IRQ号，而且irq_descs只分配给在用的IRQ。 缺点是该表
  94 必须尽可能大的hwirq号。
  95
  96 irq_domain_add_linear()和irq_domain_create_linear()在功能上是等价的，
  97 除了第一个参数不同--前者接受一个Open Firmware特定的 'struct device_node' 而
  98 后者接受一个更通用的抽象 'struct fwnode_handle' 。
  99
 100 大多数驱动应该使用线性映射
 101
 102 树状映射
 103 --------
 104
 105 ::
 106
 107         irq_domain_add_tree()
 108         irq_domain_create_tree()
 109
 110 irq_domain维护着从hwirq号到Linux IRQ的radix的树状映射。 当一个hwirq被映射时，
 111 一个irq_desc被分配，hwirq被用作radix树的查找键。
 112
 113 如果hwirq号可以非常大，树状映射是一个很好的选择，因为它不需要分配一个和最大hwirq
 114 号一样大的表。 缺点是，hwirq到IRQ号的查找取决于表中有多少条目。
 115
 116 irq_domain_add_tree()和irq_domain_create_tree()在功能上是等价的，除了第一
 117 个参数不同——前者接受一个Open Firmware特定的 'struct device_node' ，而后者接受
 118 一个更通用的抽象 'struct fwnode_handle' 。
 119
 120 很少有驱动应该需要这个映射。
 121
 122 无映射
 123 ------
 124
 125 ::
 126
 127         irq_domain_add_nomap()
 128
 129 当硬件中的hwirq号是可编程的时候，就可以采用无映射类型。 在这种情况下，最好将
 130 Linux IRQ号编入硬件本身，这样就不需要映射了。 调用irq_create_direct_mapping()
 131 会分配一个Linux IRQ号，并调用.map()回调，这样驱动就可以将Linux IRQ号编入硬件中。
 132
 133 大多数驱动程序无法使用此映射，现在它由CONFIG_IRQ_DOMAIN_NOMAP选项控制。
 134 请不要引入此API的新用户。
 135
 136 传统映射类型
 137 ------------
 138
 139 ::
 140
 141         irq_domain_add_simple()
 142         irq_domain_add_legacy()
 143         irq_domain_create_simple()
 144         irq_domain_create_legacy()
 145
 146 传统映射是已经为 hwirqs 分配了一系列 irq_descs 的驱动程序的特殊情况。 当驱动程
 147 序不能立即转换为使用线性映射时，就会使用它。 例如，许多嵌入式系统板卡支持文件使用
 148 一组用于IRQ号的定义（#define），这些定义被传递给struct设备注册。 在这种情况下，
 149 不能动态分配Linux IRQ号，应该使用传统映射。
 150
 151 顾名思义，\*_legacy()系列函数已被废弃，只是为了方便对古老平台的支持而存在。
 152 不应该增加新的用户。当\*_simple()系列函数的使用导致遗留行为时，他们也是如此。
 153
 154 传统映射假设已经为控制器分配了一个连续的IRQ号范围，并且可以通过向hwirq号添加一
 155 个固定的偏移来计算IRQ号，反之亦然。 缺点是需要中断控制器管理IRQ分配，并且需要为每
 156 个hwirq分配一个irq_desc，即使它没有被使用。
 157
 158 只有在必须支持固定的IRQ映射时，才应使用传统映射。 例如，ISA控制器将使用传统映射来
 159 映射Linux IRQ 0-15，这样现有的ISA驱动程序就能得到正确的IRQ号。
 160
 161 大多数使用传统映射的用户应该使用irq_domain_add_simple()或
 162 irq_domain_create_simple()，只有在系统提供IRQ范围时才会使用传统域，否则将使用
 163 线性域映射。这个调用的语义是这样的：如果指定了一个IRQ范围，那么 描述符将被即时分配
 164 给它，如果没有范围被分配，它将不会执行 irq_domain_add_linear() 或
 165 irq_domain_create_linear()，这意味着 *no* irq 描述符将被分配。
 166
 167 一个简单域的典型用例是，irqchip供应商同时支持动态和静态IRQ分配。
 168
 169 为了避免最终出现使用线性域而没有描述符被分配的情况，确保使用简单域的驱动程序在任何
 170 irq_find_mapping()之前调用irq_create_mapping()是非常重要的，因为后者实际上
 171 将用于静态IRQ分配情况。
 172
 173 irq_domain_add_simple()和irq_domain_create_simple()以及
 174 irq_domain_add_legacy()和irq_domain_create_legacy()在功能上是等价的，只
 175 是第一个参数不同--前者接受Open Firmware特定的 'struct device_node' ，而后者
 176 接受一个更通用的抽象 'struct fwnode_handle' 。
 177
 178 IRQ域层级结构
 179 -------------
 180
 181 在某些架构上，可能有多个中断控制器参与将一个中断从设备传送到目标CPU。
 182 让我们来看看x86平台上典型的中断传递路径吧
 183 ::
 184
 185   Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU
 186
 187 涉及到的中断控制器有三个:
 188
 189 1) IOAPIC 控制器
 190 2) 中断重映射控制器
 191 3) Local APIC 控制器
 192
 193 为了支持这样的硬件拓扑结构，使软件架构与硬件架构相匹配，为每个中断控制器建立一
 194 个irq_domain数据结构，并将这些irq_domain组织成层次结构。
 195
 196 在建立irq_domain层次结构时，靠近设备的irq_domain为子域，靠近CPU的
 197 irq_domain为父域。所以在上面的例子中，将建立如下的层次结构。
 198 ::
 199
 200         CPU Vector irq_domain (root irq_domain to manage CPU vectors)
 201                 ^
 202                 |
 203         Interrupt Remapping irq_domain (manage irq_remapping entries)
 204                 ^
 205                 |
 206         IOAPIC irq_domain (manage IOAPIC delivery entries/pins)
 207
 208 使用irq_domain层次结构的主要接口有四个:
 209
 210 1) irq_domain_alloc_irqs(): 分配IRQ描述符和与中断控制器相关的资源来传递这些中断。
 211 2) irq_domain_free_irqs(): 释放IRQ描述符和与这些中断相关的中断控制器资源。
 212 3) irq_domain_activate_irq(): 激活中断控制器硬件以传递中断。
 213 4) irq_domain_deactivate_irq(): 停用中断控制器硬件，停止传递中断。
 214
 215 为了支持irq_domain层次结构，需要做如下修改:
 216
 217 1) 一个新的字段 'parent' 被添加到irq_domain结构中；它用于维护irq_domain的层次信息。
 218 2) 一个新的字段 'parent_data' 被添加到irq_data结构中；它用于建立层次结构irq_data以
 219    匹配irq_domain层次结构。irq_data用于存储irq_domain指针和硬件irq号。
 220 3) 新的回调被添加到irq_domain_ops结构中，以支持层次结构的irq_domain操作。
 221
 222 在支持分层irq_domain和分层irq_data准备就绪后，为每个中断控制器建立一个irq_domain结
 223 构，并为每个与IRQ相关联的irq_domain分配一个irq_data结构。现在我们可以再进一步支持堆
 224 栈式(层次结构)的irq_chip。也就是说，一个irq_chip与层次结构中的每个irq_data相关联。
 225 一个子irq_chip可以自己或通过与它的父irq_chip合作来实现一个所需的操作。
 226
 227 通过堆栈式的irq_chip，中断控制器驱动只需要处理自己管理的硬件，在需要的时候可以向其父
 228 irq_chip请求服务。所以我们可以实现更简洁的软件架构。
 229
 230 为了让中断控制器驱动程序支持irq_domain层次结构，它需要做到以下几点:
 231
 232 1) 实现 irq_domain_ops.alloc 和 irq_domain_ops.free
 233 2) 可选择地实现 irq_domain_ops.activate 和 irq_domain_ops.deactivate.
 234 3) 可选择地实现一个irq_chip来管理中断控制器硬件。
 235 4) 不需要实现irq_domain_ops.map和irq_domain_ops.unmap，它们在层次结构
 236    irq_domain中是不用的。
 237
 238 irq_domain层次结构绝不是x86特有的，大量用于支持其他架构，如ARM、ARM64等。
 239
 240 调试功能
 241 ========
 242
 243 打开CONFIG_GENERIC_IRQ_DEBUGFS，可让IRQ子系统的大部分内部结构都在debugfs中暴露出来。