Low-power core

The esp32s31_lp remoteproc driver loads firmware into LP SRAM and exchanges 32-bit messages with the LP core through the hardware mailbox. The normal firmware name is esp32s31/s31-lp-core.elf. Startup and replacement are covered in LP firmware development.

Check startup and the timer

s31-lpctl status
s31-lpctl ping
s31-lpctl sleep-test 1000

status includes ready=1 once READY has arrived, the last message and mailbox counters. ping reports ready and rtt_us; the round-trip value varies. sleep-test accepts 10–5000 ms and sets DRY_RUN, so Linux stays awake. A successful timer test reports result=0 and the timer bit (0x1) in wake_reason. See the test handler and result formatting.

Test a GPIO transition

The CLI accepts LP GPIO0–7, level low or high, pull none, up or down, and a timeout of 10–5000 ms (default 1000 ms). Select a pin available on your board and keep it at the inactive level while ARM executes.

For GPIO3 high-level wake, start with the input low, then drive it high after arming and before the one-second timeout:

s31-lpctl gpio-test 3 high down 1000

For low-level wake, start high and then drive it low:

s31-lpctl gpio-test 3 low up 1000

The firmware configures the pull, waits 100 microseconds for the input to settle, and rejects an already-active input with S31_LP_SLEEP_ERR_WAKE_MASK. This check applies to DRY_RUN too. Matching the internal pull to the active level is therefore not a valid standalone test; an external circuit or strap can also change the initial level. See the ARM validation.

A successful GPIO3 test reports result=0, the GPIO bit (0x2) in wake_reason and bit 3 (0x8) in raw. A timeout means no accepted transition completed in the interval. Linux remains awake; passing this test does not establish system-suspend or deep-sleep wake reliability.

Devices and attributes

Interface	Description
`/dev/s31-lp`	Write exactly 4 bytes; read with a buffer of at least 4 bytes to receive one 32-bit mailbox word
`ready`	Whether a READY notification has been received
`last_message`	Last received word
`mailbox_stats`	Message, acknowledgement and timeout counts
`tx_message`	Send a mailbox word
`ping`	Start or read a PING/PONG test
`sleep_test`	Start or read a timer test
`gpio_test`	Start or read a GPIO test
`deep_sleep`	Read deep-sleep markers or request timed shutdown

The attributes belong to the bound LP platform device. Firmware selection and start/stop use remoteproc’s firmware and state attributes. Binary reads can block waiting for a word; a nonblocking empty read returns -EAGAIN. See the character-device implementation.

Mailbox and shared control block

Command words use the upper 16 bits for the operation and the lower 16 bits for a sequence number. READY (0x53310001) and WAKE (0x53310002) are fixed notifications. PING/PONG and STATUS accompany these sleep operations:

Operation	Purpose
PREPARE	Validate the request and supported wake configuration
ARM	Arm the transaction and its wake sources, including the inactive GPIO check
QUERY	Read state, result, wake reason and timestamps
RECLAIM	Return the completed transaction to Linux control
ABORT	Cancel the request and disarm wake sources

The shared block uses ABI version 1, with 28 packed 32-bit words (112 bytes) at 0x2E007C00. The final KiB of LP SRAM is reserved for it. Linux and LP firmware include the same protocol definition; OpenSBI’s current validation agrees with this version and layout.

Field group	Units / meaning
`deadline_lo`, `deadline_hi`	One relative interval in microseconds, despite the field name
`sleep_ticks_lo`, `sleep_ticks_hi`	Absolute RTC counter value when the timer starts / transaction is armed
`wake_ticks_lo`, `wake_ticks_hi`	Absolute RTC counter value when wake is recorded
`state`, `result`	Transaction state and protocol result code
`wake_reason`, `wake_raw`	Wake-source mask and source-specific raw bits

For retention (MEM), firmware starts the timer after OpenSBI publishes HP_ASLEEP; it does not consume the interval during Linux’s earlier device suspend work. See the timer conversion and retention start condition.

The request CRC covers bytes before request_crc; the response CRC covers bytes before response_crc, including request and result fields. Linux uses crc32_le(~0U, data, length) ^ ~0U and retries a response snapshot while LP is publishing it. The protocol header is the authoritative list of message codes, flags, states and fields; the CRC reader defines validation behavior.

System sleep commands and validation limits are in Power management.