/*
  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.
*/

/**
 * smp.h - The core table and secondary-core bring-up (FABRIC-3.10.8 MC-1).
 *
 * Core ids are dense and logical: core 0 is the boot core, whatever its
 * hardware id; the others are numbered in enumeration order. The hardware
 * id lives in the core's block (sk_percpu_t.hw_id) and never in a lock's
 * owner word.
 *
 * MC-1: a secondary core comes up, reports, and parks -- interrupts masked,
 * halted, every wake counted. It does no console, log or heap work.
 */
#ifndef STARKERNEL_SMP_H
#define STARKERNEL_SMP_H

#include <stdint.h>
#include "starkernel/percpu.h"
#include "uefi.h" /* BootInfo */

/* Enumerate the cores, bring each secondary up in turn and wait (bounded)
 * for it to park. Boot core only, interrupts off; after the heartbeat
 * init. Prints one line per core. */
void sk_smp_init(BootInfo *boot_info);

uint32_t     sk_smp_core_count(void);
sk_percpu_t *sk_smp_core(uint32_t core_id);

/* The idle point: logs a parked core's wake count when it has changed.
 * Call with no lock held. */
void sk_smp_report(void);

/* Where every secondary core's entry path lands, with its per-CPU register
 * already set to `pc`. Never returns. */
void sk_smp_secondary_main(sk_percpu_t *pc) __attribute__((noreturn));

/* ---- per ISA (arch/<isa>/smp.c) ---------------------------------------- */

/* The cores this machine has, boot core included: fills hw_ids[0..cap) in
 * enumeration order and returns the total (call with cap 0 to count). */
uint32_t arch_smp_enumerate(BootInfo *boot_info, uint64_t *hw_ids, uint32_t cap);

/* The boot core's own hardware id. */
uint64_t arch_smp_boot_hw_id(void);

/* Start the core `pc` describes on `stack_top`; returns 0 once the start
 * sequence was issued (arrival is observed through pc->online). */
int arch_smp_start(BootInfo *boot_info, sk_percpu_t *pc, void *stack_top);

/* One park step: interrupts stay masked; returns when the core wakes. */
void arch_smp_park_once(void);

/* Once `pc` is online: what the ISA can say about how it arrived (the
 * exception level, the privilege mode), as a short phrase for its line. */
const char *arch_smp_arrival(const sk_percpu_t *pc);

#endif /* STARKERNEL_SMP_H */