Skip to main content

TECH VEDA

Corporate on-site training - Submit proposal Pick your modulesSharpen your kernel skills: deep dives, drivers, Yocto, CVEs, careers — updated daily. Read the blog →
Kernel Features

I2C Transfer Timeout in Linux 7.4: One Second or Computed?

Linux 7.4-rc can compute the I2C transfer timeout from message length. How to enable it, which driver uses it, and which kernels do not have it.

I2C Transfer Timeout in Linux 7.4: One Second or Computed?

Many I2C controller drivers wait one second for every transfer, short or long. Linux 7.4-rc adds a function to the I2C core that computes the I2C transfer timeout from the message length and the bus frequency. The option is CONFIG_I2C_DYNAMIC_TIMEOUT. It is disabled by default, and in 7.4-rc2 only the Qualcomm GENI I2C driver calls the function.

Many I2C controller drivers wait a fixed time for a transfer to finish. A common value is one second, which is also the default of the I2C core. The same second applies to a two-byte register read and to a message of several thousand bytes. This article explains what Linux 7.4-rc adds, how the I2C transfer timeout is computed and how to enable the option. The change affects you if your board uses the Qualcomm GENI I2C controller, or if you maintain an I2C controller driver. Boards with another I2C controller do not change. Client drivers do not change either. A sensor driver that reads registers through the API described in our article on the regmap subsystem receives the same error codes as before.

What drivers do today with a fixed I2C transfer timeout

Every I2C adapter has a timeout field, measured in jiffies. A controller driver can set the field. If it does not, the I2C core sets it in i2c_register_adapter():

	/* Set default timeout to 1 second if not already set */
	if (adap->timeout == 0)
		adap->timeout = HZ;

User space can change the field with the I2C_TIMEOUT ioctl on a /dev/i2c-N node. The argument is in units of 10 ms.

Some drivers do not read the field. Up to Linux 7.3, the Qualcomm GENI driver used its own constant, XFER_TIMEOUT, defined as HZ. The ioctl therefore did not change how long this driver waited.

One fixed timeout causes two problems.

  • The driver waits too long when a short transfer does not complete. Two data bytes at 100 kHz need 180 microseconds on the bus. If the device keeps the clock line low and never releases it, the driver still waits for the full second. It then cancels the transfer, which has its own fixed wait, and reports -ETIMEDOUT.
  • Long transfers can need more than one second. Each byte needs nine clock periods: eight data bits and one acknowledge bit. At 100 kHz, that is 90 microseconds per byte. A message of 11,112 bytes or more needs more than one second on the bus. The largest message, 65,535 bytes, needs about 5.9 seconds.

These figures are calculated, not measured. They count the data bytes only, as the kernel formula does.

What Linux 7.4 adds

The change has three parts. The first part is a Kconfig option:

config I2C_DYNAMIC_TIMEOUT
	bool "Dynamic per-transfer timeout based on message length"
	depends on I2C
	help
	  When enabled, the I2C core computes a per-transfer timeout from the
	  message length and bus frequency instead of using a static 1-second
	  default.  A timeout explicitly configured via the I2C_TIMEOUT userspace
	  interface always takes precedence over the computed value.

	  When disabled, the existing static 1-second timeout is preserved.

	  If unsure, say N.

The second part is an exported function for controller drivers:

void i2c_update_timeout(struct i2c_adapter *adap, u32 bus_freq_hz,
			size_t len, unsigned int safety_coeff,
			unsigned int min_usec);

The third part is a new field in struct i2c_adapter, named user_timeout. The I2C_TIMEOUT ioctl now writes its value to both timeout and user_timeout. The user_timeout field exists only when the option is enabled.

The help text says that “the I2C core computes” the timeout. The core does not do this for every driver. A controller driver must call the function. In 7.4-rc2, the only caller is drivers/i2c/busses/i2c-qcom-geni.c.

How the I2C transfer timeout is computed

This is the calculation:

	if (adap->user_timeout > 0) {
		adap->timeout = adap->user_timeout;
		return;
	}

	if (WARN_ON_ONCE(!bus_freq_hz))
		return;

	bit_usec = mul_u64_u32_div(len * 9, USEC_PER_SEC, bus_freq_hz);
	total_usec = bit_usec * safety_coeff + min_usec;

The function then converts total_usec to jiffies and writes the result to adap->timeout. If the bus frequency is zero, the function prints one warning and keeps the old value.

The minimum is added, not compared. The parameter is named min_usec and the comment describes it as a floor. The code adds it to the scaled transfer time. The result is therefore never smaller than min_usec.

The driver supplies the two constants. The GENI driver passes a multiplier of 10 and a minimum of 300,000 microseconds. The commit message says that the 300 ms is for clock stretching and for faulty devices that keep the clock line low.

The result is written to the adapter field. The first versions of the patch computed the timeout inside the GENI driver. A reviewer suggested the existing timeout field of struct i2c_adapter. The core also reads that field. When a driver returns -EAGAIN after arbitration loss, __i2c_transfer() stops its retries after adap->timeout jiffies. This matters only when adap->retries is greater than zero. The GENI driver does not set retries.

A value from user space has priority. If user_timeout is greater than zero, the function copies it to timeout and returns. The I2C_TIMEOUT ioctl with an argument of 0 sets user_timeout to zero. The computed value then applies again from the next transfer.

With the GENI constants, the I2C transfer timeout before conversion to jiffies is as follows. The old value was 1,000 ms in every row.

Message length100 kHz bus400 kHz bus
2 bytes301.8 ms300.45 ms
256 bytes530.4 ms357.6 ms
4,096 bytes3,986.4 ms1,221.6 ms
65,535 bytes59,281.5 ms15,045.4 ms

The computed value is longer than the old one-second timeout for messages of 778 bytes or more at 100 kHz, and of 3,112 bytes or more at 400 kHz.

The GENI driver calls the function before each wait, with the length of the current message. One case is different. In GPI multi-descriptor mode, the hardware generates one completion interrupt for several messages. For that case, the driver passes the sum of the lengths of all messages in the transfer.

Try it

Run these commands in the top directory of a 7.4-rc kernel tree that has a .config with CONFIG_I2C enabled:

raghu@techveda.org:~/linux$ ./scripts/config --enable I2C_DYNAMIC_TIMEOUT
raghu@techveda.org:~/linux$ make ARCH=arm64 olddefconfig
raghu@techveda.org:~/linux$ grep I2C_DYNAMIC_TIMEOUT .config

The last command prints CONFIG_I2C_DYNAMIC_TIMEOUT=y. The two commits change no defconfig file, and we found no defconfig that enables the option.

On the board, check the running kernel. The examples use a Qualcomm RB3 Gen 2 board, which uses the GENI controller:

root@qcs6490-rb3gen2:~# zcat /proc/config.gz | grep I2C_DYNAMIC_TIMEOUT
root@qcs6490-rb3gen2:~# grep -w i2c_update_timeout /proc/kallsyms

The first command needs CONFIG_IKCONFIG_PROC. The second command needs CONFIG_KALLSYMS. It prints at least one line when the option is enabled. If the I2C core is a module, the line ends with [i2c_core] and appears only while the module is loaded. When the option is disabled, the function is an empty inline stub, and the command prints nothing.

The commits add no sysfs or debugfs file, so you cannot read the computed value from user space. On a bus where every transfer completes, you see no difference. The GENI driver logs a timeout with dev_dbg(), so the default kernel log does not show it. The driver also has a geni_i2c_err trace event.

Some devices stretch the clock for longer than the computed value. For such an adapter, a user-space program can set its own I2C transfer timeout. The kernel needs CONFIG_I2C_CHARDEV. The lines below are a fragment. Put the two statements in main() and check both return values:

#include <fcntl.h>
#include <sys/ioctl.h>
#include <linux/i2c-dev.h>

int fd = open("/dev/i2c-1", O_RDWR);

/* 80 units of 10 ms = 800 ms for every message wait on this adapter */
ioctl(fd, I2C_TIMEOUT, 80);

The value belongs to the adapter, not to the file descriptor. It applies to every client on that adapter, including kernel drivers. It still applies after the program closes the file. The commits add no device tree property for it, so a product must set it during each boot.

A controller driver author can use the same method as the GENI driver. Call the function immediately before the wait. Then wait for adap.timeout:

	i2c_update_timeout(&gi2c->adap, gi2c->clk_freq_out, len,
			   I2C_TIMEOUT_SAFETY_COEFFICIENT,
			   I2C_TIMEOUT_MIN_USEC);
	time_left = wait_for_completion_timeout(&gi2c->done, gi2c->adap.timeout);

Which kernels have it

The two commits are in Linus Torvalds’s tree and first appear in the v7.4-rc1 tag. Linux 7.4 is not released yet. On 15 November 2026, kernel.org lists 7.4-rc2 as mainline.

We checked the stable tree for the function name in drivers/i2c/i2c-core-base.c. It is absent from every stable and longterm series from 5.10.y to 7.3.y. A team that uses a vendor BSP based on one of these series will not find the option unless the vendor added the two commits.

Limits

  • The GENI driver changes even when the option is disabled. The new code waits for adap.timeout in place of the removed constant. With the option disabled, that field contains the one-second default. However, the I2C_TIMEOUT ioctl now changes the timeout of this driver, which it did not do in 7.3. Do not pass 0 when the option is disabled. According to the source code, the field then becomes zero. A wait of zero jiffies lasts only until the next timer tick, and a transfer that does not complete before that tick reports a timeout. We did not test this on hardware.
  • Short transfers on slow devices. For small messages, the GENI I2C transfer timeout decreases from 1,000 ms to about 300 ms. A device that keeps the clock line low for longer than that worked in 7.3 but reports a timeout with the option enabled. Use the ioctl for such an adapter.
  • Long transfers wait much longer. With the option enabled, a 4,096-byte transfer at 100 kHz that does not complete waits about 4 seconds. The largest message waits about 59 seconds.
  • The error path has other waits. After the transfer wait ends, the GENI driver cancels the transfer. The cancel, abort and reset waits keep their fixed values. The time to report an error is therefore longer than the computed value.
  • Multiplexers. Each channel of an I2C multiplexer is a separate adapter with its own fields. The GENI driver reads the fields of its own adapter. To override the timeout, call the ioctl on the device node of the root adapter.

The option depends only on I2C. It has no architecture dependency and no relation to PREEMPT_RT.

What was checked and what could not be verified

We read both commits and the v5, v7, v8 and v9 mailing-list threads. We read the relevant I2C source files at v7.4-rc2 and the GENI driver at v7.3. We searched the complete v7.3 to v7.4-rc2 patch for other callers and for defconfig changes. We found none.

We did not run this on hardware, and this article contains no captured output. The table values are calculated and do not include the rounding to jiffies. We did not check linux-next for other drivers that call the function. We did not check whether vendor kernels for Qualcomm boards use this driver.

Key takeaways

  • Linux 7.4-rc1 adds i2c_update_timeout() and CONFIG_I2C_DYNAMIC_TIMEOUT. The option is disabled by default, and only the Qualcomm GENI I2C driver calls the function.
  • With the GENI constants, the I2C transfer timeout is ten times the transfer time plus 300 ms.
  • A value set with the I2C_TIMEOUT ioctl has priority over the computed value.
  • No stable or longterm series contains the change.
Was this worth your time?

Frequently asked questions

Does CONFIG_I2C_DYNAMIC_TIMEOUT change the timeout on every I2C bus?

No. A computed I2C transfer timeout applies only to a controller driver that calls the new function. In 7.4-rc2, that is the Qualcomm GENI I2C driver only.

Which kernel version first has the computed I2C transfer timeout?

The commits first appear in v7.4-rc1. Linux 7.4 is not released yet. No stable or longterm series from 5.10.y to 7.3.y contains them.

Can user space override the computed value?

Yes. The I2C_TIMEOUT ioctl has priority over the computed value. The argument is in units of 10 ms.

References

RB
Raghu Bharadwaj

Founder, TECH VEDA — 20+ years teaching the Linux kernel, device drivers and embedded systems.

Follow on LinkedIn

Get new posts by email

Kernel, embedded Linux and AI-era engineering — a few sharp reads a month. No spam.

We email occasionally and never share your address.