ll_platform_generic.h

// Copyright 2026 by Frobenius Norm LLC 2026-05-16
// Free for non-commercial use. Commercial use requires a license.
#ifndef LL_PLATFORM_GENERIC_H
#define LL_PLATFORM_GENERIC_H
 
#include <stdio.h>
#include <stdint.h>
#include <stdarg.h>
#include <setjmp.h>
#include <type_traits>
#include <new>
#include "assert.h"
#include "unistd.h"
 
// Default all LL_ feature flags to 0 so they can be used as C++ values, not just #if guards.
#ifndef LL_ESP_ARDUINO
#define LL_ESP_ARDUINO       0
#endif
 
#ifndef LL_ARDUINO
#define LL_ARDUINO  0
#endif
 
#ifndef LL_POSIX
#define LL_POSIX         0
#endif

#ifndef LL_WASM
#define LL_WASM          0
#endif
#ifndef LL_WASI
#define LL_WASI          0
#endif
#ifndef LL_EMSCRIPTEN
#define LL_EMSCRIPTEN    0
#endif

#ifndef LL_WINDOWS
#define LL_WINDOWS       0
#endif
#ifndef LL_WIFI
#define LL_WIFI          0
#endif
#ifndef LL_LITTLEFS
#define LL_LITTLEFS      0
#endif
 
#ifndef LL_GCCHK_VISITED_GROWBY
  #if LL_ESP32
    #define LL_GCCHK_VISITED_GROWBY  4096
    #define LL_GCCHK_STACK_INIT      256
    #define LL_GCCHK_STACK_GROWBY    8
    #define LL_GCCHK_STACK_CAP       8192
    #define LL_GCCHK_VECSTACK_INIT   64
    #define LL_GCCHK_VECSTACK_GROWBY 8
    #define LL_GCCHK_VECSTACK_CAP    1024
  #else
    #define LL_GCCHK_VISITED_GROWBY  (-1)
    #define LL_GCCHK_STACK_INIT      256
    #define LL_GCCHK_STACK_GROWBY    256
    #define LL_GCCHK_STACK_CAP       (1<<20)
    #define LL_GCCHK_VECSTACK_INIT   64
    #define LL_GCCHK_VECSTACK_GROWBY 64
    #define LL_GCCHK_VECSTACK_CAP    (1<<16)
  #endif
#endif
 
#ifndef LL_EVAL_STACK_BUDGET
  #if LL_WASM
  #define LL_EVAL_STACK_BUDGET  (3UL * 1024 * 1024)   
  #elif LL_POSIX
  #define LL_EVAL_STACK_BUDGET  (6UL * 1024 * 1024)   
  #else
  #define LL_EVAL_STACK_BUDGET  (40UL * 1024)         
  #endif
#endif

#ifndef LL_EVAL_STACK_BUDGET_MIN
#define LL_EVAL_STACK_BUDGET_MIN  (16UL * 1024)
#endif

#ifndef LL_XTENSA
#define LL_XTENSA                         0
#endif
#ifndef LL_RISCV32
#define LL_RISCV32                        0
#endif

#ifndef LL_NCG_DIRAM_POOL
  #if LL_ESP32 && LL_XTENSA
    #define LL_NCG_DIRAM_POOL 1
  #else
    #define LL_NCG_DIRAM_POOL 0
  #endif
#endif
 
#ifndef LL_NCG_RISCV_POOL
  #if LL_RISCV32 && ((defined(LL_C5_PMP_RWX) && LL_C5_PMP_RWX) || \
                     (defined(LL_C5_NCG_ARENA) && LL_C5_NCG_ARENA))
    #define LL_NCG_RISCV_POOL 1
  #else
    #define LL_NCG_RISCV_POOL 0
  #endif
#endif

#ifndef LL_NCG_EXEC_FLOOR_DEFAULT
  #define LL_NCG_EXEC_FLOOR_DEFAULT 24576
#endif
 
#ifndef LL_NCG_PSRAM_EXEC
  #if defined(BOARD_HAS_PSRAM) && (LL_ESP32S3 || LL_RISCV32)
    #define LL_NCG_PSRAM_EXEC 1
  #else
    #define LL_NCG_PSRAM_EXEC 0
  #endif
#endif

#ifndef LL_EXTRAM_SEPARATE_IBUS
  #if LL_ESP32 && LL_XTENSA
    #define LL_EXTRAM_SEPARATE_IBUS 1
  #else
    #define LL_EXTRAM_SEPARATE_IBUS 0
  #endif
#endif

#ifndef LL_NCG_PSRAM_ALIAS
  #if LL_NCG_PSRAM_EXEC && LL_ESP32S3
    #define LL_NCG_PSRAM_ALIAS 1
  #else
    #define LL_NCG_PSRAM_ALIAS 0
  #endif
#endif

#ifndef LL_WIFI_RESERVE_BYTES
  #define LL_WIFI_RESERVE_BYTES  (48UL * 1024)
#endif

#ifndef LL_GC_BUDGET_WHEN_MAXED
#define LL_GC_BUDGET_WHEN_MAXED 0
#endif
 
#ifndef LL_NCG_EXEC_POOL_BYTES
  #if LL_NCG_RISCV_POOL
    #define LL_NCG_EXEC_POOL_BYTES  (32UL * 1024)
  #elif LL_ESP32S3
    #define LL_NCG_EXEC_POOL_BYTES  (32UL * 1024)
  #elif LL_ESP32
    #define LL_NCG_EXEC_POOL_BYTES  (32UL * 1024)
  #else
    #define LL_NCG_EXEC_POOL_BYTES  (32UL * 1024)
  #endif
#endif
    
#ifndef LL_ROOTSTACK_MAX
  #if LL_WASM
  #define LL_ROOTSTACK_MAX  131072
  #elif LL_POSIX
  #define LL_ROOTSTACK_MAX  262144
  #else
  #define LL_ROOTSTACK_MAX  65536
  #endif
#endif
    
#ifndef LL_ROOTSTACK_SLACK
#define LL_ROOTSTACK_SLACK  256

#ifndef LL_ROOTSTACK_INIT
  #define LL_ROOTSTACK_INIT  256
#endif
#ifndef LL_MARKSTACK_INIT
  #define LL_MARKSTACK_INIT  256
#endif
#endif
  
#ifndef LL_EVAL_ROOT_DEPTH_MAX
#define LL_EVAL_ROOT_DEPTH_MAX  (LL_ROOTSTACK_MAX - 536)
#endif


#ifndef LL_ROOT_HIGH_WATER
  #if LL_POSIX
  #define LL_ROOT_HIGH_WATER  1
  #else
  #define LL_ROOT_HIGH_WATER  0
  #endif
#endif

#ifndef LL_ROOT_BALANCE
  #if LL_POSIX
  #define LL_ROOT_BALANCE  1
  #else
  #define LL_ROOT_BALANCE  0
  #endif
#endif
#ifndef LL_HAVE_BACKTRACE
  #if defined(__GLIBC__) && !LL_ESP32
  #define LL_HAVE_BACKTRACE 1
  #else
  #define LL_HAVE_BACKTRACE 0
  #endif
#endif
 
#ifndef LL_I2C
#define LL_I2C           0
#endif
#ifndef LL_COMMONIO
#define LL_COMMONIO      0
#endif
#ifndef LL_ESP32
#define LL_ESP32         0
#endif
#ifndef LL_COMPLEX
#define LL_COMPLEX       0
#endif
#ifndef LL_RATIONAL
#define LL_RATIONAL      0
#endif
#ifndef LL_BIGNUM
#define LL_BIGNUM        0
#endif
#ifndef LL_BIGNUM_LIMB_BITS
#define LL_BIGNUM_LIMB_BITS 32
#endif
#ifndef LL_BIGNUM_STRICT_RT
#define LL_BIGNUM_STRICT_RT 0
#endif
  
#ifndef LL_MODBUS
#define LL_MODBUS        0
#endif
#ifndef LL_PROFIBUS
#define LL_PROFIBUS      0
#endif
#ifndef LL_PROFINET
#define LL_PROFINET      0
#endif
#ifndef LL_CUDA
#define LL_CUDA          0
#endif
#ifndef LL_HIP
#define LL_HIP           0
#endif
 
// Board-specific flags (set by platformio.ini build_flags per env)
#ifndef LL_ESP32_S3_DEVKIT_C
#define LL_ESP32_S3_DEVKIT_C              0
#endif
#ifndef LL_ESP32S3_N8R2
#define LL_ESP32S3_N8R2                   0
#endif
#ifndef LL_Freenove_4WD_Car_Kit_ESP32
#define LL_Freenove_4WD_Car_Kit_ESP32     0
#endif
#ifndef LL_Freenove_ESP32_WROVER
#define LL_Freenove_ESP32_WROVER          0
#endif
#ifndef LL_ESP32_N4R4
#define LL_ESP32_N4R4                     0
#endif
#ifndef LL_AMD64
#define LL_AMD64                          0
#endif
#ifndef LL_X86_64
#define LL_X86_64                         0
#endif
#ifndef LL_AARCH64
#define LL_AARCH64                        0
#endif
#ifndef LL_ARM64
#define LL_ARM64                          0
#endif
#ifndef LL_WASM32
#define LL_WASM32                         0
#endif

#ifndef LL_NETWORK
  #if LL_WASM
  #define LL_NETWORK  0 
  #else
  #define LL_NETWORK  ((LL_WIFI) || (LL_POSIX))
  #endif
#endif
#define LL_POSIX_NET  ((LL_POSIX) && (LL_NETWORK))
 
#ifndef LL_TERMIOS
  #if LL_WASM
  #define LL_TERMIOS  0 
  #else
  #define LL_TERMIOS  (LL_POSIX)
  #endif
#endif

#ifndef LL_NCG
  #if LL_WASM
  #define LL_NCG  0
  #else
  #define LL_NCG  1
  #endif
#endif

#ifndef LL_AUTOCOMPILE
  #define LL_AUTOCOMPILE  1
#endif
 

#ifndef LL_XTENSA
#define LL_XTENSA        0                
#endif
#ifndef LL_RISCV32
#define LL_RISCV32       0                
#endif
 

#if LL_ESP_ARDUINO
#include "Arduino.h"
#endif

#if LL_ARDUINO
#include <string.h>
 
unsigned long millis();
unsigned long micros();
void delay_ms(unsigned long ms);
 
static void delay(unsigned long ms) { delay_ms(ms); }

#ifndef HIGH
#define HIGH          1
#define LOW           0
#endif
#ifndef INPUT
#define INPUT         0x0
#define OUTPUT        0x1
#define INPUT_PULLUP  0x2
#endif
 
void pinMode(int pin, int mode);
void digitalWrite(int pin, int val);
int  digitalRead(int pin);
void analogWrite(int pin, int val);
int  analogRead(int pin);
void tone(int pin, unsigned int freq);
void tone(int pin, unsigned int freq, unsigned long dur);
void noTone(int pin);
void delayMicroseconds(unsigned long us);

int         ll_llarduino_pin_mode(int pin);
int         ll_llarduino_pin_duty(int pin);
int         ll_llarduino_pin_tone(int pin);
int         ll_llarduino_npins();
const char *ll_llarduino_backend();
 
typedef uint8_t byte;

class LL_String {
public:
 
  LL_String()                           { _init();  set("");  }
  LL_String(const char *other)          { _init();  set(other);  }
  LL_String(const char *other, int n)   { _init();  set(other, n);  }
  LL_String(const LL_String &other)     { _init();  set(other.ptr, other.len);  }
 
  ~LL_String()  { if (ptr) { delete[] ptr;  ptr = 0; }  len = cap = 0; }
 
  void set(const char *s) { set(s, s ? (int) strlen(s) : 0); }
 
  void set(const char *s, int n) {
    if (!s || n <= 0) { _ensure(0);  ptr[0] = '\0';  len = 0;  return; }
    if (ptr && s >= ptr && s <= ptr + len) {        
      const int off = (int) (s - ptr);
      memmove(ptr, ptr + off, (size_t) n);
    }
    else {
      _ensure(n);
      memmove(ptr, s, (size_t) n);
    }
    ptr[n] = '\0';
    len = n;
  }
 
  LL_String concat(const char *s1, const char *s2) {
    LL_String r;
    const int n1 = s1 ? (int) strlen(s1) : 0;
    const int n2 = s2 ? (int) strlen(s2) : 0;
    r._ensure(n1 + n2);
    if (n1) memmove(r.ptr,      s1, (size_t) n1);
    if (n2) memmove(r.ptr + n1, s2, (size_t) n2);
    r.ptr[n1 + n2] = '\0';
    r.len = n1 + n2;
    return r;
  }
 
  LL_String &append(const char *s1) {
    if (s1 && *s1) {
      const int n1 = (int) strlen(s1);
      const bool self = (ptr && s1 >= ptr && s1 <= ptr + len);
      const int off = self ? (int) (s1 - ptr) : 0;
      _ensure(len + n1);                           
      memmove(ptr + len, self ? ptr + off : s1, (size_t) n1);
      len += n1;
      ptr[len] = '\0';
    }
    return *this;
  }

  LL_String &append(char c) {
    _ensure(len + 1);
    ptr[len++] = c;
    ptr[len] = '\0';
    return *this;
  }
 
  LL_String substring(int start, int len_)      { return LL_String(&(ptr[start]), len_); }
 
  LL_String &operator=(const char *other)       { set(other); return *this; }
  LL_String &operator=(const LL_String &other)  { if (this != &other) set(other.ptr, other.len); return *this; }
 
  bool operator==(const char *other)            { return strcmp(ptr, other) == 0; }
  bool operator!=(const char *other)            { return strcmp(ptr, other) != 0; }
  bool operator==(const LL_String &other)       { return strcmp(ptr, other.ptr) == 0; }
  bool operator!=(const LL_String &other)       { return strcmp(ptr, other.ptr) != 0; }
  char &operator[](int ix)                      { return ptr[ix]; }
 
  LL_String operator+(const char *other)        { return concat(ptr, other); }
  LL_String operator+(const LL_String &other)   { return concat(ptr, other.ptr); }
  LL_String operator+(char c)                   { char cstr[2];  cstr[0] = c;  cstr[1] = '\0';  return concat(ptr, cstr); }
 
  LL_String &operator+=(const char *other)      { return append(other); }
  LL_String &operator+=(const LL_String &other) { return append(other.ptr); }
  LL_String &operator+=(char c)                 { return append(c); }
 
  char *c_str() const   { return ptr; }
  int length() const    { return len; }          
 
private:
  void _init() { ptr = 0;  len = 0;  cap = 0; }

  void _ensure(int need) {
    if (cap >= need + 1) return;
    int ncap = cap ? cap : 16;
    while (ncap < need + 1) ncap += ncap;        
    char *np = new char[ncap];
    if (ptr) { memmove(np, ptr, (size_t) len + 1);  delete[] ptr; }
    else     { np[0] = '\0'; }
    ptr = np;
    cap = ncap;
  }
 
  char *ptr;
  int   len;        
  int   cap;        
};
 
typedef LL_String String;
#endif

#define NOTUSED __attribute__((__unused__))                     
#define INLINE __attribute__((__inline__))                      
#define NOINLINE __attribute__((__noinline__))                  
#define CHECKPRINTF __attribute__((format(printf, 1, 2)))       
#define CHECKPRINTF_pos2 __attribute__((format(printf, 2, 3)))  


#if LL_ARDUINO
class Print {
public:
  virtual ~Print() {}
  virtual size_t write(uint8_t c) = 0;
  virtual size_t write(const uint8_t *buf, size_t n);
  size_t write(const char *s);
  size_t print(char c);
  size_t print(const char *s);
  size_t print(const String &s);
  size_t print(int n, int base = 10);
  size_t print(long n, int base = 10);
  size_t print(unsigned long n, int base = 10);
  size_t print(double v, int digits = 2);
  size_t println();                                  
  size_t println(char c);
  size_t println(const char *s);
  size_t println(const String &s);
  size_t println(int n, int base = 10);
  size_t println(long n, int base = 10);
  size_t println(unsigned long n, int base = 10);
  size_t println(double v, int digits = 2);
  size_t printf(const char *fmt, ...) CHECKPRINTF_pos2;   
};
 
class Stream : public Print {
public:
  virtual int available() = 0;
  virtual int read()      = 0;
  virtual int peek()      = 0;
  virtual void flush()    {}
};

class LLArduinoSerial : public Stream {
  int  _peeked;                                      
public:
  LLArduinoSerial() : _peeked(-1) {}
  void begin(unsigned long baud = 115200);
  void end();
  int  available() override;
  int  availableForWrite();
  int  read() override;
  int  peek() override;
  void flush() override;
  size_t write(uint8_t c) override;
  using Print::write;
};
 
extern LLArduinoSerial Serial;
 
 
#endif // LL_ARDUINO -- Print/Stream/Serial

#if LL_ARDUINO || LL_ESP_ARDUINO
const char *ll_llarduino_fmt_int(long v, int base);
const char *ll_llarduino_fmt_real(double v, int digits);
const char *ll_llarduino_eol();
#endif
 
#define CHECKPRINTF_pos3 __attribute__((format(printf, 3, 4)))  
#define CHECKPRINTF_pos4 __attribute__((format(printf, 4, 5)))  
 
// On Arduino/ESP32, IRAM_ATTR and DRAM_ATTR are already defined by Arduino.h (esp_attr.h).
// On other platforms (Linux, desktop simulation) define them as empty so the same source compiles.
#if !defined(IRAM_ATTR)
#define IRAM_ATTR                                       
#endif
#if !defined(DRAM_ATTR)
#define DRAM_ATTR                                       
#endif

// [B410, B389, B396, P208] the DRAM budget behind this number
#ifndef LL_STDIO_RX_BUFSIZE
#define LL_STDIO_RX_BUFSIZE 0            
#endif
 
const unsigned long toString_MAX_LENGTH = 8192;         
const unsigned long LL_ERRFORM_MAX = 400;
const unsigned long LL_ENVFRAME_MAX = 32;
const unsigned long LL_PRINT_LIST_MAX = 4096;
String toString(const char *fmt, ...) CHECKPRINTF;      
 
 
#define ME(_me_) NOTUSED const char me[] = _me_                 
#define ll_isdef(sym) (#sym[0])                                 
 
void global_printf(const char *fmt, ...);               

void global_spill_begin();

void global_term_quiet(bool echo, bool logs);

#if LL_EMSCRIPTEN
void global_term_push_line(const char *s);
#endif


 
typedef unsigned char Byte_t;   
typedef bool Bool_t;            
typedef char Char_t;            
typedef int32_t ll_codepoint_t;  
 
typedef Char_t const *Charst_t;         
typedef Byte_t const *Bytest_t;         
typedef Char_t *CharVec_t;              
typedef Byte_t *ByteVec_t;              

void *ll_payload_alloc_bytes(size_t nbytes);
void  ll_payload_free(void *p);

template <typename T> static inline T *ll_payload_new(size_t n)
{
  return (T *) ll_payload_alloc_bytes(n * sizeof(T));
}

void *ll_dram_alloc_bytes(size_t nbytes);
void  ll_dram_free(void *p);

typedef uintptr_t Word_t;       
typedef void *Ptr_t;            
static_assert(sizeof(Word_t) >= sizeof(void *),
              "Word_t must hold a pointer -- see the P174 note above; LLP64 (Windows x64) breaks "
              "the old `unsigned long` spelling because long is 32 bits there and pointers are 64.");
 
typedef int32_t  LL_int32;      


inline int ll_u8_seqlen(unsigned char b0)
{
  if (b0 < 0x80) return 1;
  if ((b0 & 0xE0) == 0xC0) return 2;
  if ((b0 & 0xF0) == 0xE0) return 3;
  if ((b0 & 0xF8) == 0xF0) return 4;
  return 1;
}

inline ll_codepoint_t ll_u8_decode(const char *p, int *nb)
{
  unsigned char b0 = (unsigned char) p[0];
  int n = ll_u8_seqlen(b0);
  if (nb) *nb = n;
  if (n == 1) return (ll_codepoint_t) b0;
  ll_codepoint_t cp = b0 & (0xFF >> (n + 1));
  for (int i = 1; i < n; i++) {
    unsigned char c = (unsigned char) p[i];
    if ((c & 0xC0) != 0x80) { if (nb) *nb = 1; return (ll_codepoint_t) b0; }
    cp = (cp << 6) | (c & 0x3F);
  }
  return cp;
}

inline int ll_u8_encode(ll_codepoint_t cp, char *out)
{
  if (cp < 0x80)    { out[0] = (char) cp; return 1; }
  if (cp < 0x800)   { out[0] = (char)(0xC0 | (cp >> 6));  out[1] = (char)(0x80 | (cp & 0x3F)); return 2; }
  if (cp < 0x10000) { out[0] = (char)(0xE0 | (cp >> 12)); out[1] = (char)(0x80 | ((cp >> 6) & 0x3F));
                      out[2] = (char)(0x80 | (cp & 0x3F)); return 3; }
  out[0] = (char)(0xF0 | (cp >> 18));         out[1] = (char)(0x80 | ((cp >> 12) & 0x3F));
  out[2] = (char)(0x80 | ((cp >> 6) & 0x3F)); out[3] = (char)(0x80 | (cp & 0x3F));  return 4;
}

inline LL_int32 ll_u8_strlen(const char *s)
{
  LL_int32 n = 0;
  for (const char *p = s; *p; n++) p += ll_u8_seqlen((unsigned char) *p);
  return n;
}

inline LL_int32 ll_u8_strlen_n(const char *s, LL_int32 nbytes)
{
  LL_int32 n = 0;
  for (LL_int32 i = 0; i < nbytes; n++) i += ll_u8_seqlen((unsigned char) s[i]);
  return n;
}

inline const char *ll_u8_index_n(const char *s, LL_int32 nbytes, LL_int32 k)
{
  LL_int32 i = 0;
  for (LL_int32 c = 0; c < k; c++) {
    if (i >= nbytes) return 0;
    i += ll_u8_seqlen((unsigned char) s[i]);
  }
  return (i <= nbytes) ? (s + i) : 0;
}

inline const char *ll_u8_index(const char *s, LL_int32 k)
{
  const char *p = s;
  for (LL_int32 i = 0; i < k; i++) {
    if (!*p) return 0;
    p += ll_u8_seqlen((unsigned char) *p);
  }
  return p;
}
 
typedef int64_t  LL_int64;      
typedef float   LL_float32;     
typedef double  LL_float64;     
 
static_assert(sizeof(Word_t)    == sizeof(Ptr_t),  "Word_t size must be == Ptr_t size\n");
static_assert(sizeof(Word_t)    >= sizeof(LL_int32), "Word_t size must be >= LL_int32 size\n");
static_assert(sizeof(LL_float32) == 4,              "LL_float32 must be 4 bytes\n");
static_assert(sizeof(LL_float64) == 8,              "LL_float64 must be 8 bytes\n");
 
//The AsciiConverter class mitigates printf formatting problems caused by different int sizes on different processors, when using printf-style format string (%u, %d %lu %ld etc).
class AsciiConverter {
public:
 
  char *dec(Word_t n) {                       
    char *ptr = slot_end();
 
    *ptr = '\0';
    do {
      Word_t d = n % 10;
      n /= 10;
      char c = d + '0';
      *--ptr = c;
    } while (n);
    return ptr;
  }
 
  char *dec(LL_int32 n) {
    if (n >= 0) return dec((Word_t) n);
    if (n == INT32_MIN) return dec((LL_int64) n);   
    char *ptr = dec(-n);
    *--ptr = '-';
    return ptr;
  }

  template <typename T>
  typename std::enable_if<std::is_same<T, int>::value && !std::is_same<LL_int32, int>::value,
                          char *>::type
  dec(T n) { return dec((LL_int32) n); }
 
  char *dec(LL_int64 n) {
    // Full 64-bit signed decimal; avoids conflict with dec(Word_t) on 64-bit platforms.
    char *ptr = slot_end();                   
    bool neg = (n < 0);
    uint64_t uv = neg ? (n == INT64_MIN ? (uint64_t) 9223372036854775808ULL : (uint64_t) -n)
                      : (uint64_t) n;
    do { *--ptr = (char)('0' + (uv % 10)); uv /= 10; } while (uv);
    if (neg) *--ptr = '-';
    return ptr;
  }
 
  char *hex(Word_t n) {
    char *ptr  = slot_end();                  
    LL_int32 nibs = sizeof(Word_t) * 2;
 
    *ptr = '\0';
    while (nibs--) {
      Word_t d = n & 0x0f;
      n >>= 4;
      char c = (d < 10) ? (d + '0') : (d - 10 + 'a');
      *--ptr = c;
    }
    return ptr;
 
  }
 
  char *dec(LL_float32 n) {
    char *b = slot_base();                    
    snprintf(b, SLOT, "%f", (LL_float64) n);
    return b;
  }
 
private:
  // [P238 Ph1]
  static const LL_int32 SLOTS = 16;
  static const LL_int32 SLOT  = 64;
  static_assert(SLOT >= 3 + 20,                  "dec(LL_int64): sign + 20 digits + NUL");
  static_assert(SLOT >= 2 + sizeof(Word_t) * 2,  "hex(Word_t): nibbles + NUL");
  static_assert(SLOT >= 48,                      "dec(LL_float32): %f of 3.4e38 needs 47 chars");
  char     buf[SLOTS][SLOT];
  LL_int32 next = 0;
  char *slot_base() { next = (next + 1) % SLOTS;  return buf[next]; }
  char *slot_end()  { char *b = slot_base();  b[SLOT - 1] = '\0';  return &b[SLOT - 1]; }
};
 
extern AsciiConverter ascii;
  
class LambPlatform {
public:

  LambPlatform() {}
  ~LambPlatform() { end(); }
 
  void begin(void);
  void loop(void);                      
  void end(void);
  
  void reboot(void);
  
  const char *name();                   
  void identification(void);            
 
  LL_int32 free_heap();
  // [B508, B609, B676] why these four exist separately from free_heap()
    LL_int32 free_internal();                   
  LL_int32 free_dma();                          
  LL_int32 largest_free_internal();             
  LL_int32 largest_free_dma();                  
  LL_int32 cell_pool_free();                    
 
  // [B593] why the pool query was abstracted here
  void *cell_block_alloc(unsigned long nbytes);  
  void  cell_block_free(void *blk);              
 
  // [B593, B117]
  const char *mem_placement(void *p);            
 
  // [B627] the absence this records, and the write-cost measurement
  LL_int64 fs_total();                           
  LL_int64 fs_used();                            
  LL_int32 free_stack();                        
  Bool_t heap_integrity_check(Bool_t complain=false);   

  LL_float32 rand11() {
    const int max_int = (~((unsigned int) 0)) >> 1;
    const int min_int = -max_int - 1;
    const LL_float32 min  = (LL_float32) min_int;
    
    LL_int32 n;
    rand((byte *) &n, sizeof(n));
    return (n / min);
  }
  
  LL_float32 rand01()                   { return (rand11() + 1.0) / 2.0; }
 
  void rand(byte *buf, LL_int32 len);   
  void rand11(LL_float32 *buf, LL_int32 n)      { while (n--) *buf++ = rand11(); }
  void rand01(LL_float32 *buf, LL_int32 n)      { while (n--) *buf++ = rand01(); }
 
  LL_int32 loop_elapsed_ms()    { return millis() - loop_start_ms; }    
  LL_int32 loop_elapsed_us()    { return micros() - loop_start_us; }    

 
private:
  LL_int32 loop_start_ms;
  LL_int32 loop_start_us;
};
 
extern LambPlatform lambPlatform;

#if LL_LITTLEFS
#include "LittleFS.h"
typedef File File_Native;
#endif
 
#if LL_POSIX
#include <stdio.h>
typedef FILE* File_Native;
#endif

class LL_File {
public:
 
  LL_File();
  ~LL_File();
 
  bool isOpen() { return _path != ""; }
  int read(void);
  int write(byte b);
  int seek(unsigned long target, int whence=SEEK_SET);
  int tell();
  int size();
  int close();
 
  int read(byte *b, int n) {
    LL_int32 nread = 0;
    while (n--) {
      int ch = read();
      if (ch == EOF) return nread;
      b[nread++] = ch;
    }
    return nread;
  }
  
  int read(char *s, int n) { return read((byte *) s, n); }  
  int write(const byte *b, int n) { while (n--) write(*b++); return n; }
  int write(const char *s, int n) { while (n--) write((byte) *s++); return n; }
  int peek();
  
  File_Native _theFile;
  String _path;
  String _mode;
 
private:
 
};

 
// [P211 Ph1] and [B396], [B88], [B60], [B428], [B411], [B662] for the claims that collided
bool ll_fastram_reserve(const char *tag, size_t bytes);

void ll_wifi_boot_reserve();

bool ll_fastram_reserve_pinned(const char *tag, size_t bytes);

void ll_fastram_release(const char *tag);

void ll_fastram_release_unclaimed();

 
// Declarations lived in ll_platform_Windows.h until 2026-10-06; the implementation file is
// unchanged and is still the only place Win32 is named.  [P264] [P174]
#if LL_WINDOWS

size_t ll_win_self_exe_path(char *buf, size_t cap);

int ll_win_mkdir(const char *path, int mode);

int ll_win_set_system_time(long long utc_seconds);
 
#endif // LL_WINDOWS


 
// The interface lived in ll_panel.h until 2026-10-06; every LambLisp element now takes it
// from the generic platform.  It was extracted from the camera driver before that.  [P264] [P231]
class Lamb;   // the operations below take `Lamb &`; function pointers need only an incomplete type

#ifndef LL_PANEL_ST7789_EYE
  #define LL_PANEL_ST7789_EYE 0   // was documented as env-set while nothing set it [B557]
#endif

#ifndef LL_PANEL_ST7701_AITRIP
  #define LL_PANEL_ST7701_AITRIP 0
#endif

#if LL_PANEL_ST7789_EYE || LL_PANEL_ST7701_AITRIP
  #define LL_PANEL 1
#else
  #define LL_PANEL 0
#endif

enum LL_PanelModel {
  LL_PANEL_PUSH = 0,   
  LL_PANEL_SCAN = 1    
};

struct LL_Panel {
  const char   *name;          
  int           w, h;          
  LL_PanelModel model;         
  bool        (*init)(Lamb &lamb);                                                  
  void        (*fill)(Lamb &lamb, int x, int y, int w, int h, uint16_t color);       
  void        (*blit)(Lamb &lamb, int x, int y, int w, int h, const uint16_t *src);  
  uint16_t   *(*fb)(void);                                                          
  void        (*set_brightness)(Lamb &lamb, int percent);                           
  void        (*on_off)(Lamb &lamb, bool on);                                       
};

const LL_Panel *ll_panel_active(void);

void            ll_panel_register(const LL_Panel *p);

bool            ll_panel_ready(void);

void            ll_panel_blit_rgb565(Lamb &lamb, int x, int y, int w, int h, const uint16_t *src);


class LL_File_System {
public:
  LL_File *open(const char *path, const char *mode);
  bool exists(const char *path);
  int rm(const char *path);
  int mv(const char *from, const char *to);
  int mkdir(const char *path);
 
private:
};
 
extern LL_File_System ll_file_system;

#if LL_WIRE
#include "Wire.h"
extern TwoWire *LL_Wire;
#endif
 
#if LL_WIFI
#include "WiFi.h"
#include "WiFiClientSecure.h"
extern WiFiClass *LL_WiFi;
#endif

class LambStdioClass {
public:
  int setTxBufferSize(int n);
  int setRxBufferSize(int n);

  bool set_input_callback(void (*cb)());
  
  void begin(void) { begin(115200); }
  void begin(unsigned long baudrate);
  void end();
  int available(void);
  int availableForWrite(void);
  int read(void);
  int write(uint8_t c);
  int write(char c) { return write((uint8_t) c); }
  
  void flush(void);
 
  int read(byte *buf, int max) {
    int nread = 0;
    while (max--) {
      int b = read();
      if (b == EOF) break;
      *buf++ = b;
    }
    return nread;
  }
 
  int read(char *s, int max)            { return read((uint8_t *) s, max); }
  int write(const char *s, int n)       { return write((uint8_t *) s, n); }
  int write(const byte *b, size_t n)    { int i=n;  while (i--) write(*b++);  return n; }
  int write(const char *s)              { int i=0;  while (*s) { write(*s++); i++; }  return i; }
  
  operator bool() { return true; }
};
 
extern LambStdioClass LambStdio;
 
typedef byte uuid_t[16];

#define ll_once(_once_something) do {           \
    static bool _visited_ = false;              \
    if (!_visited_) {                           \
      _visited_ = true;                         \
      { _once_something; }                      \
    }                                           \
  } while (0)                                   \
    //
//

#define ll_every(_every_so_often_ms, _every_something_to_do) do {       \
    static unsigned long _every_next = 0;                       \
    unsigned long _every_now = millis();                        \
    if (_every_now >= _every_next) {                            \
      { _every_something_to_do; }                               \
      _every_next = _every_now + (_every_so_often_ms);          \
    }                                                           \
  } while (0)                                                   \
    //
//
 
/*
  The embedded debug catcher ensures that an address is available to be set as a BREAKPOINT for a
  hardware debugger.  This is useful in cases where the generated code has been heavily inlined --
  a catch arm that is inlined away has no address to break on, and this gives every catch one.
  Undefine this symbol if not using a hardware debugger, or redefine it to point to a different
  breakpoint target.
 
  IT IS NOT A NO-OP, WHICH MATTERS BECAUSE IT LOOKS LIKE ONE AT ALL TEN USE SITES.  A bare
  `ll_debug_catcher;` in a catch arm reads as a leftover, and in `main.cpp`'s hand-written copies
  of `ll_catch_terminal` it reads as a stray statement.  It calls `embedded_debug_catcher()`
  (`ll_vm_util.cpp:22`), which does:
 
      ll_every(10000, { magenta("%s caught\n", me); ll_term.flush(); delay(10); });
 
  `ll_every`'s argument is MILLISECONDS, not a call count -- so the common path is one `millis()`
  and a compare, and at most once per TEN SECONDS it prints a magenta `caught` line, flushes the
  terminal, and stalls 10 ms.
 
  TWO CONSEQUENCES WORTH KNOWING.  First, that 10 ms stall is on the FAULT path of SHIPPED
  firmware: nothing undefines this symbol anywhere in the tree despite the advice above, so a
  customer program that throws carries it.  For a hard-real-time node that is a real, if bounded,
  cost on the error path -- the same class of finding as [B765], where every raise logged.  Second,
  it is NOT the cause of [B839]'s 6.4-29 ms per caught raise: at one firing per 10 s against
  `guard-raise`'s 3.2 s for 500 raises it contributes about 10 ms to the whole benchmark, ~0.3%.
  Ruled out by arithmetic rather than left as a suspicion.
*/
void embedded_debug_catcher();
#define ll_debug_catcher embedded_debug_catcher()
//#define ll_debug_catcher ll_term.flush()
 
// ── Settings file paths ──────────────────────────────────────────────────────
#if LL_LITTLEFS
#define LAMB_SETTINGS_PATH  "/Settings-Lamb.scm"   
#define SETTINGS_PATH       "/Settings.scm"         
#else
#define LAMB_SETTINGS_PATH  "Settings-Lamb.scm"   
#define SETTINGS_PATH       "Settings.scm"
#endif
 
// ── Pre-allocation settings ──────────────────────────────────────────────────
struct LambPreSettings {
  LL_int32 cell_block_size      = 8 * 1024;   
  LL_int32 extension_block_size = 4 * 1024;   
  LL_int32 gc_total_marked      = 0;
  // [B610]
  LL_int32 gc_pool_target       = 0;
  LL_int32 ncg_frame_pool_size  = 16;        
  LL_int32 sint_in_iram         = 1;
  LL_int32 rootstack_in_iram    = 1;
  LL_int32 va_list_max          = (LL_int32) toString_MAX_LENGTH;
  // [B441] and [B417] for the keys it must preserve
  LL_int32 boot_pending         = 0;
  void load();               
  bool apply_key(const char *key, long val);
};

void ll_pre_settings_write(LL_int32 boot_pending);
void ll_settings_boot_ok(void);

extern LambPreSettings ll_pre_settings;

extern LL_int32 ll_cell_block_size_effective;

extern LL_int32 ll_va_list_max;

#define ll_try try

extern const void *ll_catch_last_err;   
extern int         ll_catch_repeats;    
#define LL_CATCH_REPEAT_LIMIT 4
 
// [B665] why bad_alloc is converted at the first handler
// [B765] the 25,000-line noise measurement behind this
#define LL_ERR_IS_USER_RAISE(__e__) \
  ((__e__)->type() == Cell::T_ERROR && strcmp((__e__)->error_get_chars(), "__raise__") == 0)
 
/* WHAT `ll_catch` DOES AND DOES NOT DO -- read this before deciding where a frame may go.
 *
 *  IT LOGS AND RETHROWS.  It does NOT touch the rootstack.  That is deliberate and it is NOT a
 *  gap: the rootstack is unwound at the MOP3 BOUNDARY, by `mop3_catch`, which restores the depth
 *  `mop3_try` saved on entry.  An `ll_catch` frame between the throw and that boundary has nothing
 *  to restore -- it did not save a depth, and restoring to its own would discard entries its
 *  caller still owns.
 *
 *  SO THE THREE HANDLERS DO THREE DIFFERENT JOBS:
 *    `mop3_catch`        APPLICATION error -- restore to the mop3 boundary so the REPL continues.
 *    `ll_catch`          intermediate frame -- log once, annotate, rethrow.  Rootstack untouched.
 *    `ll_catch_terminal` SYSTEM RESCUE -- something escaped everything; keep running.  Also does
 *                        not restore, because by the time it is reached the mop3 boundaries have.
 *
 *  MEASURED, 2026-10-13, because this was a standing uncertainty and reading could not settle it:
 *  a 50,000-deep recursion pushed 181,439 of 261,608 root slots and threw; the next error at the
 *  REPL reported `entry=1`, i.e. the depth was fully restored on the way out.  Six other error
 *  kinds all reported `entry=1 catch=1` at the terminal frame.  That is the [B652] probe in
 *  `main.cpp` answered: the rootstack is NOT leaked across an unwind.
 *
 *  IF YOU NEED A RESTORE ON THIS PATH, pass it in: `ll_catch(gc_root_setdepth(saved))` with the
 *  depth saved BEFORE the try.  `ll_vm_rdr.cpp:279` and `ll_vm_mop3_extra.cpp:54` do exactly that,
 *  and they are the right pattern for a frame whose cleanup cannot wait for the mop3 boundary. */
#define ll_catch(__code_before_rethrow__)                               \
  catch (std::bad_alloc &) {                                            \
    Sexpr_t __err__ = NIL->mk_error("%s out of memory (C++ allocation failed)", me); \
    ll_catch_last_err = (const void *) __err__;                         \
    ll_catch_repeats  = 1;                                              \
    global_printf("\r[%d] %s ll_catch(): %s\n", millis(), me, __err__->error_get_chars()); \
    ll_debug_catcher;                                                   \
    __code_before_rethrow__;                                            \
    throw __err__;                                                      \
  }                                                                     \
  catch (Sexpr_t __err__) {                                             \
    if (__err__->type() != Cell::T_ERROR)                               \
      throw NIL->mk_error("ll_catch() BUG in %s bad type %s", me, __err__->dump().c_str()); \
                                                                        \
    if (!LL_ERR_IS_USER_RAISE(__err__)) {                               \
      if ((const void *) __err__ != ll_catch_last_err) {                \
        ll_catch_last_err = (const void *) __err__;                     \
        ll_catch_repeats  = 0;                                          \
      }                                                                 \
      if (++ll_catch_repeats <= LL_CATCH_REPEAT_LIMIT)                  \
        global_printf("\r[%d] %s ll_catch(): %s\n", millis(), me, __err__->error_get_chars()); \
      else if (ll_catch_repeats == LL_CATCH_REPEAT_LIMIT + 1)           \
        global_printf("\r[%d] %s ll_catch(): ... same error still unwinding; further frames suppressed\n", millis(), me); \
    }                                                                   \
                                                                        \
    ll_debug_catcher;                                                   \
    __code_before_rethrow__;                                            \
    throw __err__;                                                      \
  }                                                                     \
  //
 
#define ll_catch_terminal                                               \
  catch (std::bad_alloc &) {                                            \
    global_printf("\r[%d] %s ll_catch_terminal: out of memory (C++ allocation failed)\n", \
                  millis(), me);                                        \
    ll_debug_catcher;                                                   \
  }                                                                     \
  catch (Sexpr_t __err__) {                                             \
    /* [B765] inside a macro a // comment would swallow the \ continuation, so block form. */ \
                      \
    if (LL_ERR_IS_USER_RAISE(__err__))                                  \
      global_printf("\r[%d] %s ll_catch_terminal: UNCAUGHT raise: %s\n",        \
                    millis(), me, __err__->error_get_irritants()->str().c_str()); \
      \
    else if (__err__->type() != Cell::T_ERROR)                          \
      global_printf("\r[%d] %s ll_catch_terminal: non-error type %d\n", \
                    millis(), me, __err__->type());                     \
    else                                                                \
      global_printf("\r[%d] %s ll_catch_terminal: %s\n",                \
                    millis(), me, __err__->error_get_chars());          \
    ll_debug_catcher;                                                   \
  }                                                                     \
  //

#ifdef __cplusplus
const char *const *ll_feature_names(int *count);
#endif

#ifdef __cplusplus
bool ll_term_ansi(void);           
void ll_term_ansi_set(bool on);    
bool ll_term_ansi_detect(void);    
#if LL_WINDOWS
int  ll_win_enable_vt(void);       
void ll_win_yield_ms(unsigned ms); 
#endif
#endif
 
 
#endif