1/*-
2 * SPDX-License-Identifier: BSD-2-Clause
3 *
4 * Copyright (c) 1997, Stefan Esser <se@freebsd.org>
5 * All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 * 1. Redistributions of source code must retain the above copyright
11 *    notice unmodified, this list of conditions, and the following
12 *    disclaimer.
13 * 2. Redistributions in binary form must reproduce the above copyright
14 *    notice, this list of conditions and the following disclaimer in the
15 *    documentation and/or other materials provided with the distribution.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29#ifndef _SYS_INTERRUPT_H_
30#define _SYS_INTERRUPT_H_
31
32#include <sys/_lock.h>
33#include <sys/_mutex.h>
34#include <sys/ck.h>
35
36struct intr_event;
37struct intr_thread;
38struct trapframe;
39
40/*
41 * Describe a hardware interrupt handler.
42 *
43 * Multiple interrupt handlers for a specific event can be chained
44 * together.
45 */
46struct intr_handler {
47	driver_filter_t	*ih_filter;	/* Filter handler function. */
48	driver_intr_t	*ih_handler;	/* Threaded handler function. */
49	void		*ih_argument;	/* Argument to pass to handlers. */
50	int		 ih_flags;
51	char		 ih_name[MAXCOMLEN + 1]; /* Name of handler. */
52	struct intr_event *ih_event;	/* Event we are connected to. */
53	int		 ih_need;	/* Needs service. */
54	CK_SLIST_ENTRY(intr_handler) ih_next; /* Next handler for this event. */
55	u_char		 ih_pri;	/* Priority of this handler. */
56};
57
58/* Interrupt handle flags kept in ih_flags */
59#define	IH_NET		0x00000001	/* Network. */
60#define	IH_EXCLUSIVE	0x00000002	/* Exclusive interrupt. */
61#define	IH_ENTROPY	0x00000004	/* Device is a good entropy source. */
62#define	IH_DEAD		0x00000008	/* Handler should be removed. */
63#define	IH_SUSP		0x00000010	/* Device is powered down. */
64#define	IH_CHANGED	0x40000000	/* Handler state is changed. */
65#define	IH_MPSAFE	0x80000000	/* Handler does not need Giant. */
66
67/*
68 * Describe an interrupt event.  An event holds a list of handlers.
69 * The 'pre_ithread', 'post_ithread', 'post_filter', and 'assign_cpu'
70 * hooks are used to invoke MD code for certain operations.
71 *
72 * The 'pre_ithread' hook is called when an interrupt thread for
73 * handlers without filters is scheduled.  It is responsible for
74 * ensuring that 1) the system won't be swamped with an interrupt
75 * storm from the associated source while the ithread runs and 2) the
76 * current CPU is able to receive interrupts from other interrupt
77 * sources.  The first is usually accomplished by disabling
78 * level-triggered interrupts until the ithread completes.  The second
79 * is accomplished on some platforms by acknowledging the interrupt
80 * via an EOI.
81 *
82 * The 'post_ithread' hook is invoked when an ithread finishes.  It is
83 * responsible for ensuring that the associated interrupt source will
84 * trigger an interrupt when it is asserted in the future.  Usually
85 * this is implemented by enabling a level-triggered interrupt that
86 * was previously disabled via the 'pre_ithread' hook.
87 *
88 * The 'post_filter' hook is invoked when a filter handles an
89 * interrupt.  It is responsible for ensuring that the current CPU is
90 * able to receive interrupts again.  On some platforms this is done
91 * by acknowledging the interrupts via an EOI.
92 *
93 * The 'assign_cpu' hook is used to bind an interrupt source to a
94 * specific CPU.  If the interrupt cannot be bound, this function may
95 * return an error.
96 *
97 * Note that device drivers may also use interrupt events to manage
98 * multiplexing interrupt interrupt handler into handlers for child
99 * devices.  In that case, the above hooks are not used.  The device
100 * can create an event for its interrupt resource and register child
101 * event handlers with that event.  It can then use
102 * intr_event_execute_handlers() to execute non-filter handlers.
103 * Currently filter handlers are not supported by this, but that can
104 * be added by splitting out the filter loop from intr_event_handle()
105 * if desired.
106 */
107struct intr_event {
108	TAILQ_ENTRY(intr_event) ie_list;
109	CK_SLIST_HEAD(, intr_handler) ie_handlers; /* Interrupt handlers. */
110	char		ie_name[MAXCOMLEN + 1]; /* Individual event name. */
111	char		ie_fullname[MAXCOMLEN + 1];
112	struct mtx	ie_lock;
113	void		*ie_source;	/* Cookie used by MD code. */
114	struct intr_thread *ie_thread;	/* Thread we are connected to. */
115	void		(*ie_pre_ithread)(void *);
116	void		(*ie_post_ithread)(void *);
117	void		(*ie_post_filter)(void *);
118	int		(*ie_assign_cpu)(void *, int);
119	int		ie_flags;
120	int		ie_hflags;	/* Cumulative flags of all handlers. */
121	int		ie_count;	/* Loop counter. */
122	int		ie_warncnt;	/* Rate-check interrupt storm warns. */
123	struct timeval	ie_warntm;
124	u_int		ie_irq;		/* Physical irq number if !SOFT. */
125	int		ie_cpu;		/* CPU this event is bound to. */
126	volatile int	ie_phase;	/* Switched to establish a barrier. */
127	volatile int	ie_active[2];	/* Filters in ISR context. */
128};
129
130/* Interrupt event flags kept in ie_flags. */
131#define	IE_SOFT		0x000001	/* Software interrupt. */
132#define	IE_ADDING_THREAD 0x000004	/* Currently building an ithread. */
133
134/* Flags to pass to swi_sched. */
135#define	SWI_FROMNMI	0x1
136#define	SWI_DELAY	0x2
137
138/*
139 * Software interrupt numbers.  Historically this was used to determine
140 * the relative priority of SWI ithreads.
141 */
142#define	SWI_TTY		0
143#define	SWI_NET		1
144#define	SWI_CAMBIO	2
145#define	SWI_BUSDMA	3
146#define	SWI_CLOCK	4
147#define	SWI_TQ_FAST	5
148#define	SWI_TQ		6
149#define	SWI_TQ_GIANT	6
150
151/* Maximum number of stray interrupts to log */
152#define	INTR_STRAY_LOG_MAX	5
153
154struct proc;
155
156extern struct	intr_event *clk_intr_event;
157
158/* Counts and names for statistics (defined in MD code). */
159extern u_long 	*intrcnt;	/* counts for each device and stray */
160extern char 	*intrnames;	/* string table containing device names */
161extern size_t	sintrcnt;	/* size of intrcnt table */
162extern size_t	sintrnames;	/* size of intrnames table */
163
164#ifdef DDB
165void	db_dump_intr_event(struct intr_event *ie, int handlers);
166#endif
167u_char	intr_priority(enum intr_type flags);
168int	intr_event_add_handler(struct intr_event *ie, const char *name,
169	    driver_filter_t filter, driver_intr_t handler, void *arg,
170	    u_char pri, enum intr_type flags, void **cookiep);
171int	intr_event_bind(struct intr_event *ie, int cpu);
172int	intr_event_bind_irqonly(struct intr_event *ie, int cpu);
173int	intr_event_bind_ithread(struct intr_event *ie, int cpu);
174struct _cpuset;
175int	intr_event_bind_ithread_cpuset(struct intr_event *ie,
176	    struct _cpuset *mask);
177int	intr_event_create(struct intr_event **event, void *source,
178	    int flags, u_int irq, void (*pre_ithread)(void *),
179	    void (*post_ithread)(void *), void (*post_filter)(void *),
180	    int (*assign_cpu)(void *, int), const char *fmt, ...)
181	    __printflike(9, 10);
182int	intr_event_describe_handler(struct intr_event *ie, void *cookie,
183	    const char *descr);
184int	intr_event_destroy(struct intr_event *ie);
185int	intr_event_handle(struct intr_event *ie, struct trapframe *frame);
186int	intr_event_remove_handler(void *cookie);
187int	intr_event_suspend_handler(void *cookie);
188int	intr_event_resume_handler(void *cookie);
189int	intr_getaffinity(int irq, int mode, void *mask);
190void	*intr_handler_source(void *cookie);
191int	intr_setaffinity(int irq, int mode, const void *mask);
192void	_intr_drain(int irq);  /* LinuxKPI only. */
193int	swi_add(struct intr_event **eventp, const char *name,
194	    driver_intr_t handler, void *arg, int pri, enum intr_type flags,
195	    void **cookiep);
196void	swi_sched(void *cookie, int flags);
197int	swi_remove(void *cookie);
198
199#endif
200