[PATCH v5 5/5] tools: i3c: add i3ctransfer utility

[Sam Agazaryan <samagazaryan@google.com>]

Add the i3ctransfer userspace utility to tools/i3c/ for testing and
interacting with I3C target devices via /dev/bus/i3c/* character
devices.

Based on the i3ctransfer tool from i3c-tools by Vitor Soares, updated
for the unified I3C_IOC_XFER UAPI (struct i3c_ioc_xfer):
  - Supports SDR and HDR (HDR-DDR, HDR-TSP, HDR-TSL) transfer modes
    via -m/--mode and -c/--command options.
  - Reports actual_len bytes received on read transfers.

Signed-off-by: Sam Agazaryan <samagazaryan@google.com>
---
Note to Vitor Soares:
  This patch ports your GPL-2.0 i3ctransfer utility from i3c-tools into
  tools/i3c/ and updates it for struct i3c_ioc_xfer (SDR/HDR modes and
  actual_len read reporting). Since the original GitHub commit did not
  include a Signed-off-by tag, could you please reply with your
  Signed-off-by or Acked-by so we can properly record your sign-off?

 MAINTAINERS             |   1 +
 tools/Makefile          |  13 +-
 tools/i3c/Build         |   1 +
 tools/i3c/Makefile      |  58 ++++++++
 tools/i3c/i3ctransfer.c | 307 ++++++++++++++++++++++++++++++++++++++++
 5 files changed, 374 insertions(+), 6 deletions(-)
 create mode 100644 tools/i3c/Build
 create mode 100644 tools/i3c/Makefile
 create mode 100644 tools/i3c/i3ctransfer.c

diff --git a/MAINTAINERS b/MAINTAINERS
index 30a5cb12c4f0..8a4166ebc9dc 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12365,6 +12365,7 @@ F:	drivers/i3c/
 F:	include/dt-bindings/i3c/
 F:	include/linux/i3c/
 F:	include/uapi/linux/i3c/
+F:	tools/i3c/
 
 IBM Operation Panel Input Driver
 M:	Eddie James <eajames@linux.ibm.com>
diff --git a/tools/Makefile b/tools/Makefile
index cb40961a740f..7c17e7555fd7 100644
--- a/tools/Makefile
+++ b/tools/Makefile
@@ -20,6 +20,7 @@ help:
 	@echo '  freefall               - laptop accelerometer program for disk protection'
 	@echo '  gpio                   - GPIO tools'
 	@echo '  hv                     - tools used when in Hyper-V clients'
+	@echo '  i3c                    - I3C tools'
 	@echo '  iio                    - IIO tools'
 	@echo '  intel-speed-select     - Intel Speed Select tool'
 	@echo '  kvm_stat               - top-like utility for displaying kvm statistics'
@@ -70,7 +71,7 @@ acpi: FORCE
 cpupower: FORCE
 	$(call descend,power/$@)
 
-counter dma firewire hv guest bootconfig spi usb virtio mm bpf iio gpio objtool leds wmi firmware debugging tracing: FORCE
+counter dma firewire hv guest bootconfig spi usb virtio mm bpf i3c iio gpio objtool leds wmi firmware debugging tracing: FORCE
 	$(call descend,$@)
 
 bpf/%: FORCE
@@ -126,7 +127,7 @@ ynl: FORCE
 all: acpi counter cpupower dma gpio hv firewire \
 		perf selftests bootconfig spi turbostat usb \
 		virtio mm bpf x86_energy_perf_policy \
-		tmon freefall iio objtool kvm_stat wmi \
+		tmon freefall i3c iio objtool kvm_stat wmi \
 		debugging tracing thermal thermometer thermal-engine ynl
 
 acpi_install:
@@ -135,7 +136,7 @@ acpi_install:
 cpupower_install:
 	$(call descend,power/$(@:_install=),install)
 
-counter_install dma_install firewire_install gpio_install hv_install iio_install perf_install bootconfig_install spi_install usb_install virtio_install mm_install bpf_install objtool_install wmi_install debugging_install tracing_install:
+counter_install dma_install firewire_install gpio_install hv_install i3c_install iio_install perf_install bootconfig_install spi_install usb_install virtio_install mm_install bpf_install objtool_install wmi_install debugging_install tracing_install:
 	$(call descend,$(@:_install=),install)
 
 selftests_install:
@@ -166,7 +167,7 @@ ynl_install:
 	$(call descend,net/$(@:_install=),install)
 
 install: acpi_install counter_install cpupower_install dma_install gpio_install \
-		hv_install firewire_install iio_install \
+		hv_install firewire_install i3c_install iio_install \
 		perf_install selftests_install turbostat_install usb_install \
 		virtio_install mm_install bpf_install x86_energy_perf_policy_install \
 		tmon_install freefall_install objtool_install kvm_stat_install \
@@ -179,7 +180,7 @@ acpi_clean:
 cpupower_clean:
 	$(call descend,power/cpupower,clean)
 
-counter_clean dma_clean hv_clean firewire_clean bootconfig_clean spi_clean usb_clean virtio_clean mm_clean wmi_clean bpf_clean iio_clean gpio_clean objtool_clean leds_clean firmware_clean debugging_clean tracing_clean:
+counter_clean dma_clean hv_clean firewire_clean bootconfig_clean spi_clean usb_clean virtio_clean mm_clean wmi_clean bpf_clean i3c_clean iio_clean gpio_clean objtool_clean leds_clean firmware_clean debugging_clean tracing_clean:
 	$(call descend,$(@:_clean=),clean)
 
 libapi_clean:
@@ -227,7 +228,7 @@ ynl_clean:
 
 clean: acpi_clean counter_clean cpupower_clean dma_clean hv_clean firewire_clean \
 		perf_clean selftests_clean turbostat_clean bootconfig_clean spi_clean usb_clean virtio_clean \
-		mm_clean bpf_clean iio_clean x86_energy_perf_policy_clean tmon_clean \
+		mm_clean bpf_clean i3c_clean iio_clean x86_energy_perf_policy_clean tmon_clean \
 		freefall_clean build_clean libbpf_clean libsubcmd_clean \
 		gpio_clean objtool_clean leds_clean wmi_clean firmware_clean debugging_clean \
 		intel-speed-select_clean tracing_clean thermal_clean thermometer_clean thermal-engine_clean \
diff --git a/tools/i3c/Build b/tools/i3c/Build
new file mode 100644
index 000000000000..6a22328ad983
--- /dev/null
+++ b/tools/i3c/Build
@@ -0,0 +1 @@
+i3ctransfer-y += i3ctransfer.o
diff --git a/tools/i3c/Makefile b/tools/i3c/Makefile
new file mode 100644
index 000000000000..43ce8769185b
--- /dev/null
+++ b/tools/i3c/Makefile
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: GPL-2.0-only
+include ../scripts/Makefile.include
+
+bindir ?= /usr/bin
+
+ifeq ($(srctree),)
+srctree := $(patsubst %/,%,$(dir $(CURDIR)))
+srctree := $(patsubst %/,%,$(dir $(srctree)))
+endif
+
+# Do not use make's built-in rules
+# (this improves performance and avoids hard-to-debug behaviour);
+MAKEFLAGS += -r
+
+CFLAGS += -O2 -Wall -g -D_GNU_SOURCE -I$(OUTPUT)include
+
+ALL_TARGETS := i3ctransfer
+ALL_PROGRAMS := $(patsubst %,$(OUTPUT)%,$(ALL_TARGETS))
+
+all: $(ALL_PROGRAMS)
+
+export srctree OUTPUT CC LD CFLAGS
+include $(srctree)/tools/build/Makefile.include
+
+#
+# We need the following to be outside of kernel tree
+#
+$(OUTPUT)include/linux/i3c: ../../include/uapi/linux/i3c
+	mkdir -p $(OUTPUT)include/linux/i3c 2>&1 || true
+	ln -sf $(CURDIR)/../../include/uapi/linux/i3c/i3cdev.h $@
+
+prepare: $(OUTPUT)include/linux/i3c
+
+#
+# i3ctransfer
+#
+I3CTRANSFER_IN := $(OUTPUT)i3ctransfer-in.o
+$(I3CTRANSFER_IN): prepare FORCE
+	$(Q)$(MAKE) $(build)=i3ctransfer
+$(OUTPUT)i3ctransfer: $(I3CTRANSFER_IN)
+	$(QUIET_LINK)$(CC) $(CFLAGS) $(LDFLAGS) $< -o $@
+
+clean:
+	rm -f $(ALL_PROGRAMS)
+	rm -rf $(OUTPUT)include/
+	find $(or $(OUTPUT),.) -name '*.o' -delete
+	find $(or $(OUTPUT),.) -name '\.*.o.d' -delete
+	find $(or $(OUTPUT),.) -name '\.*.o.cmd' -delete
+
+install: $(ALL_PROGRAMS)
+	install -d -m 755 $(DESTDIR)$(bindir);		\
+	for program in $(ALL_PROGRAMS); do		\
+		install $$program $(DESTDIR)$(bindir);	\
+	done
+
+FORCE:
+
+.PHONY: all install clean FORCE prepare
diff --git a/tools/i3c/i3ctransfer.c b/tools/i3c/i3ctransfer.c
new file mode 100644
index 000000000000..a5b071e63530
--- /dev/null
+++ b/tools/i3c/i3ctransfer.c
@@ -0,0 +1,307 @@
+// SPDX-License-Identifier: GPL-2.0
+/*
+ * Copyright (c) 2019 Synopsys, Inc. and/or its affiliates.
+ * Copyright (c) 2026 Google LLC
+ *
+ * Author: Vitor Soares <vitor.soares@synopsys.com>
+ */
+
+#include <ctype.h>
+#include <errno.h>
+#include <fcntl.h>
+#include <getopt.h>
+#include <limits.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/ioctl.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include <linux/i3c/i3cdev.h>
+
+#define VERSION "0.2"
+
+static const char *sopts = "d:m:c:r:w:vh";
+static const struct option lopts[] = {
+	{"device",		required_argument,	NULL,	'd' },
+	{"mode",		required_argument,	NULL,	'm' },
+	{"command",		required_argument,	NULL,	'c' },
+	{"read",		required_argument,	NULL,	'r' },
+	{"write",		required_argument,	NULL,	'w' },
+	{"help",		no_argument,		NULL,	'h' },
+	{"version",		no_argument,		NULL,	'v' },
+	{0, 0, 0, 0}
+};
+
+static void print_usage(const char *name)
+{
+	fprintf(stderr, "usage: %s options...\n", name);
+	fprintf(stderr, "  options:\n");
+	fprintf(stderr, "    -d --device  <dev>    device to use.\n");
+	fprintf(stderr,
+		"    -m --mode    <mode>   sdr (default), hdr-ddr, hdr-tsp, hdr-tsl.\n");
+	fprintf(stderr,
+		"    -c --command <cmd>    HDR command byte (0x00-0x7f W, 0x80-0xff R).\n");
+	fprintf(stderr, "    -r --read    <len>    read data length in bytes.\n");
+	fprintf(stderr,
+		"    -w --write   <block>  write comma-separated bytes (e.g. 0x01,0x02).\n");
+	fprintf(stderr, "    -h --help             output usage message and exit.\n");
+	fprintf(stderr, "    -v --version          output version number and exit.\n");
+}
+
+static int parse_mode(const char *arg, uint8_t *mode)
+{
+	char *endptr;
+	long val;
+
+	if (!strcmp(arg, "sdr")) {
+		*mode = I3C_XFER_MODE_SDR;
+		return 0;
+	}
+	if (!strcmp(arg, "hdr-ddr") || !strcmp(arg, "ddr")) {
+		*mode = I3C_XFER_MODE_HDR_DDR;
+		return 0;
+	}
+	if (!strcmp(arg, "hdr-tsp") || !strcmp(arg, "tsp")) {
+		*mode = I3C_XFER_MODE_HDR_TSP;
+		return 0;
+	}
+	if (!strcmp(arg, "hdr-tsl") || !strcmp(arg, "tsl")) {
+		*mode = I3C_XFER_MODE_HDR_TSL;
+		return 0;
+	}
+
+	val = strtol(arg, &endptr, 0);
+	if (*endptr == '\0' &&
+	    (val == I3C_XFER_MODE_HDR_DDR ||
+	     val == I3C_XFER_MODE_HDR_TSP ||
+	     val == I3C_XFER_MODE_HDR_TSL ||
+	     val == I3C_XFER_MODE_SDR)) {
+		*mode = (uint8_t)val;
+		return 0;
+	}
+
+	fprintf(stderr, "Error: invalid transfer mode '%s'\n", arg);
+	return -1;
+}
+
+static int rx_args_to_xfer(struct i3c_ioc_xfer *xfer, char *arg,
+			   uint8_t mode, int cmd)
+{
+	char *endptr;
+	uint8_t *tmp;
+	long len;
+
+	len = strtol(arg, &endptr, 0);
+	if (*endptr != '\0' || len <= 0 || len > UINT16_MAX) {
+		fprintf(stderr, "Error: invalid read length '%s'\n", arg);
+		return -1;
+	}
+
+	if (mode == I3C_XFER_MODE_SDR) {
+		xfer->rnw = I3C_DEV_DIR_READ;
+	} else {
+		if (cmd < 0 || !(cmd & 0x80)) {
+			fprintf(stderr,
+				"Error: HDR read requires command (-c) in range 0x80..0xff\n");
+			return -1;
+		}
+		xfer->cmd = (uint8_t)cmd;
+	}
+
+	tmp = calloc(len, sizeof(uint8_t));
+	if (!tmp)
+		return -1;
+
+	xfer->mode = mode;
+	xfer->len = (uint16_t)len;
+	xfer->data = (uintptr_t)tmp;
+
+	return 0;
+}
+
+static int w_args_to_xfer(struct i3c_ioc_xfer *xfer, char *arg,
+			  uint8_t mode, int cmd)
+{
+	char *data_ptrs[256];
+	int len, i = 0;
+	uint8_t *tmp;
+
+	if (mode == I3C_XFER_MODE_SDR) {
+		xfer->rnw = I3C_DEV_DIR_WRITE;
+	} else {
+		if (cmd < 0 || (cmd & 0x80)) {
+			fprintf(stderr,
+				"Error: HDR write requires command (-c) in range 0x00..0x7f\n");
+			return -1;
+		}
+		xfer->cmd = (uint8_t)cmd;
+	}
+
+	data_ptrs[i] = strtok(arg, ",");
+	while (data_ptrs[i] && i < 255)
+		data_ptrs[++i] = strtok(NULL, ",");
+
+	if (i == 0) {
+		fprintf(stderr, "Error: empty write data block\n");
+		return -1;
+	}
+
+	tmp = calloc(i, sizeof(uint8_t));
+	if (!tmp)
+		return -1;
+
+	for (len = 0; len < i; len++) {
+		char *endptr;
+		long val = strtol(data_ptrs[len], &endptr, 0);
+
+		if (*endptr != '\0' || val < 0 || val > UINT8_MAX) {
+			fprintf(stderr, "Error: invalid byte value '%s'\n",
+				data_ptrs[len]);
+			free(tmp);
+			return -1;
+		}
+		tmp[len] = (uint8_t)val;
+	}
+
+	xfer->mode = mode;
+	xfer->len = (uint16_t)len;
+	xfer->data = (uintptr_t)tmp;
+
+	return 0;
+}
+
+static void print_rx_data(const struct i3c_ioc_xfer *xfer)
+{
+	const uint8_t *tmp = (const uint8_t *)(uintptr_t)xfer->data;
+	int i;
+
+	fprintf(stdout, "  received data (%u bytes):\n", xfer->actual_len);
+	for (i = 0; i < xfer->actual_len; i++)
+		fprintf(stdout, "    0x%02x\n", tmp[i]);
+}
+
+int main(int argc, char *argv[])
+{
+	uint8_t mode = I3C_XFER_MODE_SDR;
+	struct i3c_ioc_xfer *xfers;
+	char *device = NULL;
+	int file, ret, opt, i;
+	int nxfers = 0;
+	int cmd = -1;
+
+	while ((opt = getopt_long(argc, argv, sopts, lopts, NULL)) != EOF) {
+		switch (opt) {
+		case 'h':
+			print_usage(argv[0]);
+			return EXIT_SUCCESS;
+		case 'v':
+			fprintf(stderr, "%s - %s\n", argv[0], VERSION);
+			return EXIT_SUCCESS;
+		case 'd':
+			device = optarg;
+			break;
+		case 'm':
+			if (parse_mode(optarg, &mode))
+				return EXIT_FAILURE;
+			break;
+		case 'c': {
+			char *endptr;
+			long val = strtol(optarg, &endptr, 0);
+
+			if (*endptr != '\0' || val < 0 || val > UINT8_MAX) {
+				fprintf(stderr, "Error: invalid command '%s'\n",
+					optarg);
+				return EXIT_FAILURE;
+			}
+			cmd = (int)val;
+			break;
+		}
+		case 'r':
+		case 'w':
+			nxfers++;
+			break;
+		default:
+			print_usage(argv[0]);
+			return EXIT_FAILURE;
+		}
+	}
+
+	if (!device || nxfers == 0) {
+		print_usage(argv[0]);
+		return EXIT_FAILURE;
+	}
+
+	file = open(device, O_RDWR);
+	if (file < 0) {
+		fprintf(stderr, "Error: failed to open %s: %s\n",
+			device, strerror(errno));
+		return EXIT_FAILURE;
+	}
+
+	xfers = calloc(nxfers, sizeof(*xfers));
+	if (!xfers) {
+		close(file);
+		return EXIT_FAILURE;
+	}
+
+	optind = 1;
+	nxfers = 0;
+	cmd = -1;
+
+	while ((opt = getopt_long(argc, argv, sopts, lopts, NULL)) != EOF) {
+		switch (opt) {
+		case 'h':
+		case 'v':
+		case 'd':
+		case 'm':
+			break;
+		case 'c':
+			cmd = (int)strtol(optarg, NULL, 0);
+			break;
+		case 'r':
+			if (rx_args_to_xfer(&xfers[nxfers], optarg, mode, cmd)) {
+				ret = EXIT_FAILURE;
+				goto err_free;
+			}
+			nxfers++;
+			break;
+		case 'w':
+			if (w_args_to_xfer(&xfers[nxfers], optarg, mode, cmd)) {
+				ret = EXIT_FAILURE;
+				goto err_free;
+			}
+			nxfers++;
+			break;
+		}
+	}
+
+	if (ioctl(file, I3C_IOC_XFER(nxfers), xfers) < 0) {
+		fprintf(stderr, "Error: transfer failed: %s\n", strerror(errno));
+		ret = EXIT_FAILURE;
+		goto err_free;
+	}
+
+	for (i = 0; i < nxfers; i++) {
+		bool is_read = (mode == I3C_XFER_MODE_SDR) ?
+			       (xfers[i].rnw == I3C_DEV_DIR_READ) :
+			       (xfers[i].cmd & 0x80);
+
+		fprintf(stdout, "Success on message %d\n", i);
+		if (is_read)
+			print_rx_data(&xfers[i]);
+	}
+
+	ret = EXIT_SUCCESS;
+
+err_free:
+	for (i = 0; i < nxfers; i++)
+		free((void *)(uintptr_t)xfers[i].data);
+	free(xfers);
+	close(file);
+
+	return ret;
+}
-- 
2.55.0.1082.g2b9226bbc0-goog