[src/trunk]: src/lib/libc/sys Add more notes explaining how debuggers work on...

[kamil <kamil%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/54cff2b7f995
branches:  trunk
changeset: 350177:54cff2b7f995
user:      kamil <kamil%NetBSD.org@localhost>
date:      Sat Jan 07 05:51:14 2017 +0000

description:
Add more notes explaining how debuggers work on NetBSD

Explain:
 - execve(2) handling and behavior, SIGTRAP & TRAP_EXEC
 - reference PaX MPROTECT restrictions for debuggers
 - software breakpoints handling and behavior, SIGTRAP & TRAP_BKPT
 - single step behavior, SIGTRAP & TRAP_TRACE
 - list predefined MI symbols for help debuggers in port specific headers
 - explain that PT_TRACE_ME does not send a SIGSTOP signal

Sponsored by <The NetBSD Foundation>

diffstat:

 lib/libc/sys/ptrace.2 |  106 ++++++++++++++++++++++++++++++++++++++++++-------
 1 files changed, 90 insertions(+), 16 deletions(-)

diffs (149 lines):

diff -r 5b5bfc6b2fa3 -r 54cff2b7f995 lib/libc/sys/ptrace.2
--- a/lib/libc/sys/ptrace.2     Sat Jan 07 04:44:12 2017 +0000
+++ b/lib/libc/sys/ptrace.2     Sat Jan 07 05:51:14 2017 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: ptrace.2,v 1.49 2017/01/07 03:41:25 kamil Exp $
+.\"    $NetBSD: ptrace.2,v 1.50 2017/01/07 05:51:14 kamil Exp $
 .\"
 .\" This file is in the public domain.
 .Dd January 7, 2016
@@ -43,12 +43,86 @@
 .Fn ptrace
 is the mechanism by which all this happens.
 .Pp
+When a process that is traced by a debugger request and calls
+.Xr execve 2
+or any of the routines built on it
+.Po
+such as
+.Xr execv 3
+.Pc ,
+it will stop before executing the first instruction of the new image and emit
+.Dv SIGRAP
+with
+.Dv si_code
+set to
+.Dv TRAP_EXEC .
+If a program is traced with the
+.Dv PT_SYSCALL
+option enabled,
+this event notifier is disabled.
+If a traced program calls
+.Xr execve 2
+any setuid or setgid bits on the executable being executed will be ignored.
+.Pp
+Program (software) breakpoints are reported with
+.Dv SIGTRAP
+and the
+.Dv si_code
+value set to
+.Dv TRAP_BKPT .
+These breakpoints are machine specific instructions that interrput the process.
+In order to put a trap by a tracer into the tracee's program,
+debugger must violate the
+.Dv PaX MPROTECT
+restrictions.
+For details check the
+.Dv security.pax.mprotect.ptrace
+option described in
+.Xr sysctl 7 .
+When a tracee is interrputed by a trap,
+the trap is not removed by the kernel and it must be handled by a debugger.
+.Pp
+If a program is traced with single steps
+.Dv ( PT_STEP )
+it reports each step with
+.Dv SIGTRAP
+with
+.Dv si_code
+set to
+.Dv TRAP_TRACE .
+.Pp
+A debugger might reuse a port specific symbols,
+to help writing portable code as described in the port specific part of the
+.In sys/ptrace.h
+header.
+Among these symbols,
+there are:
+.Bl -dash -tag
+.It
+.Dv PTRACE_REG_PC
+.It
+.Dv PTRACE_REG_SET_PC
+.It
+.Dv PTRACE_REG_SP
+.It
+.Dv PTRACE_REG_INTRV
+.It
+.Dv PTRACE_BREAKPOINT
+.It
+.Dv PTRACE_BREAKPOINT_SIZE
+.It
+.Dv PTRACE_BREAKPOINT_ADJ
+.El
+.Pp
 The
 .Fa request
-argument specifies what operation is being performed; the meaning of
+argument
+of
+.Nm
+specifies what operation is being performed; the meaning of
 the rest of the arguments depends on the operation, but except for one
 special case noted below, all
-.Fn ptrace
+.Nm
 calls are made by the tracing process, and the
 .Fa pid
 argument specifies the process ID of the traced process.
@@ -59,20 +133,14 @@
 This request is the only one used by the traced process; it declares
 that the process expects to be traced by its parent.
 All the other arguments are ignored.
-(If the parent process does not expect to trace
+If the parent process does not expect to trace
 the child, it will probably be rather confused by the results; once the
 traced process stops, it cannot be made to continue except via
-.Fn ptrace . )
-When a process has used this request and calls
-.Xr execve 2
-or any of the routines built on it
-.Po
-such as
-.Xr execv 3
-.Pc ,
-it will stop before executing the first instruction of the new image.
-Also, any setuid or setgid bits on the executable being executed will
-be ignored.
+.Fn ptrace .
+.Pp
+This call does not stop the process neither emit
+.Dv SIGSTOP
+to parent.
 .It Dv PT_READ_I , Dv PT_READ_D
 These requests read a single
 .Li int
@@ -138,8 +206,14 @@
 not be executing a setuid or setgid executable.
 (If the tracing process is running as root,
 these restrictions do not apply.)
+.Pp
 The tracing process will see the newly-traced process stop and may then
 control it as if it had been traced all along.
+It means that the
+.Dv SIGSTOP
+signal is emitted to tracer.
+It is different behavior to the one from
+.Dv PT_TRACE_ME .
 .Pp
 Three other restrictions apply to all tracing processes, even those
 running as root.
@@ -360,7 +434,7 @@
 .Li sizeof(struct ptrace_siginfo) .
 .Pp
 In order to pass faked signal to the tracee,
-the siginal type must match the signal passed to process with
+the signal type must match the signal passed to process with
 .Dv PT_CONTINUE ,
 .Dv PT_DETACH
 or