drivers: i2s: honour the configured timeout in i2s_buf_write()

[thc1006]

i2s_buf_write() acquires its memory block with K_FOREVER, so on a multithreaded build neither error code it documents for that step can be produced: -ENOMEM because K_FOREVER does not return it, which also leaves the if (ret < 0) below the call as dead code, and -EAGAIN because nothing ever times out. An application that exhausts the TX slab blocks forever instead of being told. Without CONFIG_MULTITHREADING the slab treats every timeout as no-wait, so only -EAGAIN is unreachable there.

Passing the configured timeout through fixes both, and k_mem_slab_alloc() already returns exactly the two documented codes, so the errno goes back unchanged rather than being flattened to -ENOMEM.

Fixes #113333

Two stages, not one deadline

Drivers already apply the same configured timeout when enqueueing the block, so after this change the call can spend it twice, once acquiring and once enqueueing. Making it a single end-to-end deadline would need a way to pass the remaining time into i2s_write(), and the API has no room for that today, so I documented it as a per-stage bound rather than quietly leave the impression it is one.

That also means no single timeout value reproduces the old combination of an unbounded acquisition and a bounded enqueue, which is what the migration note now says.

A related problem I am deliberately keeping out of this PR

Several drivers pass i2s_config.timeout straight into K_MSEC(). Z_TIMEOUT_MS() is MAX(t, 0), so SYS_FOREVER_MS becomes K_NO_WAIT there, and the field documents SYS_FOREVER_MS as a valid value. Four drivers do this; the twenty other call sites in the subsystem already convert with SYS_TIMEOUT_MS(). It predates this change and is a driver fix rather than an API one, so I filed it separately as #116030.

Testing

The two new tests queue NUM_TX_BLOCKS blocks without starting the stream, which leaves every one of them owned by the driver, then check that the next call reports -ENOMEM with a timeout of 0 and -EAGAIN with a finite one. Both fail before the driver's write(), so no loopback fixture is involved. Draining through i2s_buf_write() rather than the slab API keeps this usable from a user thread, since k_mem_slab_alloc() is not a syscall, so one helper covers the supervisor and userspace copies of the allocation.

Built for esp32s3_devkitc/esp32s3/procpu. I have not run the suite on hardware; it needs the loopback fixture.

[sylvioalves]

Please check z_vrfy_i2s_buf_write() in i2s_handlers.c as it would also need the same timeout.

[sylvioalves]

Suggested change

	: K_MSEC(tx_cfg->timeout));
	: SYS_TIMEOUT_MS(tx_cfg->timeout));

[thc1006]

Took it, and a bit further: SYS_TIMEOUT_MS maps SYS_FOREVER_MS itself, so the whole ternary goes.

[sylvioalves]

Would you also add an entry in the migration-guide file that i2s_buf_write() API now honors the timeout properly?

[thc1006]

Good catch on the verifier. It had the same K_FOREVER and was also flattening the result to -ENOMEM, so both now use SYS_TIMEOUT_MS and return what the slab gives. Migration-guide entry added under a new I2S section.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud