pipe_fs_i.h

  1/* SPDX-License-Identifier: GPL-2.0 */
  2#ifndef _LINUX_PIPE_FS_I_H
  3#define _LINUX_PIPE_FS_I_H
  4
  5#define PIPE_DEF_BUFFERS	16
  6
  7#define PIPE_BUF_FLAG_LRU	0x01	/* page is on the LRU */
  8#define PIPE_BUF_FLAG_ATOMIC	0x02	/* was atomically mapped */
  9#define PIPE_BUF_FLAG_GIFT	0x04	/* page is a gift */
 10#define PIPE_BUF_FLAG_PACKET	0x08	/* read() as a packet */
 11#define PIPE_BUF_FLAG_CAN_MERGE	0x10	/* can merge buffers */
 12#define PIPE_BUF_FLAG_WHOLE	0x20	/* read() must return entire buffer or error */
 13#ifdef CONFIG_WATCH_QUEUE
 14#define PIPE_BUF_FLAG_LOSS	0x40	/* Message loss happened after this buffer */
 15#endif
 16
 17/**
 18 *	struct pipe_buffer - a linux kernel pipe buffer
 19 *	@page: the page containing the data for the pipe buffer
 20 *	@offset: offset of data inside the @page
 21 *	@len: length of data inside the @page
 22 *	@ops: operations associated with this buffer. See @pipe_buf_operations.
 23 *	@flags: pipe buffer flags. See above.
 24 *	@private: private data owned by the ops.
 25 **/
 26struct pipe_buffer {
 27	struct page *page;
 28	unsigned int offset, len;
 29	const struct pipe_buf_operations *ops;
 30	unsigned int flags;
 31	unsigned long private;
 32};
 33
 34/*
 35 * Really only alpha needs 32-bit fields, but
 36 * might as well do it for 64-bit architectures
 37 * since that's what we've historically done,
 38 * and it makes 'head_tail' always be a simple
 39 * 'unsigned long'.
 40 */
 41#ifdef CONFIG_64BIT
 42typedef unsigned int pipe_index_t;
 43#else
 44typedef unsigned short pipe_index_t;
 45#endif
 46
 47/**
 48 *	struct pipe_index - pipe indeces
 49 *	@head: The point of buffer production
 50 *	@tail: The point of buffer consumption
 51 *	@head_tail: unsigned long union of @head and @tail
 52 */
 53union pipe_index {
 54	unsigned long head_tail;
 55	struct {
 56		pipe_index_t head;
 57		pipe_index_t tail;
 58	};
 59};
 60
 61/**
 62 *	struct pipe_inode_info - a linux kernel pipe
 63 *	@mutex: mutex protecting the whole thing
 64 *	@rd_wait: reader wait point in case of empty pipe
 65 *	@wr_wait: writer wait point in case of full pipe
 66 *	@pipe_index: the pipe indeces
 67 *	@note_loss: The next read() should insert a data-lost message
 68 *	@max_usage: The maximum number of slots that may be used in the ring
 69 *	@ring_size: total number of buffers (should be a power of 2)
 70 *	@nr_accounted: The amount this pipe accounts for in user->pipe_bufs
 71 *	@tmp_page: cached released page
 72 *	@readers: number of current readers of this pipe
 73 *	@writers: number of current writers of this pipe
 74 *	@files: number of struct file referring this pipe (protected by ->i_lock)
 75 *	@r_counter: reader counter
 76 *	@w_counter: writer counter
 77 *	@poll_usage: is this pipe used for epoll, which has crazy wakeups?
 78 *	@fasync_readers: reader side fasync
 79 *	@fasync_writers: writer side fasync
 80 *	@bufs: the circular array of pipe buffers
 81 *	@user: the user who created this pipe
 82 *	@watch_queue: If this pipe is a watch_queue, this is the stuff for that
 83 **/
 84struct pipe_inode_info {
 85	struct mutex mutex;
 86	wait_queue_head_t rd_wait, wr_wait;
 87
 88	union pipe_index;
 89
 90	unsigned int max_usage;
 91	unsigned int ring_size;
 92	unsigned int nr_accounted;
 93	unsigned int readers;
 94	unsigned int writers;
 95	unsigned int files;
 96	unsigned int r_counter;
 97	unsigned int w_counter;
 98	bool poll_usage;
 99#ifdef CONFIG_WATCH_QUEUE
100	bool note_loss;
101#endif
102	struct page *tmp_page[2];
103	struct fasync_struct *fasync_readers;
104	struct fasync_struct *fasync_writers;
105	struct pipe_buffer *bufs;
106	struct user_struct *user;
107#ifdef CONFIG_WATCH_QUEUE
108	struct watch_queue *watch_queue;
109#endif
110};
111
112/*
113 * Note on the nesting of these functions:
114 *
115 * ->confirm()
116 *	->try_steal()
117 *
118 * That is, ->try_steal() must be called on a confirmed buffer.  See below for
119 * the meaning of each operation.  Also see the kerneldoc in fs/pipe.c for the
120 * pipe and generic variants of these hooks.
121 */
122struct pipe_buf_operations {
123	/*
124	 * ->confirm() verifies that the data in the pipe buffer is there
125	 * and that the contents are good. If the pages in the pipe belong
126	 * to a file system, we may need to wait for IO completion in this
127	 * hook. Returns 0 for good, or a negative error value in case of
128	 * error.  If not present all pages are considered good.
129	 */
130	int (*confirm)(struct pipe_inode_info *, struct pipe_buffer *);
131
132	/*
133	 * When the contents of this pipe buffer has been completely
134	 * consumed by a reader, ->release() is called.
135	 */
136	void (*release)(struct pipe_inode_info *, struct pipe_buffer *);
137
138	/*
139	 * Attempt to take ownership of the pipe buffer and its contents.
140	 * ->try_steal() returns %true for success, in which case the contents
141	 * of the pipe (the buf->page) is locked and now completely owned by the
142	 * caller. The page may then be transferred to a different mapping, the
143	 * most often used case is insertion into different file address space
144	 * cache.
145	 */
146	bool (*try_steal)(struct pipe_inode_info *, struct pipe_buffer *);
147
148	/*
149	 * Get a reference to the pipe buffer.
150	 */
151	bool (*get)(struct pipe_inode_info *, struct pipe_buffer *);
152};
153
154/**
155 * pipe_has_watch_queue - Check whether the pipe is a watch_queue,
156 * i.e. it was created with O_NOTIFICATION_PIPE
157 * @pipe: The pipe to check
158 *
159 * Return: true if pipe is a watch queue, false otherwise.
160 */
161static inline bool pipe_has_watch_queue(const struct pipe_inode_info *pipe)
162{
163#ifdef CONFIG_WATCH_QUEUE
164	return pipe->watch_queue != NULL;
165#else
166	return false;
167#endif
168}
169
170/**
171 * pipe_occupancy - Return number of slots used in the pipe
172 * @head: The pipe ring head pointer
173 * @tail: The pipe ring tail pointer
174 */
175static inline unsigned int pipe_occupancy(unsigned int head, unsigned int tail)
176{
177	return (pipe_index_t)(head - tail);
178}
179
180/**
181 * pipe_empty - Return true if the pipe is empty
182 * @head: The pipe ring head pointer
183 * @tail: The pipe ring tail pointer
184 */
185static inline bool pipe_empty(unsigned int head, unsigned int tail)
186{
187	return !pipe_occupancy(head, tail);
188}
189
190/**
191 * pipe_full - Return true if the pipe is full
192 * @head: The pipe ring head pointer
193 * @tail: The pipe ring tail pointer
194 * @limit: The maximum amount of slots available.
195 */
196static inline bool pipe_full(unsigned int head, unsigned int tail,
197			     unsigned int limit)
198{
199	return pipe_occupancy(head, tail) >= limit;
200}
201
202/**
203 * pipe_is_full - Return true if the pipe is full
204 * @pipe: the pipe
205 */
206static inline bool pipe_is_full(const struct pipe_inode_info *pipe)
207{
208	return pipe_full(pipe->head, pipe->tail, pipe->max_usage);
209}
210
211/**
212 * pipe_is_empty - Return true if the pipe is empty
213 * @pipe: the pipe
214 */
215static inline bool pipe_is_empty(const struct pipe_inode_info *pipe)
216{
217	return pipe_empty(pipe->head, pipe->tail);
218}
219
220/**
221 * pipe_buf_usage - Return how many pipe buffers are in use
222 * @pipe: the pipe
223 */
224static inline unsigned int pipe_buf_usage(const struct pipe_inode_info *pipe)
225{
226	return pipe_occupancy(pipe->head, pipe->tail);
227}
228
229/**
230 * pipe_buf - Return the pipe buffer for the specified slot in the pipe ring
231 * @pipe: The pipe to access
232 * @slot: The slot of interest
233 */
234static inline struct pipe_buffer *pipe_buf(const struct pipe_inode_info *pipe,
235					   unsigned int slot)
236{
237	return &pipe->bufs[slot & (pipe->ring_size - 1)];
238}
239
240/**
241 * pipe_head_buf - Return the pipe buffer at the head of the pipe ring
242 * @pipe: The pipe to access
243 */
244static inline struct pipe_buffer *pipe_head_buf(const struct pipe_inode_info *pipe)
245{
246	return pipe_buf(pipe, pipe->head);
247}
248
249/**
250 * pipe_buf_get - get a reference to a pipe_buffer
251 * @pipe:	the pipe that the buffer belongs to
252 * @buf:	the buffer to get a reference to
253 *
254 * Return: %true if the reference was successfully obtained.
255 */
256static inline __must_check bool pipe_buf_get(struct pipe_inode_info *pipe,
257				struct pipe_buffer *buf)
258{
259	return buf->ops->get(pipe, buf);
260}
261
262/**
263 * pipe_buf_release - put a reference to a pipe_buffer
264 * @pipe:	the pipe that the buffer belongs to
265 * @buf:	the buffer to put a reference to
266 */
267static inline void pipe_buf_release(struct pipe_inode_info *pipe,
268				    struct pipe_buffer *buf)
269{
270	const struct pipe_buf_operations *ops = buf->ops;
271
272	buf->ops = NULL;
273	ops->release(pipe, buf);
274}
275
276/**
277 * pipe_buf_confirm - verify contents of the pipe buffer
278 * @pipe:	the pipe that the buffer belongs to
279 * @buf:	the buffer to confirm
280 */
281static inline int pipe_buf_confirm(struct pipe_inode_info *pipe,
282				   struct pipe_buffer *buf)
283{
284	if (!buf->ops->confirm)
285		return 0;
286	return buf->ops->confirm(pipe, buf);
287}
288
289/**
290 * pipe_buf_try_steal - attempt to take ownership of a pipe_buffer
291 * @pipe:	the pipe that the buffer belongs to
292 * @buf:	the buffer to attempt to steal
293 */
294static inline bool pipe_buf_try_steal(struct pipe_inode_info *pipe,
295		struct pipe_buffer *buf)
296{
297	if (!buf->ops->try_steal)
298		return false;
299	return buf->ops->try_steal(pipe, buf);
300}
301
302/* Differs from PIPE_BUF in that PIPE_SIZE is the length of the actual
303   memory allocation, whereas PIPE_BUF makes atomicity guarantees.  */
304#define PIPE_SIZE		PAGE_SIZE
305
306/* Pipe lock and unlock operations */
307void pipe_lock(struct pipe_inode_info *);
308void pipe_unlock(struct pipe_inode_info *);
309void pipe_double_lock(struct pipe_inode_info *, struct pipe_inode_info *);
310
311/* Wait for a pipe to be readable/writable while dropping the pipe lock */
312void pipe_wait_readable(struct pipe_inode_info *);
313void pipe_wait_writable(struct pipe_inode_info *);
314
315struct pipe_inode_info *alloc_pipe_info(void);
316void free_pipe_info(struct pipe_inode_info *);
317
318/* Generic pipe buffer ops functions */
319bool generic_pipe_buf_get(struct pipe_inode_info *, struct pipe_buffer *);
320bool generic_pipe_buf_try_steal(struct pipe_inode_info *, struct pipe_buffer *);
321void generic_pipe_buf_release(struct pipe_inode_info *, struct pipe_buffer *);
322
323extern const struct pipe_buf_operations nosteal_pipe_buf_ops;
324
325unsigned long account_pipe_buffers(struct user_struct *user,
326				   unsigned long old, unsigned long new);
327bool too_many_pipe_buffers_soft(unsigned long user_bufs);
328bool too_many_pipe_buffers_hard(unsigned long user_bufs);
329bool pipe_is_unprivileged_user(void);
330
331/* for F_SETPIPE_SZ and F_GETPIPE_SZ */
332int pipe_resize_ring(struct pipe_inode_info *pipe, unsigned int nr_slots);
333long pipe_fcntl(struct file *, unsigned int, unsigned int arg);
334struct pipe_inode_info *get_pipe_info(struct file *file, bool for_splice);
335
336int create_pipe_files(struct file **, int);
337unsigned int round_pipe_size(unsigned int size);
338
339#endif