Merge tag 'for_upstream' of git://git.kernel.org/pub/scm/virt/kvm/mst/qemu into staging
[qemu.git] / linux-user / safe-syscall.h
1 /*
2 * safe-syscall.h: prototypes for linux-user signal-race-safe syscalls
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, see <http://www.gnu.org/licenses/>.
16 */
17
18 #ifndef LINUX_USER_SAFE_SYSCALL_H
19 #define LINUX_USER_SAFE_SYSCALL_H
20
21 /**
22 * safe_syscall:
23 * @int number: number of system call to make
24 * ...: arguments to the system call
25 *
26 * Call a system call if guest signal not pending.
27 * This has the same API as the libc syscall() function, except that it
28 * may return -1 with errno == TARGET_ERESTARTSYS if a signal was pending.
29 *
30 * Returns: the system call result, or -1 with an error code in errno
31 * (Errnos are host errnos; we rely on TARGET_ERESTARTSYS not clashing
32 * with any of the host errno values.)
33 */
34
35 /*
36 * A guide to using safe_syscall() to handle interactions between guest
37 * syscalls and guest signals:
38 *
39 * Guest syscalls come in two flavours:
40 *
41 * (1) Non-interruptible syscalls
42 *
43 * These are guest syscalls that never get interrupted by signals and
44 * so never return EINTR. They can be implemented straightforwardly in
45 * QEMU: just make sure that if the implementation code has to make any
46 * blocking calls that those calls are retried if they return EINTR.
47 * It's also OK to implement these with safe_syscall, though it will be
48 * a little less efficient if a signal is delivered at the 'wrong' moment.
49 *
50 * Some non-interruptible syscalls need to be handled using block_signals()
51 * to block signals for the duration of the syscall. This mainly applies
52 * to code which needs to modify the data structures used by the
53 * host_signal_handler() function and the functions it calls, including
54 * all syscalls which change the thread's signal mask.
55 *
56 * (2) Interruptible syscalls
57 *
58 * These are guest syscalls that can be interrupted by signals and
59 * for which we need to either return EINTR or arrange for the guest
60 * syscall to be restarted. This category includes both syscalls which
61 * always restart (and in the kernel return -ERESTARTNOINTR), ones
62 * which only restart if there is no handler (kernel returns -ERESTARTNOHAND
63 * or -ERESTART_RESTARTBLOCK), and the most common kind which restart
64 * if the handler was registered with SA_RESTART (kernel returns
65 * -ERESTARTSYS). System calls which are only interruptible in some
66 * situations (like 'open') also need to be handled this way.
67 *
68 * Here it is important that the host syscall is made
69 * via this safe_syscall() function, and *not* via the host libc.
70 * If the host libc is used then the implementation will appear to work
71 * most of the time, but there will be a race condition where a
72 * signal could arrive just before we make the host syscall inside libc,
73 * and then then guest syscall will not correctly be interrupted.
74 * Instead the implementation of the guest syscall can use the safe_syscall
75 * function but otherwise just return the result or errno in the usual
76 * way; the main loop code will take care of restarting the syscall
77 * if appropriate.
78 *
79 * (If the implementation needs to make multiple host syscalls this is
80 * OK; any which might really block must be via safe_syscall(); for those
81 * which are only technically blocking (ie which we know in practice won't
82 * stay in the host kernel indefinitely) it's OK to use libc if necessary.
83 * You must be able to cope with backing out correctly if some safe_syscall
84 * you make in the implementation returns either -TARGET_ERESTARTSYS or
85 * EINTR though.)
86 *
87 * block_signals() cannot be used for interruptible syscalls.
88 *
89 *
90 * How and why the safe_syscall implementation works:
91 *
92 * The basic setup is that we make the host syscall via a known
93 * section of host native assembly. If a signal occurs, our signal
94 * handler checks the interrupted host PC against the addresse of that
95 * known section. If the PC is before or at the address of the syscall
96 * instruction then we change the PC to point at a "return
97 * -TARGET_ERESTARTSYS" code path instead, and then exit the signal handler
98 * (causing the safe_syscall() call to immediately return that value).
99 * Then in the main.c loop if we see this magic return value we adjust
100 * the guest PC to wind it back to before the system call, and invoke
101 * the guest signal handler as usual.
102 *
103 * This winding-back will happen in two cases:
104 * (1) signal came in just before we took the host syscall (a race);
105 * in this case we'll take the guest signal and have another go
106 * at the syscall afterwards, and this is indistinguishable for the
107 * guest from the timing having been different such that the guest
108 * signal really did win the race
109 * (2) signal came in while the host syscall was blocking, and the
110 * host kernel decided the syscall should be restarted;
111 * in this case we want to restart the guest syscall also, and so
112 * rewinding is the right thing. (Note that "restart" semantics mean
113 * "first call the signal handler, then reattempt the syscall".)
114 * The other situation to consider is when a signal came in while the
115 * host syscall was blocking, and the host kernel decided that the syscall
116 * should not be restarted; in this case QEMU's host signal handler will
117 * be invoked with the PC pointing just after the syscall instruction,
118 * with registers indicating an EINTR return; the special code in the
119 * handler will not kick in, and we will return EINTR to the guest as
120 * we should.
121 *
122 * Notice that we can leave the host kernel to make the decision for
123 * us about whether to do a restart of the syscall or not; we do not
124 * need to check SA_RESTART flags in QEMU or distinguish the various
125 * kinds of restartability.
126 */
127 #ifdef HAVE_SAFE_SYSCALL
128 /* The core part of this function is implemented in assembly */
129 extern long safe_syscall_base(int *pending, long number, ...);
130 /* These are defined by the safe-syscall.inc.S file */
131 extern char safe_syscall_start[];
132 extern char safe_syscall_end[];
133
134 #define safe_syscall(...) \
135 ({ \
136 long ret_; \
137 int *psp_ = &((TaskState *)thread_cpu->opaque)->signal_pending; \
138 ret_ = safe_syscall_base(psp_, __VA_ARGS__); \
139 if (is_error(ret_)) { \
140 errno = -ret_; \
141 ret_ = -1; \
142 } \
143 ret_; \
144 })
145
146 #else
147
148 /*
149 * Fallback for architectures which don't yet provide a safe-syscall assembly
150 * fragment; note that this is racy!
151 * This should go away when all host architectures have been updated.
152 */
153 #define safe_syscall syscall
154
155 #endif
156
157 #endif