Skip to content
php-baremetal REGISTRY
Publish a package

php-baremetal/esp32-executor

bm-lib MIT

ESP32 executor task: device pollers and work run on a core-0 task with an internal-RAM stack.

needs no platform HAL

The executor task of the ESP32 firmware: one FreeRTOS task, pinned to core 0 with its stack in internal RAM, that runs work handed over by HALs and the background samplers of devices. It exists because the PHP task (core 1) has its stack in PSRAM: on ESP32 a task with a PSRAM stack must not run code that touches the flash or suspends the flash cache (NVS, Wi-Fi driver calls, PHY calibration, esp_light_sleep_start()), so HALs run that code here and wait for the result.

Key Value
Type bm-lib (support library, C only, no PHP API)
Header executor.h
ESP-IDF components esp_timer (plus FreeRTOS)
Used by esp32-wifi-hal, esp32-i2c-hal, esp32-store-hal, esp32-sys-hal

Install

Projects do not require it: the HALs that use it require it, and conductor installs them. A package that needs it adds it to its own composer.json and includes executor.h:

json
{ "require": { "php-baremetal/esp32-executor": "^1.0" } }

The task

Property Value
Name executor
Core 0 (core 1 belongs to the PHP task)
Stack 8192 bytes, internal RAM
Priority 4
Work queue 16 entries
Started lazily, by the first executor_run_sync() or executor_poll(); a firmware that uses neither has no task

The task blocks on its work queue. While samplers are registered it waits at most until the earliest one is due, so it wakes once per sampling period and the chip can light-sleep in between; work and samplers run one after the other on the task, never at the same time.

Running work: executor_run_sync()

c
esp_err_t executor_run_sync(esp_err_t (*fn)(void *arg), void *arg, uint32_t enqueue_timeout_ms);
bool executor_on_task(void);

Runs fn(arg) on the executor and blocks the caller until it returns, then returns its result. Called from the executor itself, it runs fn inline. It returns ESP_ERR_TIMEOUT when the work queue stays full for enqueue_timeout_ms, and ESP_ERR_INVALID_STATE when the task cannot be created; once queued, the wait for completion has no limit. fn must not call PHP or the Zend allocator: only the PHP task may.

Users: esp32-wifi-hal (every esp_wifi_*, esp_netif_*, nvs_flash_* call, 1000 ms enqueue limit), esp32-store-hal (NVS), esp32-sys-hal (sys_light_sleep()), esp32-i2c-hal (every transaction of a bus owned by the executor).

Background samplers: executor_poll()

c
executor_poller_t *executor_poll(esp_err_t (*sample)(void *dev, void *out),
                                 void *dev, size_t sample_size, uint32_t hz, size_t depth);
void   executor_poll_pause(executor_poller_t *p, bool paused);
void   executor_poll_on_sample(executor_poller_t *p, void (*notify)(void *arg), void *arg);
bool   executor_poll_latest(executor_poller_t *p, void *out);
size_t executor_poll_drain(executor_poller_t *p, void *out, size_t max_samples);
Function Does
executor_poll() Registers a sampler: the executor calls sample(dev, out) every 1000 / hz ms (whole milliseconds, at least 1) and stores each successful sample in a ring of depth slots. A second call with the same sample and dev only changes the rate. Returns NULL for a size of 0 or over 64 bytes, hz 0, no free slot, or no memory.
executor_poll_pause() Pauses (true) or resumes (false) a poller. Paused, it takes no samples and does not count in the executor's wait, so the chip can sleep through it; the ring and its unread samples stay. On resume the next sample is due now. A sample already being taken when the pause comes can still land in the ring.
executor_poll_on_sample() Installs a callback run on the executor right after each stored sample, outside the ring lock. It must not block or touch PHP: post to a queue (ext-i2c calls bm_events_emit()). On return, no call of the previous callback is running.
executor_poll_latest() Copies the most recent sample; false before the first one.
executor_poll_drain() Copies up to max_samples unread samples, oldest first, and marks them read. Samples overwritten by a full ring are lost.

sample() runs on core 0 and does its own bus locking. A sample that returns an error is not stored.

Limit Value
Samplers in the firmware 8
Sample size 1 to 64 bytes
Ring depth 1 to 256 samples (0 means 64; larger is clamped)

Samplers are never removed; executor_poll_pause() pauses one, and a paused sampler does not wake the task. Each running sampler keeps waking the task once per period, so with the power-save option on the chip never sleeps longer than the shortest period.

On-demand jobs: executor_irq()

c
executor_irq_t *executor_irq(esp_err_t (*service)(void *dev), void *dev);
void executor_irq_kick_from_isr(executor_irq_t *j);
void executor_irq_after(executor_irq_t *j, uint32_t ms);
void executor_irq_pause(executor_irq_t *j, bool paused);
void executor_irq_cancel(executor_irq_t *j);
Function Called from Does
executor_irq() a task Registers a job: service(dev) runs on the executor task, and only when asked (no periodic wake-ups). Starts the executor if needed. Returns NULL with no free slot (4 in the firmware) or no memory.
executor_irq_kick_from_isr() an interrupt handler Asks for one run as soon as the executor can. A second kick before the run is merged into it. Only touches atomics and wakes the task with the FromISR queue send.
executor_irq_after() a task Asks for one run after ms, replacing a delayed run still pending. An immediate kick wins and absorbs the delayed run.
executor_irq_pause() a task Paused, new kicks are dropped, and so are a pending kick and a pending delayed run (also one racing the pause). A run already taken by the executor may still execute once after pause returns. Resuming (false) on a job that is not paused changes nothing: a pending run survives.
executor_irq_cancel() a task No more runs, and the job is freed. It runs on the executor task, serial with the services: it waits for a running service() to finish (inline when called from a service, so no deadlock). On return service(dev) is not running and never starts again, so the caller may free dev. Remove the interrupt handler that kicks the job before calling it (and make sure no ISR is still running on another core): the handle is invalid once cancel returns.

service() runs on core 0 after the pollers, as sole owner of the bus (no lock needed), and its result is ignored. The executor blocks until the earliest poller or delayed run is due, so an idle job lets the chip sleep.

License

MIT.