xref: /freebsd/sys/sys/aio.h (revision 7d536dc855c85c15bf45f033d108a61b1f3cecc3)
1 /*-
2  * Copyright (c) 1997 John S. Dyson.  All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  * 1. Redistributions of source code must retain the above copyright
8  *    notice, this list of conditions and the following disclaimer.
9  * 2. John S. Dyson's name may not be used to endorse or promote products
10  *    derived from this software without specific prior written permission.
11  *
12  * DISCLAIMER:  This code isn't warranted to do anything useful.  Anything
13  * bad that happens because of using this software isn't the responsibility
14  * of the author.  This software is distributed AS-IS.
15  *
16  * $FreeBSD$
17  */
18 
19 #ifndef _SYS_AIO_H_
20 #define	_SYS_AIO_H_
21 
22 #include <sys/types.h>
23 #include <sys/signal.h>
24 #ifdef _KERNEL
25 #include <sys/queue.h>
26 #include <sys/event.h>
27 #include <sys/signalvar.h>
28 #endif
29 
30 /*
31  * Returned by aio_cancel:
32  */
33 #define	AIO_CANCELED		0x1
34 #define	AIO_NOTCANCELED		0x2
35 #define	AIO_ALLDONE		0x3
36 
37 /*
38  * LIO opcodes
39  */
40 #define	LIO_NOP			0x0
41 #define LIO_WRITE		0x1
42 #define	LIO_READ		0x2
43 #ifdef _KERNEL
44 #define	LIO_SYNC		0x3
45 #define	LIO_MLOCK		0x4
46 #endif
47 
48 /*
49  * LIO modes
50  */
51 #define	LIO_NOWAIT		0x0
52 #define	LIO_WAIT		0x1
53 
54 /*
55  * Maximum number of allowed LIO operations
56  */
57 #define	AIO_LISTIO_MAX		16
58 
59 #ifdef _KERNEL
60 
61 /* Default values of tunables for the AIO worker pool. */
62 
63 #ifndef MAX_AIO_PROCS
64 #define MAX_AIO_PROCS		32
65 #endif
66 
67 #ifndef TARGET_AIO_PROCS
68 #define TARGET_AIO_PROCS	4
69 #endif
70 
71 #ifndef AIOD_LIFETIME_DEFAULT
72 #define AIOD_LIFETIME_DEFAULT	(30 * hz)
73 #endif
74 
75 #endif
76 
77 /*
78  * Private members for aiocb -- don't access
79  * directly.
80  */
81 struct __aiocb_private {
82 	long	status;
83 	long	error;
84 	void	*kernelinfo;
85 };
86 
87 /*
88  * I/O control block
89  */
90 typedef struct aiocb {
91 	int	aio_fildes;		/* File descriptor */
92 	off_t	aio_offset;		/* File offset for I/O */
93 	volatile void *aio_buf;         /* I/O buffer in process space */
94 	size_t	aio_nbytes;		/* Number of bytes for I/O */
95 	int	__spare__[2];
96 	void	*__spare2__;
97 	int	aio_lio_opcode;		/* LIO opcode */
98 	int	aio_reqprio;		/* Request priority -- ignored */
99 	struct	__aiocb_private	_aiocb_private;
100 	struct	sigevent aio_sigevent;	/* Signal to deliver */
101 } aiocb_t;
102 
103 #ifdef _KERNEL
104 
105 typedef void aio_cancel_fn_t(struct kaiocb *);
106 typedef void aio_handle_fn_t(struct kaiocb *);
107 
108 /*
109  * Kernel version of an I/O control block.
110  *
111  * Locking key:
112  * * - need not protected
113  * a - locked by kaioinfo lock
114  * b - locked by backend lock
115  * c - locked by aio_job_mtx
116  */
117 struct kaiocb {
118 	TAILQ_ENTRY(kaiocb) list;	/* (b) backend-specific list of jobs */
119 	TAILQ_ENTRY(kaiocb) plist;	/* (a) lists of pending / done jobs */
120 	TAILQ_ENTRY(kaiocb) allist;	/* (a) list of all jobs in proc */
121 	int	jobflags;		/* (a) job flags */
122 	int	inputcharge;		/* (*) input blocks */
123 	int	outputcharge;		/* (*) output blocks */
124 	struct	bio *bp;		/* (*) BIO backend BIO pointer */
125 	struct	buf *pbuf;		/* (*) BIO backend buffer pointer */
126 	struct	vm_page *pages[btoc(MAXPHYS)+1]; /* BIO backend pages */
127 	int	npages;			/* BIO backend number of pages */
128 	struct	proc *userproc;		/* (*) user process */
129 	struct	ucred *cred;		/* (*) active credential when created */
130 	struct	file *fd_file;		/* (*) pointer to file structure */
131 	struct	aioliojob *lio;		/* (*) optional lio job */
132 	struct	aiocb *ujob;		/* (*) pointer in userspace of aiocb */
133 	struct	knlist klist;		/* (a) list of knotes */
134 	struct	aiocb uaiocb;		/* (*) copy of user I/O control block */
135 	ksiginfo_t ksi;			/* (a) realtime signal info */
136 	uint64_t seqno;			/* (*) job number */
137 	int	pending;		/* (a) number of pending I/O, aio_fsync only */
138 	aio_cancel_fn_t *cancel_fn;	/* (a) backend cancel function */
139 	aio_handle_fn_t *handle_fn;	/* (c) backend handle function */
140 };
141 
142 struct socket;
143 struct sockbuf;
144 
145 /*
146  * AIO backends should permit cancellation of queued requests waiting to
147  * be serviced by installing a cancel routine while the request is
148  * queued.  The cancellation routine should dequeue the request if
149  * necessary and cancel it.  Care must be used to handle races between
150  * queueing and dequeueing requests and cancellation.
151  *
152  * When queueing a request somewhere such that it can be cancelled, the
153  * caller should:
154  *
155  *  1) Acquire lock that protects the associated queue.
156  *  2) Call aio_set_cancel_function() to install the cancel routine.
157  *  3) If that fails, the request has a pending cancel and should be
158  *     cancelled via aio_cancel().
159  *  4) Queue the request.
160  *
161  * When dequeueing a request to service it or hand it off to somewhere else,
162  * the caller should:
163  *
164  *  1) Acquire the lock that protects the associated queue.
165  *  2) Dequeue the request.
166  *  3) Call aio_clear_cancel_function() to clear the cancel routine.
167  *  4) If that fails, the cancel routine is about to be called.  The
168  *     caller should ignore the request.
169  *
170  * The cancel routine should:
171  *
172  *  1) Acquire the lock that protects the associated queue.
173  *  2) Call aio_cancel_cleared() to determine if the request is already
174  *     dequeued due to a race with dequeueing thread.
175  *  3) If that fails, dequeue the request.
176  *  4) Cancel the request via aio_cancel().
177  */
178 
179 bool	aio_cancel_cleared(struct kaiocb *job);
180 void	aio_cancel(struct kaiocb *job);
181 bool	aio_clear_cancel_function(struct kaiocb *job);
182 void	aio_complete(struct kaiocb *job, long status, int error);
183 void	aio_schedule(struct kaiocb *job, aio_handle_fn_t *func);
184 bool	aio_set_cancel_function(struct kaiocb *job, aio_cancel_fn_t *func);
185 void	aio_switch_vmspace(struct kaiocb *job);
186 
187 #else /* !_KERNEL */
188 
189 struct timespec;
190 
191 __BEGIN_DECLS
192 /*
193  * Asynchronously read from a file
194  */
195 int	aio_read(struct aiocb *);
196 
197 /*
198  * Asynchronously write to file
199  */
200 int	aio_write(struct aiocb *);
201 
202 /*
203  * List I/O Asynchronously/synchronously read/write to/from file
204  *	"lio_mode" specifies whether or not the I/O is synchronous.
205  *	"acb_list" is an array of "nacb_listent" I/O control blocks.
206  *	when all I/Os are complete, the optional signal "sig" is sent.
207  */
208 int	lio_listio(int, struct aiocb * const [], int, struct sigevent *);
209 
210 /*
211  * Get completion status
212  *	returns EINPROGRESS until I/O is complete.
213  *	this routine does not block.
214  */
215 int	aio_error(const struct aiocb *);
216 
217 /*
218  * Finish up I/O, releasing I/O resources and returns the value
219  *	that would have been associated with a synchronous I/O request.
220  *	This routine must be called once and only once for each
221  *	I/O control block who has had I/O associated with it.
222  */
223 ssize_t	aio_return(struct aiocb *);
224 
225 /*
226  * Cancel I/O
227  */
228 int	aio_cancel(int, struct aiocb *);
229 
230 /*
231  * Suspend until all specified I/O or timeout is complete.
232  */
233 int	aio_suspend(const struct aiocb * const[], int, const struct timespec *);
234 
235 /*
236  * Asynchronous mlock
237  */
238 int	aio_mlock(struct aiocb *);
239 
240 #ifdef __BSD_VISIBLE
241 int	aio_waitcomplete(struct aiocb **, struct timespec *);
242 #endif
243 
244 int	aio_fsync(int op, struct aiocb *aiocbp);
245 __END_DECLS
246 
247 #endif /* !_KERNEL */
248 
249 #endif /* !_SYS_AIO_H_ */
250