hw/i2c: Add remote I2C master with host CUSE bridge
PATCH v5 1/1 hw/i2c: Add remote I2C master with host CUSE bridge
Add a "remote-i2c-master" device that exposes a QEMU I2C bus to the host system through a FUSE/CUSE character device. This lets external host programs and standard i2c-tools interact with I2C slaves emulated inside QEMU as if they were real devices attached to the host.
The implementation is split into three layers:
- A non-blocking finite state machine that drives the QEMU I2C master. It is pumped by a QEMU Bottom Half and uses virtual timers to yield during long transfers and to model clock stretching for asynchronous slaves, so the main loop is never blocked. The FSM walks IDLE -> ADDR -> SEND/RECV -> WAIT_STRETCH -> END -> FINISHED and handles NACKs (ENXIO), lost arbitration (EBUSY, with optional back-off and retry), stretch timeouts, and manual abort/reset.
- An abstract RemoteI2CBackend QOM base class that decouples the internal I2C hardware state machine (the frontend) from any host-specific transport, exposing on_tx_complete and on_tx_error virtual callbacks.
- A concrete remote-i2c-backend-cuse backend implementing that transport over CUSE. It manages the FUSE session and integrates its file descriptors into QEMU's main AioContext event loop, translates Linux I2C_RDWR, I2C_SMBUS and I2C_SLAVE ioctls into generic byte streams for the FSM, and formats responses back into Linux I2C/SMBus structures for the FUSE driver. SMBus repeated start is supported for atomic write-then-read operations.
Example usage:
-device remote-i2c-master,i2cbus=i2c-bus.0,devname=i2c-33 -object remote-i2c-backend-cuse,id=b0,devname=i2c-33
This creates /dev/i2c-33 on the host, usable with i2c-tools:
i2cdetect -y -l
i2cget -y <bus_id> <addr> <reg>
---
v2:
- docs/system/devices/remote-i2c-master.rst: Documented concurrent bus access details and the 'raise-arbitrage-lost' property.
---
v3:
- qapi/qom.json: Fix RemoteI2CBackendCuseProperties formatting and expand member documentation (devname, fuse-opts, debug).
- tests/qtest: Add remote-i2c-cuse-test covering capabilities, functional smoke test, synchronous sensor read/write.
---
v4:
- qapi: reference the rst doc via :doc:
- qapi: fuse-opts is now ['str'] instead of a space-separated string
- qapi: drop redundant 'debug' property (pass -d via fuse-opts)
---
v5:
- docs/system/device-emulation.rst: add remote-i2c-master.rst to the toctree under "Emulated Devices"
- qapi/qom.json: move RemoteI2CBackendCuseProperties definition before RemoteObjectProperties as requested; change "for usage information" to "for detailed usage information"
---
--- docs/system/device-emulation.rst | 1 + docs/system/devices/remote-i2c-master.rst | 217 ++++ hw/i2c/Kconfig | 5 + hw/i2c/meson.build | 6 + hw/i2c/remote-i2c-backend.c | 30 + hw/i2c/remote-i2c-cuse.c | 1173 +++++++++++++++++++++ hw/i2c/remote-i2c-fsm.c | 521 +++++++++ hw/i2c/remote-i2c-master.c | 145 +++ hw/i2c/trace-events | 29 + include/hw/i2c/remote-i2c-backend.h | 70 ++ include/hw/i2c/remote-i2c-cuse.h | 93 ++ include/hw/i2c/remote-i2c-master.h | 77 ++ qapi/qom.json | 29 + tests/qtest/meson.build | 2 + tests/qtest/remote-i2c-cuse-test.c | 326 ++++++ 15 files changed, 2724 insertions(+) create mode 100644 docs/system/devices/remote-i2c-master.rst create mode 100644 hw/i2c/remote-i2c-backend.c create mode 100644 hw/i2c/remote-i2c-cuse.c create mode 100644 hw/i2c/remote-i2c-fsm.c create mode 100644 hw/i2c/remote-i2c-master.c create mode 100644 include/hw/i2c/remote-i2c-backend.h create mode 100644 include/hw/i2c/remote-i2c-cuse.h create mode 100644 include/hw/i2c/remote-i2c-master.h create mode 100644 tests/qtest/remote-i2c-cuse-test.c
docs/system/device-emulation.rst +1 -0
@@ -95,6 +95,7 @@ Emulated Devices devices/keyboard.rst devices/net.rst devices/nvme.rst + devices/remote-i2c-master.rst devices/scsi/index.rst devices/usb-u2f.rst devices/usb.rst
docs/system/devices/remote-i2c-master.rst new file +217 -0
217 lines not on this page · raw message
hw/i2c/Kconfig +5 -0
@@ -49,3 +49,8 @@ config PMBUS config BCM2835_I2C bool select I2C + +config REMOTE_I2C_MASTER + bool + select I2C + default y if I2C_DEVICES
hw/i2c/meson.build +6 -0
@@ -18,4 +18,10 @@ i2c_ss.add(when: 'CONFIG_PPC4XX', if_true: files('ppc4xx_i2c.c')) i2c_ss.add(when: 'CONFIG_PCA954X', if_true: files('i2c_mux_pca954x.c')) i2c_ss.add(when: 'CONFIG_PMBUS', if_true: files('pmbus_device.c')) i2c_ss.add(when: 'CONFIG_BCM2835_I2C', if_true: files('bcm2835_i2c.c')) +i2c_ss.add(when: 'CONFIG_REMOTE_I2C_MASTER', if_true: files( + 'remote-i2c-master.c', + 'remote-i2c-backend.c', + 'remote-i2c-cuse.c', + 'remote-i2c-fsm.c' +)) system_ss.add_all(when: 'CONFIG_I2C', if_true: i2c_ss)
hw/i2c/remote-i2c-backend.c new file +30 -0
@@ -0,0 +1,30 @@ +// SPDX-License-Identifier: GPL-2.0-or-later +/* +* Remote I2C Backend (Abstract Base Class) +* +* This module defines the abstract backend interface for the Remote I2C Master. +* It provides the QEMU Object Model (QOM) base class that strictly decouples +* the internal QEMU I2C hardware state machine (the frontend) from +* host-specific transport layers. +* +* Author: +* Ilya Chichkov <[email protected]> +* +*/ +#include "qemu/osdep.h" +#include "hw/i2c/remote-i2c-backend.h" + +static const TypeInfo remote_i2c_backend_info = { + .name =TYPE_REMOTE_I2C_BACKEND , + .parent =TYPE_OBJECT , + .instance_size =sizeof (RemoteI2CBackend), + .class_size =sizeof (RemoteI2CBackendClass), + .abstract = true, +}; + +static void remote_i2c_backend_register_types (void ) +{ +type_register_static (&remote_i2c_backend_info); +} + +type_init (remote_i2c_backend_register_types)
hw/i2c/remote-i2c-cuse.c new file +1173 -0
1,173 lines not on this page · raw message
hw/i2c/remote-i2c-fsm.c new file +521 -0
521 lines not on this page · raw message
hw/i2c/remote-i2c-master.c new file +145 -0
145 lines not on this page · raw message
hw/i2c/trace-events +29 -0
@@ -61,3 +61,32 @@ pca954x_read_data(uint8_t value) "PCA954X read data: 0x%02x" imx_i2c_read(const char *id, const char *reg, uint64_t ofs, uint64_t value) "%s:[%s (0x%" PRIx64 ")] -> 0x%02" PRIx64 imx_i2c_write(const char *id, const char *reg, uint64_t ofs, uint64_t value) "%s:[%s (0x%" PRIx64 ")] <- 0x%02" PRIx64 + +# remote-i2c-master.c +remote_i2c_master_realize(void) "device realized" +remote_i2c_master_reset_enter(void) "reset enter" +remote_i2c_master_backend_select(const char *backend) "selected backend: %s" + +# remote-i2c-fsm.c +remote_i2c_master_bus_state_change(const char *old, const char *new) "bus State: %s -> %s" +remote_i2c_master_async_ack(void) "async ACK received" +remote_i2c_master_abort(int error, uint8_t addr, const char *reason) "transaction ABORTED (errno=%d) addr=0x%02x, reason: %s" +remote_i2c_master_timeout(uint16_t timeout) "watchdog timer expired (timeout_ms=%d)" +remote_i2c_master_stretch_delay(uint16_t delay) "master simulating stretch delay: %d" +remote_i2c_master_send_byte(uint8_t byte) "wire TX: 0x%02x" +remote_i2c_master_recv_byte(uint8_t byte) "wire RX: 0x%02x" +remote_i2c_master_arbitration_lost(const char *abort_transaction) "arbitration lost, %s" + +# remote-i2c-cuse.c +remote_i2c_master_fuse_export(void) "FUSE session setup complete" +remote_i2c_master_fuse_io_read(void) "FUSE event loop: reading buf" +remote_i2c_master_i2cdev_init(void) "CUSE init" +remote_i2c_master_i2cdev_open(void) "CUSE open" +remote_i2c_master_i2cdev_release(void) "CUSE release" +remote_i2c_master_i2cdev_ioctl(int cmd) "IOCTL Start cmd: 0x%x" +remote_i2c_master_i2cdev_ioctl_finished(int cmd) "IOCTL Finish cmd: 0x%x" +remote_i2c_master_i2cdev_functional(void) "IOCTL: Query Functionality" +remote_i2c_master_i2cdev_address(uint32_t address) "IOCTL: Set slave address: 0x%x" +remote_i2c_master_i2cdev_smbus(uint8_t state) "IOCTL: SMBus machine state: 0x%x" +remote_i2c_master_i2cdev_send(uint32_t size) "TX start size: 0x%x" +remote_i2c_master_i2cdev_receive(uint32_t size) "RX start size: 0x%x"
include/hw/i2c/remote-i2c-backend.h new file +70 -0
70 lines not on this page · raw message
include/hw/i2c/remote-i2c-cuse.h new file +93 -0
93 lines not on this page · raw message
include/hw/i2c/remote-i2c-master.h new file +77 -0
77 lines not on this page · raw message
qapi/qom.json +29 -0
@@ -840,6 +840,31 @@ 'data': { 'chardev': 'str', '*log': 'str' } } +## +# @RemoteI2CBackendCuseProperties: +# +# Properties for the CUSE remote I2C backend. See +# :doc:`/system/devices/remote-i2c-master` for detailed +# usage information. +# +# @devname: The name of the character device node to create under /dev +# (e.g., 'i2c-33' creates /dev/i2c-33). The node is accessible +# via the standard Linux I2C device interface and usable directly +# with i2c-tools and the Linux i2c-dev API. +# +# @fuse-opts: Options passed verbatim to the FUSE/CUSE session at +# mount time, one option (or argument) per list element. For +# example ['-d'] enables debug tracing, and ['-o', 'allow_other'] +# grants other users access. See the libfuse documentation for +# the full list of supported options. +# +# Since: 11.2 +## +{ 'struct': 'RemoteI2CBackendCuseProperties', + 'data': { 'devname': 'str', + '*fuse-opts': ['str'] }, + 'if': 'CONFIG_LINUX' } + ## # @RemoteObjectProperties: #
@@ -1258,6 +1283,8 @@ 'tls-creds-psk', 'tls-creds-x509', 'tls-cipher-suites', + { 'name': 'remote-i2c-backend-cuse', + 'if': 'CONFIG_LINUX' }, { 'name': 'x-remote-object', 'features': [ 'unstable' ] }, { 'name': 'x-vfio-user-server', 'features': [ 'unstable' ] } ] }
@@ -1334,6 +1361,8 @@ 'tls-creds-psk': 'TlsCredsPskProperties', 'tls-creds-x509': 'TlsCredsX509Properties', 'tls-cipher-suites': 'TlsCredsProperties', + 'remote-i2c-backend-cuse': { 'type': 'RemoteI2CBackendCuseProperties', + 'if': 'CONFIG_LINUX' }, 'x-remote-object': 'RemoteObjectProperties', 'x-vfio-user-server': 'VfioUserServerProperties' } }
tests/qtest/meson.build +2 -0
@@ -54,6 +54,7 @@ qtests_i386 = \ (slirp.found() ? ['pxe-test'] : []) + \ qtests_filter + \ (config_all_devices.has_key('CONFIG_ACPI_VMGENID') ? ['vmgenid-test'] : []) + \ + (config_all_devices.has_key('CONFIG_REMOTE_I2C_MASTER') and host_os == 'linux' ? ['remote-i2c-cuse-test'] : []) + \ (config_all_devices.has_key('CONFIG_AHCI_ICH9') and have_tools ? ['ahci-test'] : []) + \ (config_all_devices.has_key('CONFIG_AHCI_ICH9') ? ['tco-test'] : []) + \ (config_all_devices.has_key('CONFIG_FDC_ISA') ? ['fdc-test'] : []) + \
@@ -236,6 +237,7 @@ qtests_stm32l4x5 = \ qtests_arm = \ (config_all_devices.has_key('CONFIG_MPS2') ? ['sse-timer-test'] : []) + \ + (config_all_devices.has_key('CONFIG_REMOTE_I2C_MASTER') and host_os == 'linux' ? ['remote-i2c-cuse-test'] : []) + \ (config_all_devices.has_key('CONFIG_CMSDK_APB_DUALTIMER') ? ['cmsdk-apb-dualtimer-test'] : []) + \ (config_all_devices.has_key('CONFIG_CMSDK_APB_TIMER') ? ['cmsdk-apb-timer-test'] : []) + \ (config_all_devices.has_key('CONFIG_STELLARIS') or
tests/qtest/remote-i2c-cuse-test.c new file +326 -0
326 lines not on this page · raw message
Signature · 1 line
2.43.0
Quoted 80 lines · Ilya Chichkov
Add a "remote-i2c-master" device that exposes a QEMU I2C bus to the host system through a FUSE/CUSE character device. This lets external host programs and standard i2c-tools interact with I2C slaves emulated inside QEMU as if they were real devices attached to the host.
The implementation is split into three layers:
- A non-blocking finite state machine that drives the QEMU I2C master. It is pumped by a QEMU Bottom Half and uses virtual timers to yield during long transfers and to model clock stretching for asynchronous slaves, so the main loop is never blocked. The FSM walks IDLE -> ADDR -> SEND/RECV ->
WAIT_STRETCH-> END -> FINISHED and handles NACKs (ENXIO), lost arbitration (EBUSY, with optional back-off and retry), stretch timeouts, and manual abort/reset.- An abstract RemoteI2CBackend QOM base class that decouples the internal I2C hardware state machine (the frontend) from any host-specific transport, exposing
on_tx_completeandon_tx_errorvirtual callbacks.- A concrete remote-i2c-backend-cuse backend implementing that transport over CUSE. It manages the FUSE session and integrates its file descriptors into QEMU's main AioContext event loop, translates Linux
I2C_RDWR,I2C_SMBUSandI2C_SLAVEioctls into generic byte streams for the FSM, and formats responses back into Linux I2C/SMBus structures for the FUSE driver. SMBus repeated start is supported for atomic write-then-read operations.Example usage:
-device remote-i2c-master,i2cbus=i2c-bus.0,devname=i2c-33 -object remote-i2c-backend-cuse,id=b0,devname=i2c-33This creates
/dev/i2c-33on the host, usable with i2c-tools:i2cdetect -y -l
i2cget -y <bus_id> <addr> <reg>Signed-off-by Ilya Chichkov <[email protected]>---
v2:
-docs/system/devices/remote-i2c-master.rst: Documented concurrent bus access details and the 'raise-arbitrage-lost' property.
---
v3:
-qapi/qom.json: Fix RemoteI2CBackendCuseProperties formatting and expand member documentation (devname, fuse-opts, debug).
- tests/qtest: Add remote-i2c-cuse-test covering capabilities, functional smoke test, synchronous sensor read/write.
---
v4:
- qapi: reference the rst doc via :doc:
- qapi: fuse-opts is now ['str'] instead of a space-separated string
- qapi: drop redundant 'debug' property (pass -d via fuse-opts)
---
v5:
-docs/system/device-emulation.rst: addremote-i2c-master.rstto the toctree under "Emulated Devices"
-qapi/qom.json: move RemoteI2CBackendCuseProperties definition before RemoteObjectProperties as requested; change "for usage information" to "for detailed usage information"
------ docs/system/device-emulation.rst | 1 + docs/system/devices/remote-i2c-master.rst | 217 ++++ hw/i2c/Kconfig | 5 + hw/i2c/meson.build | 6 + hw/i2c/remote-i2c-backend.c | 30 + hw/i2c/remote-i2c-cuse.c | 1173 +++++++++++++++++++++ hw/i2c/remote-i2c-fsm.c | 521 +++++++++ hw/i2c/remote-i2c-master.c | 145 +++ hw/i2c/trace-events | 29 + include/hw/i2c/remote-i2c-backend.h | 70 ++ include/hw/i2c/remote-i2c-cuse.h | 93 ++ include/hw/i2c/remote-i2c-master.h | 77 ++ qapi/qom.json | 29 + tests/qtest/meson.build | 2 + tests/qtest/remote-i2c-cuse-test.c | 326 ++++++ 15 files changed, 2724 insertions(+)
Quoted 9 lines
create mode 100644
docs/system/devices/remote-i2c-master.rstcreate mode 100644hw/i2c/remote-i2c-backend.ccreate mode 100644hw/i2c/remote-i2c-cuse.c
create mode 100644hw/i2c/remote-i2c-fsm.c
create mode 100644hw/i2c/remote-i2c-master.ccreate mode 100644include/hw/i2c/remote-i2c-backend.hcreate mode 100644include/hw/i2c/remote-i2c-cuse.hcreate mode 100644include/hw/i2c/remote-i2c-master.hcreate mode 100644tests/qtest/remote-i2c-cuse-test.c
If I understand this proposal correctly, it lets host-side i2c tools talk to emulated I2C devices. The example is i2cdetect/i2cget against a tmp105 on an Aspeed bus.
QEMU already has mechanisms for this though. qtest can read/write I2C registers programmatically, QMP can query device state, and the guest OS itself sees the I2C bus natively.
The dependency cost seems high for the use case: libfuse3 + the cuse kernel module pulled into the system emulator build. It's also ~3K lines of new code, three QOM types, FUSE session management, etc. The surface area for bugs is large. It's a heavy burden for what it gives.
I think a lighter QMP-based approach would serve the same purpose, maybe better, and fit in better in QEMU, without the dependency and maintenance cost:
- No host kernel dependency
- Works remotely (QMP over socket)
- Fits QEMU's existing management model
- Much less code
- Testable without root or kernel modules
Have you considered extending QMP with an I2C transaction command instead? Something like:
{ 'command': 'i2c-transfer',
'data': { 'bus': 'str',
'address': 'uint8',
'read': 'bool',
'*data': ['uint8'],
'*length': 'uint16' },
'returns': { '*data': ['uint8'] } }Thanks,
C.
Hi Cédric,
Quoted 3 lines · Cédric Le Goater
I think a lighter QMP-based approach would serve the same purpose, maybe better, and fit in better in QEMU, without the dependency and maintenance cost:
As Corey and I discussed earlier in the thread, QMP doesn't cover the primary motivation for this patch: zero-code transparency for existing host software.
An i2c-transfer QMP command would be a great addition for custom scripts, but the main goal here is to allow native Linux user-space binaries (like i2c-tools,
lm-sensors) running on the host to talk to QEMU's I2C slaves unmodified, simply by opening /dev/i2c-N. Rewriting legacy test suites to speak QMP JSON over a socket is often not feasible.
Quoted 3 lines
The dependency cost seems high for the use case: libfuse3 + the cuse kernel module pulled into the system emulator build. It's also ~3K lines of new code, three QOM types, FUSE session management, etc.
Regarding dependencies, libfuse3 is actually not new to the project — it has been a supported QEMU dependency for a long time (already used by the block layer in block/export/fuse.c). Also, just to clarify the diff: the core implementation is roughly ~2K lines. The remaining ~900 lines are dedicated entirely to qtests and RST documentation.
However, I agree about not polluting the core emulation build with Linux-specific
headers and libfuse3. The maintenance cost must be minimized. To address this, I've refactored the architecture for v6 to ensure strict isolation:
- All Linux and FUSE-specific headers are removed from public QEMU headers. The internal state structure is now opaque and hidden insideremote-i2c-cuse.c.
- The CUSE backend is isolated behind its own CONFIG_REMOTE_I2C_BACKEND_CUSE in Kconfig and meson.build, strictly depending on LINUX and fuse3.
On macOS, Windows, or minimalistic builds without libfuse, QEMU will build cleanly without pulling in this backend or any of its dependencies.
Would making the CUSE transport a strictly optional, isolated Linux-only backend alleviate your concerns regarding the hardware emulation core?
Best regards,
Ilya
ср, 22 июл. 2026 г. в 20:42, Cédric Le Goater <[email protected]>:
Quoted 132 lines · Ilya Chichkov
Quoted 80 lines
Add a "remote-i2c-master" device that exposes a QEMU I2C bus to the host system through a FUSE/CUSE character device. This lets external host programs and standard i2c-tools interact with I2C slaves emulated inside QEMU as if they were real devices attached to the host.
The implementation is split into three layers:
- A non-blocking finite state machine that drives the QEMU I2C master. It is pumped by a QEMU Bottom Half and uses virtual timers to yield during long transfers and to model clock stretching for asynchronous slaves, so the main loop is never blocked. The FSM walks IDLE -> ADDR -> SEND/RECV ->
WAIT_STRETCH-> END -> FINISHED and handles NACKs (ENXIO), lost arbitration (EBUSY, with optional back-off and retry), stretch timeouts, and manual abort/reset.- An abstract RemoteI2CBackend QOM base class that decouples the internal I2C hardware state machine (the frontend) from any host-specific transport, exposing
on_tx_completeandon_tx_errorvirtual callbacks.- A concrete remote-i2c-backend-cuse backend implementing that transport over CUSE. It manages the FUSE session and integrates its file descriptors into QEMU's main AioContext event loop, translates Linux
I2C_RDWR,I2C_SMBUSandI2C_SLAVEioctls into generic byte streams for the FSM, and formats responses back into Linux I2C/SMBus structures for the FUSE driver. SMBus repeated start is supported for atomic write-then-read operations.Example usage:
-device remote-i2c-master,i2cbus=i2c-bus.0,devname=i2c-33 -object remote-i2c-backend-cuse,id=b0,devname=i2c-33This creates
/dev/i2c-33on the host, usable with i2c-tools:i2cdetect -y -l
i2cget -y <bus_id> <addr> <reg>Signed-off-by Ilya Chichkov <[email protected]>---
v2:
-docs/system/devices/remote-i2c-master.rst: Documented concurrent bus access details and the 'raise-arbitrage-lost' property.
---
v3:
-qapi/qom.json: Fix RemoteI2CBackendCuseProperties formatting and expand member documentation (devname, fuse-opts, debug).
- tests/qtest: Add remote-i2c-cuse-test covering capabilities, functional smoke test, synchronous sensor read/write.
---
v4:
- qapi: reference the rst doc via :doc:
- qapi: fuse-opts is now ['str'] instead of a space-separated string
- qapi: drop redundant 'debug' property (pass -d via fuse-opts)
---
v5:
-docs/system/device-emulation.rst: addremote-i2c-master.rstto the toctree under "Emulated Devices"
-qapi/qom.json: move RemoteI2CBackendCuseProperties definition before RemoteObjectProperties as requested; change "for usage information" to "for detailed usage information"
------ docs/system/device-emulation.rst | 1 + docs/system/devices/remote-i2c-master.rst | 217 ++++ hw/i2c/Kconfig | 5 + hw/i2c/meson.build | 6 + hw/i2c/remote-i2c-backend.c | 30 + hw/i2c/remote-i2c-cuse.c | 1173 +++++++++++++++++++++ hw/i2c/remote-i2c-fsm.c | 521 +++++++++ hw/i2c/remote-i2c-master.c | 145 +++ hw/i2c/trace-events | 29 + include/hw/i2c/remote-i2c-backend.h | 70 ++ include/hw/i2c/remote-i2c-cuse.h | 93 ++ include/hw/i2c/remote-i2c-master.h | 77 ++ qapi/qom.json | 29 + tests/qtest/meson.build | 2 + tests/qtest/remote-i2c-cuse-test.c | 326 ++++++ 15 files changed, 2724 insertions(+)Quoted 9 lines
create mode 100644
docs/system/devices/remote-i2c-master.rstcreate mode 100644hw/i2c/remote-i2c-backend.ccreate mode 100644hw/i2c/remote-i2c-cuse.c
create mode 100644hw/i2c/remote-i2c-fsm.c
create mode 100644hw/i2c/remote-i2c-master.ccreate mode 100644include/hw/i2c/remote-i2c-backend.hcreate mode 100644include/hw/i2c/remote-i2c-cuse.hcreate mode 100644include/hw/i2c/remote-i2c-master.hcreate mode 100644tests/qtest/remote-i2c-cuse-test.cIf I understand this proposal correctly, it lets host-side i2c tools talk to emulated I2C devices. The example is i2cdetect/i2cget against a tmp105 on an Aspeed bus.
QEMU already has mechanisms for this though. qtest can read/write I2C registers programmatically, QMP can query device state, and the guest OS itself sees the I2C bus natively.
The dependency cost seems high for the use case: libfuse3 + the cuse kernel module pulled into the system emulator build. It's also ~3K lines of new code, three QOM types, FUSE session management, etc. The surface area for bugs is large. It's a heavy burden for what it gives.
I think a lighter QMP-based approach would serve the same purpose, maybe better, and fit in better in QEMU, without the dependency and maintenance cost:
- No host kernel dependency
- Works remotely (QMP over socket)
- Fits QEMU's existing management model
- Much less code
- Testable without root or kernel modulesHave you considered extending QMP with an I2C transaction command instead? Something like:
{ 'command': 'i2c-transfer', 'data': { 'bus': 'str', 'address': 'uint8', 'read': 'bool', '*data': ['uint8'], '*length': 'uint16' }, 'returns': { '*data': ['uint8'] } }Thanks,
C.
Quoted 10 lines · Ilya Chichkov
Hi Cédric,
Quoted 3 lines · Cédric Le Goater
I think a lighter QMP-based approach would serve the same purpose, maybe better, and fit in better in QEMU, without the dependency and maintenance cost:
As Corey and I discussed earlier in the thread, QMP doesn't cover the primary motivation for this patch: zero-code transparency for existing host software.
Quoted 6 lines
An
i2c-transferQMP command would be a great addition for custom scripts, but the main goal here is to allow native Linux user-space binaries (like i2c-tools,
lm-sensors) running on the host to talk to QEMU's I2C slaves unmodified, simply by opening/dev/i2c-N. Rewriting legacy test suites to speak QMP JSON over a socket is often not feasible.
I think what Cédric is saying here is that if you provided a generic QMP interface that allowed these sorts of operations and wrote an external program that used said interface to provide a fuse interface, that would be better. It has a number of advantages:
* You add an interface to QEMU that others can easily use to test devices.
* You are not tied to QEMU when you want to extend the functions of the fuse interface.
* It's one less dependency in QEMU. QEMU has a *lot* of dependencies, and the fewer the better.
The only disadvantage I can think of is that it's one more piece of software if you are setting this up.
This is not a big piece of software, I agree, but from experience I think you will be happier with this sort of design in the long run. It puts you more in control of what you are doing.
And, of course, it makes the QEMU maintainers happier :-).
-corey
Quoted 165 lines
Quoted 4 lines
The dependency cost seems high for the use case: libfuse3 + the cuse kernel module pulled into the system emulator build. It's also ~3K lines of new code, three QOM types, FUSE session management, etc.
Regarding dependencies,
libfuse3is actually not new to the project — it has been a supported QEMU dependency for a long time (already used by the block layer inblock/export/fuse.c). Also, just to clarify the diff: the core implementation is roughly ~2K lines. The remaining ~900 lines are dedicated entirely to qtests and RST documentation.However, I agree about not polluting the core emulation build with Linux-specific
headers and libfuse3. The maintenance cost must be minimized. To address this, I've refactored the architecture for v6 to ensure strict isolation:- All Linux and FUSE-specific headers are removed from public QEMU headers. The internal state structure is now opaque and hidden inside
remote-i2c-cuse.c.
- The CUSE backend is isolated behind its ownCONFIG_REMOTE_I2C_BACKEND_CUSEinKconfigand meson.build, strictly depending on LINUX and fuse3.On macOS, Windows, or minimalistic builds without libfuse, QEMU will build cleanly without pulling in this backend or any of its dependencies.
Would making the CUSE transport a strictly optional, isolated Linux-only backend alleviate your concerns regarding the hardware emulation core?
Best regards,
Ilyaср, 22 июл. 2026 г. в 20:42, Cédric Le Goater <[email protected]>:
Quoted 132 lines · Ilya Chichkov
Quoted 80 lines
Add a "remote-i2c-master" device that exposes a QEMU I2C bus to the host system through a FUSE/CUSE character device. This lets external host programs and standard i2c-tools interact with I2C slaves emulated inside QEMU as if they were real devices attached to the host.
The implementation is split into three layers:
- A non-blocking finite state machine that drives the QEMU I2C master. It is pumped by a QEMU Bottom Half and uses virtual timers to yield during long transfers and to model clock stretching for asynchronous slaves, so the main loop is never blocked. The FSM walks IDLE -> ADDR -> SEND/RECV ->
WAIT_STRETCH-> END -> FINISHED and handles NACKs (ENXIO), lost arbitration (EBUSY, with optional back-off and retry), stretch timeouts, and manual abort/reset.- An abstract RemoteI2CBackend QOM base class that decouples the internal I2C hardware state machine (the frontend) from any host-specific transport, exposing
on_tx_completeandon_tx_errorvirtual callbacks.- A concrete remote-i2c-backend-cuse backend implementing that transport over CUSE. It manages the FUSE session and integrates its file descriptors into QEMU's main AioContext event loop, translates Linux
I2C_RDWR,I2C_SMBUSandI2C_SLAVEioctls into generic byte streams for the FSM, and formats responses back into Linux I2C/SMBus structures for the FUSE driver. SMBus repeated start is supported for atomic write-then-read operations.Example usage:
-device remote-i2c-master,i2cbus=i2c-bus.0,devname=i2c-33 -object remote-i2c-backend-cuse,id=b0,devname=i2c-33This creates
/dev/i2c-33on the host, usable with i2c-tools:i2cdetect -y -l
i2cget -y <bus_id> <addr> <reg>Signed-off-by Ilya Chichkov <[email protected]>---
v2:
-docs/system/devices/remote-i2c-master.rst: Documented concurrent bus access details and the 'raise-arbitrage-lost' property.
---
v3:
-qapi/qom.json: Fix RemoteI2CBackendCuseProperties formatting and expand member documentation (devname, fuse-opts, debug).
- tests/qtest: Add remote-i2c-cuse-test covering capabilities, functional smoke test, synchronous sensor read/write.
---
v4:
- qapi: reference the rst doc via :doc:
- qapi: fuse-opts is now ['str'] instead of a space-separated string
- qapi: drop redundant 'debug' property (pass -d via fuse-opts)
---
v5:
-docs/system/device-emulation.rst: addremote-i2c-master.rstto the toctree under "Emulated Devices"
-qapi/qom.json: move RemoteI2CBackendCuseProperties definition before RemoteObjectProperties as requested; change "for usage information" to "for detailed usage information"
------ docs/system/device-emulation.rst | 1 + docs/system/devices/remote-i2c-master.rst | 217 ++++ hw/i2c/Kconfig | 5 + hw/i2c/meson.build | 6 + hw/i2c/remote-i2c-backend.c | 30 + hw/i2c/remote-i2c-cuse.c | 1173 +++++++++++++++++++++ hw/i2c/remote-i2c-fsm.c | 521 +++++++++ hw/i2c/remote-i2c-master.c | 145 +++ hw/i2c/trace-events | 29 + include/hw/i2c/remote-i2c-backend.h | 70 ++ include/hw/i2c/remote-i2c-cuse.h | 93 ++ include/hw/i2c/remote-i2c-master.h | 77 ++ qapi/qom.json | 29 + tests/qtest/meson.build | 2 + tests/qtest/remote-i2c-cuse-test.c | 326 ++++++ 15 files changed, 2724 insertions(+)Quoted 9 lines
create mode 100644
docs/system/devices/remote-i2c-master.rstcreate mode 100644hw/i2c/remote-i2c-backend.ccreate mode 100644hw/i2c/remote-i2c-cuse.c
create mode 100644hw/i2c/remote-i2c-fsm.c
create mode 100644hw/i2c/remote-i2c-master.ccreate mode 100644include/hw/i2c/remote-i2c-backend.hcreate mode 100644include/hw/i2c/remote-i2c-cuse.hcreate mode 100644include/hw/i2c/remote-i2c-master.hcreate mode 100644tests/qtest/remote-i2c-cuse-test.cIf I understand this proposal correctly, it lets host-side i2c tools talk to emulated I2C devices. The example is i2cdetect/i2cget against a tmp105 on an Aspeed bus.
QEMU already has mechanisms for this though. qtest can read/write I2C registers programmatically, QMP can query device state, and the guest OS itself sees the I2C bus natively.
The dependency cost seems high for the use case: libfuse3 + the cuse kernel module pulled into the system emulator build. It's also ~3K lines of new code, three QOM types, FUSE session management, etc. The surface area for bugs is large. It's a heavy burden for what it gives.
I think a lighter QMP-based approach would serve the same purpose, maybe better, and fit in better in QEMU, without the dependency and maintenance cost:
- No host kernel dependency
- Works remotely (QMP over socket)
- Fits QEMU's existing management model
- Much less code
- Testable without root or kernel modulesHave you considered extending QMP with an I2C transaction command instead? Something like:
{ 'command': 'i2c-transfer', 'data': { 'bus': 'str', 'address': 'uint8', 'read': 'bool', '*data': ['uint8'], '*length': 'uint16' }, 'returns': { '*data': ['uint8'] } }Thanks,
C.
Hi Corey, Cédric,
Quoted 4 lines · Corey Minyard
I think what Cédric is saying here is that if you provided a generic QMP interface that allowed these sorts of operations and wrote an external program that used said interface to provide a fuse interface, that would be better.
I see your point about keeping the core emulator clean and minimizing dependencies.
I am willing to pivot to this architectural direction. I can drop the CUSE backend from this patch series and instead implement the i2c-transfer QMP command, as Cédric originally suggested. I will handle the CUSE part externally.
Before I send v6, are there any other concerns regarding the core FSM logic, or would replacing CUSE with a QMP backend be sufficient?
Best regards,
Ilya
пт, 24 июл. 2026 г. в 16:31, Corey Minyard <[email protected]>:
Quoted 209 lines · Ilya Chichkov
Quoted 10 lines
Hi Cédric,
Quoted 3 lines · Cédric Le Goater
I think a lighter QMP-based approach would serve the same purpose, maybe better, and fit in better in QEMU, without the dependency and maintenance cost:
As Corey and I discussed earlier in the thread, QMP doesn't cover the primary motivation for this patch: zero-code transparency for existing host software.
Quoted 6 lines
An
i2c-transferQMP command would be a great addition for custom scripts, but the main goal here is to allow native Linux user-space binaries (like i2c-tools,
lm-sensors) running on the host to talk to QEMU's I2C slaves unmodified, simply by opening/dev/i2c-N. Rewriting legacy test suites to speak QMP JSON over a socket is often not feasible.I think what Cédric is saying here is that if you provided a generic QMP interface that allowed these sorts of operations and wrote an external program that used said interface to provide a fuse interface, that would be better. It has a number of advantages:
* You add an interface to QEMU that others can easily use to test devices.
* You are not tied to QEMU when you want to extend the functions of the fuse interface.
* It's one less dependency in QEMU. QEMU has a *lot* of dependencies, and the fewer the better.
The only disadvantage I can think of is that it's one more piece of software if you are setting this up.
This is not a big piece of software, I agree, but from experience I think you will be happier with this sort of design in the long run. It puts you more in control of what you are doing.
And, of course, it makes the QEMU maintainers happier :-).
-corey
Quoted 165 lines
Quoted 4 lines
The dependency cost seems high for the use case: libfuse3 + the cuse kernel module pulled into the system emulator build. It's also ~3K lines of new code, three QOM types, FUSE session management, etc.
Regarding dependencies,
libfuse3is actually not new to the project — it has been a supported QEMU dependency for a long time (already used by the block layer inblock/export/fuse.c). Also, just to clarify the diff: the core implementation is roughly ~2K lines. The remaining ~900 lines are dedicated entirely to qtests and RST documentation.However, I agree about not polluting the core emulation build with Linux-specific
headers and libfuse3. The maintenance cost must be minimized. To address this, I've refactored the architecture for v6 to ensure strict isolation:- All Linux and FUSE-specific headers are removed from public QEMU headers. The internal state structure is now opaque and hidden inside
remote-i2c-cuse.c.
- The CUSE backend is isolated behind its ownCONFIG_REMOTE_I2C_BACKEND_CUSEinKconfigand meson.build, strictly depending on LINUX and fuse3.On macOS, Windows, or minimalistic builds without libfuse, QEMU will build cleanly without pulling in this backend or any of its dependencies.
Would making the CUSE transport a strictly optional, isolated Linux-only backend alleviate your concerns regarding the hardware emulation core?
Best regards,
Ilyaср, 22 июл. 2026 г. в 20:42, Cédric Le Goater <[email protected]>:
Quoted 132 lines · Ilya Chichkov
Quoted 80 lines
Add a "remote-i2c-master" device that exposes a QEMU I2C bus to the host system through a FUSE/CUSE character device. This lets external host programs and standard i2c-tools interact with I2C slaves emulated inside QEMU as if they were real devices attached to the host.
The implementation is split into three layers:
- A non-blocking finite state machine that drives the QEMU I2C master. It is pumped by a QEMU Bottom Half and uses virtual timers to yield during long transfers and to model clock stretching for asynchronous slaves, so the main loop is never blocked. The FSM walks IDLE -> ADDR -> SEND/RECV ->
WAIT_STRETCH-> END -> FINISHED and handles NACKs (ENXIO), lost arbitration (EBUSY, with optional back-off and retry), stretch timeouts, and manual abort/reset.- An abstract RemoteI2CBackend QOM base class that decouples the internal I2C hardware state machine (the frontend) from any host-specific transport, exposing
on_tx_completeandon_tx_errorvirtual callbacks.- A concrete remote-i2c-backend-cuse backend implementing that transport over CUSE. It manages the FUSE session and integrates its file descriptors into QEMU's main AioContext event loop, translates Linux
I2C_RDWR,I2C_SMBUSandI2C_SLAVEioctls into generic byte streams for the FSM, and formats responses back into Linux I2C/SMBus structures for the FUSE driver. SMBus repeated start is supported for atomic write-then-read operations.Example usage:
-device remote-i2c-master,i2cbus=i2c-bus.0,devname=i2c-33 -object remote-i2c-backend-cuse,id=b0,devname=i2c-33This creates
/dev/i2c-33on the host, usable with i2c-tools:i2cdetect -y -l
i2cget -y <bus_id> <addr> <reg>Signed-off-by Ilya Chichkov <[email protected]>---
v2:
-docs/system/devices/remote-i2c-master.rst: Documented concurrent bus access details and the 'raise-arbitrage-lost' property.
---
v3:
-qapi/qom.json: Fix RemoteI2CBackendCuseProperties formatting and expand member documentation (devname, fuse-opts, debug).
- tests/qtest: Add remote-i2c-cuse-test covering capabilities, functional smoke test, synchronous sensor read/write.
---
v4:
- qapi: reference the rst doc via :doc:
- qapi: fuse-opts is now ['str'] instead of a space-separated string
- qapi: drop redundant 'debug' property (pass -d via fuse-opts)
---
v5:
-docs/system/device-emulation.rst: addremote-i2c-master.rstto the toctree under "Emulated Devices"
-qapi/qom.json: move RemoteI2CBackendCuseProperties definition before RemoteObjectProperties as requested; change "for usage information" to "for detailed usage information"
------ docs/system/device-emulation.rst | 1 + docs/system/devices/remote-i2c-master.rst | 217 ++++ hw/i2c/Kconfig | 5 + hw/i2c/meson.build | 6 + hw/i2c/remote-i2c-backend.c | 30 + hw/i2c/remote-i2c-cuse.c | 1173 +++++++++++++++++++++ hw/i2c/remote-i2c-fsm.c | 521 +++++++++ hw/i2c/remote-i2c-master.c | 145 +++ hw/i2c/trace-events | 29 + include/hw/i2c/remote-i2c-backend.h | 70 ++ include/hw/i2c/remote-i2c-cuse.h | 93 ++ include/hw/i2c/remote-i2c-master.h | 77 ++ qapi/qom.json | 29 + tests/qtest/meson.build | 2 + tests/qtest/remote-i2c-cuse-test.c | 326 ++++++ 15 files changed, 2724 insertions(+)Quoted 9 lines
create mode 100644
docs/system/devices/remote-i2c-master.rstcreate mode 100644hw/i2c/remote-i2c-backend.ccreate mode 100644hw/i2c/remote-i2c-cuse.c
create mode 100644hw/i2c/remote-i2c-fsm.c
create mode 100644hw/i2c/remote-i2c-master.ccreate mode 100644include/hw/i2c/remote-i2c-backend.hcreate mode 100644include/hw/i2c/remote-i2c-cuse.hcreate mode 100644include/hw/i2c/remote-i2c-master.hcreate mode 100644tests/qtest/remote-i2c-cuse-test.cIf I understand this proposal correctly, it lets host-side i2c tools talk to emulated I2C devices. The example is i2cdetect/i2cget against a tmp105 on an Aspeed bus.
QEMU already has mechanisms for this though. qtest can read/write I2C registers programmatically, QMP can query device state, and the guest OS itself sees the I2C bus natively.
The dependency cost seems high for the use case: libfuse3 + the cuse kernel module pulled into the system emulator build. It's also ~3K lines of new code, three QOM types, FUSE session management, etc. The surface area for bugs is large. It's a heavy burden for what it gives.
I think a lighter QMP-based approach would serve the same purpose, maybe better, and fit in better in QEMU, without the dependency and maintenance cost:
- No host kernel dependency
- Works remotely (QMP over socket)
- Fits QEMU's existing management model
- Much less code
- Testable without root or kernel modulesHave you considered extending QMP with an I2C transaction command instead? Something like:
{ 'command': 'i2c-transfer', 'data': { 'bus': 'str', 'address': 'uint8', 'read': 'bool', '*data': ['uint8'], '*length': 'uint16' }, 'returns': { '*data': ['uint8'] } }Thanks,
C.
Quoted 11 lines · Ilya Chichkov
Hi Corey, Cédric,
Quoted 4 lines · Corey Minyard
I think what Cédric is saying here is that if you provided a generic QMP interface that allowed these sorts of operations and wrote an external program that used said interface to provide a fuse interface, that would be better.
I see your point about keeping the core emulator clean and minimizing dependencies.
Quoted 7 lines
I am willing to pivot to this architectural direction. I can drop the CUSE backend from this patch series and instead implement the
i2c-transferQMP command, as Cédric originally suggested. I will handle the CUSE part externally.Before I send v6, are there any other concerns regarding the core FSM logic, or would replacing CUSE with a QMP backend be sufficient?
I didn't see anything, it looked clean and well written to me, but I am not as much of a QEMU expert as others. I kind of happened into this as I know a lot about IPMI and I2C.
-corey
Quoted 215 lines
Best regards,
Ilyaпт, 24 июл. 2026 г. в 16:31, Corey Minyard <[email protected]>:
Quoted 209 lines · Ilya Chichkov
Quoted 10 lines
Hi Cédric,
Quoted 3 lines · Cédric Le Goater
I think a lighter QMP-based approach would serve the same purpose, maybe better, and fit in better in QEMU, without the dependency and maintenance cost:
As Corey and I discussed earlier in the thread, QMP doesn't cover the primary motivation for this patch: zero-code transparency for existing host software.
Quoted 6 lines
An
i2c-transferQMP command would be a great addition for custom scripts, but the main goal here is to allow native Linux user-space binaries (like i2c-tools,
lm-sensors) running on the host to talk to QEMU's I2C slaves unmodified, simply by opening/dev/i2c-N. Rewriting legacy test suites to speak QMP JSON over a socket is often not feasible.I think what Cédric is saying here is that if you provided a generic QMP interface that allowed these sorts of operations and wrote an external program that used said interface to provide a fuse interface, that would be better. It has a number of advantages:
* You add an interface to QEMU that others can easily use to test devices.
* You are not tied to QEMU when you want to extend the functions of the fuse interface.
* It's one less dependency in QEMU. QEMU has a *lot* of dependencies, and the fewer the better.
The only disadvantage I can think of is that it's one more piece of software if you are setting this up.
This is not a big piece of software, I agree, but from experience I think you will be happier with this sort of design in the long run. It puts you more in control of what you are doing.
And, of course, it makes the QEMU maintainers happier :-).
-corey
Quoted 165 lines
Quoted 4 lines
The dependency cost seems high for the use case: libfuse3 + the cuse kernel module pulled into the system emulator build. It's also ~3K lines of new code, three QOM types, FUSE session management, etc.
Regarding dependencies,
libfuse3is actually not new to the project — it has been a supported QEMU dependency for a long time (already used by the block layer inblock/export/fuse.c). Also, just to clarify the diff: the core implementation is roughly ~2K lines. The remaining ~900 lines are dedicated entirely to qtests and RST documentation.However, I agree about not polluting the core emulation build with Linux-specific
headers and libfuse3. The maintenance cost must be minimized. To address this, I've refactored the architecture for v6 to ensure strict isolation:- All Linux and FUSE-specific headers are removed from public QEMU headers. The internal state structure is now opaque and hidden inside
remote-i2c-cuse.c.
- The CUSE backend is isolated behind its ownCONFIG_REMOTE_I2C_BACKEND_CUSEinKconfigand meson.build, strictly depending on LINUX and fuse3.On macOS, Windows, or minimalistic builds without libfuse, QEMU will build cleanly without pulling in this backend or any of its dependencies.
Would making the CUSE transport a strictly optional, isolated Linux-only backend alleviate your concerns regarding the hardware emulation core?
Best regards,
Ilyaср, 22 июл. 2026 г. в 20:42, Cédric Le Goater <[email protected]>:
Quoted 132 lines · Ilya Chichkov
Quoted 80 lines
Add a "remote-i2c-master" device that exposes a QEMU I2C bus to the host system through a FUSE/CUSE character device. This lets external host programs and standard i2c-tools interact with I2C slaves emulated inside QEMU as if they were real devices attached to the host.
The implementation is split into three layers:
- A non-blocking finite state machine that drives the QEMU I2C master. It is pumped by a QEMU Bottom Half and uses virtual timers to yield during long transfers and to model clock stretching for asynchronous slaves, so the main loop is never blocked. The FSM walks IDLE -> ADDR -> SEND/RECV ->
WAIT_STRETCH-> END -> FINISHED and handles NACKs (ENXIO), lost arbitration (EBUSY, with optional back-off and retry), stretch timeouts, and manual abort/reset.- An abstract RemoteI2CBackend QOM base class that decouples the internal I2C hardware state machine (the frontend) from any host-specific transport, exposing
on_tx_completeandon_tx_errorvirtual callbacks.- A concrete remote-i2c-backend-cuse backend implementing that transport over CUSE. It manages the FUSE session and integrates its file descriptors into QEMU's main AioContext event loop, translates Linux
I2C_RDWR,I2C_SMBUSandI2C_SLAVEioctls into generic byte streams for the FSM, and formats responses back into Linux I2C/SMBus structures for the FUSE driver. SMBus repeated start is supported for atomic write-then-read operations.Example usage:
-device remote-i2c-master,i2cbus=i2c-bus.0,devname=i2c-33 -object remote-i2c-backend-cuse,id=b0,devname=i2c-33This creates
/dev/i2c-33on the host, usable with i2c-tools:i2cdetect -y -l
i2cget -y <bus_id> <addr> <reg>Signed-off-by Ilya Chichkov <[email protected]>---
v2:
-docs/system/devices/remote-i2c-master.rst: Documented concurrent bus access details and the 'raise-arbitrage-lost' property.
---
v3:
-qapi/qom.json: Fix RemoteI2CBackendCuseProperties formatting and expand member documentation (devname, fuse-opts, debug).
- tests/qtest: Add remote-i2c-cuse-test covering capabilities, functional smoke test, synchronous sensor read/write.
---
v4:
- qapi: reference the rst doc via :doc:
- qapi: fuse-opts is now ['str'] instead of a space-separated string
- qapi: drop redundant 'debug' property (pass -d via fuse-opts)
---
v5:
-docs/system/device-emulation.rst: addremote-i2c-master.rstto the toctree under "Emulated Devices"
-qapi/qom.json: move RemoteI2CBackendCuseProperties definition before RemoteObjectProperties as requested; change "for usage information" to "for detailed usage information"
------ docs/system/device-emulation.rst | 1 + docs/system/devices/remote-i2c-master.rst | 217 ++++ hw/i2c/Kconfig | 5 + hw/i2c/meson.build | 6 + hw/i2c/remote-i2c-backend.c | 30 + hw/i2c/remote-i2c-cuse.c | 1173 +++++++++++++++++++++ hw/i2c/remote-i2c-fsm.c | 521 +++++++++ hw/i2c/remote-i2c-master.c | 145 +++ hw/i2c/trace-events | 29 + include/hw/i2c/remote-i2c-backend.h | 70 ++ include/hw/i2c/remote-i2c-cuse.h | 93 ++ include/hw/i2c/remote-i2c-master.h | 77 ++ qapi/qom.json | 29 + tests/qtest/meson.build | 2 + tests/qtest/remote-i2c-cuse-test.c | 326 ++++++ 15 files changed, 2724 insertions(+)Quoted 9 lines
create mode 100644
docs/system/devices/remote-i2c-master.rstcreate mode 100644hw/i2c/remote-i2c-backend.ccreate mode 100644hw/i2c/remote-i2c-cuse.c
create mode 100644hw/i2c/remote-i2c-fsm.c
create mode 100644hw/i2c/remote-i2c-master.ccreate mode 100644include/hw/i2c/remote-i2c-backend.hcreate mode 100644include/hw/i2c/remote-i2c-cuse.hcreate mode 100644include/hw/i2c/remote-i2c-master.hcreate mode 100644tests/qtest/remote-i2c-cuse-test.cIf I understand this proposal correctly, it lets host-side i2c tools talk to emulated I2C devices. The example is i2cdetect/i2cget against a tmp105 on an Aspeed bus.
QEMU already has mechanisms for this though. qtest can read/write I2C registers programmatically, QMP can query device state, and the guest OS itself sees the I2C bus natively.
The dependency cost seems high for the use case: libfuse3 + the cuse kernel module pulled into the system emulator build. It's also ~3K lines of new code, three QOM types, FUSE session management, etc. The surface area for bugs is large. It's a heavy burden for what it gives.
I think a lighter QMP-based approach would serve the same purpose, maybe better, and fit in better in QEMU, without the dependency and maintenance cost:
- No host kernel dependency
- Works remotely (QMP over socket)
- Fits QEMU's existing management model
- Much less code
- Testable without root or kernel modulesHave you considered extending QMP with an I2C transaction command instead? Something like:
{ 'command': 'i2c-transfer', 'data': { 'bus': 'str', 'address': 'uint8', 'read': 'bool', '*data': ['uint8'], '*length': 'uint16' }, 'returns': { '*data': ['uint8'] } }Thanks,
C.
Ping
Best regards, Ilya
пт, 24 июл. 2026 г. в 18:15, Corey Minyard <[email protected]>:
Quoted 242 lines · Ilya Chichkov
Quoted 11 lines
Hi Corey, Cédric,
Quoted 4 lines · Corey Minyard
I think what Cédric is saying here is that if you provided a generic QMP interface that allowed these sorts of operations and wrote an external program that used said interface to provide a fuse interface, that would be better.
I see your point about keeping the core emulator clean and minimizing dependencies.
Quoted 7 lines
I am willing to pivot to this architectural direction. I can drop the CUSE backend from this patch series and instead implement the
i2c-transferQMP command, as Cédric originally suggested. I will handle the CUSE part externally.Before I send v6, are there any other concerns regarding the core FSM logic, or would replacing CUSE with a QMP backend be sufficient?
I didn't see anything, it looked clean and well written to me, but I am not as much of a QEMU expert as others. I kind of happened into this as I know a lot about IPMI and I2C.
-corey
Quoted 215 lines
Best regards,
Ilyaпт, 24 июл. 2026 г. в 16:31, Corey Minyard <[email protected]>:
Quoted 209 lines · Ilya Chichkov
Quoted 10 lines
Hi Cédric,
Quoted 3 lines · Cédric Le Goater
I think a lighter QMP-based approach would serve the same purpose, maybe better, and fit in better in QEMU, without the dependency and maintenance cost:
As Corey and I discussed earlier in the thread, QMP doesn't cover the primary motivation for this patch: zero-code transparency for existing host software.
Quoted 6 lines
An
i2c-transferQMP command would be a great addition for custom scripts, but the main goal here is to allow native Linux user-space binaries (like i2c-tools,
lm-sensors) running on the host to talk to QEMU's I2C slaves unmodified, simply by opening/dev/i2c-N. Rewriting legacy test suites to speak QMP JSON over a socket is often not feasible.I think what Cédric is saying here is that if you provided a generic QMP interface that allowed these sorts of operations and wrote an external program that used said interface to provide a fuse interface, that would be better. It has a number of advantages:
* You add an interface to QEMU that others can easily use to test devices.
* You are not tied to QEMU when you want to extend the functions of the fuse interface.
* It's one less dependency in QEMU. QEMU has a *lot* of dependencies, and the fewer the better.
The only disadvantage I can think of is that it's one more piece of software if you are setting this up.
This is not a big piece of software, I agree, but from experience I think you will be happier with this sort of design in the long run. It puts you more in control of what you are doing.
And, of course, it makes the QEMU maintainers happier :-).
-corey
Quoted 165 lines
Quoted 4 lines
The dependency cost seems high for the use case: libfuse3 + the cuse kernel module pulled into the system emulator build. It's also ~3K lines of new code, three QOM types, FUSE session management, etc.
Regarding dependencies,
libfuse3is actually not new to the project — it has been a supported QEMU dependency for a long time (already used by the block layer inblock/export/fuse.c). Also, just to clarify the diff: the core implementation is roughly ~2K lines. The remaining ~900 lines are dedicated entirely to qtests and RST documentation.However, I agree about not polluting the core emulation build with Linux-specific
headers and libfuse3. The maintenance cost must be minimized. To address this, I've refactored the architecture for v6 to ensure strict isolation:- All Linux and FUSE-specific headers are removed from public QEMU headers. The internal state structure is now opaque and hidden inside
remote-i2c-cuse.c.
- The CUSE backend is isolated behind its ownCONFIG_REMOTE_I2C_BACKEND_CUSEinKconfigand meson.build, strictly depending on LINUX and fuse3.On macOS, Windows, or minimalistic builds without libfuse, QEMU will build cleanly without pulling in this backend or any of its dependencies.
Would making the CUSE transport a strictly optional, isolated Linux-only backend alleviate your concerns regarding the hardware emulation core?
Best regards,
Ilyaср, 22 июл. 2026 г. в 20:42, Cédric Le Goater <[email protected]>:
Quoted 132 lines · Ilya Chichkov
Quoted 80 lines
Add a "remote-i2c-master" device that exposes a QEMU I2C bus to the host system through a FUSE/CUSE character device. This lets external host programs and standard i2c-tools interact with I2C slaves emulated inside QEMU as if they were real devices attached to the host.
The implementation is split into three layers:
- A non-blocking finite state machine that drives the QEMU I2C master. It is pumped by a QEMU Bottom Half and uses virtual timers to yield during long transfers and to model clock stretching for asynchronous slaves, so the main loop is never blocked. The FSM walks IDLE -> ADDR -> SEND/RECV ->
WAIT_STRETCH-> END -> FINISHED and handles NACKs (ENXIO), lost arbitration (EBUSY, with optional back-off and retry), stretch timeouts, and manual abort/reset.- An abstract RemoteI2CBackend QOM base class that decouples the internal I2C hardware state machine (the frontend) from any host-specific transport, exposing
on_tx_completeandon_tx_errorvirtual callbacks.- A concrete remote-i2c-backend-cuse backend implementing that transport over CUSE. It manages the FUSE session and integrates its file descriptors into QEMU's main AioContext event loop, translates Linux
I2C_RDWR,I2C_SMBUSandI2C_SLAVEioctls into generic byte streams for the FSM, and formats responses back into Linux I2C/SMBus structures for the FUSE driver. SMBus repeated start is supported for atomic write-then-read operations.Example usage:
-device remote-i2c-master,i2cbus=i2c-bus.0,devname=i2c-33 -object remote-i2c-backend-cuse,id=b0,devname=i2c-33This creates
/dev/i2c-33on the host, usable with i2c-tools:i2cdetect -y -l
i2cget -y <bus_id> <addr> <reg>Signed-off-by Ilya Chichkov <[email protected]>---
v2:
-docs/system/devices/remote-i2c-master.rst: Documented concurrent bus access details and the 'raise-arbitrage-lost' property.
---
v3:
-qapi/qom.json: Fix RemoteI2CBackendCuseProperties formatting and expand member documentation (devname, fuse-opts, debug).
- tests/qtest: Add remote-i2c-cuse-test covering capabilities, functional smoke test, synchronous sensor read/write.
---
v4:
- qapi: reference the rst doc via :doc:
- qapi: fuse-opts is now ['str'] instead of a space-separated string
- qapi: drop redundant 'debug' property (pass -d via fuse-opts)
---
v5:
-docs/system/device-emulation.rst: addremote-i2c-master.rstto the toctree under "Emulated Devices"
-qapi/qom.json: move RemoteI2CBackendCuseProperties definition before RemoteObjectProperties as requested; change "for usage information" to "for detailed usage information"
------ docs/system/device-emulation.rst | 1 + docs/system/devices/remote-i2c-master.rst | 217 ++++ hw/i2c/Kconfig | 5 + hw/i2c/meson.build | 6 + hw/i2c/remote-i2c-backend.c | 30 + hw/i2c/remote-i2c-cuse.c | 1173 +++++++++++++++++++++ hw/i2c/remote-i2c-fsm.c | 521 +++++++++ hw/i2c/remote-i2c-master.c | 145 +++ hw/i2c/trace-events | 29 + include/hw/i2c/remote-i2c-backend.h | 70 ++ include/hw/i2c/remote-i2c-cuse.h | 93 ++ include/hw/i2c/remote-i2c-master.h | 77 ++ qapi/qom.json | 29 + tests/qtest/meson.build | 2 + tests/qtest/remote-i2c-cuse-test.c | 326 ++++++ 15 files changed, 2724 insertions(+)Quoted 9 lines
create mode 100644
docs/system/devices/remote-i2c-master.rstcreate mode 100644hw/i2c/remote-i2c-backend.ccreate mode 100644hw/i2c/remote-i2c-cuse.c
create mode 100644hw/i2c/remote-i2c-fsm.c
create mode 100644hw/i2c/remote-i2c-master.ccreate mode 100644include/hw/i2c/remote-i2c-backend.hcreate mode 100644include/hw/i2c/remote-i2c-cuse.hcreate mode 100644include/hw/i2c/remote-i2c-master.hcreate mode 100644tests/qtest/remote-i2c-cuse-test.cIf I understand this proposal correctly, it lets host-side i2c tools talk to emulated I2C devices. The example is i2cdetect/i2cget against a tmp105 on an Aspeed bus.
QEMU already has mechanisms for this though. qtest can read/write I2C registers programmatically, QMP can query device state, and the guest OS itself sees the I2C bus natively.
The dependency cost seems high for the use case: libfuse3 + the cuse kernel module pulled into the system emulator build. It's also ~3K lines of new code, three QOM types, FUSE session management, etc. The surface area for bugs is large. It's a heavy burden for what it gives.
I think a lighter QMP-based approach would serve the same purpose, maybe better, and fit in better in QEMU, without the dependency and maintenance cost:
- No host kernel dependency
- Works remotely (QMP over socket)
- Fits QEMU's existing management model
- Much less code
- Testable without root or kernel modulesHave you considered extending QMP with an I2C transaction command instead? Something like:
{ 'command': 'i2c-transfer', 'data': { 'bus': 'str', 'address': 'uint8', 'read': 'bool', '*data': ['uint8'], '*length': 'uint16' }, 'returns': { '*data': ['uint8'] } }Thanks,
C.