[PATCH 3/3] Documentation: add a caveat for seccomp filter and vsyscall emulation

[Will Drewry <wad@chromium.org>]

With the addition of seccomp support to vsyscall emulation:
  http://permalink.gmane.org/gmane.linux.kernel/1327732
and the prior patch in this series.

Update the documentation to indicate quirky behaviors when the 'ip' is
in the vsyscall page and vsyscall emulation is in effect.

Signed-off-by: Will Drewry <wad@chromium.org>
---
 Documentation/prctl/seccomp_filter.txt |   22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/Documentation/prctl/seccomp_filter.txt b/Documentation/prctl/seccomp_filter.txt
index 597c3c5..67ed88b 100644
--- a/Documentation/prctl/seccomp_filter.txt
+++ b/Documentation/prctl/seccomp_filter.txt
@@ -161,3 +161,25 @@ architecture supports both ptrace_event and seccomp, it will be able to
 support seccomp filter with minor fixup: SIGSYS support and seccomp return
 value checking.  Then it must just add CONFIG_HAVE_ARCH_SECCOMP_FILTER
 to its arch-specific Kconfig.
+
+
+Caveats
+-------
+
+On x86-64 with vsyscall emulation enabled and while servicing a
+vsyscall-emulated system call:
+- A return value of SECCOMP_RET_TRAP will set a si_call_addr pointing to
+  the vsyscall entry for the given call and not the address after the
+  'syscall' instruction.  Any code which wants to restart the call
+  should return to that address and code wishing to return simulating
+  completion may either sigreturn normally or simulate a ret instruction
+  and use the return address from the stack.
+- A return value of SECCOMP_RET_TRACE will signal the tracer as usual,
+  but the syscall may not be changed to another system call using the
+  orig_rax register. It may only be changed to a different value in
+  order to skip the currently emulated call and any change will result
+  in that behavior.  The remainder of the registers may be altered as
+  usual.
+- Detection of this quirky behavior may be done by checking for getcpu,
+  time, or gettimeofday and if the si_call_addr or rip is in the
+  vsyscall page, specifically at the start of the specific entry call.
-- 
1.7.9.5