Architecture: memory and execution

This page describes two things at once: where code and data physically live on the chip, and what the firmware does from reset to the first byte of output. The important idea to hold onto is that this is a real, unmodified Zend engine running the same compile-then-execute pipeline it runs on a server. What changes is the environment around it: a few hundred KB of fast internal SRAM, a large but slower PSRAM heap, a single CPU core, code executed straight out of flash, and no operating system underneath other than FreeRTOS.

The worked example throughout is the ESP32-P4. The ESP32-S3 has the same shape with different sizes and peripherals; the differences are collected in the last section.

Memory map

The chip has four distinct places where code and data live, each with a role. The single most important fact is that code is not copied into RAM to run. It executes straight from flash through the MMU cache — execute in place, "XIP" — which is why a few hundred KB of internal SRAM is enough to run a multi-megabyte image. Internal SRAM is small and fast; PSRAM is large and holds everything that grows at runtime.

The static footprint is modest. About 97 KB of uninitialized data plus a handful of KB of initialized data sits well inside the 768 KB of internal SRAM. Everything that grows while a script runs lives in PSRAM instead. See footprint.md for the exact numbers of the current build.

Why PHP allocates into PSRAM

PSRAM is where PHP allocates, and this is deliberate at two levels.

First, Zend's own memory manager is switched off. The firmware sets USE_ZEND_ALLOC=0 in the environment before the engine starts, which tells Zend to route every allocation through plain malloc/free instead of its internal arena allocator.

/* PHP allocations go to PSRAM (see CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL=0), which
 * keeps internal RAM free for DMA and FreeRTOS. */
setenv("USE_ZEND_ALLOC", "0", 1);

Second, ESP-IDF is configured to send malloc to PSRAM. The board's chip-level defaults enable external PSRAM as a malloc region and, critically, set the internal-allocation threshold to zero so that all allocations — not just large ones — land in PSRAM.

# 32 MB in-package PSRAM. This is where the runtime heap lives: with
# USE_ZEND_ALLOC=0 the engine uses malloc, and SPIRAM_USE_MALLOC routes large
# allocations to PSRAM.
CONFIG_SPIRAM=y
CONFIG_SPIRAM_USE_MALLOC=y
# Send ALL malloc() allocations to PSRAM (threshold 0), not just large ones.
# PHP makes thousands of small allocations; with the default 16 KB threshold they
# land in internal RAM and exhaust it, starving DMA (the SD card) and FreeRTOS.
CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL=0

Why the PHP task stack is large

The engine runs on its own FreeRTOS task with a 64 KB stack. That is large for an embedded task, and for two concrete reasons: the PHP compiler recurses heavily while descending a syntax tree, and zend_bailout unwinds fatal errors with setjmp/longjmp, which needs the frames it jumps over to still be on the stack.

/* 64 KB: with a smaller stack the board resets on trivial scripts.
 * ESP-IDF's xTaskCreate takes the stack size in bytes. */
#define PHP_TASK_STACK_BYTES (64 * 1024)

void app_main(void)
{
    ESP_LOGI(TAG, "starting PHP runtime");
    xTaskCreate(php_task, "php", PHP_TASK_STACK_BYTES, NULL, 5, NULL);
}

app_main() does nothing but spawn this task. Everything else — mounting storage, bringing up the network, initializing the engine, running the script — happens inside php_task.

Execution flow: from reset to output

The first steps are the ordinary ESP-IDF boot sequence. Everything after app_main() is the firmware's own pipeline.

1. 01

   Reset

   hands control to the ROM bootloader.

2. 02

   The **second-stage bootloader** in flash loads the app partition and jumps to it.
3. 03

   `app_main()`

   runs from flash and creates the FreeRTOS php task (64 KB stack).

4. 04

   Inside the task: **mount storage** (microSD and/or the embedded FAT image) and, on a

   networked board, bring the link up and log the address.

5. 05

   Resolve the **entry script** (embedded source takes priority over the SD card) and set up

   optional features: OPcache ini defaults, OPENSSL_CONF, the TLS CA bundle, the baked .env.

6. 06

   `php_embed_init()`

   brings the Zend engine up.

7. 07

   Register per-project C extensions

   , then run the entry script under the selected execution model.

Concretely, take <?php echo 1 + 1;. The source goes into zend_compile_string(), which tokenizes it, builds a syntax tree, and lowers it to opcodes — the instructions of PHP's virtual machine. The opcodes live in the PSRAM heap. zend_execute() then runs the VM: a loop that takes one opcode at a time and calls the C function implementing it (ZEND_ADD, ZEND_ECHO, and the rest). ZEND_ECHO reaches the SAPI's output funnel, ub_write, and from there the bytes go to the serial console or, under the web-server model, into the HTTP response.

It is exactly the path the code takes on a server. Here it runs on a single core at a few hundred MHz instead of on a PC.

The portable "call" VM

Zend can generate several dispatch variants for its virtual machine. The common one on desktop builds is the "goto" variant, which uses GCC's computed-goto (labels-as-values) to thread from one opcode handler to the next. That variant does not compile cleanly on these targets, so this build uses the portable "call" variant instead: the dispatch loop is an ordinary switch/ function-call over opcodes. The engine's behaviour is identical; only the dispatch mechanism differs. The practical consequence is portability — the same engine source builds for RISC-V (P4) and Xtensa (S3) without touching any VM code.

The embed SAPI

PHP always runs behind a SAPI (Server API): the CLI SAPI, the FPM SAPI, Apache's module, and so on. This firmware embeds PHP through the embed SAPI, the minimal library interface meant for hosting the engine inside another C program. php_embed_init() starts the engine and opens one request; php_embed_shutdown() tears it down.

The firmware customizes the embed module in a few places. The default output sink is replaced so that engine output goes straight to the console, always reporting the full length written.

/*
 * Output sink for the engine: echo, print, printf, var_dump and php_printf() all
 * funnel through here. Write straight to the console and always report the full
 * length. The embed SAPI's default ub_write treats a short write as a dropped
 * connection, which fires php_handle_aborted_connection() -> zend_bailout() ->
 * exit(); on this target exit() then aborts inside newlib.
 */
static size_t esp_ub_write(const char *str, size_t len)
{
    fwrite(str, 1, len, stdout);
    fflush(stdout);
    return len;
}

The engine has no dlopen: HAVE_LIBDL is undefined and there are no POSIX signals (ZEND_SIGNALS is off) under FreeRTOS/newlib. A few other embed hooks are set before php_embed_init() so the values take effect from the first line of the script:

• ini_defaults seeds OPcache directives (which are PHP_INI_SYSTEM and cannot be set at runtime). See opcache.md.
• name is changed to cli-server in the web-server model so frameworks treat each run as an HTTP request rather than a CLI invocation.
• environment (OPENSSL_CONF, the TLS CA path, and the baked project .env) is applied with setenv() before init so it appears in $_ENV/getenv().

The static-extension model

A normal PHP build discovers extensions at configure time and can load some at runtime via dlopen. This build does neither. There is no dynamic loading; every extension is compiled in and linked statically. The list is hand-written (because configure is not run) as a php_builtin_extensions[] table that php_register_internal_extensions() walks at startup.

static zend_module_entry * const php_builtin_extensions[] = {
#ifdef PHP_EXT_DATE_ENABLED
    &date_module_entry,
#endif
    phpext_pcre_ptr,
    phpext_hash_ptr,
    phpext_json_ptr,
    phpext_random_ptr,
    phpext_reflection_ptr,
    phpext_standard_ptr,
    phpext_spl_ptr,
    /* ... optional ctype/mbstring/filter/tokenizer/session/openssl/pdo ... */
    &gpio_module_entry,
    &store_module_entry,
    &mem_module_entry,
};

PHPAPI int php_register_internal_extensions(void)
{
    return php_register_extensions(php_builtin_extensions, EXTCOUNT);
}

The rules of this model:

• The table must match the extensions actually compiled. A name listed but not built fails the link with an unresolved phpext_<name>_ptr.
• Optional extensions are gated by PHP_EXT_*_ENABLED macros set from the build configuration, so the table shrinks and grows with what the project selected.
• date is left out of the default set because it pulls in timelib and the timezone database; a lightweight stub stands in unless PHP_EXT_DATE_ENABLED is set.
• Ordering matters where one module depends on another — pdo is registered before pdo_sqlite.
• The three trailing entries — gpio, store, mem — are this project's own built-in hardware/persistence extensions, always present. See persistent-store.md and in-ram-store.md.

Which of the optional bundled extensions are available, and their current status, is tracked in porting-status.md.

Per-project C extensions

Beyond the built-in table, a project can drop its own C extensions into ./firmware/exts/<name>/. The php_project_exts component compiles them and generates a table of zend_module_entry pointers, linked with whole-archive. These are registered after php_embed_init(), so their functions, classes and constants are available to the script — MINIT runs, though there is no per-request RINIT for a module added this late, which a hardware-driver extension does not need. The symbols are weak, so a firmware built with no project extensions still links and the count resolves to zero. This is covered in custom-extensions.md.

extern zend_module_entry * const php_esp32_project_extensions[] __attribute__((weak));
extern const int php_esp32_project_extension_count __attribute__((weak));

static void register_project_extensions(void)
{
    if (&php_esp32_project_extension_count == NULL || php_esp32_project_extension_count == 0) {
        return;
    }
    for (int i = 0; i < php_esp32_project_extension_count; i++) {
        zend_module_entry *m = php_esp32_project_extensions[i];
        if (zend_startup_module(m) == SUCCESS) {
            ESP_LOGI(TAG, "project ext '%s' registered", m->name);
        }
    }
}

The three execution models

The firmware supports three shapes of program. The first two share the same build (the default, "run-script + setup/loop"); the third is a separate build type selected with -DPHP_PROJECT_WEB_SERVER=ON.

<?php
echo "Hello from " . PHP_OS . "\n";
echo 1 + 1, "\n";

for (uint32_t tick = 0; ; tick++) {
    zval arg; ZVAL_LONG(&arg, tick);
    zval ret; ZVAL_UNDEF(&ret);
    zend_call_known_function(fn_loop, NULL, NULL, &ret, 1, &arg, NULL);
    zval_ptr_dtor(&ret);

    if (EG(exception)) {
        zend_clear_exception();   /* log-and-continue */
    }
    /* Refcounting frees most garbage immediately; cycles need a periodic sweep. */
    if ((tick & 0xFF) == 0) {
        gc_collect_cycles();
        ESP_LOGI(TAG, "tick %u -- heap free: %u bytes",
                 (unsigned) tick, (unsigned) esp_get_free_heap_size());
    }
}

Inside the web-server model

The web-server model has enough moving parts to be worth a closer look. Its defining constraint is that PHP must run on the task that has the 64 KB stack, not on the HTTP server's task.

php_embed_init() opens one request; the firmware closes that opened request and then cycles a fresh php_request_startup() → run the entry script → php_request_shutdown() for every HTTP request. Because each request is shared-nothing, re-running the top-level script every time does not trip redeclaration errors.

Two tasks, a shared slot, two semaphores

The HTTP server runs its handler on the small-stacked httpd task; PHP runs on php_task. They hand a single request back and forth through two binary semaphores:

1. 01

   The `httpd` handler parses the request off the socket into a single static `ws_request_t`

   (method, URI, query, headers, cookies, and the POST body — read here, on the task that owns the socket).

2. 02

   It serves the request directly if the path maps to an existing static file under the document

   root (public/) — no PHP cycle, exactly like try_files $uri /index.php. .php files, directories, /, and paths containing .. are never served this way.

3. 03

   Otherwise it gives `s_ws_req_ready`, waking `php_task`, and blocks on `s_ws_resp_ready`.
4. 04

   `php_task` runs one full request cycle: it fills `SG(request_info)` before startup (so `$_GET`

   / $_POST see the query and body), calls php_request_startup(), runs the script under zend_try/zend_catch, flushes any headers the script set, and calls php_request_shutdown(). Output is appended to a growing response buffer by the SAPI ub_write hook.

5. 05

   `php_task` gives `s_ws_resp_ready`; the `httpd` task wakes and sends the captured status,

   headers and body, then frees the body buffer.

The httpd server handles one request at a time, so the single shared ws_request_t, the single response buffer and the header-capture buffers are all safe. Neither task touches the socket while the other is using it.

Per-request SAPI hooks

For the duration of the web server, the live sapi_module copy is pointed at a set of request-scoped hooks (the copy sapi_startup() made at init time):

sapi_module.ub_write                  = ws_ub_write;
sapi_module.send_headers              = ws_send_headers;
sapi_module.read_post                 = ws_read_post;
sapi_module.read_cookies              = ws_read_cookies;
sapi_module.register_server_variables = ws_register_server_vars;
php_request_shutdown(NULL);   /* end the request embed_init opened; module stays up */

One-time init script

The web-server build accepts an optional init script ([web-server] init) that runs once, after php_embed_init() and before the HTTP server starts, in the request that init already opened — so its output goes to the console. Its effects that live below PHP (C-extension state, mem_ or store_ values) are then shared by every later request. A failure is logged but not fatal; the server still comes up.

Full engine-level detail on the SAPI is in porting-notes.md.

The board.h HAL

main.c is board-agnostic. Everything specific to a board's wiring — the microSD pins and power, the Ethernet controller, the mount and network-bring-up code — lives behind a small interface in each board's board.h and its board.c. main.c includes board.h and talks only to this contract; it does not know whether storage is 4-bit SDIO or SPI, or whether the network is an internal MAC or an external SPI chip.

The interface has two parts: capability macros that the firmware compiles against, and functions that each board implements.

The macros gate whole code paths at compile time. A -zero board with no card slot leaves BOARD_HAS_MICROSD undefined, so the SD path is never built or probed; a build that asked for microSD on such a board fails at compile time with a clear #error rather than at link time with a missing board_mount_storage(). Boards without networking leave BOARD_HAS_NETWORK undefined, and the netif, DNS and network-bring-up code is compiled out entirely.

board_mount_storage

board_network_up

Build-time patches

The stock PHP sources are patched at build time. The patches are small and each addresses one portability point; they are applied per PHP version under components/php/versions/<ver>/patches/php/. The current set:

Everything else — the engine, the VM, the bundled extensions — is unmodified PHP. This is why a version bump is mostly a matter of regenerating these patches against the new tree rather than re-porting the engine.

How the ESP32-S3 differs

The shape is the same; the sizes and a couple of peripherals change.

• CPU / toolchain. The S3 is dual-core Xtensa LX7 rather than the P4's RISC-V, so PHP is built with the xtensa-esp32s3-elf toolchain. The portable "call" VM means no engine code changes.
• Memory. 8 MB of PSRAM instead of up to 32 MB, and 16 MB of flash instead of 32 MB. The same firmware and heap fit with less headroom: plain applications and a live web server run comfortably; a full framework's container-compile step does not.
• Storage. microSD over SPI (SD_MOSI=6, SD_MISO=5, SD_CLK=7, SD_CS=4) rather than the P4's 4-bit SDIO — the S3 has no internal SD host.
• Network. On the S3-ETH the wired network is a W5500 SPI Ethernet controller (MAC+PHY in one chip) rather than an internal MAC with an RMII PHY; the SD card and the W5500 sit on separate SPI hosts so they do not share pins.

All of that is contained in the board's board.c and board.h. main.c and the engine do not know the difference — the same board_mount_storage() / board_network_up() contract holds, and the same USE_ZEND_ALLOC=0 → malloc → PSRAM routing applies (the S3 family config sets the same CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL=0).