Interrupt definitions in DTS (device tree) files for Xilinx Zynq-7000 / ARM

Having some trouble to figure out what I should write in my own hand-written DTS entry for my logic, I ended up reading the sources of the Linux kernel (version 3.3, which is the currently used for Zynq). The purpose is to hook up a device defined in the PL of a Zynq-7000 (FPGA-style logic fabric) for my Zedboard, but at this time, the automatic generation tool for DTS I’ve written about ignores PL modules.

There’s also a more general post about the Device Tree.

So if the UART’s entry looks like this,

uart@e0001000 {
 compatible = "xlnx,ps7-uart-1.00.a";
 reg = <0xe0001000 0x1000>;
 interrupts = <0x0 0x32 0x0>;
 interrupt-parent = <&gic>;
 clock = <50000000>;
};

What does the “interrupts = <0x0 0x32 0x0>” part stand for? How do I get my definition right?

This is what I figure out. If you just want the bottom line, skip the walkthrough, which I left here for future reference (future kernels etc).

The walkthrough

These values are put into an of_irq structure, which is defined in include/linux/of_irq.h as follows:

/**
 * of_irq - container for device_node/irq_specifier pair for an irq controller
 * @controller: pointer to interrupt controller device tree node
 * @size: size of interrupt specifier
 * @specifier: array of cells @size long specifing the specific interrupt
 *
 * This structure is returned when an interrupt is mapped. The controller
 * field needs to be put() after use
 */
#define OF_MAX_IRQ_SPEC        4 /* We handle specifiers of at most 4 cells */
struct of_irq {
 struct device_node *controller; /* Interrupt controller node */
 u32 size; /* Specifier size */
 u32 specifier[OF_MAX_IRQ_SPEC]; /* Specifier copy */
}

We have of_irq_map_one() in drivers/of/irq.c fetching the “interrupt” property from the device tree, calling of_irq_map_raw() in the same file, which populates the of_irq structure with data. Specifically, we have the “specifier” field containing the data in the array exactly as it appears in the DTS file, and “size” indicating the number of elements.

Then irq_of_parse_and_map()  tears the of_irq into its three components, calling irq_create_of_mapping() with these.

This function resolves the hardware number of the interrupt by calling the function given in the dt_translate entry of the ops entry of the interrupt controller structure. In arch/arm/common/gic.c this entry is populated with the gic_irq_domain_dt_translate() function, which is defined in the same file. Note that “dt_translate” becomes “xlate” in later kernels) .

This translation function reveals what the interrupt specification means, as detailed in “the bottom line”.

irq_create_of_mapping() also calls irq_domain_to_irq() to calculate the IRQ number to be known within Linux, and more interesting, irq_set_irq_type(), which is defined in kernel/irq/chip.c. The latter function merely takes the bus lock, calls __irq_set_trigger(), and released the lock. Well, for one important exception: It does nothing if the IRQ type is set to IRQ_TYPE_NONE. In other words, the chip’s default is retained.

I didn’t bother to follow up __irq_set_trigger(), because it’s pretty obvious what this function is meant to do, and following it to the precise point is tedious, as it’s boiling down to some hardware-specific function.

The bottom line

The first value is a flag indicating if the interrupt is an SPI (shared peripheral interrupt). A nonzero value means it is an SPI.

The second value is the interrupt number. The translate function adds 16 to SPIs and 32 to non-SPIs, so for interrupts generated by fabric logic in a Zynq, the number in the DTS file should be the hardware number (as shown in Xilinx Platform Studio, XPS) minus 32.

The third value is the type of interrupt, which is ANDed wtih IRQ_TYPE_SENSE_MASK (= 0x0f), which is defined in include/linux/irq.h. Also from this file is the meaning of the IRQ types as shown at the end of this post. Refer to the values in the “enum” clause: IRQ_TYPE_LEVEL_HIGH is 4 and IRQ_TYPE_EDGE_RISING is 1.

Cortex-A9 can’t support any other interrupt types, as put in arch/arm/common/gic.c:

if (type != IRQ_TYPE_LEVEL_HIGH && type != IRQ_TYPE_EDGE_RISING)
 return -EINVAL

Returning -EINVAL means “failed because of invalid value”, so it says it all.

An important conclusion is that the common choice of zero for the third value actually means “leave it as it was”. This is not a necessarily clever choice, in particular if some bootloader fools around setting things it shouldn’t. It’s not a likely scenario, but it will be extremely difficult to spot a problem like this, since we all naturally assume that the interrupt attributes are completely set when the system boots up.

Anyhow, the reset default value for all of the relevant interrupts is an active High level. However, software is required to the interrupts for L1 cache and parity to rising-edge sensitivity. See the Zynq-7000 EPP Technical Reference Manual (TRM), section 7.2.3.

UART example revisited

Now let’s look at the interrupts = <0x0 0x32 0x0> definition again, with some help from the TRM. From the address of the registers, 0xe0001000, it’s clear that it’s UART1 (see TRM, appendix B.33). According to Table 7-3 in TRM’s section 7.2.3, UART1′s interrupt number is 82. Since the first value is 0, it’s declared as a non-SPI, so the second value should be the hardware number minus 32, which is 50, or 0x32. The third value says to leave the interrupt type as is.

The only offbeat thing here is the name of the section, under which the interrupt is listed: “Shared Peripheral Interrupts”. And still, it’s declared as a non-SPI. So it looks like this SPI thing isn’t so important.

Excerpt from irq.h

/*
 * IRQ line status.
 *
 * Bits 0-7 are the same as the IRQF_* bits in linux/interrupt.h
 *
 * IRQ_TYPE_NONE        - default, unspecified type
 * IRQ_TYPE_EDGE_RISING        - rising edge triggered
 * IRQ_TYPE_EDGE_FALLING    - falling edge triggered
 * IRQ_TYPE_EDGE_BOTH        - rising and falling edge triggered
 * IRQ_TYPE_LEVEL_HIGH        - high level triggered
 * IRQ_TYPE_LEVEL_LOW        - low level triggered
 * IRQ_TYPE_LEVEL_MASK        - Mask to filter out the level bits
 * IRQ_TYPE_SENSE_MASK        - Mask for all the above bits
 * IRQ_TYPE_PROBE        - Special flag for probing in progress
 *
 * Bits which can be modified via irq_set/clear/modify_status_flags()
 * IRQ_LEVEL            - Interrupt is level type. Will be also
 *                  updated in the code when the above trigger
 *                  bits are modified via irq_set_irq_type()
 * IRQ_PER_CPU            - Mark an interrupt PER_CPU. Will protect
 *                  it from affinity setting
 * IRQ_NOPROBE            - Interrupt cannot be probed by autoprobing
 * IRQ_NOREQUEST        - Interrupt cannot be requested via
 *                  request_irq()
 * IRQ_NOTHREAD            - Interrupt cannot be threaded
 * IRQ_NOAUTOEN            - Interrupt is not automatically enabled in
 *                  request/setup_irq()
 * IRQ_NO_BALANCING        - Interrupt cannot be balanced (affinity set)
 * IRQ_MOVE_PCNTXT        - Interrupt can be migrated from process context
 * IRQ_NESTED_TRHEAD        - Interrupt nests into another thread
 * IRQ_PER_CPU_DEVID        - Dev_id is a per-cpu variable
 */
enum {
 IRQ_TYPE_NONE        = 0x00000000,
 IRQ_TYPE_EDGE_RISING    = 0x00000001,
 IRQ_TYPE_EDGE_FALLING    = 0x00000002,
 IRQ_TYPE_EDGE_BOTH    = (IRQ_TYPE_EDGE_FALLING | IRQ_TYPE_EDGE_RISING),
 IRQ_TYPE_LEVEL_HIGH    = 0x00000004,
 IRQ_TYPE_LEVEL_LOW    = 0x00000008,
 IRQ_TYPE_LEVEL_MASK    = (IRQ_TYPE_LEVEL_LOW | IRQ_TYPE_LEVEL_HIGH),
 IRQ_TYPE_SENSE_MASK    = 0x0000000f,

 IRQ_TYPE_PROBE        = 0x00000010,

 IRQ_LEVEL        = (1 <<  8),
 IRQ_PER_CPU        = (1 <<  9),
 IRQ_NOPROBE        = (1 << 10),
 IRQ_NOREQUEST        = (1 << 11),
 IRQ_NOAUTOEN        = (1 << 12),
 IRQ_NO_BALANCING    = (1 << 13),
 IRQ_MOVE_PCNTXT        = (1 << 14),
 IRQ_NESTED_THREAD    = (1 << 15),
 IRQ_NOTHREAD        = (1 << 16),
 IRQ_PER_CPU_DEVID    = (1 << 17),
};