threaded irq

/**
 * struct irq_desc - interrupt descriptor
 * @irq:                interrupt number for this descriptor
 * @timer_rand_state:   pointer to timer rand state struct
 * @kstat_irqs:         irq stats per cpu
 * @irq_2_iommu:        iommu with this irq
 * @handle_irq:         highlevel irq-events handler [if NULL, __do_IRQ()]
 * @chip:               low level interrupt hardware access
 * @msi_desc:           MSI descriptor
 * @handler_data:       per-IRQ data for the irq_chip methods
 * @chip_data:          platform-specific per-chip private data for the chip
 *                      methods, to allow shared chip implementations
 * @action:             the irq action chain
 * @status:             status information
 * @depth:              disable-depth, for nested irq_disable() calls
 * @wake_depth:         enable depth, for multiple set_irq_wake() callers
 * @irq_count:          stats field to detect stalled irqs
 * @last_unhandled:     aging timer for unhandled count
 * @irqs_unhandled:     stats field for spurious unhandled interrupts
 * @lock:               locking for SMP
 * @affinity:           IRQ affinity on SMP
 * @node:               node index useful for balancing
 * @pending_mask:       pending rebalanced interrupts
 * @threads_active:     number of irqaction threads currently running
 * @wait_for_threads:   wait queue for sync_irq to wait for threaded handlers
 * @dir:                /proc/irq/ procfs entry
 * @name:               flow handler name for /proc/interrupts output
 */
//irq_desc实际是个用于构成数组的数据结构。这里irq就是我们熟悉的irq号，每个设备申请到一个IRQ，就需要填充一个irq_desc，
//并由kernel放入所维护的数组中进行管理
struct irq_desc {
        unsigned int            irq;
        struct timer_rand_state *timer_rand_state;
        unsigned int            *kstat_irqs;
#ifdef CONFIG_INTR_REMAP
        struct irq_2_iommu      *irq_2_iommu;
#endif
        irq_flow_handler_t      handle_irq;
        struct irq_chip         *chip;          //...
        struct msi_desc         *msi_desc;      //...
        void                    *handler_data;
        void                    *chip_data;
        struct irqaction        *action;        // IRQ action list ... 实际上是一个单向链表
        unsigned int            status;         /* IRQ status */

        unsigned int            depth;          /* nested irq disables */
        unsigned int            wake_depth;     /* nested wake enables */
        unsigned int            irq_count;      /* For detecting broken IRQs */
        unsigned long           last_unhandled; /* Aging timer for unhandled count */
        unsigned int            irqs_unhandled;
        spinlock_t              lock;
#ifdef CONFIG_SMP
        cpumask_var_t           affinity;
        unsigned int            node;
#ifdef CONFIG_GENERIC_PENDING_IRQ
        cpumask_var_t           pending_mask;
#endif
#endif
        atomic_t                threads_active;
        wait_queue_head_t       wait_for_threads;
#ifdef CONFIG_PROC_FS
        struct proc_dir_entry   *dir;
#endif
        const char              *name;
} ____cacheline_internodealigned_in_smp;


/**
 * struct irq_chip - hardware interrupt chip descriptor
 *
 * @name:               name for /proc/interrupts
 * @startup:            start up the interrupt (defaults to ->enable if NULL)
 * @shutdown:           shut down the interrupt (defaults to ->disable if NULL)
 * @enable:             enable the interrupt (defaults to chip->unmask if NULL)
 * @disable:            disable the interrupt (defaults to chip->mask if NULL)
 * @ack:                start of a new interrupt
 * @mask:               mask an interrupt source
 * @mask_ack:           ack and mask an interrupt source
 * @unmask:             unmask an interrupt source
 * @eoi:                end of interrupt - chip level
 * @end:                end of interrupt - flow level
 * @set_affinity:       set the CPU affinity on SMP machines
 * @retrigger:          resend an IRQ to the CPU
 * @set_type:           set the flow type (IRQ_TYPE_LEVEL/etc.) of an IRQ
 * @set_wake:           enable/disable power-management wake-on of an IRQ
 *
 * @bus_lock:           function to lock access to slow bus (i2c) chips
 * @bus_sync_unlock:    function to sync and unlock slow bus (i2c) chips
 *
 * @release:            release function solely used by UML
 * @typename:           obsoleted by name, kept as migration helper
 */
struct irq_chip {
        const char      *name;
        unsigned int    (*startup)(unsigned int irq);
        void            (*shutdown)(unsigned int irq);
        void            (*enable)(unsigned int irq);
        void            (*disable)(unsigned int irq);

        void            (*ack)(unsigned int irq);
        void            (*mask)(unsigned int irq);
        void            (*mask_ack)(unsigned int irq);
        void            (*unmask)(unsigned int irq);
        void            (*eoi)(unsigned int irq);

        void            (*end)(unsigned int irq);
        int             (*set_affinity)(unsigned int irq,
                                        const struct cpumask *dest);
        int             (*retrigger)(unsigned int irq);
        int             (*set_type)(unsigned int irq, unsigned int flow_type);
        int             (*set_wake)(unsigned int irq, unsigned int on);

        void            (*bus_lock)(unsigned int irq);
        void            (*bus_sync_unlock)(unsigned int irq);

        /* Currently used only by UML, might disappear one day.*/
#ifdef CONFIG_IRQ_RELEASE_METHOD
        void            (*release)(unsigned int irq, void *dev_id);
#endif
        //For compatibility, ->typename is copied into ->name. Will disappear.
        const char      *typename;
};





//request一个IRQ的过程实际上就是构造irqaction项，free一个IRQ的过程就是移除不需要的irqaction项。
/**
 * struct irqaction - per interrupt action descriptor
 * @handler:    interrupt handler function
 * @flags:      flags (see IRQF_* above)
 * @name:       name of the device
 * @dev_id:     cookie to identify the device
 * @next:       pointer to the next irqaction for shared interrupts
 * @irq:        interrupt number
 * @dir:        pointer to the proc/irq/NN/name entry
 * @thread_fn:  interupt handler function for threaded interrupts
 * @thread:     thread pointer for threaded interrupts
 * @thread_flags:       flags related to @thread
 */
struct irqaction {
        irq_handler_t         handler;
        unsigned long         flags;
        const char            *name;
        void                  *dev_id;
        struct irqaction      *next;
        int                   irq;
        struct proc_dir_entry *dir;
        irq_handler_t         thread_fn;
        struct task_struct    *thread;
        unsigned long         thread_flags;
};

//struct irqaction中的handler定义了中断处理函数,*next指向了下一个irqaction，也就是说irqaction是以链表的形式存在的。也就是说，
//每一个IRQ对应一个irq_desc，而irq_desc维护着irq_chip管理了硬件层面的中断使能，同时irq_desc也维护了一个irqaction链表。

/**
 *      request_threaded_irq - allocate an interrupt line
 *      @irq      : Interrupt line to allocate
 *      @handler  : Function to be called when the IRQ occurs. Primary handler for threaded interrupts
 *                  If NULL and thread_fn != NULL the default primary handler is installed
 *      @thread_fn: Function called from the irq handler thread If NULL, no irq thread is created
 *      @irqflags : Interrupt type flags
 *      @devname  : An ascii name for the claiming device
 *      @dev_id   : A cookie passed back to the handler function
 *
 *      This call allocates interrupt resources and enables the interrupt line and IRQ handling. From the
 *      point this call is made your handler function may be invoked. Since your handler function must 
 *      clear any interrupt the board raises, you must take care both to initialise your hardware and to 
 *      set up the interrupt handler in the right order.
 *
 *      If you want to set up a threaded irq handler for your device then you need to supply @handler and
 *      @thread_fn. @handler ist still called in hard interrupt context and has to check whether the 
 *      interrupt originates from the device. If yes it needs to disable the interrupt on the device and 
 *      return IRQ_WAKE_THREAD which will wake up the handler thread and run @thread_fn. This split handler
 *      design is necessary to support shared interrupts.
 *
 *      Dev_id must be globally unique. Normally the address of the device data structure is used as the 
 *      cookie. Since the handler receives this value it makes sense to use it.
 *
 *      If your interrupt is shared you must pass a non NULL dev_id as this is required when freeing the 
 *      interrupt.
 *
 *      Flags:
 *
 *      IRQF_SHARED             Interrupt is shared
 *      IRQF_DISABLED           Disable local interrupts while processing
 *      IRQF_SAMPLE_RANDOM      The interrupt can be used for entropy
 *      IRQF_TRIGGER_*          Specify active edge(s) or level
 *
 */

/*
分析request_threaded_irq()函数中的各个形参
1>. irq:       表示申请的中断号。
2>. handler:   表示中断服务例程
3>. thread_fn：中断线程化，此处传递的是NULL。NULL表示没有中断线程化。
                  此参数是最新版本中才出现的。为什么要提出中断线程化?
               在 Linux 中，中断具有最高的优先级。不论在任何时刻，只要产生中断事件，内核将立即执行相应的中断
                  处理程序，等到所有挂起的中断和软中断处理完毕后才能执行正常的任务，因此有可能造成实时任务得不
                  到及时的处理。中断线程化之后，中断将作为内核线程运行而且被赋予不同的实时优先级，实时任务可以
                  有比中断线程更高的优先级。这样，具有最高优先级的实时任务就能得到优先处理，即使在严重负载下仍
                  有实时性保证。but,并不是所有的中断都可以被线程化，比如时钟中断，主要用来维护系统时间以及定时器
                  等，其中定时器是操作系统的脉搏，一旦被线程化，就有可能被挂起，这样后果将不堪设想，所以不应当
                  被线程化。 
4>. irqflags: 表示中断标志位。
5>. devname:  表示请求中断的设备的名称。

6>.dev_id:    对应于request_irq()函数中所传递的第五个参数，可取任意值，但必须唯一能够代表发出中断请求的设备，通常取描述该设备的结构体。 
                 共享中断时所用。
*/
int request_threaded_irq(unsigned int irq, irq_handler_t handler, irq_handler_t thread_fn, unsigned long irq flags,
                         const char *devname, void *dev_id)
{
        struct irqaction *action;
        struct irq_desc *desc;
        int retval;

        //handle_IRQ_event() always ignores IRQF_DISABLED except for the _first_ irqaction (sigh).  That can cause
        //oopsing, but the behavior is classified as "will not fix" so we need to start nudging drivers
        //away from using that idiom.
        if ((irqflags & (IRQF_SHARED|IRQF_DISABLED)) == (IRQF_SHARED|IRQF_DISABLED)) {
                pr_warning("IRQ %d/%s: IRQF_DISABLED is not guaranteed on shared IRQs\n", irq, devname);
        }

#ifdef CONFIG_LOCKDEP
        //Lockdep wants atomic interrupt handlers:
        irqflags |= IRQF_DISABLED;
#endif
        //Sanity-check: shared interrupts must pass in a real dev-ID, otherwise we'll have trouble later trying 
        //to figure out which interrupt is which (messes up the interrupt freeing logic etc).
        if ((irqflags & IRQF_SHARED) && !dev_id)
                return -EINVAL;

        desc = irq_to_desc(irq);
        if (!desc)
                return -EINVAL;

        if (desc->status & IRQ_NOREQUEST)
                return -EINVAL;

        if (!handler) {
                if (!thread_fn)
                        return -EINVAL;
                handler = irq_default_primary_handler;
        }

        action = kzalloc(sizeof(struct irqaction), GFP_KERNEL);
        if (!action)
                return -ENOMEM;

        action->handler = handler;
        action->thread_fn = thread_fn;
        action->flags = irqflags;
        action->name = devname;
        action->dev_id = dev_id;

        chip_bus_lock(irq, desc);
        retval = __setup_irq(irq, desc, action);
        chip_bus_sync_unlock(irq, desc);

        if (retval)
                kfree(action);

#ifdef CONFIG_DEBUG_SHIRQ
        if (irqflags & IRQF_SHARED) {
                //It's a shared IRQ -- the driver ought to be prepared for it to happen immediately, so let's make sure....
                //We disable the irq to make sure that a 'real' IRQ doesn't run in parallel with our fake.
                unsigned long flags;

                disable_irq(irq);
                local_irq_save(flags);

                handler(irq, dev_id);

                local_irq_restore(flags);
                enable_irq(irq);
        }
#endif
        return retval;
}



/*
 * Internal function to register an irqaction - typically used to
 * allocate special interrupts that are part of the architecture.
 */
static int
__setup_irq(unsigned int irq, struct irq_desc *desc, struct irqaction *new)
{
        struct irqaction *old, **old_ptr;
        const char *old_name = NULL;
        unsigned long flags;
        int nested, shared = 0;
        int ret;

        if (!desc)
                return -EINVAL;

        if (desc->chip == &no_irq_chip)
                return -ENOSYS;
        /*
         * Some drivers like serial.c use request_irq() heavily,
         * so we have to be careful not to interfere with a
         * running system.
         */
        if (new->flags & IRQF_SAMPLE_RANDOM) {
                /*
                 * This function might sleep, we want to call it first,
                 * outside of the atomic block.
                 * Yes, this might clear the entropy pool if the wrong
                 * driver is attempted to be loaded, without actually
                 * installing a new handler, but is this really a problem,
                 * only the sysadmin is able to do this.
                 */
                rand_initialize_irq(irq);
        }

        /* Oneshot interrupts are not allowed with shared */
        if ((new->flags & IRQF_ONESHOT) && (new->flags & IRQF_SHARED))
                return -EINVAL;

        /*
         * Check whether the interrupt nests into another interrupt
         * thread.
         */
        nested = desc->status & IRQ_NESTED_THREAD;
        if (nested) {
                if (!new->thread_fn)
                        return -EINVAL;
                /*
                 * Replace the primary handler which was provided from
                 * the driver for non nested interrupt handling by the
                 * dummy function which warns when called.
                 */
                new->handler = irq_nested_primary_handler;
        }

        /*
         * Create a handler thread when a thread function is supplied
         * and the interrupt does not nest into another interrupt
         * thread.
         */
        if (new->thread_fn && !nested) {
                struct task_struct *t;

                t = kthread_create(irq_thread, new, "irq/%d-%s", irq,
                                   new->name);
                if (IS_ERR(t))
                        return PTR_ERR(t);
                /*
                 * We keep the reference to the task struct even if
                 * the thread dies to avoid that the interrupt code
                 * references an already freed task_struct.
                 */
                get_task_struct(t);
                new->thread = t;
        }

        /*
         * The following block of code has to be executed atomically
         */
        spin_lock_irqsave(&desc->lock, flags);
        old_ptr = &desc->action;
        old = *old_ptr;
        if (old) {
                /*
                 * Can't share interrupts unless both agree to and are
                 * the same type (level, edge, polarity). So both flag
                 * fields must have IRQF_SHARED set and the bits which
                 * set the trigger type must match.
                 */
                if (!((old->flags & new->flags) & IRQF_SHARED) ||
                     ((old->flags ^ new->flags) & IRQF_TRIGGER_MASK)) {
                        old_name = old->name;
                        goto mismatch;
                }

#if defined(CONFIG_IRQ_PER_CPU)
                /* All handlers must agree on per-cpuness */
                if ((old->flags & IRQF_PERCPU) !=
                    (new->flags & IRQF_PERCPU))
                        goto mismatch;
#endif

                /* add new interrupt at end of irq queue */
                do {
                        old_ptr = &old->next;
                        old = *old_ptr;
                } while (old);
                shared = 1;
        }

        if (!shared) {
                irq_chip_set_defaults(desc->chip);

                init_waitqueue_head(&desc->wait_for_threads);

                /* Setup the type (level, edge polarity) if configured: */
                if (new->flags & IRQF_TRIGGER_MASK) {
                        ret = __irq_set_trigger(desc, irq,
                                        new->flags & IRQF_TRIGGER_MASK);

                        if (ret)
                                goto out_thread;
                } else
                        compat_irq_chip_set_default_handler(desc);
#if defined(CONFIG_IRQ_PER_CPU)
                if (new->flags & IRQF_PERCPU)
                        desc->status |= IRQ_PER_CPU;
#endif

                desc->status &= ~(IRQ_AUTODETECT | IRQ_WAITING | IRQ_ONESHOT |
                                  IRQ_INPROGRESS | IRQ_SPURIOUS_DISABLED);

                if (new->flags & IRQF_ONESHOT)
                        desc->status |= IRQ_ONESHOT;

                if (!(desc->status & IRQ_NOAUTOEN)) {
                        desc->depth = 0;
                        desc->status &= ~IRQ_DISABLED;
                        desc->chip->startup(irq);
                } else
                        /* Undo nested disables: */
                        desc->depth = 1;

                /* Exclude IRQ from balancing if requested */
                if (new->flags & IRQF_NOBALANCING)
                        desc->status |= IRQ_NO_BALANCING;

                /* Set default affinity mask once everything is setup */
                setup_affinity(irq, desc);

        } else if ((new->flags & IRQF_TRIGGER_MASK)
                        && (new->flags & IRQF_TRIGGER_MASK)
                                != (desc->status & IRQ_TYPE_SENSE_MASK)) {
                /* hope the handler works with the actual trigger mode... */
                pr_warning("IRQ %d uses trigger mode %d; requested %d\n",
                                irq, (int)(desc->status & IRQ_TYPE_SENSE_MASK),
                                (int)(new->flags & IRQF_TRIGGER_MASK));
        }

        new->irq = irq;
        *old_ptr = new;

        /* Reset broken irq detection when installing new handler */
        desc->irq_count = 0;
        desc->irqs_unhandled = 0;

        /*
         * Check whether we disabled the irq via the spurious handler
         * before. Reenable it and give it another chance.
         */
        if (shared && (desc->status & IRQ_SPURIOUS_DISABLED)) {
                desc->status &= ~IRQ_SPURIOUS_DISABLED;
                __enable_irq(desc, irq, false);
        }

        spin_unlock_irqrestore(&desc->lock, flags);

        /*
         * Strictly no need to wake it up, but hung_task complains
         * when no hard interrupt wakes the thread up.
         */
        if (new->thread)
                wake_up_process(new->thread);

        register_irq_proc(irq, desc);
        new->dir = NULL;
        register_handler_proc(irq, new);

        return 0;


mismatch:
#ifdef CONFIG_DEBUG_SHIRQ
        if (!(new->flags & IRQF_PROBE_SHARED)) {
                printk(KERN_ERR "IRQ handler type mismatch for IRQ %d\n", irq);
                if (old_name)
                        printk(KERN_ERR "current handler: %s\n", old_name);
                dump_stack();
        }
#endif
        ret = -EBUSY;

out_thread:
        spin_unlock_irqrestore(&desc->lock, flags);
        if (new->thread) {
                struct task_struct *t = new->thread;


                new->thread = NULL;
                if (likely(!test_bit(IRQTF_DIED, &new->thread_flags)))
                        kthread_stop(t);
                put_task_struct(t);
        }
        return ret;
}