[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()实现.