Thu Nov 23 21:27:08 2023 UTC ()

stack(7): Clarify thread stack guard vs program stack guard.

Just in case this confuses anyone dealing with PR pkg/57708.

XXX pullup-10


(riastradh)

diff -r1.1 -r1.2 src/share/man/man7/stack.7

--- src/share/man/man7/stack.7 2023/11/23 21:20:49	1.1
+++ src/share/man/man7/stack.7 2023/11/23 21:27:08	1.2

 @@ -1,275 +1,280 @@
-.\"	$NetBSD: stack.7,v 1.1 2023/11/23 21:20:49 riastradh Exp $
+.\"	$NetBSD: stack.7,v 1.2 2023/11/23 21:27:08 riastradh Exp $
 .\"
 .\" Copyright (c) 2023 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
 .\" 1. Redistributions of source code must retain the above copyright
 .\"    notice, this list of conditions and the following disclaimer.
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
 .\"
 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
 .Dd November 23, 2023
 .Dt STACK 7
 .Os
 .Sh NAME
 .Nm stack
 .Nd layout of program execution stack memory
 .Sh DESCRIPTION
 When executing a program, with the
 .Xr execve 2
 or
 .Xr posix_spawn 3
 families of system calls,
 .Nx
 reserves a region in the new program image's virtual address space for
 the
 .Em stack ,
 which stores return addresses and local variables for nested procedure
 calls in program execution.
 Similarly, threads created with
 .Xr pthread_create 3
 have regions allocated for per-thread stacks.
 .Pp
 The stack grows from the
 .Em base ,
 where information of the outermost procedure call is stored, fixed at
 program start, to the
 .Em stack pointer ,
+a
 .Tn CPU
 register that points to information used by the current procedure call,
 varying during execution as procedures are called.
 .Pp
 On most architectures, the stack base is at higher-numbered virtual
 addresses and the stack pointer is at lower-numbered virtual addresses
 \(em on these architectures,
 .Em the stack grows down .
 On some other architectures, notably
 .Tn HP PA-RISC
 .Pq Sq hppa ,
 the stack base is at lower-numbered virtual addresses and the stack
 pointer is at higher-numbered virtual addresses, so on those
 architectures
 .Em the stack grows up .
 .Pp
 In the kernel, the C preprocessor macro
 .Dv __HAVE_MACHINE_STACK_GROWS_UP
 is defined in
 .In machine/types.h
 on architectures where the stack grows up.
 .Ss Main thread
 For single-threaded programs, and for the main thread of multi-threaded
 programs,
 .Nx
 reserves virtual addresses as follows on architectures where the stack
 grows down:
 .Bd -literal
 +--------------------+ USRSTACK
 | stack gap          |
 +--------------------+ stack base
 | accessible stack   |
 | .                  |
 | .                  | <-- stack pointer (varies during execution)
 | .                  |
 +--------------------+ (stack base) - (soft stack rlimit)
 | inaccessible stack |
 +--------------------+ (stack base) - (hard stack rlimit)
 | guard/redzone      |
 +--------------------+ USRSTACK - MAXSSIZ
 .Ed
 .Pp
 On architectures where the stack grows up, the layout is:
 .Bd -literal
 +--------------------+ USRSTACK + MAXSSIZ
 | guard/redzone      |
 +--------------------+ (stack base) + (hard stack rlimit)
 | inaccessible pages |
 +--------------------+ (stack base) + (soft stack rlimit)
 | .                  |
 | .                  | <-- stack pointer (varies during execution)
 | .                  |
 | accessible pages   |
 +--------------------+ stack base
 | stack gap          |
 +--------------------+ USRSTACK
 .Ed
 .Bl -bullet
 .It
 The
 .Em stack guard
 is allocated so that any access \(em read, write, or execute \(em will
 deliver
 .Dv SIGSEGV
 to the process.
 This serves to detect stack overflow and crash rather than silently
 overwrite other memory in the program's virtual address space.
 The size of the stack guard is tuned by the
 .Li vm.guard_size
 .Xr sysctl 7
 knob.
 .Pp
 The stack guard is also sometimes known as the
 .Sq redzone
 or
 .Sq red zone ,
 although the term
 .Sq red zone
 is also sometimes used to mean a fixed space
 .Em above
 the stack pointer (in the direction of stack growth) that the system
 guarantees will it will not overwrite when calling a signal handler in
 the
 .Tn ABI
 of some architectures; see also
 .Xr sigaltstack 2
 to specify an alternate stack base for the kernel to use when invoking
 signal handlers on signal delivery.
 .It
 The
 .Em inaccessible pages
 of the stack region are allocated so that any access will also deliver
 .Dv SIGSEGV
 to the process, but they can be made accessible by changing the soft
 stack rlimit with
 .Xr setrlimit 2 .
 .It
 The
 .Em accessible pages
 of the stack region are allocated with read/write access permitted, and
 are used to store the actual data in the program stack.
 .It
 When
 .Tn PaX ASLR ,
 address space layout randomization, is enabled, the
 .Em stack gap
 is an
 .Em unallocated
 space of a size chosen unpredictably at random at program startup time.
 When
 .Tn PaX ASLR
 is disabled, the stack gap is empty.
 .El
 .Pp
 All of the boundaries \(em
 .Dv USRSTACK ,
 the stack base, and the boundaries between the accessible,
 inaccessible, and guard pages \(em are page-aligned, or rounded to be
 page-aligned even if the rlimits are not themselves page-aligned,
 rounding so that the sizes of the regions do not exceed the rlimits.
 .Pp
 The stack base is exposed to programs via the
 .Dv AT_STACKBASE
 .Xr elf 5
 auxiliary info vector entry.
 .Pp
 The per-architecture constants
 .Dv USRSTACK
 and
 .Dv MAXSSIZ
 are defined in
 .In machine/vmparam.h .
 .Ss Non-main threads
 Threads created with
 .Xr pthread_create 3
 have stacks allocated at dynamically chosen addresses, and cannot be
 resized after creation.
 On architectures where the stack grows down, the layout is:
 .Bd -literal
 +--------------------+ stackaddr
 | .                  |
 | .                  | <-- stack pointer (varies during execution)
 | .                  |
 | stack              |
 +--------------------+ stackaddr - stacksize
 | guard/redzone      |
 +--------------------+ stackaddr - stacksize - guardsize
 .Ed
 .Pp
 On architectures where the stack grows up, the layout is:
 .Bd -literal
 +--------------------+ stackaddr + stacksize + guardsize
 | guard/redzone      |
 +--------------------+ stackaddr + stacksize
 | .                  |
 | .                  | <-- stack pointer (varies during execution)
 | .                  |
 | stack              |
 +--------------------+ stackaddr
 .Ed
 .Pp
 The parameters stackaddr, stacksize, and guardsize can be obtained from
 an existing thread using
 .Xr pthread_getattr_np 3 ,
 .Xr pthread_attr_getguardsize 3 ,
 and the
 .Xr pthread_attr_getstack 3
 family of functions.
 .Pp
 When creating a thread, the stack can be manually allocated and the
 parameters can be set using
 .Xr pthread_attr_setguardsize 3
 and the
 .Xr pthread_attr_setstack 3
 family of functions.
 However, the stack parameters cannot be changed after thread creation.
 The default guard size is tuned by the
 .Li vm.thread_guard_size
 .Xr sysctl 7
 knob.
 .Pp
 For the main thread,
 .Xr pthread_getattr_np 3
 returns a
 .Em snapshot
 of the parameters as they existed at program startup, so that stackaddr
 and stacksize reflect the current accessible pages of the stack, and
 guardsize is the value of the
 .Li vm.guard_size
 .Xr sysctl 7
 knob at the time of program startup.
 (Note that this means the
 .Xr pthread 3
 view of the main thread's stack guard may not coincide with the actual
 stack guard \(em it may overlap with, or lie entirely in, the
 inaccessible pages of the stack reserved on program start.)
 However, if the program changes its soft stack rlimit with
 .Xr setrlimit 2 ,
 this snapshot may become stale.
 .Sh SEE ALSO
 .Xr execve 2 ,
 .Xr mmap 2 ,
 .Xr mprotect 2 ,
 .Xr sigaltstack 2 ,
 .Xr ucontext 2 ,
 .Xr posix_spawn 3 ,
 .Xr pthread 3 ,
 .Xr security 7 ,
 .Xr sysctl 7 ,
 .Xr paxctl 8
 .Sh BUGS
 .Tn PaX ASLR
 doesn't actually guarantee an accessible stack reservation of length
 equal to the soft stack rlimit \(em owing to a bug (XXX which PR
 number?),
 .Nx
 may sometimes reserve less space than the soft rlimit, in which case
 the accessible pages of the stack cannot be extended.
 .Pp
 There is a race between the kernel's access of
 .Li vm.guard_size
 at exec time, and userland's access of
 .Li vm.guard_size
 in
 .Xr pthread 3
 initialization.