include/linux/shm_signal.h

   1 /*
   2  * Copyright 2009 Novell.  All Rights Reserved.
   3  *
   4  * Author:
   5  *      Gregory Haskins <ghaskins@novell.com>
   6  *
   7  * This file is free software; you can redistribute it and/or modify
   8  * it under the terms of version 2 of the GNU General Public License
   9  * as published by the Free Software Foundation.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software Foundation,
  18  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
  19  */
  20
  21 #ifndef _LINUX_SHM_SIGNAL_H
  22 #define _LINUX_SHM_SIGNAL_H
  23
  24 #include <linux/types.h>
  25
  26 /*
  27  *---------
  28  * The following structures represent data that is shared across boundaries
  29  * which may be quite disparate from one another (e.g. Windows vs Linux,
  30  * 32 vs 64 bit, etc).  Therefore, care has been taken to make sure they
  31  * present data in a manner that is independent of the environment.
  32  *-----------
  33  */
  34
  35 #define SHM_SIGNAL_MAGIC 0x58fa39df
  36 #define SHM_SIGNAL_VER   1
  37
  38 struct shm_signal_irq {
  39         __u8                  enabled;
  40         __u8                  pending;
  41         __u8                  dirty;
  42 };
  43
  44 enum shm_signal_locality {
  45         shm_locality_north,
  46         shm_locality_south,
  47 };
  48
  49 struct shm_signal_desc {
  50         __u32                 magic;
  51         __u32                 ver;
  52         struct shm_signal_irq irq[2];
  53 };
  54
  55 /* --- END SHARED STRUCTURES --- */
  56
  57 #ifdef __KERNEL__
  58
  59 #include <linux/kref.h>
  60 #include <linux/interrupt.h>
  61
  62 struct shm_signal_notifier {
  63         void (*signal)(struct shm_signal_notifier *);
  64 };
  65
  66 struct shm_signal;
  67
  68 struct shm_signal_ops {
  69         int      (*inject)(struct shm_signal *s);
  70         void     (*fault)(struct shm_signal *s, const char *fmt, ...);
  71         void     (*release)(struct shm_signal *s);
  72 };
  73
  74 enum {
  75         shm_signal_in_wakeup,
  76 };
  77
  78 struct shm_signal {
  79         struct kref                 kref;
  80         spinlock_t                  lock;
  81         enum shm_signal_locality    locale;
  82         unsigned long               flags;
  83         struct shm_signal_ops      *ops;
  84         struct shm_signal_desc     *desc;
  85         struct shm_signal_notifier *notifier;
  86         struct tasklet_struct       deferred_notify;
  87 };
  88
  89 #define SHM_SIGNAL_FAULT(s, fmt, args...)  \
  90   ((s)->ops->fault ? (s)->ops->fault((s), fmt, ## args) : panic(fmt, ## args))
  91
  92  /*
  93   * These functions should only be used internally
  94   */
  95 void _shm_signal_release(struct kref *kref);
  96 void _shm_signal_wakeup(struct shm_signal *s);
  97
  98 /**
  99  * shm_signal_init() - initialize an SHM_SIGNAL
 100  * @s:        SHM_SIGNAL context
 101  *
 102  * Initializes SHM_SIGNAL context before first use
 103  *
 104  **/
 105 void shm_signal_init(struct shm_signal *s, enum shm_signal_locality locale,
 106                      struct shm_signal_ops *ops, struct shm_signal_desc *desc);
 107
 108 /**
 109  * shm_signal_get() - acquire an SHM_SIGNAL context reference
 110  * @s:        SHM_SIGNAL context
 111  *
 112  **/
 113 static inline struct shm_signal *shm_signal_get(struct shm_signal *s)
 114 {
 115         kref_get(&s->kref);
 116
 117         return s;
 118 }
 119
 120 /**
 121  * shm_signal_put() - release an SHM_SIGNAL context reference
 122  * @s:        SHM_SIGNAL context
 123  *
 124  **/
 125 static inline void shm_signal_put(struct shm_signal *s)
 126 {
 127         kref_put(&s->kref, _shm_signal_release);
 128 }
 129
 130 /**
 131  * shm_signal_enable() - enables local notifications on an SHM_SIGNAL
 132  * @s:        SHM_SIGNAL context
 133  * @flags:      Reserved for future use, must be 0
 134  *
 135  * Enables/unmasks the registered notifier (if applicable) to receive wakeups
 136  * whenever the remote side performs an shm_signal() operation. A notification
 137  * will be dispatched immediately if any pending signals have already been
 138  * issued prior to invoking this call.
 139  *
 140  * This is synonymous with unmasking an interrupt.
 141  *
 142  * Returns: success = 0, <0 = ERRNO
 143  *
 144  **/
 145 int shm_signal_enable(struct shm_signal *s, int flags);
 146
 147 /**
 148  * shm_signal_disable() - disable local notifications on an SHM_SIGNAL
 149  * @s:        SHM_SIGNAL context
 150  * @flags:      Reserved for future use, must be 0
 151  *
 152  * Disables/masks the registered shm_signal_notifier (if applicable) from
 153  * receiving any further notifications.  Any subsequent calls to shm_signal()
 154  * by the remote side will update the shm as dirty, but will not traverse the
 155  * locale boundary and will not invoke the notifier callback.  Signals
 156  * delivered while masked will be deferred until shm_signal_enable() is
 157  * invoked.
 158  *
 159  * This is synonymous with masking an interrupt
 160  *
 161  * Returns: success = 0, <0 = ERRNO
 162  *
 163  **/
 164 int shm_signal_disable(struct shm_signal *s, int flags);
 165
 166 /**
 167  * shm_signal_inject() - notify the remote side about shm changes
 168  * @s:        SHM_SIGNAL context
 169  * @flags:      Reserved for future use, must be 0
 170  *
 171  * Marks the shm state as "dirty" and, if enabled, will traverse
 172  * a locale boundary to inject a remote notification.  The remote
 173  * side controls whether the notification should be delivered via
 174  * the shm_signal_enable/disable() interface.
 175  *
 176  * The specifics of how to traverse a locale boundary are abstracted
 177  * by the shm_signal_ops->signal() interface and provided by a particular
 178  * implementation.  However, typically going north to south would be
 179  * something like a syscall/hypercall, and going south to north would be
 180  * something like a posix-signal/guest-interrupt.
 181  *
 182  * Returns: success = 0, <0 = ERRNO
 183  *
 184  **/
 185 int shm_signal_inject(struct shm_signal *s, int flags);
 186
 187 #endif /* __KERNEL__ */
 188
 189 #endif /* _LINUX_SHM_SIGNAL_H */