drivers/staging/gasket/gasket_interrupt.h

   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