/*
  StarForth — Steady-State Virtual Machine Runtime

  Copyright (c) 2023–2025 Robert A. James
  All rights reserved.

  This file is part of the StarForth project.

  Licensed under the StarForth License, Version 1.0 (the "License");
  you may not use this file except in compliance with the License.

  You may obtain a copy of the License at:
      https://github.com/star.4th@proton.me/StarForth/LICENSE.txt

  This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
  express or implied, including but not limited to the warranties of
  merchantability, fitness for a particular purpose, and noninfringement.

 See the License for the specific language governing permissions and
 limitations under the License.

 StarForth — Steady-State Virtual Machine Runtime
  Copyright (c) 2023–2025 Robert A. James
  All rights reserved.

  This file is part of the StarForth project.

  Licensed under the StarForth License, Version 1.0 (the "License");
  you may not use this file except in compliance with the License.

  You may obtain a copy of the License at:
       https://github.com/star.4th@proton.me/StarForth/LICENSE.txt

  This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
  express or implied, including but not limited to the warranties of
  merchantability, fitness for a particular purpose, and noninfringement.

  See the License for the specific language governing permissions and
  limitations under the License.

 */

/**
 * arena.h - VM arena management for StarKernel builds.
 *
 * Hosted builds never include this header. Kernel integration layers use it
 * to provision the PMM-backed VM arena before handing memory to the VM core.
 */

#ifndef STARKERNEL_VM_ARENA_H
#define STARKERNEL_VM_ARENA_H

#ifdef __STARKERNEL__

#include <stddef.h>
#include <stdint.h>

uint64_t sk_vm_arena_alloc(void);
void     sk_vm_arena_free(void);
uint8_t *sk_vm_arena_ptr(void);
size_t   sk_vm_arena_size(void);
int      sk_vm_arena_is_initialized(void);
void     sk_vm_arena_assert_guards(const char *tag);

/**
 * sk_vm_native_stack_t - one VM's own dedicated native (C) stack.
 *
 * FABRIC-3.md §XXVIII (Stage 1, preemptive-context-switch per-VM native
 * stacks, 2026-09-13). Unlike sk_vm_arena_alloc() -- whose PMM+guard-page
 * path is exercised only for Hera; every baby VM's "arena" is actually a
 * plain kmalloc block, per host_services.c's kernel_alloc() -- every native
 * stack, for every VM without exception, gets its own real, independent
 * pmm_alloc_contiguous() allocation with guard pages. A stack overflow is
 * exactly the failure mode guard pages exist for, and unlike the dictionary
 * arena, a corrupted stack can also corrupt whatever saved context Stage 2
 * later trusts -- worth the extra PMM pages every VM, not just Hera.
 *
 * Caller owns this struct (stored directly on the VM, mirroring how
 * vm->memory already holds its own arena pointer directly rather than going
 * through any module-level registry) and passes it back unchanged to
 * sk_vm_native_stack_free().
 */
typedef struct {
    uint64_t paddr;         /* physical base (for pmm_free_contiguous) */
    uint64_t guard_vaddr;   /* virtual base of the whole guarded region */
    uint64_t stack_top;     /* initial SP value -- stacks grow down on all
                              * 3 arches, so this is guard_vaddr + one guard
                              * page + the full stack size */
} sk_vm_native_stack_t;

int  sk_vm_native_stack_alloc(sk_vm_native_stack_t *out);
void sk_vm_native_stack_free(const sk_vm_native_stack_t *stack);

#endif /* __STARKERNEL__ */

#endif /* STARKERNEL_VM_ARENA_H */