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