stack_posix.c

Go to the documentation of this file.

/* -*- C -*-
 * Serene programming language
 * Copyright (C) 2019-2026 Sameer Rahmani <lxsameer@lxsameer.com>
 *
 * This library is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library.  If not, see <https://www.gnu.org/licenses/>.
 */
 
#include <stdint.h>
 
#include "serene/rt/configuration.h"
#include "serene/rt/fiber.h"
#include "serene/rt/mm/interface.h"
#include "serene/utils.h"
 
// POSIX stack backend, mmap-based allocation with a guard page. On a target without mmap (Windows)
// this file compiles to nothing and a sibling backend should supply srn_fiber_stack_alloc/free
// instead. The selection is by target macro, so the whole runtime source set can be handed to a
// cross compiler and only the matching backend emits symbols.
#if defined(__unix__) || defined(__APPLE__)
 
#  include <sys/mman.h>
 
#  ifdef __APPLE__
#    define STACK_FLAGS MAP_PRIVATE | MAP_ANONYMOUS
#  else
#    define STACK_FLAGS MAP_PRIVATE | MAP_ANONYMOUS | MAP_NORESERVE | MAP_STACK
#  endif
 
// TODO(lxsameer): move from fixed stacks to growable stacks once a precise GC
// and stack maps exist. A growable stack sizes itself to the live call depth
// and grows on demand, which removes both the overflow gap and the worst case
// reservation each fiber pays now. Growing a running stack means relocating
// it, which needs a stack map to find and rewrite every live pointer, so it
// depends on the GC landing first.
 
// NOLINTBEGIN(hicpp-sign*, performance-no-int*)
srn_fiber_stack_t srn_fiber_stack_alloc(size_t size, size_t guard_pages) {
  const size_t os_page_size = srn_mm_get_os_page_size();
 
  // The guard band catches most stack overflows but not all of them. A stack
  // overflows one page at a time when it grows through ordinary calls, or when
  // the compiler probes each page (-fstack-clash-protection, which the runtime
  // builds with). Either way the growing stack steps onto the band and faults.
  // The gap is a single function whose frame is larger than the whole band and
  // was built without page probing. Such a frame can jump past the band in one
  // move and write into the next mapping without faulting. A wider band makes
  // that jump less likely, but only page probing in the offending code can rule
  // it out, and foreign code is not always built that way.
  const size_t guard_size   = guard_pages * os_page_size;
  const size_t desired_size = size ? size : SRN_CONFIG_DEFAULT_FIBER_STACK_SIZE;
 
  // Reject sizes the page rounding below would wrap. A wrapped size would
  // silently grant a tiny stack instead of failing.
  PANIC_IF(
    desired_size > SIZE_MAX - guard_size - os_page_size, "Requested fiber stack size is too large"
  );
 
  // Round upto a multiple of PAGE size
  const size_t usable = (desired_size + os_page_size - 1) & ~(os_page_size - 1);
  // Add the guard band below the usable region
  const size_t total = usable + guard_size;
 
  // Since stack grows downward, the starting point where mmap returns will be the end of the stack
  // for us. We could of used MAP_GROWSDOWN to change the behaviour, but that causes the stack to
  // grow, but we have a fix stack.
  void *end = mmap(
    nullptr, total, PROT_READ | PROT_WRITE, STACK_FLAGS,
    // according to the man page, for anonymous mode fd should be -1
    -1,
    // according to the man page, for anonymous mode offset should be 0
    0
  );
 
  PANIC_IF(end == MAP_FAILED, "Failed to allocate the stack for the fiber subsystem");
 
  if (mprotect(end, guard_size, PROT_NONE) == -1) {
    munmap(end, total);
    PANIC("Failed to allocate the guard band for the fiber subsystem");
  }
 
  const uintptr_t start = (uintptr_t)end + (uintptr_t)total;
  const uintptr_t limit = (uintptr_t)end + (uintptr_t)guard_size;
 
  srn_fiber_stack_t stack = {.start = (void *)start, .limit = (void *)limit, .guard = end};
  return stack;
}
 
void srn_fiber_stack_free(srn_fiber_stack_t stack) {
  munmap(stack.guard, (uintptr_t)stack.start - (uintptr_t)stack.guard);
}
// NOLINTEND(hicpp-sign*, performance-no-int*)
 
#endif // POSIX stack backend