system/i3c: added i3c tools

system/i3c/CMakeLists.txt

@@ -0,0 +1,25 @@
+# ##############################################################################
+# apps/system/i3c/CMakeLists.txt
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for
+# additional information regarding copyright ownership.  The ASF licenses this
+# file to you under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License.  You may obtain a copy of
+# the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations under
+# the License.
+#
+# ##############################################################################
+
+if(CONFIG_SYSTEM_I3CTOOL)
+  set(SRCS i3c_main.c)
+  nuttx_add_application(NAME i3c SRCS ${SRCS} STACKSIZE
+                        ${CONFIG_DEFAULT_TASK_STACKSIZE})
+endif()

system/i3c/Kconfig

@@ -0,0 +1,28 @@
+#
+# For a description of the syntax of this configuration file,
+# see the file kconfig-language.txt in the NuttX tools repository.
+#
+
+menuconfig SYSTEM_I3CTOOL
+	tristate "I3C tool"
+	default n
+	depends on I3C
+	select I3C_DRIVER
+	---help---
+		Enable support for the I3C tool.
+
+if SYSTEM_I3CTOOL
+
+config I3CTOOL_DEF_TARGETADDR
+	hex "Default I3C device target address"
+	default 0xffff
+	---help---
+		Default I3C device target address (default: 0xffff)
+
+config I3CTOOL_DEFBUS
+	int "Default I2C bus number"
+	default 0
+	---help---
+		Default I3C bus number (default: 0)
+
+endif

system/i3c/Make.defs

@@ -0,0 +1,23 @@
+############################################################################
+# apps/system/i3c/Make.defs
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.  The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+############################################################################
+
+ifneq ($(CONFIG_SYSTEM_I3CTOOL),)
+CONFIGURED_APPS += $(APPDIR)/system/i3c
+endif

system/i3c/Makefile

@@ -0,0 +1,30 @@
+############################################################################
+# apps/system/i3c/Makefile
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.  The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+############################################################################
+
+include $(APPDIR)/Make.defs
+
+MAINSRC = i3c_main.c
+
+PROGNAME = i3c
+PRIORITY = SCHED_PRIORITY_DEFAULT
+STACKSIZE = $(CONFIG_DEFAULT_TASK_STACKSIZE)
+MODULE = $(CONFIG_SYSTEM_I3CTOOL)
+
+include $(APPDIR)/Application.mk

system/i3c/README.md

@@ -0,0 +1,89 @@
+# System / `i3c` I3C Tool
+
+The I3C tool provides a way to debug I3C related problems. This README file will
+provide usage information for the I3C tools.
+
+- System Requirements
+  - I3C Driver
+  - I2C Driver, If Has I2C Device
+  - Configuration Options
+
+# Configuration Options
+
+ - `CONFIG_NSH_BUILTIN_APPS` – Build the tools as an NSH built-in command.
+ - `CONFIG_I3CTOOL_DEFBUS`   – A default bus number (default `0`).
+
+# Usage:
+
+Write one data byte in single private transfer
+
+i3c -b bus -m manufid -p partid -w 0xde
+
+Write multiple data bytes in single private transfer
+
+i3c -b bus -m manufid -p partid -w "0xde,0xad,0xbe,0xef"
+
+Write multiple data bytes in multiple private transfers
+
+i3c -b bus -m manufid -p partid -w "0xde,0xad" -w "0xbe,0xef"
+
+Read multiple data bytes in single private transfer
+
+i3c -b bus -m manufid -p partid -r <data_length>
+
+Read multiple data bytes in multiple private transfer
+
+i3c -b bus -m manufid -p partid -r <data_length> -r <data_length>
+
+Read and write multiple data bytes in multiple private transfer
+
+i3c -b bus -m manufid -p partid -w "0xde,0xad,0xbe,0xef" -r <data_length>
+
+Get device information using PID
+
+i3c -b bus -m manufid -p partid -g
+
+Parameters:
+
+  1) bus: I3C bus number
+  2) manufid: Manufacturer ID (upper 16 bits of device PID)
+  3) partid: Part ID (middle 16 bits of device PID)
+  4) <data_length>: Data length to read on this message
+
+Note: The manufid and partid are extracted from the device's 48-bit Provisional
+ID (PID). To find these values, first use the -g option to get device information,
+then extract:
+  - manufid = (PID >> 32) & 0xFFFF
+  - partid  = (PID >> 16) & 0xFFFF
+
+# Example
+  1. i3c -b 0 -m 0x01E0 -p 0x0001 -w 0xde
+  2. i3c -b 0 -m 0x01E0 -p 0x0001 -w "0xde,0xad,0xbe,0xef"
+  3. i3c -b 0 -m 0x01E0 -p 0x0001 -w "0xde,0xad" -w "0xbe,0xef"
+  4. i3c -b 0 -m 0x01E0 -p 0x0001 -r 0x10
+  5. i3c -b 0 -m 0x01E0 -p 0x0001 -r 0x10  -r 0x10
+  6. i3c -b 0 -m 0x01E0 -p 0x0001 -w "0xde,0xad,0xbe,0xef" -r 0x10
+  7. i3c -b 0 -m 0x01E0 -p 0x0001 -g
+
+# Migration from target_addr
+
+Previous versions used `-d targetaddr` to specify the device address. The new
+version uses `-m manufid -p partid` to identify devices by their unique PID.
+
+To migrate:
+1. Get device PID using the old command (if available):
+   ```
+   i3c -b 0 -d <addr> -g
+   ```
+   Output: `i3c_device_info - pid 0x01E000010000XXXX`
+
+2. Extract manufid and partid from PID:
+   ```
+   manufid = 0x01E0  (bits 47-32)
+   partid  = 0x0001  (bits 31-16)
+   ```
+
+3. Use new command format:
+   ```
+   i3c -b 0 -m 0x01E0 -p 0x0001 -r 0x10
+   ```