Interrupts: Hardware-Level I/O Signaling

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// Shared IRQ handler - must identify which device(s) interrupted
irqreturn_t shared_irq_handler(int irq, void *dev_id) {
    // When multiple devices share an IRQ, we must check each one
    
    // Check device A
    if (device_a->status_register & INTERRUPT_PENDING) {
        handle_device_a_interrupt();
        device_a->status_register = CLEAR_INTERRUPT;
        return IRQ_HANDLED;
    }
    
    // Check device B
    if (device_b->status_register & INTERRUPT_PENDING) {
        handle_device_b_interrupt();
        device_b->status_register = CLEAR_INTERRUPT;
        return IRQ_HANDLED;
    }
    
    // Check device C
    if (device_c->status_register & INTERRUPT_PENDING) {
        handle_device_c_interrupt();
        device_c->status_register = CLEAR_INTERRUPT;
        return IRQ_HANDLED;
    }
    
    // None of our devices caused the interrupt
    // (Some other device on the shared line must handle it)
    return IRQ_NONE;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

// Examples of CORRECT and INCORRECT interrupt handler code
 
// WRONG: This handler can crash the system
irqreturn_t bad_handler(int irq, void *dev_id) {
    // BUG: GFP_KERNEL may sleep waiting for memory
    void *buffer = kmalloc(1024, GFP_KERNEL);
    
    // BUG: Mutex may sleep waiting for lock holder
    mutex_lock(&device_mutex);
    
    // BUG: copy_to_user may trigger page fault
    copy_to_user(user_ptr, data, size);
    
    // BUG: This may sleep for disk I/O
    write_log_file(event_data);
    
    return IRQ_HANDLED;
}
 
// CORRECT: This handler follows all constraints
irqreturn_t good_handler(int irq, void *dev_id) {
    struct device_state *dev = dev_id;
    
    // Use GFP_ATOMIC for interrupt-context allocation
    void *buffer = kmalloc(1024, GFP_ATOMIC);
    if (!buffer) {
        // Just drop the data—can't sleep to get memory
        dev->dropped_events++;
        goto ack_and_return;
    }
    
    // Use spinlock, not mutex
    spin_lock(&dev->spinlock);
    
    // Read device data directly (no user space)
    memcpy_fromio(buffer, dev->hardware_buffer, 1024);
    list_add(&new_entry->list, &dev->pending_work);
    
    spin_unlock(&dev->spinlock);
    
    // Schedule work for non-critical processing later
    schedule_work(&dev->bottom_half_work);
    
ack_and_return:
    // Clear interrupt condition
    writel(ACK_INTERRUPT, dev->status_reg);
    
    return IRQ_HANDLED;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

// The networking softirqs in Linux
 
// Defined softirq types (include/linux/interrupt.h)
enum {
    HI_SOFTIRQ = 0,      // High-priority tasklets
    TIMER_SOFTIRQ,       // Timer callbacks
    NET_TX_SOFTIRQ,      // Network transmit
    NET_RX_SOFTIRQ,      // Network receive
    BLOCK_SOFTIRQ,       // Block device completion
    IRQ_POLL_SOFTIRQ,    // IRQ polling
    TASKLET_SOFTIRQ,     // Regular tasklets
    SCHED_SOFTIRQ,       // Scheduler balancing
    HRTIMER_SOFTIRQ,     // High-res timer
    RCU_SOFTIRQ,         // RCU callbacks
    NR_SOFTIRQS          // Count
};
 
// Raising (scheduling) a softirq from interrupt handler
irqreturn_t network_irq_handler(int irq, void *dev_id) {
    struct net_device *dev = dev_id;
    
    // Minimal work: grab packet from hardware
    if (dev->hardare_has_packet()) {
        napi_schedule(&dev->napi);  // This eventually raises NET_RX_SOFTIRQ
    }
    
    // Clear interrupt
    dev->ack_interrupt();
    
    return IRQ_HANDLED;
}
 
// Softirq handler runs later with interrupts enabled
void net_rx_softirq_handler(struct softirq_action *h) {
    // Process all pending network receive work
    // Can run for up to 2ms (net.core.netdev_budget_usecs)
    // Then yields to allow other softirqs and processes
    
    while (packets_pending && !budget_exhausted) {
        struct sk_buff *skb = dequeue_packet();
        process_packet(skb);  // Parse headers, checksums, etc.
        deliver_to_socket(skb);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

// Tasklet usage example
 
// Static tasklet declaration
DECLARE_TASKLET(my_tasklet, my_tasklet_function);
 
// Or dynamic allocation
struct tasklet_struct my_dynamic_tasklet;
 
void init_my_tasklet(void) {
    tasklet_init(&my_dynamic_tasklet, 
                 my_tasklet_function, 
                 (unsigned long)my_device_data);
}
 
// Tasklet function - runs in softirq context
void my_tasklet_function(unsigned long data) {
    struct my_device *dev = (struct my_device *)data;
    
    // SAFE: Same tasklet never runs concurrently with itself
    // (still needs locks for data shared with other contexts)
    
    process_device_data(dev);
    update_device_statistics(dev);
    wakeup_waiting_processes(dev);
}
 
// Schedule tasklet from interrupt handler
irqreturn_t my_interrupt_handler(int irq, void *dev_id) {
    // Do minimal essential work
    capture_hardware_state();
    acknowledge_interrupt();
    
    // Schedule tasklet for bulk processing
    tasklet_schedule(&my_tasklet);
    
    return IRQ_HANDLED;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

// Workqueue usage example
 
// Define work structure (often embedded in device struct)
struct my_device {
    struct work_struct deferred_work;
    int device_id;
    // ... other fields ...
};
 
// Work function - runs in process context, CAN SLEEP
void my_work_function(struct work_struct *work) {
    struct my_device *dev = container_of(work, struct my_device, deferred_work);
    
    // These operations are ALLOWED here but NOT in interrupt handlers:
    
    // Allocate memory (may sleep waiting for pages)
    void *buffer = kmalloc(4096, GFP_KERNEL);
    
    // Acquire mutex (may sleep waiting for holder)
    mutex_lock(&dev->mutex);
    
    // Perform file I/O (sleeps for disk)
    write_to_log_file(event_data);
    
    // Sleep deliberately
    msleep(10);  // Delay 10ms
    
    mutex_unlock(&dev->mutex);
    kfree(buffer);
}
 
// Schedule work from interrupt handler
irqreturn_t my_interrupt_handler(int irq, void *dev_id) {
    struct my_device *dev = dev_id;
    
    // Capture time-critical data
    dev->last_event_type = read_hardware_register();
    acknowledge_interrupt();
    
    // Schedule workqueue item for complex processing
    schedule_work(&dev->deferred_work);
    
    return IRQ_HANDLED;
}
 
// Initialize during driver probe
int my_driver_probe(void) {
    INIT_WORK(&my_device->deferred_work, my_work_function);
    return 0;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

// Linux interrupt handler registration
 
/**
 * request_irq - Register an interrupt handler
 * @irq:      The interrupt number
 * @handler:  The handler function
 * @flags:    Flags (sharing, trigger type, etc.)
 * @name:     Device name (for /proc/interrupts)
 * @dev_id:   Private data passed to handler
 *
 * Returns: 0 on success, negative error on failure
 */
int request_irq(unsigned int irq,
                irq_handler_t handler,
                unsigned long flags,
                const char *name,
                void *dev_id);
 
// Example driver using request_irq
int my_device_probe(struct pci_dev *pdev) {
    struct my_device *dev;
    int irq_num;
    int ret;
    
    dev = kzalloc(sizeof(*dev), GFP_KERNEL);
    if (!dev)
        return -ENOMEM;
    
    // Get IRQ number from PCI configuration
    irq_num = pdev->irq;
    
    // Register interrupt handler
    ret = request_irq(irq_num,
                      my_interrupt_handler,
                      IRQF_SHARED,        // Allow sharing with other devices
                      "my_device",         // Name shown in /proc/interrupts
                      dev);                // Passed to handler as dev_id
    
    if (ret) {
        dev_err(&pdev->dev, "Failed to register IRQ %d: %d\n", irq_num, ret);
        kfree(dev);
        return ret;
    }
    
    dev->irq = irq_num;
    pci_set_drvdata(pdev, dev);
    
    return 0;
}
 
// Cleanup - always free IRQ before releasing device memory!
void my_device_remove(struct pci_dev *pdev) {
    struct my_device *dev = pci_get_drvdata(pdev);
    
    // CRITICAL: Free IRQ before freeing device memory
    // Otherwise, an interrupt could reference freed memory
    free_irq(dev->irq, dev);
    
    kfree(dev);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

// Threaded interrupt handler registration
 
/**
 * request_threaded_irq - Register a threaded interrupt handler
 * @irq:           The interrupt number
 * @handler:       Primary handler (runs in hard IRQ context)
 * @thread_fn:     Threaded handler (runs in process context)
 * @flags:         IRQ flags
 * @name:          Device name
 * @dev_id:        Private data
 *
 * The primary handler runs immediately in hard IRQ context.
 * If it returns IRQ_WAKE_THREAD, the thread_fn is woken.
 */
int request_threaded_irq(unsigned int irq,
                         irq_handler_t handler,      // Hard IRQ part
                         irq_handler_t thread_fn,    // Thread part
                         unsigned long flags,
                         const char *name,
                         void *dev_id);
 
// Example: Splitting work between hard and threaded handlers
irqreturn_t my_hard_handler(int irq, void *dev_id) {
    struct my_device *dev = dev_id;
    u32 status = ioread32(dev->status_reg);
    
    // Check if we caused this interrupt
    if (!(status & MY_INTERRUPT_PENDING))
        return IRQ_NONE;
    
    // Acknowledge interrupt (MUST happen quickly)
    iowrite32(MY_ACK, dev->status_reg);
    
    // Store status for threaded handler
    dev->interrupt_status = status;
    
    // Wake the thread for heavy processing
    return IRQ_WAKE_THREAD;
}
 
irqreturn_t my_thread_handler(int irq, void *dev_id) {
    struct my_device *dev = dev_id;
    
    // We're in process context here - can sleep!
    
    // Acquire mutex (would crash in hard IRQ context)
    mutex_lock(&dev->big_mutex);
    
    // Do extensive processing
    if (dev->interrupt_status & DATA_READY) {
        void *buf = kmalloc(dev->data_size, GFP_KERNEL);  // Can sleep
        process_incoming_data(dev, buf);
        kfree(buf);
    }
    
    mutex_unlock(&dev->big_mutex);
    
    return IRQ_HANDLED;
}
 
// Registration
request_threaded_irq(irq_num, 
                     my_hard_handler,
                     my_thread_handler,
                     IRQF_ONESHOT | IRQF_SHARED,  // ONESHOT keeps IRQ masked
                     "my_device",
                     dev);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

// High-performance interrupt handler techniques
 
// Pre-allocated buffer pool - avoid runtime allocation
struct buffer_pool {
    struct buffer *free_list;
    spinlock_t lock;
} ____cacheline_aligned_in_smp;  // Avoid false sharing
 
static DEFINE_PER_CPU(struct buffer_pool, buffer_pools);
 
static inline struct buffer *fast_alloc_buffer(void) {
    struct buffer_pool *pool = this_cpu_ptr(&buffer_pools);
    struct buffer *buf;
    
    // Per-CPU pool avoids cross-CPU contention
    spin_lock(&pool->lock);
    buf = pool->free_list;
    if (buf)
        pool->free_list = buf->next;
    spin_unlock(&pool->lock);
    
    return buf;  // May be NULL - caller handles
}
 
// Batched interrupt processing
irqreturn_t high_perf_handler(int irq, void *dev_id) {
    struct device *dev = dev_id;
    int events_processed = 0;
    u32 status;
    
    // Read status ONCE, not in a loop - I/O is expensive
    status = ioread32(dev->status_reg);
    
    // Process ALL pending events in one invocation
    while (status & EVENTS_PENDING) {
        struct buffer *buf = fast_alloc_buffer();
        if (!buf) {
            // Can't process more - come back later
            dev->stats.alloc_failures++;
            break;
        }
        
        // Copy data from hardware to buffer
        memcpy_fromio(buf->data, dev->data_reg, DATA_SIZE);
        
        // Add to processing queue (lockless enqueue)
        llist_add(&buf->llist, &dev->pending);
        
        events_processed++;
        status = ioread32(dev->status_reg);  // Recheck
    }
    
    // Single acknowledgment for all processed events
    iowrite32(ACK_ALL, dev->status_reg);
    
    // Per-CPU statistics - no locking needed
    this_cpu_add(dev->stats.irq_count, events_processed);
    
    if (events_processed)
        tasklet_schedule(&dev->process_tasklet);
    
    return events_processed ? IRQ_HANDLED : IRQ_NONE;
}