1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3  * Gasket common interrupt module. Defines functions for enabling
4  * eventfd-triggered interrupts between a Gasket device and a host process.
5  *
6  * Copyright (C) 2018 Google, Inc.
7  */
8 #ifndef __GASKET_INTERRUPT_H__
9 #define __GASKET_INTERRUPT_H__
10 
11 #include <linux/eventfd.h>
12 #include <linux/pci.h>
13 
14 #include "gasket_core.h"
15 
16 /* Note that this currently assumes that device interrupts are a dense set,
17  * numbered from 0 - (num_interrupts - 1). Should this have to change, these
18  * APIs will have to be updated.
19  */
20 
21 /* Opaque type used to hold interrupt subsystem data. */
22 struct gasket_interrupt_data;
23 
24 /*
25  * Initialize the interrupt module.
26  * @gasket_dev: The Gasket device structure for the device to be initted.
27  * @type: Type of the interrupt. (See gasket_interrupt_type).
28  * @name: The name to associate with these interrupts.
29  * @interrupts: An array of all interrupt descriptions for this device.
30  * @num_interrupts: The length of the @interrupts array.
31  * @pack_width: The width, in bits, of a single field in a packed interrupt reg.
32  * @bar_index: The bar containing all interrupt registers.
33  *
34  * Allocates and initializes data to track interrupt state for a device.
35  * After this call, no interrupts will be configured/delivered; call
36  * gasket_interrupt_set_vector[_packed] to associate each interrupt with an
37  * __iomem location, then gasket_interrupt_set_eventfd to associate an eventfd
38  * with an interrupt.
39  *
40  * If num_interrupts interrupts are not available, this call will return a
41  * negative error code. In that case, gasket_interrupt_cleanup should still be
42  * called. Returns 0 on success (which can include a device where interrupts
43  * are not possible to set up, but is otherwise OK; that device will report
44  * status LAMED.)
45  */
46 int gasket_interrupt_init(struct gasket_dev *gasket_dev, const char *name,
47 			  int type,
48 			  const struct gasket_interrupt_desc *interrupts,
49 			  int num_interrupts, int pack_width, int bar_index,
50 			  const struct gasket_wire_interrupt_offsets *wire_int_offsets);
51 
52 /*
53  * Clean up a device's interrupt structure.
54  * @gasket_dev: The Gasket information structure for this device.
55  *
56  * Cleans up the device's interrupts and deallocates data.
57  */
58 void gasket_interrupt_cleanup(struct gasket_dev *gasket_dev);
59 
60 /*
61  * Clean up and re-initialize the MSI-x subsystem.
62  * @gasket_dev: The Gasket information structure for this device.
63  *
64  * Performs a teardown of the MSI-x subsystem and re-initializes it. Does not
65  * free the underlying data structures. Returns 0 on success and an error code
66  * on error.
67  */
68 int gasket_interrupt_reinit(struct gasket_dev *gasket_dev);
69 
70 /*
71  * Reset the counts stored in the interrupt subsystem.
72  * @gasket_dev: The Gasket information structure for this device.
73  *
74  * Sets the counts of all interrupts in the subsystem to 0.
75  */
76 int gasket_interrupt_reset_counts(struct gasket_dev *gasket_dev);
77 
78 /*
79  * Associates an eventfd with a device interrupt.
80  * @data: Pointer to device interrupt data.
81  * @interrupt: The device interrupt to configure.
82  * @event_fd: The eventfd to associate with the interrupt.
83  *
84  * Prepares the host to receive notification of device interrupts by associating
85  * event_fd with interrupt. Upon receipt of a device interrupt, event_fd will be
86  * signaled, after successful configuration.
87  *
88  * Returns 0 on success, a negative error code otherwise.
89  */
90 int gasket_interrupt_set_eventfd(struct gasket_interrupt_data *interrupt_data,
91 				 int interrupt, int event_fd);
92 
93 /*
94  * Removes an interrupt-eventfd association.
95  * @data: Pointer to device interrupt data.
96  * @interrupt: The device interrupt to de-associate.
97  *
98  * Removes any eventfd associated with the specified interrupt, if any.
99  */
100 int gasket_interrupt_clear_eventfd(struct gasket_interrupt_data *interrupt_data,
101 				   int interrupt);
102 
103 /*
104  * The below functions exist for backwards compatibility.
105  * No new uses should be written.
106  */
107 /*
108  * Get the health of the interrupt subsystem.
109  * @gasket_dev: The Gasket device struct.
110  *
111  * Returns DEAD if not set up, LAMED if initialization failed, and ALIVE
112  * otherwise.
113  */
114 
115 int gasket_interrupt_system_status(struct gasket_dev *gasket_dev);
116 
117 #endif
118