[PATCH] relay: migrate from relayfs to a generic relay API
[linux-2.6.git] / include / linux / relay.h
1 /*
2  * linux/include/linux/relay.h
3  *
4  * Copyright (C) 2002, 2003 - Tom Zanussi (zanussi@us.ibm.com), IBM Corp
5  * Copyright (C) 1999, 2000, 2001, 2002 - Karim Yaghmour (karim@opersys.com)
6  *
7  * CONFIG_RELAY definitions and declarations
8  */
9
10 #ifndef _LINUX_RELAY_H
11 #define _LINUX_RELAY_H
12
13 #include <linux/config.h>
14 #include <linux/types.h>
15 #include <linux/sched.h>
16 #include <linux/wait.h>
17 #include <linux/list.h>
18 #include <linux/fs.h>
19 #include <linux/poll.h>
20 #include <linux/kref.h>
21
22 /* Needs a _much_ better name... */
23 #define FIX_SIZE(x) ((((x) - 1) & PAGE_MASK) + PAGE_SIZE)
24
25 /*
26  * Tracks changes to rchan/rchan_buf structs
27  */
28 #define RELAYFS_CHANNEL_VERSION         6
29
30 /*
31  * Per-cpu relay channel buffer
32  */
33 struct rchan_buf
34 {
35         void *start;                    /* start of channel buffer */
36         void *data;                     /* start of current sub-buffer */
37         size_t offset;                  /* current offset into sub-buffer */
38         size_t subbufs_produced;        /* count of sub-buffers produced */
39         size_t subbufs_consumed;        /* count of sub-buffers consumed */
40         struct rchan *chan;             /* associated channel */
41         wait_queue_head_t read_wait;    /* reader wait queue */
42         struct work_struct wake_readers; /* reader wake-up work struct */
43         struct dentry *dentry;          /* channel file dentry */
44         struct kref kref;               /* channel buffer refcount */
45         struct page **page_array;       /* array of current buffer pages */
46         unsigned int page_count;        /* number of current buffer pages */
47         unsigned int finalized;         /* buffer has been finalized */
48         size_t *padding;                /* padding counts per sub-buffer */
49         size_t prev_padding;            /* temporary variable */
50         size_t bytes_consumed;          /* bytes consumed in cur read subbuf */
51         unsigned int cpu;               /* this buf's cpu */
52 } ____cacheline_aligned;
53
54 /*
55  * Relay channel data structure
56  */
57 struct rchan
58 {
59         u32 version;                    /* the version of this struct */
60         size_t subbuf_size;             /* sub-buffer size */
61         size_t n_subbufs;               /* number of sub-buffers per buffer */
62         size_t alloc_size;              /* total buffer size allocated */
63         struct rchan_callbacks *cb;     /* client callbacks */
64         struct kref kref;               /* channel refcount */
65         void *private_data;             /* for user-defined data */
66         size_t last_toobig;             /* tried to log event > subbuf size */
67         struct rchan_buf *buf[NR_CPUS]; /* per-cpu channel buffers */
68 };
69
70 /*
71  * Relay channel client callbacks
72  */
73 struct rchan_callbacks
74 {
75         /*
76          * subbuf_start - called on buffer-switch to a new sub-buffer
77          * @buf: the channel buffer containing the new sub-buffer
78          * @subbuf: the start of the new sub-buffer
79          * @prev_subbuf: the start of the previous sub-buffer
80          * @prev_padding: unused space at the end of previous sub-buffer
81          *
82          * The client should return 1 to continue logging, 0 to stop
83          * logging.
84          *
85          * NOTE: subbuf_start will also be invoked when the buffer is
86          *       created, so that the first sub-buffer can be initialized
87          *       if necessary.  In this case, prev_subbuf will be NULL.
88          *
89          * NOTE: the client can reserve bytes at the beginning of the new
90          *       sub-buffer by calling subbuf_start_reserve() in this callback.
91          */
92         int (*subbuf_start) (struct rchan_buf *buf,
93                              void *subbuf,
94                              void *prev_subbuf,
95                              size_t prev_padding);
96
97         /*
98          * buf_mapped - relay buffer mmap notification
99          * @buf: the channel buffer
100          * @filp: relay file pointer
101          *
102          * Called when a relay file is successfully mmapped
103          */
104         void (*buf_mapped)(struct rchan_buf *buf,
105                            struct file *filp);
106
107         /*
108          * buf_unmapped - relay buffer unmap notification
109          * @buf: the channel buffer
110          * @filp: relay file pointer
111          *
112          * Called when a relay file is successfully unmapped
113          */
114         void (*buf_unmapped)(struct rchan_buf *buf,
115                              struct file *filp);
116         /*
117          * create_buf_file - create file to represent a relay channel buffer
118          * @filename: the name of the file to create
119          * @parent: the parent of the file to create
120          * @mode: the mode of the file to create
121          * @buf: the channel buffer
122          * @is_global: outparam - set non-zero if the buffer should be global
123          *
124          * Called during relay_open(), once for each per-cpu buffer,
125          * to allow the client to create a file to be used to
126          * represent the corresponding channel buffer.  If the file is
127          * created outside of relay, the parent must also exist in
128          * that filesystem.
129          *
130          * The callback should return the dentry of the file created
131          * to represent the relay buffer.
132          *
133          * Setting the is_global outparam to a non-zero value will
134          * cause relay_open() to create a single global buffer rather
135          * than the default set of per-cpu buffers.
136          *
137          * See Documentation/filesystems/relayfs.txt for more info.
138          */
139         struct dentry *(*create_buf_file)(const char *filename,
140                                           struct dentry *parent,
141                                           int mode,
142                                           struct rchan_buf *buf,
143                                           int *is_global);
144
145         /*
146          * remove_buf_file - remove file representing a relay channel buffer
147          * @dentry: the dentry of the file to remove
148          *
149          * Called during relay_close(), once for each per-cpu buffer,
150          * to allow the client to remove a file used to represent a
151          * channel buffer.
152          *
153          * The callback should return 0 if successful, negative if not.
154          */
155         int (*remove_buf_file)(struct dentry *dentry);
156 };
157
158 /*
159  * CONFIG_RELAY kernel API, kernel/relay.c
160  */
161
162 struct rchan *relay_open(const char *base_filename,
163                          struct dentry *parent,
164                          size_t subbuf_size,
165                          size_t n_subbufs,
166                          struct rchan_callbacks *cb);
167 extern void relay_close(struct rchan *chan);
168 extern void relay_flush(struct rchan *chan);
169 extern void relay_subbufs_consumed(struct rchan *chan,
170                                    unsigned int cpu,
171                                    size_t consumed);
172 extern void relay_reset(struct rchan *chan);
173 extern int relay_buf_full(struct rchan_buf *buf);
174
175 extern size_t relay_switch_subbuf(struct rchan_buf *buf,
176                                   size_t length);
177
178 /**
179  *      relay_write - write data into the channel
180  *      @chan: relay channel
181  *      @data: data to be written
182  *      @length: number of bytes to write
183  *
184  *      Writes data into the current cpu's channel buffer.
185  *
186  *      Protects the buffer by disabling interrupts.  Use this
187  *      if you might be logging from interrupt context.  Try
188  *      __relay_write() if you know you won't be logging from
189  *      interrupt context.
190  */
191 static inline void relay_write(struct rchan *chan,
192                                const void *data,
193                                size_t length)
194 {
195         unsigned long flags;
196         struct rchan_buf *buf;
197
198         local_irq_save(flags);
199         buf = chan->buf[smp_processor_id()];
200         if (unlikely(buf->offset + length > chan->subbuf_size))
201                 length = relay_switch_subbuf(buf, length);
202         memcpy(buf->data + buf->offset, data, length);
203         buf->offset += length;
204         local_irq_restore(flags);
205 }
206
207 /**
208  *      __relay_write - write data into the channel
209  *      @chan: relay channel
210  *      @data: data to be written
211  *      @length: number of bytes to write
212  *
213  *      Writes data into the current cpu's channel buffer.
214  *
215  *      Protects the buffer by disabling preemption.  Use
216  *      relay_write() if you might be logging from interrupt
217  *      context.
218  */
219 static inline void __relay_write(struct rchan *chan,
220                                  const void *data,
221                                  size_t length)
222 {
223         struct rchan_buf *buf;
224
225         buf = chan->buf[get_cpu()];
226         if (unlikely(buf->offset + length > buf->chan->subbuf_size))
227                 length = relay_switch_subbuf(buf, length);
228         memcpy(buf->data + buf->offset, data, length);
229         buf->offset += length;
230         put_cpu();
231 }
232
233 /**
234  *      relay_reserve - reserve slot in channel buffer
235  *      @chan: relay channel
236  *      @length: number of bytes to reserve
237  *
238  *      Returns pointer to reserved slot, NULL if full.
239  *
240  *      Reserves a slot in the current cpu's channel buffer.
241  *      Does not protect the buffer at all - caller must provide
242  *      appropriate synchronization.
243  */
244 static inline void *relay_reserve(struct rchan *chan, size_t length)
245 {
246         void *reserved;
247         struct rchan_buf *buf = chan->buf[smp_processor_id()];
248
249         if (unlikely(buf->offset + length > buf->chan->subbuf_size)) {
250                 length = relay_switch_subbuf(buf, length);
251                 if (!length)
252                         return NULL;
253         }
254         reserved = buf->data + buf->offset;
255         buf->offset += length;
256
257         return reserved;
258 }
259
260 /**
261  *      subbuf_start_reserve - reserve bytes at the start of a sub-buffer
262  *      @buf: relay channel buffer
263  *      @length: number of bytes to reserve
264  *
265  *      Helper function used to reserve bytes at the beginning of
266  *      a sub-buffer in the subbuf_start() callback.
267  */
268 static inline void subbuf_start_reserve(struct rchan_buf *buf,
269                                         size_t length)
270 {
271         BUG_ON(length >= buf->chan->subbuf_size - 1);
272         buf->offset = length;
273 }
274
275 /*
276  * exported relay file operations, kernel/relay.c
277  */
278 extern struct file_operations relay_file_operations;
279
280 #endif /* _LINUX_RELAY_H */
281