[RK3288][Android6.0] IRQ-domain.txt 翻译

Platform: RK3288
OS: Android 6.0
Kernel: 3.10.92

在前面文章学习RK818驱动时, 用到了irq doamin, 这里顺便把

kernel/Documentation/IRQ-domain.txt的使用部分翻译下,供大家参考.

The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
irq numbers, but they don't provide any support for reverse mapping of
the controller-local IRQ (hwirq) number into the Linux IRQ number
space.
irq_alloc_desc*()和irq_free_desc*()只负责irq numbers的映射和释放,但不提供保存
IRQ numbers 和 hwirq的映射空间.

The irq_domain library adds mapping between hwirq and IRQ numbers on
top of the irq_alloc_desc*() API.  An irq_domain to manage mapping is
preferred over interrupt controller drivers open coding their own
reverse mapping scheme.
irq_domain用irq_alloc_desc*()添加hwirq和IRQ numbers之前的映射,相对使用中断
控制器驱动来处理保留映射会更好.

irq_domain also implements translation from Device Tree interrupt
specifiers to hwirq numbers, and can be easily extended to support
other IRQ topology data sources.
irq_domain也可以处理dts中的hwirq numbers, 而且容易扩展支持其他IRQ拓扑数据源.

=== irq_domain usage ===
An interrupt controller driver creates and registers an irq_domain by
calling one of the irq_domain_add_*() functions (each mapping method
has a different allocator function, more on that later).  The function
will return a pointer to the irq_domain on success.  The caller must
provide the allocator function with an irq_domain_ops structure with
the .map callback populated as a minimum.
irq_domain通过irq_domain_add_*()创建和注册,每个创建函数的分配方法也不一样.
不过最终都是返回的是irq_domain指针. 调用参数需要实现irq_domain_ops以及至少
要实现.map回调函数.

In most cases, the irq_domain will begin empty without any mappings
between hwirq and IRQ numbers.  Mappings are added to the irq_domain
by calling irq_create_mapping() which accepts the irq_domain and a
hwirq number as arguments.  If a mapping for the hwirq doesn't already
exist then it will allocate a new Linux irq_desc, associate it with
the hwirq, and call the .map() callback so the driver can perform any
required hardware setup.
irq_domain开始创建的映射表是空的,然后需要调用irq_create_mapping()创建
IRQ numbers和hwirq之间的具体映射关系.创建映射的时候会分配一个新的Linux irq_desc,
和hwirq关联上后,就会调用.map()回调函数, 这样驱动可以执行任何硬件相关的配置.

When an interrupt is received, irq_find_mapping() function should
be used to find the Linux IRQ number from the hwirq number.
当中断收到后, 使用irq_find_mapping()找到hwirq number对应的IRQ number.

The irq_create_mapping() function must be called *atleast once*
before any call to irq_find_mapping(), lest the descriptor will not
be allocated.
调用irq_find_mapping()之前先要跑irq_create_mapping(), 否则会找到不到.

If the driver has the Linux IRQ number or the irq_data pointer, and
needs to know the associated hwirq number (such as in the irq_chip
callbacks) then it can be directly obtained from irq_data->hwirq.
如果驱动irq_data有值,并且需要知道关联的hwirq number,可以直接从irq_data->hwirq获取.

=== Types of irq_domain mappings ===
There are several mechanisms available for reverse mapping from hwirq
to Linux irq, and each mechanism uses a different allocation function.
Which reverse map type should be used depends on the use case.  Each
of the reverse map types are described below:

==== Linear ====
irq_domain_add_linear()

The linear reverse map maintains a fixed size table indexed by the
hwirq number.  When a hwirq is mapped, an irq_desc is allocated for
the hwirq, and the IRQ number is stored in the table.
线性映射保留一张固定的表,通过hwirq number来索引.当hwirq被映射后, 会相应地分配
一个irq_desc, IRQ number就被存在表中.

The Linear map is a good choice when the maximum number of hwirqs is
fixed and a relatively small number (~ < 256).  The advantages of this
map are fixed time lookup for IRQ numbers, and irq_descs are only
allocated for in-use IRQs.  The disadvantage is that the table must be
as large as the largest possible hwirq number.
当hwirqs是固定的而且小于256, 用线性映射更好.它的优势是寻找时间固定,并且irq_descs
只在in-use IRQs分配.缺点是表格和hwirq 最大numbers一样大.

The majority of drivers should use the linear map.
大部分情况应该用线性映射.

==== Tree ====
irq_domain_add_tree()

The irq_domain maintains a radix tree map from hwirq numbers to Linux
IRQs.  When an hwirq is mapped, an irq_desc is allocated and the
hwirq is used as the lookup key for the radix tree.
此种方法使用radix tree来维护map, 通过key来查找.

The tree map is a good choice if the hwirq number can be very large
since it doesn't need to allocate a table as large as the largest
hwirq number.  The disadvantage is that hwirq to IRQ number lookup is
dependent on how many entries are in the table.
此方法适合hwirq number非常大的时候, 因为它不需要分配和hwirq一样大的table.
缺点是查表效率依赖与table里的entries数量.

Very few drivers should need this mapping.  At the moment, powerpc
iseries is the only user.
目前只有powerpc平台使用这种方法.

==== No Map ===-
irq_domain_add_nomap()

The No Map mapping is to be used when the hwirq number is
programmable in the hardware.  In this case it is best to program the
Linux IRQ number into the hardware itself so that no mapping is
required.  Calling irq_create_direct_mapping() will allocate a Linux
IRQ number and call the .map() callback so that driver can program the
Linux IRQ number into the hardware.
当有些硬件可以对hwirq number编程时,IRQ number被编进硬件寄存器里,那么就不需要映射了.
这种情况下通过irq_create_direct_mapping()实现.