drivers/i3c: support i3c driver frameworks

Documentation/components/drivers/index.rst

@@ -108,6 +108,11 @@ Subdirectories of ``nuttx/drivers``
 
   I2S drivers and support logic.
 
+
+* ``i3c/`` :doc:`special/i3c`
+
+  I3C drivers and support logic.
+
 * ``input/`` :doc:`character/input/index`
 
   This directory holds implementations of human input device (HID) drivers.

Documentation/components/drivers/special/i3c.rst

@@ -0,0 +1,65 @@
+==================
+I3C Device Drivers
+==================
+
+The I3C (Improved Inter-Integrated Circuit) driver is a comprehensive software framework designed to
+support the advanced features of the I3C protocol. It comprises a system framework and underlying IP
+drivers, both of which are critical components for enabling seamless communication between I3C devices.
+The system framework, provided by vela os, offers user-level device nodes and kernel-level driver
+interfaces. Meanwhile, the underlying IP drivers, developed specifically for the I3C driver framework,
+handle the implementation of IP functionalities and the adaptation of framework-level interfaces.
+
+- Key Components of the I3C Driver Framework:
+
+ #. **Dynamic Addressing and Access**: One of the primary advancements of I3C over I2C is its support
+    for dynamic addressing. This allows for more flexible device management and addressing schemes.
+ #. **CCC (Common Command Codes) Support**: The I3C driver framework enables the transmission of CCC commands,
+    which extend the functionality and capabilities of I3C devices. Dynamic address allocation and
+    release commands are mandatory, while other CCC commands are optional and can be implemented as
+    needed.
+ #. **Data Transmission**: The framework supports both I3C and I2C device data transmission, ensuring
+    compatibility with existing I2C devices while leveraging the enhanced features of I3C.
+ #. **Interface Callbacks**: The I3C driver framework provides a set of callback interfaces that enable
+    IP drivers to interact with the framework layer. These include interfaces for dynamic address
+    configuration and release, CCC command transmission, I3C device data transmission, and I2C device
+    data transmission.
+
+- Data Structures and Interfaces:
+
+ #. **I3C Master Controller (struct i3c_master_controller)**: Represents an I3C controller and manages
+    basic software information for the I3C bus.
+ #. **I3C Bus Operation Callbacks (struct i3c_master_controller_ops)**: Enables application-level access
+    to I3C for data transmission and other operations. Key functions include bus_init for bus initialization,
+    attach_i3c_dev and attach_i2c_dev for device attachment, ccc_xfer for CCC command transmission, priv_xfers
+    for private data transmission, and i2c_xfers for I2C device data transmission.
+ #. **Data Structures for I2C and I3C Transmissions**: Separate structures (struct i2c_msg_s and struct i3c_priv_xfer)
+    are defined for encapsulating data transmitted to I2C and I3C devices, respectively.
+ #. **CCC Command Transmission (struct i3c_ccc_cmd)**: A dedicated structure for encapsulating CCC commands
+    transmitted to I3C devices.
+
+- Application Usage of I3C
+
+Applications interact with I3C devices through device nodes (/dev/i3cX for I3C and /dev/i2cX for I2C devices,
+where X represents the specific bus number). Standard file operations such as open, close, read, write, and ioctl are supported.
+
+- IOCTL Commands:
+
+  #. For I2C devices, IOCTL commands like I2C_TRANSFER and I2C_RESET are available, allowing applications to transmit
+     data and reset I2C devices.
+  #. For I3C devices, a range of IOCTL commands are provided, including I3CIOC_PRIV_XFERS for data transmission,
+     I3CIOC_EN_IBI and I3CIOC_DIS_IBI for enabling and disabling IBI (In-Band Interrupt) commands, I3CIOC_REQ_IBI and
+     I3CIOC_FREE_IBI for requesting and releasing IBI commands, and I3CIOC_GET_DEVINFO for retrieving device information.
+
+- Data Transmission Format:
+
+When transmitting data to I3C slave devices, applications must encapsulate their data in a struct i3c_transfer_s
+format. This structure includes fields such as target_addr for the slave device address, nxfers for the number of
+data frames to be transmitted, xfers for the data frame format, and additional fields for IBI operation requests and
+device information retrieval.
+
+- Provisional ID Implementation:
+
+Due to the use of dynamic addressing in I3C, devices may be identified using Provisional IDs (PIDs). These PIDs
+are encoded in the reg[3] array of the boardinfo structure, with specific rules for encoding manufacturer ID, part ID,
+instance ID, and extra information. This encoding scheme ensures unique identifiability of I3C devices, even when static
+addressing is not

Documentation/components/drivers/special/index.rst

@@ -29,6 +29,7 @@ following section.
   dma.rst
   framebuffer.rst
   i2c.rst
+  i3c.rst
   ioexpander.rst
   lcd.rst
   mtd.rst

Kconfig

@@ -1603,6 +1603,37 @@ config DEBUG_I2S_INFO
 
 endif # DEBUG_I2S
 
+config DEBUG_I3C
+	bool "I3C Debug Features"
+	default n
+	depends on I3C
+	---help---
+		Enable I3C debug features.
+
+		Support for this debug option is architecture-specific and may not
+		be available for some MCUs.
+
+if DEBUG_I3C
+
+config DEBUG_I3C_ERROR
+	bool "I3C Error Output"
+	default n
+	depends on DEBUG_ERROR
+	---help---
+		Enable I3C driver error output to SYSLOG.
+
+		Support for this debug option is architecture-specific and may not
+		be available for some MCUs.
+
+config DEBUG_I3C_INFO
+	bool "I3C Informational Output"
+	default n
+	depends on DEBUG_INFO
+	---help---
+		Enable I3C driver informational output to SYSLOG.
+
+endif # DEBUG_I3C
+
 config DEBUG_PWM
 	bool "PWM Debug Features"
 	default n

LICENSE

@@ -8674,3 +8674,14 @@ LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+drivers/i3c/device.c
+drivers/i3c/i3c_driver.c
+drivers/i3c/master.c
+drivers/i3c/internals.h
+======================
+
+ Copyright (C) 2018 Cadence Design Systems Inc.
+ Author: Boris Brezillon <[email protected]>
+
+ SPDX-License-Identifier: Apache-2.0

drivers/Kconfig

@@ -12,6 +12,7 @@ source "drivers/loop/Kconfig"
 source "drivers/can/Kconfig"
 source "drivers/clk/Kconfig"
 source "drivers/i2c/Kconfig"
+source "drivers/i3c/Kconfig"
 source "drivers/spi/Kconfig"
 source "drivers/i2s/Kconfig"
 source "drivers/ipcc/Kconfig"

drivers/Makefile

@@ -38,6 +38,7 @@ include math/Make.defs
 include motor/Make.defs
 include i2c/Make.defs
 include i2s/Make.defs
+include i3c/Make.defs
 include ipcc/Make.defs
 include input/Make.defs
 include ioexpander/Make.defs

drivers/i3c/CMakeLists.txt

@@ -0,0 +1,29 @@
+# ##############################################################################
+# drivers/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_I3C)
+  set(SRCS master.c device.c)
+
+  if(CONFIG_I3C_DRIVER)
+    list(APPEND SRCS i3c_driver.c)
+  endif()
+
+  target_sources(drivers PRIVATE ${SRCS})
+endif()

drivers/i3c/Kconfig

@@ -0,0 +1,24 @@
+#
+# For a description of the syntax of this configuration file,
+# see the file kconfig-language.txt in the NuttX tools repository.
+#
+
+menuconfig I3C
+	bool "I3C Driver Support"
+	default n
+	---help---
+		This selection enables building of the "upper-half" I3C driver.
+		See include/nuttx/i3c/master.h for further I3C driver information.
+
+if I3C
+
+config I3C_DRIVER
+	bool "I3C character driver"
+	default n
+	---help---
+		Build in support for a character driver at /dev/i3c[N] that may be
+		used to perform I3C bus transfers from applications.  The intent of
+		this driver is to support I3C testing.  It is not suitable for use
+		in any real driver application.
+
+endif # I3C

drivers/i3c/Make.defs

@@ -0,0 +1,35 @@
+############################################################################
+# drivers/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.
+#
+############################################################################
+
+# Include I3C driver build surrport
+
+ifeq ($(CONFIG_I3C),y)
+
+CSRCS += master.c device.c
+
+ifeq ($(CONFIG_I3C_DRIVER),y)
+CSRCS += i3c_driver.c
+endif
+
+DEPPATH += --dep-path i3c
+VPATH += :i3c
+CFLAGS += ${INCDIR_PREFIX}$(TOPDIR)$(DELIM)drivers$(DELIM)i3c
+
+endif # CONFIG_I3C