ext-i2c · Reference
Bus ownership and power-save
Who drives the wire: the PHP task under a lock (Bus::SYNC) or the executor task (Bus::CORE1). The choice matters for interrupts, background samplers and the power-save option.
The firmware runs PHP on its own task on core 1. Next to it, esp32-executor provides one executor task on
core 0 (8 KB stack in internal RAM) that runs device samplers and work handed over by extensions. A bus's
owner, fixed when the bus is first created, decides which of the two drives the wire.
Bus::SYNC
The default. The caller runs each transaction itself while holding a per-bus mutex. From PHP the caller is the PHP task; a background sampler of a device on the same bus runs on the executor and takes the same mutex, so the two never overlap on the wire. The I2C interrupt is bound to the core that opened the bus, here core 1.
Bus::CORE1
The executor task owns the wire. The bus is opened on the executor, and every transaction from PHP (including
scan() and a driver's constructor) is queued to it while the PHP task waits for the result. Samplers already
run there, so on this bus they need no lock round-trip with PHP. If the executor queue stays full for one
second, the call fails with ESP_ERR_TIMEOUT.
Pick CORE1 when a bus carries background samplers and you want PHP's own transactions serialised with them on
one task; keep SYNC otherwise. Both behave the same from PHP.
Power-save
The SDK option power-save ("options": { "power-save": "on" } in extra.baremetal) lets the chip enter light
sleep automatically whenever every task is waiting.
new Bus(..., owner: Bus::CORE1)throws while power-save is on:Bus::CORE1 is not available with the power-save option; use Bus::SYNC. UseBus::SYNC.poll()is accepted on aSYNCbus, but the sampler wakes the chip once per period, so the chip never sleeps longer than1000 / $hzms.poll()returns aBaremetal\I2c\Poller; itsstop()pauses the sampler, and a stopped sampler does not wake the chip (see Background sampling). Keep rates low and start one only when the project needs it.- Buses are not closed around light sleep; the descriptor's sleep hooks are not called by ext-i2c (see Writing a driver).
Rules that follow from the firmware
- Native code never calls PHP from the executor: a sampler's notification only posts to the event queue, and listeners run on the PHP task.
- I2C transfers do not touch the flash, so they are allowed on the PHP task (whose stack is in PSRAM).
- A driver's
initand PHP methods run on the PHP task; only their transfers are routed (lock or executor). A driver'spoll.sampleruns on the executor, so it must not call PHP or the Zend allocator.
Related
- Bus PHP API
- Background sampling and events PHP API
- esp32-i2c-hal HAL
- esp32-executor Library