diff --git a/Kconfig b/Kconfig index 340838fc9a..1aba0c18f8 100644 --- a/Kconfig +++ b/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 diff --git a/LICENSE b/LICENSE index b24ee0ff1e..241792ccd3 100644 --- a/LICENSE +++ b/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 + + SPDX-License-Identifier: Apache-2.0 diff --git a/drivers/Kconfig b/drivers/Kconfig index 751b07052a..71d3d1ec9e 100644 --- a/drivers/Kconfig +++ b/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" diff --git a/drivers/Makefile b/drivers/Makefile index 87992a1d62..4fe069d461 100644 --- a/drivers/Makefile +++ b/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 diff --git a/drivers/i3c/CMakeLists.txt b/drivers/i3c/CMakeLists.txt new file mode 100644 index 0000000000..e82e0968c5 --- /dev/null +++ b/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() diff --git a/drivers/i3c/Kconfig b/drivers/i3c/Kconfig new file mode 100644 index 0000000000..37e0bd3578 --- /dev/null +++ b/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 diff --git a/drivers/i3c/Make.defs b/drivers/i3c/Make.defs new file mode 100644 index 0000000000..7e7f0a04fc --- /dev/null +++ b/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 diff --git a/drivers/i3c/device.c b/drivers/i3c/device.c new file mode 100644 index 0000000000..388913a3be --- /dev/null +++ b/drivers/i3c/device.c @@ -0,0 +1,310 @@ +/**************************************************************************** + * drivers/i3c/device.c + * + * 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. + * + ****************************************************************************/ + +/**************************************************************************** + * Included Files + ****************************************************************************/ + +#include "internals.h" + +/**************************************************************************** + * Public Functions + ****************************************************************************/ + +/**************************************************************************** + * Name: i3c_device_do_priv_xfers + * + * Description: + * Do I3C SDR private transfers directed to a specific device. + * + * Initiate one or several private SDR transfers with @dev. + * + * This function can sleep and thus cannot be called in atomic context. + * + * Input Parameters: + * dev - Device with which the transfers should be done + * xfers - Array of transfers + * nxfers - Number of transfers + * + * Returned Value: + * 0 in case of success, a negative error core otherwise. + * + ****************************************************************************/ + +int i3c_device_do_priv_xfers(FAR const struct i3c_device *dev, + FAR struct i3c_priv_xfer *xfers, + int nxfers) +{ + int ret; + int i; + + if (nxfers < 1) + { + return 0; + } + + for (i = 0; i < nxfers; i++) + { + if (!xfers[i].len || !xfers[i].data.in) + { + return -EINVAL; + } + } + + i3c_bus_normaluse_lock(dev->bus); + ret = i3c_dev_do_priv_xfers_locked(dev->desc, xfers, nxfers); + i3c_bus_normaluse_unlock(dev->bus); + + return ret; +} + +/**************************************************************************** + * Name: i3c_device_get_info + * Get I3C device information, Retrieve I3C dev info. + * + * Input Parameters: + * dev - Device we want information on. + * info - The information object to fill in. + * + ****************************************************************************/ + +void i3c_device_get_info(FAR const struct i3c_device *dev, + FAR struct i3c_device_info *info) +{ + if (!info) + { + return; + } + + i3c_bus_normaluse_lock(dev->bus); + if (dev->desc) + { + *info = dev->desc->info; + } + + i3c_bus_normaluse_unlock(dev->bus); +} + +/**************************************************************************** + * Name: i3c_device_disable_ibi + * + * Description: + * Disable IBIs coming from a specific device. + * + * This function disable IBIs coming from a specific device and wait for + * all pending IBIs to be processed. + * + * Input Parameters: + * dev - Device on which IBIs should be disabled + * + * Returned Value: + * 0 in case of success, a negative error core otherwise. + * + ****************************************************************************/ + +int i3c_device_disable_ibi(FAR const struct i3c_device *dev) +{ + int ret = -ENOENT; + + i3c_bus_normaluse_lock(dev->bus); + if (dev->desc) + { + nxmutex_lock(&dev->desc->ibi_lock); + ret = i3c_dev_disable_ibi_locked(dev->desc); + nxmutex_unlock(&dev->desc->ibi_lock); + } + + i3c_bus_normaluse_unlock(dev->bus); + + return ret; +} + +/**************************************************************************** + * Name: i3c_device_enable_ibi + * + * Description: + * Enable IBIs coming from a specific device. + * + * This function enable IBIs coming from a specific device and wait for + * all pending IBIs to be processed. This should be called on a device + * where i3c_device_request_ibi() has succeeded. + * + * Note that IBIs from this device might be received before this function + * returns to its caller. + * + * Input Parameters: + * dev - Device on which IBIs should be enabled + * + * Returned Value: + * 0 in case of success, a negative error core otherwise. + * + ****************************************************************************/ + +int i3c_device_enable_ibi(FAR const struct i3c_device *dev) +{ + int ret = -ENOENT; + + i3c_bus_normaluse_lock(dev->bus); + if (dev->desc) + { + nxmutex_lock(&dev->desc->ibi_lock); + ret = i3c_dev_enable_ibi_locked(dev->desc); + nxmutex_unlock(&dev->desc->ibi_lock); + } + + i3c_bus_normaluse_unlock(dev->bus); + + return ret; +} + +/**************************************************************************** + * Name: i3c_device_request_ibi + * + * Description: + * Request an IBI. + * + * This function is responsible for pre-allocating all resources needed to + * process IBIs coming from @dev. When this function returns, the IBI is + * not enabled until i3c_device_enable_ibi() is called. + * + * Input Parameters: + * dev - Device for which we should enable IBIs + * req - Setup requested for this IBI + * + * Returned Value: + * 0 in case of success, a negative error core otherwise. + * + ****************************************************************************/ + +int i3c_device_request_ibi(FAR const struct i3c_device *dev, + FAR const struct i3c_ibi_setup *req) +{ + int ret = -ENOENT; + + if (!req->handler || !req->num_slots) + { + return -EINVAL; + } + + i3c_bus_normaluse_lock(dev->bus); + if (dev->desc) + { + nxmutex_lock(&dev->desc->ibi_lock); + ret = i3c_dev_request_ibi_locked(dev->desc, req); + nxmutex_unlock(&dev->desc->ibi_lock); + } + + i3c_bus_normaluse_unlock(dev->bus); + + return ret; +} + +/**************************************************************************** + * Name: i3c_device_free_ibi + * + * Description: + * Free all resources needed for IBI handling. + * + * This function is responsible for de-allocating resources previously + * allocated by i3c_device_request_ibi(). It should be called after + * disabling IBIs with i3c_device_disable_ibi(). + * + * Input Parameters: + * dev - Device on which you want to release IBI resources + * + ****************************************************************************/ + +void i3c_device_free_ibi(FAR const struct i3c_device *dev) +{ + i3c_bus_normaluse_lock(dev->bus); + if (dev->desc) + { + nxmutex_lock(&dev->desc->ibi_lock); + i3c_dev_free_ibi_locked(dev->desc); + nxmutex_unlock(&dev->desc->ibi_lock); + } + + i3c_bus_normaluse_unlock(dev->bus); +} + +/**************************************************************************** + * Name: i3c_master_find_i3c_dev + * + * Description: + * This function is used to be find a i3c_device address by master handle + * and provisional ID. + * + * Input Parameters: + * master - The master used to get i3c_device on the bus + * id - An instance of i3c_device_id, include manufid,partid and so on. + * + * Returned Value: + * Struct i3c_device var in case of success, NULL otherwise. + ****************************************************************************/ + +FAR const struct i3c_device *i3c_master_find_i3c_dev( + FAR struct i3c_master_controller *master, + FAR const struct i3c_device_id *id) +{ + FAR struct i3c_dev_desc *desc; + uint16_t manuf; + uint16_t part; + uint16_t ext_info; + bool rndpid; + + i3c_bus_normaluse_lock(&master->bus); + i3c_bus_for_each_i3cdev(&master->bus, desc) + { + manuf = I3C_PID_MANUF_ID(desc->info.pid); + part = I3C_PID_PART_ID(desc->info.pid); + ext_info = I3C_PID_EXTRA_INFO(desc->info.pid); + rndpid = I3C_PID_RND_LOWER_32BITS(desc->info.pid); + + if ((id->match_flags & I3C_MATCH_DCR) && + id->dcr != desc->info.dcr) + { + continue; + } + + if ((id->match_flags & I3C_MATCH_MANUF) && + id->manuf_id != manuf) + { + continue; + } + + if ((id->match_flags & I3C_MATCH_PART) && + (rndpid || id->part_id != part)) + { + continue; + } + + if ((id->match_flags & I3C_MATCH_EXTRA_INFO) && + (rndpid || id->extra_info != ext_info)) + { + continue; + } + + i3c_bus_normaluse_unlock(&master->bus); + return desc->dev; + } + + i3c_bus_normaluse_unlock(&master->bus); + return NULL; +} diff --git a/drivers/i3c/i3c_driver.c b/drivers/i3c/i3c_driver.c new file mode 100644 index 0000000000..f3d11c6821 --- /dev/null +++ b/drivers/i3c/i3c_driver.c @@ -0,0 +1,398 @@ +/**************************************************************************** + * drivers/i3c/i3c_driver.c + * + * 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. + * + ****************************************************************************/ + +/**************************************************************************** + * Included Files + ****************************************************************************/ + +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include + +/**************************************************************************** + * Pre-processor Definitions + ****************************************************************************/ + +#define DEVNAME_FMT "/dev/i3c%d" +#define DEVNAME_FMTLEN (8 + 3 + 1) + +/**************************************************************************** + * Private Types + ****************************************************************************/ + +/* Driver state structure */ + +struct i3c_driver_s +{ + /* Contained I3C lower half driver */ + + FAR struct i3c_master_controller *master; + + /* Mutual exclusion */ + + mutex_t lock; + + /* Number of open references */ + + int16_t crefs; + + /* True, driver has been unlinked */ + +#ifndef CONFIG_DISABLE_PSEUDOFS_OPERATIONS + bool unlinked; +#endif +}; + +/**************************************************************************** + * Private Function Prototypes + ****************************************************************************/ + +static int i3cdrvr_open(FAR struct file *filep); +static int i3cdrvr_close(FAR struct file *filep); +static ssize_t i3cdrvr_read(FAR struct file *filep, FAR char *buffer, + size_t buflen); +static ssize_t i3cdrvr_write(FAR struct file *filep, FAR const char *buffer, + size_t buflen); +static int i3cdrvr_ioctl(FAR struct file *filep, int cmd, + unsigned long arg); +static int i3cdrvr_unlink(FAR struct inode *inode); + +/**************************************************************************** + * Private Data + ****************************************************************************/ + +static const struct file_operations g_i3cdrvr_fops = +{ + i3cdrvr_open, /* open */ + i3cdrvr_close, /* close */ + i3cdrvr_read, /* read */ + i3cdrvr_write, /* write */ + NULL, /* seek */ + i3cdrvr_ioctl, /* ioctl */ + NULL, /* mmap */ + NULL, /* truncate */ + NULL /* poll */ +#ifndef CONFIG_DISABLE_PSEUDOFS_OPERATIONS + , i3cdrvr_unlink /* unlink */ +#endif +}; + +/**************************************************************************** + * Private Functions + ****************************************************************************/ + +/**************************************************************************** + * Name: i3cdrvr_open + ****************************************************************************/ + +static int i3cdrvr_open(FAR struct file *filep) +{ + FAR struct inode *inode; + FAR struct i3c_driver_s *priv; + int ret; + + DEBUGASSERT(filep != NULL && filep->f_inode != NULL); + inode = filep->f_inode; + + priv = inode->i_private; + DEBUGASSERT(priv); + + /* Get exclusive access to the I3C driver state structure */ + + ret = nxmutex_lock(&priv->lock); + if (ret < 0) + { + return ret; + } + + /* Increment the count of open references on the driver */ + + priv->crefs++; + DEBUGASSERT(priv->crefs > 0); + + nxmutex_unlock(&priv->lock); + return OK; +} + +/**************************************************************************** + * Name: i3cdrvr_close + ****************************************************************************/ + +static int i3cdrvr_close(FAR struct file *filep) +{ + FAR struct inode *inode; + FAR struct i3c_driver_s *priv; + int ret; + + /* Get our private data structure */ + + DEBUGASSERT(filep != NULL && filep->f_inode != NULL); + inode = filep->f_inode; + + priv = inode->i_private; + DEBUGASSERT(priv); + + /* Get exclusive access to the I3C driver state structure */ + + ret = nxmutex_lock(&priv->lock); + if (ret < 0) + { + return ret; + } + + /* Decrement the count of open references on the driver */ + + DEBUGASSERT(priv->crefs > 0); + priv->crefs--; + + /* If the count has decremented to zero,then commit Hara-Kiri now. */ + +#ifndef CONFIG_DISABLE_PSEUDOFS_OPERATIONS + if (priv->crefs <= 0 && priv->unlinked) +#else + if (priv->crefs <= 0) +#endif + { + nxmutex_destroy(&priv->lock); + kmm_free(priv); + return OK; + } + + nxmutex_unlock(&priv->lock); + return OK; +} + +/**************************************************************************** + * Name: i3cdrvr_read + ****************************************************************************/ + +static ssize_t i3cdrvr_read(FAR struct file *filep, FAR char *buffer, + size_t len) +{ + return 0; /* Return EOF */ +} + +/**************************************************************************** + * Name: i3cdrvr_write + ****************************************************************************/ + +static ssize_t i3cdrvr_write(FAR struct file *filep, FAR const char *buffer, + size_t len) +{ + return len; /* Say that everything was written */ +} + +/**************************************************************************** + * Name: i3cdrvr_ioctl + ****************************************************************************/ + +static int i3cdrvr_ioctl(FAR struct file *filep, int cmd, unsigned long arg) +{ + FAR struct inode *inode; + FAR struct i3c_driver_s *priv; + FAR struct i3c_transfer_s *transfer; + FAR struct i3c_dev_desc *desc; + bool obtain = false; + uint16_t manufid; + uint16_t partid; + int ret; + + DEBUGASSERT(filep != NULL && filep->f_inode != NULL); + inode = filep->f_inode; + + priv = inode->i_private; + DEBUGASSERT(priv); + + /* Get exclusive access to the I3C driver state structure */ + + ret = nxmutex_lock(&priv->lock); + if (ret < 0) + { + return ret; + } + + transfer = (FAR struct i3c_transfer_s *)((uintptr_t)arg); + DEBUGASSERT(transfer != NULL); + + i3c_bus_normaluse_lock(&priv->master->bus); + i3c_bus_for_each_i3cdev(&priv->master->bus, desc) + { + manufid = I3C_PID_MANUF_ID(desc->info.pid); + partid = I3C_PID_PART_ID(desc->info.pid); + + if (manufid == transfer->manufid && partid == transfer->partid) + { + obtain = true; + break; + } + } + + i3c_bus_normaluse_unlock(&priv->master->bus); + if (!obtain) + { + nxmutex_unlock(&priv->lock); + return -ENXIO; + } + + /* Process the IOCTL command */ + + switch (cmd) + { + case I3CIOC_PRIV_XFERS: + + DEBUGASSERT(transfer->xfers != NULL); + + /* Perform the transfer */ + + ret = i3c_device_do_priv_xfers(desc->dev, transfer->xfers, + transfer->nxfers); + break; + case I3CIOC_GET_DEVINFO: + + DEBUGASSERT(transfer->info != NULL); + + /* Perform the get specified i3c device operating */ + + i3c_device_get_info(desc->dev, transfer->info); + break; + default: + ret = -ENOTTY; + break; + } + + nxmutex_unlock(&priv->lock); + return ret; +} + +/**************************************************************************** + * Name: i3cdrvr_unlink + ****************************************************************************/ + +#ifndef CONFIG_DISABLE_PSEUDOFS_OPERATIONS +static int i3cdrvr_unlink(FAR struct inode *inode) +{ + FAR struct i3c_driver_s *priv; + int ret; + + /* Get our private data structure */ + + DEBUGASSERT(inode != NULL && inode->i_private != NULL); + priv = (FAR struct i3c_driver_s *)inode->i_private; + + /* Get exclusive access to the I3C driver state structure */ + + ret = nxmutex_lock(&priv->lock); + if (ret < 0) + { + return ret; + } + + /* Are there open references to the driver data structure? */ + + if (priv->crefs <= 0) + { + nxmutex_destroy(&priv->lock); + kmm_free(priv); + return OK; + } + + /* No... just mark the driver as unlinked and free the resources when the + * last client closes their reference to the driver. + */ + + priv->unlinked = true; + nxmutex_unlock(&priv->lock); + return ret; +} +#endif + +/**************************************************************************** + * Public Functions + ****************************************************************************/ + +/**************************************************************************** + * Name: i3c_register + * + * Description: + * Create and register the I3C character driver. + * + * The I3C character driver is a simple character driver that supports I3C + * transfers. The intent of this driver is to support I3C testing. It is + * not suitable for use in any real driver application. + * + * Input Parameters: + * master - the lower half of an the controller object about I3C master + * driver. + * bus - The I3C bus number. This will be used as the I3C device minor + * number. The I3C character device will be registered as /dev/i3cN + * where N is the minor number + * + * Returned Value: + * OK if the driver was successfully register; A negated errno value is + * returned on any failure. + * + ****************************************************************************/ + +int i3c_register(FAR struct i3c_master_controller *master, int bus) +{ + FAR struct i3c_driver_s *priv; + char devname[DEVNAME_FMTLEN]; + int ret; + + /* Sanity check */ + + DEBUGASSERT(master != NULL && (unsigned)bus < 1000); + + priv = kmm_zalloc(sizeof(struct i3c_driver_s)); + if (priv == NULL) + { + return -ENOMEM; + } + + priv->master = master; + nxmutex_init(&priv->lock); + + /* Create the character device name */ + + snprintf(devname, sizeof(devname), DEVNAME_FMT, bus); + ret = register_driver(devname, &g_i3cdrvr_fops, 0666, priv); + if (ret < 0) + { + /* Free the device structure if we failed to create the character + * device. + */ + + nxmutex_destroy(&priv->lock); + kmm_free(priv); + } + + /* Return the result of the registration */ + + return ret; +} + diff --git a/drivers/i3c/internals.h b/drivers/i3c/internals.h new file mode 100644 index 0000000000..4f6ecf9c1e --- /dev/null +++ b/drivers/i3c/internals.h @@ -0,0 +1,49 @@ +/**************************************************************************** + * drivers/i3c/internals.h + * + * 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. + * + ****************************************************************************/ + +#ifndef __INCLUDE_NUTTX_I3C_INTERNALS_H +#define __INCLUDE_NUTTX_I3C_INTERNALS_H + +/**************************************************************************** + * Included Files + ****************************************************************************/ + +#include + +/**************************************************************************** + * Public Functions Definitions + ****************************************************************************/ + +void i3c_bus_normaluse_lock(FAR struct i3c_bus *bus); +void i3c_bus_normaluse_unlock(FAR struct i3c_bus *bus); + +FAR struct i3c_master_controller * + i3c_adapter_to_i3c_master(FAR struct i3c_master_s *i3c_master); + +int i3c_dev_do_priv_xfers_locked(FAR struct i3c_dev_desc *dev, + FAR struct i3c_priv_xfer *xfers, + int nxfers); +int i3c_dev_disable_ibi_locked(FAR struct i3c_dev_desc *dev); +int i3c_dev_enable_ibi_locked(FAR struct i3c_dev_desc *dev); +int i3c_dev_request_ibi_locked(FAR struct i3c_dev_desc *dev, + FAR const struct i3c_ibi_setup *req); +void i3c_dev_free_ibi_locked(FAR struct i3c_dev_desc *dev); + +#endif /* __INCLUDE_NUTTX_I3C_INTERNAL_H */ diff --git a/drivers/i3c/master.c b/drivers/i3c/master.c new file mode 100644 index 0000000000..d9c21adcc4 --- /dev/null +++ b/drivers/i3c/master.c @@ -0,0 +1,2286 @@ +/**************************************************************************** + * drivers/i3c/master.c + * + * 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. + * + ****************************************************************************/ + +/**************************************************************************** + * Included Files + ****************************************************************************/ + +#include +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include "internals.h" + +/**************************************************************************** + * Private Data + ****************************************************************************/ + +/**************************************************************************** + * Private Functions + ****************************************************************************/ + +/**************************************************************************** + * Name: i3c_bus_maintenance_lock + * + * Description: + * Lock the bus for a maintenance operation + * + * This function takes the bus lock so that no other operations can + * occur on the bus. This is needed for all kind of bus maintenance + * operation, like + * - enabling/disabling slave events + * - re-triggering DAA + * - changing the dynamic address of a device + * - relinquishing mastership + * + * The reason for this kind of locking is that we don't want drivers + * and core logic to rely on I3C device information that could be + * changed behind their back. + * + * Input Parameters: + * bus - I3C bus to take the lock on. + * + ****************************************************************************/ + +static void i3c_bus_maintenance_lock(FAR struct i3c_bus *bus) +{ + nxmutex_lock(&bus->lock); +} + +/**************************************************************************** + * Name: i3c_bus_maintenance_unlock + * + * Description: + * Release the bus lock after a maintenance operation. + * + * Should be called when the bus maintenance operation is done. + * See i3c_bus_maintenance_lock() for more details on what these + * maintenance operations are. + * + * Input Parameters: + * bus - I3C bus to release the lock on. + * + ****************************************************************************/ + +static void i3c_bus_maintenance_unlock(FAR struct i3c_bus *bus) +{ + nxmutex_unlock(&bus->lock); +} + +/**************************************************************************** + * Name: i3c_bus_to_i3c_master + ****************************************************************************/ + +static FAR struct i3c_master_controller * +i3c_bus_to_i3c_master(FAR struct i3c_bus *i3cbus) +{ + return container_of(i3cbus, struct i3c_master_controller, bus); +} + +static FAR struct i3c_master_controller * +i2c_adapter_to_i3c_master(FAR struct i2c_master_s *i2c_master) +{ + return container_of(i2c_master, struct i3c_master_controller, i2c); +} + +static int i3c_master_to_i2c_bus_number( + FAR struct i3c_master_controller *master) +{ + return master->i2c_bus_id; +} + +/**************************************************************************** + * Name: i3c_bus_get_addr_slot_status + ****************************************************************************/ + +static enum i3c_addr_slot_status +i3c_bus_get_addr_slot_status(FAR struct i3c_bus *bus, uint16_t addr) +{ + int32_t status; + int bitpos = addr * 2; + + if (addr > I3C_I2C_MAX_ADDR) + { + return I3C_ADDR_SLOT_RSVD; + } + + status = bus->addrslots[bitpos / I3C_BITS_PER_LONG]; + status >>= bitpos % I3C_BITS_PER_LONG; + + return status & I3C_ADDR_SLOT_STATUS_MASK; +} + +/**************************************************************************** + * Name: i3c_bus_set_addr_slot_status + ****************************************************************************/ + +static void i3c_bus_set_addr_slot_status(FAR struct i3c_bus *bus, + uint16_t addr, enum i3c_addr_slot_status status) +{ + int bitpos = addr * 2; + FAR uint32_t *ptr; + + if (addr > I3C_I2C_MAX_ADDR) + { + return; + } + + ptr = bus->addrslots + (bitpos / I3C_BITS_PER_LONG); + *ptr &= ~((unsigned long)I3C_ADDR_SLOT_STATUS_MASK << + (bitpos % I3C_BITS_PER_LONG)); + *ptr |= (unsigned long)status << (bitpos % I3C_BITS_PER_LONG); +} + +/**************************************************************************** + * Name: i3c_bus_dev_addr_is_avail + ****************************************************************************/ + +static bool i3c_bus_dev_addr_is_avail(FAR struct i3c_bus *bus, + unsigned char addr) +{ + enum i3c_addr_slot_status status; + + status = i3c_bus_get_addr_slot_status(bus, addr); + return status == I3C_ADDR_SLOT_FREE; +} + +/**************************************************************************** + * Name: i3c_bus_get_free_addr + ****************************************************************************/ + +static int i3c_bus_get_free_addr(FAR struct i3c_bus *bus, + unsigned char start_addr) +{ + enum i3c_addr_slot_status status; + unsigned char addr; + + for (addr = start_addr; addr < I3C_MAX_ADDR; addr++) + { + status = i3c_bus_get_addr_slot_status(bus, addr); + if (status == I3C_ADDR_SLOT_FREE) + { + return addr; + } + } + + return -ENOMEM; +} + +/**************************************************************************** + * Name: i3c_bus_init_addrslots + ****************************************************************************/ + +static void i3c_bus_init_addrslots(FAR struct i3c_bus *bus) +{ + int i; + + /* Addresses 0 to 7 are reserved. */ + + for (i = 0; i < 8; i++) + { + i3c_bus_set_addr_slot_status(bus, i, I3C_ADDR_SLOT_RSVD); + } + + /* Reserve broadcast address and all addresses that might collide + * with the broadcast address when facing a single bit error. + */ + + i3c_bus_set_addr_slot_status(bus, I3C_BROADCAST_ADDR, + I3C_ADDR_SLOT_RSVD); + for (i = 0; i < 7; i++) + { + i3c_bus_set_addr_slot_status(bus, I3C_BROADCAST_ADDR ^ I3C_BIT(i), + I3C_ADDR_SLOT_RSVD); + } +} + +/**************************************************************************** + * Name: i3c_bus_init + ****************************************************************************/ + +static void i3c_bus_init(FAR struct i3c_bus *i3cbus) +{ + FAR struct i3c_master_controller *master; + master = i3c_bus_to_i3c_master(i3cbus); + + nxmutex_init(&i3cbus->lock); + list_initialize(&i3cbus->devs.i3c); + i3c_bus_init_addrslots(i3cbus); + i3cbus->mode = I3C_BUS_MODE_PURE; + i3cbus->id = master->i3c_bus_id; +} + +/**************************************************************************** + * Name: i3c_bus_set_mode + ****************************************************************************/ + +static int i3c_bus_set_mode(FAR struct i3c_bus *i3cbus, + enum i3c_bus_mode mode, unsigned long max_i2c_scl_rate) +{ + i3cbus->mode = mode; + + switch (i3cbus->mode) + { + case I3C_BUS_MODE_PURE: + { + if (!i3cbus->scl_rate.i3c) + { + i3cbus->scl_rate.i3c = I3C_BUS_TYP_I3C_SCL_RATE; + } + } + break; + case I3C_BUS_MODE_MIXED_FAST: + case I3C_BUS_MODE_MIXED_LIMITED: + { + if (!i3cbus->scl_rate.i3c) + { + i3cbus->scl_rate.i3c = I3C_BUS_TYP_I3C_SCL_RATE; + } + + if (!i3cbus->scl_rate.i2c) + { + i3cbus->scl_rate.i2c = max_i2c_scl_rate; + } + } + break; + case I3C_BUS_MODE_MIXED_SLOW: + { + if (!i3cbus->scl_rate.i2c) + { + i3cbus->scl_rate.i2c = max_i2c_scl_rate; + } + + if (!i3cbus->scl_rate.i3c || + i3cbus->scl_rate.i3c > i3cbus->scl_rate.i2c) + { + i3cbus->scl_rate.i3c = i3cbus->scl_rate.i2c; + } + } + break; + default: + return -EINVAL; + } + + /* I3C/I2C frequency may have been overridden, check that user-provided + * values are not exceeding max possible frequency. + */ + + if (i3cbus->scl_rate.i3c > I3C_BUS_MAX_I3C_SCL_RATE || + i3cbus->scl_rate.i2c > I3C_BUS_I2C_FM_PLUS_SCL_RATE) + { + return -EINVAL; + } + + return 0; +} + +static int i3c_master_to_i3c_bus_number( + FAR struct i3c_master_controller *master) +{ + return master->i3c_bus_id; +} + +/**************************************************************************** + * Name: i3c_ccc_cmd_dest_init + ****************************************************************************/ + +static FAR void *i3c_ccc_cmd_dest_init(FAR struct i3c_ccc_cmd_dest *dest, + unsigned char addr, uint16_t payloadlen) +{ + dest->addr = addr; + dest->payload.len = payloadlen; + if (payloadlen) + { + dest->payload.data = kmm_zalloc(payloadlen); + } + else + { + dest->payload.data = NULL; + } + + return dest->payload.data; +} + +/**************************************************************************** + * Name: i3c_ccc_cmd_dest_cleanup + ****************************************************************************/ + +static void i3c_ccc_cmd_dest_cleanup(FAR struct i3c_ccc_cmd_dest *dest) +{ + kmm_free(dest->payload.data); +} + +static void i3c_ccc_cmd_init(FAR struct i3c_ccc_cmd *cmd, bool rnw, + unsigned char id, FAR struct i3c_ccc_cmd_dest *dests, + unsigned int ndests) +{ + cmd->rnw = rnw ? 1 : 0; + cmd->id = id; + cmd->dests = dests; + cmd->ndests = ndests; + cmd->err = I3C_ERROR_UNKNOWN; +} + +/**************************************************************************** + * Name: i3c_master_send_ccc_cmd_locked + ****************************************************************************/ + +static int i3c_master_send_ccc_cmd_locked( + FAR struct i3c_master_controller *master, + FAR struct i3c_ccc_cmd *cmd) +{ + int ret; + + if (!cmd || !master) + { + return -EINVAL; + } + + if (master->init_done && + nxmutex_is_locked(&master->bus.lock)) + { + return -EINVAL; + } + + if (!master->ops->send_ccc_cmd) + { + return -ENOTSUP; + } + + if ((cmd->id & I3C_CCC_DIRECT) && (!cmd->dests || !cmd->ndests)) + { + return -EINVAL; + } + + if (master->ops->supports_ccc_cmd && + !master->ops->supports_ccc_cmd(master, cmd)) + { + return -ENOTSUP; + } + + ret = master->ops->send_ccc_cmd(master, cmd); + if (ret) + { + if (cmd->err != I3C_ERROR_UNKNOWN) + { + return cmd->err; + } + + return ret; + } + + return 0; +} + +static FAR struct i3c_dev_desc * +i3c_master_alloc_i3c_dev(FAR struct i3c_master_controller *master, + FAR const struct i3c_device_info *info) +{ + FAR struct i3c_dev_desc *dev; + + dev = kmm_zalloc(sizeof(*dev)); + if (!dev) + { + return NULL; + } + + dev->common.master = master; + dev->info = *info; + nxmutex_init(&dev->ibi_lock); + + return dev; +} + +static int i3c_master_rstdaa_locked(FAR struct i3c_master_controller *master, + unsigned char addr) +{ + enum i3c_addr_slot_status addrstat; + struct i3c_ccc_cmd_dest dest; + struct i3c_ccc_cmd cmd; + int ret; + + if (!master) + { + return -EINVAL; + } + + addrstat = i3c_bus_get_addr_slot_status(&master->bus, addr); + if (addr != I3C_BROADCAST_ADDR && addrstat != I3C_ADDR_SLOT_I3C_DEV) + { + return -EINVAL; + } + + i3c_ccc_cmd_dest_init(&dest, addr, 0); + i3c_ccc_cmd_init(&cmd, false, + I3C_CCC_RSTDAA(addr == I3C_BROADCAST_ADDR), + &dest, 1); + ret = i3c_master_send_ccc_cmd_locked(master, &cmd); + i3c_ccc_cmd_dest_cleanup(&dest); + + return ret; +} + +static int i3c_master_enec_disec_locked( + FAR struct i3c_master_controller *master, + unsigned char addr, bool enable, unsigned char evts) +{ + FAR struct i3c_ccc_events *events; + struct i3c_ccc_cmd_dest dest; + struct i3c_ccc_cmd cmd; + int ret; + + events = i3c_ccc_cmd_dest_init(&dest, addr, sizeof(*events)); + if (!events) + { + return -ENOMEM; + } + + events->events = evts; + i3c_ccc_cmd_init(&cmd, false, + enable ? + I3C_CCC_ENEC(addr == I3C_BROADCAST_ADDR) : + I3C_CCC_DISEC(addr == I3C_BROADCAST_ADDR), + &dest, 1); + ret = i3c_master_send_ccc_cmd_locked(master, &cmd); + i3c_ccc_cmd_dest_cleanup(&dest); + + return ret; +} + +static int i3c_master_setda_locked(FAR struct i3c_master_controller *master, + unsigned char oldaddr, unsigned char newaddr, bool setdasa) +{ + struct i3c_ccc_cmd_dest dest; + FAR struct i3c_ccc_setda *setda; + struct i3c_ccc_cmd cmd; + int ret; + + if (!oldaddr || !newaddr) + { + return -EINVAL; + } + + setda = i3c_ccc_cmd_dest_init(&dest, oldaddr, sizeof(*setda)); + if (!setda) + { + return -ENOMEM; + } + + setda->addr = newaddr << 1; + i3c_ccc_cmd_init(&cmd, false, + setdasa ? I3C_CCC_SETDASA : I3C_CCC_SETNEWDA, + &dest, 1); + ret = i3c_master_send_ccc_cmd_locked(master, &cmd); + i3c_ccc_cmd_dest_cleanup(&dest); + + return ret; +} + +static int i3c_master_setnewda_locked( + FAR struct i3c_master_controller *master, + unsigned char oldaddr, unsigned char newaddr) +{ + return i3c_master_setda_locked(master, oldaddr, newaddr, false); +} + +static int i3c_master_getmrl_locked(FAR struct i3c_master_controller *master, + FAR struct i3c_device_info *info) +{ + struct i3c_ccc_cmd_dest dest; + FAR struct i3c_ccc_mrl *mrl; + struct i3c_ccc_cmd cmd; + int ret; + + mrl = i3c_ccc_cmd_dest_init(&dest, info->dyn_addr, sizeof(*mrl)); + if (!mrl) + { + return -ENOMEM; + } + + /* When the device does not have IBI payload GETMRL only returns 2 + * bytes of data. + */ + + if (!(info->bcr & I3C_BCR_IBI_PAYLOAD)) + { + dest.payload.len -= 1; + } + + i3c_ccc_cmd_init(&cmd, true, I3C_CCC_GETMRL, &dest, 1); + ret = i3c_master_send_ccc_cmd_locked(master, &cmd); + if (ret) + { + goto out; + } + + switch (dest.payload.len) + { + case 3: + { + info->max_ibi_len = mrl->ibi_len; + info->max_read_len = ntohs(mrl->read_len); + } + break; + case 2: + { + info->max_read_len = ntohs(mrl->read_len); + } + break; + default: + ret = -EIO; + goto out; + } + +out: + i3c_ccc_cmd_dest_cleanup(&dest); + + return ret; +} + +static int i3c_master_getmwl_locked(FAR struct i3c_master_controller *master, + FAR struct i3c_device_info *info) +{ + struct i3c_ccc_cmd_dest dest; + FAR struct i3c_ccc_mwl *mwl; + struct i3c_ccc_cmd cmd; + int ret; + + mwl = i3c_ccc_cmd_dest_init(&dest, info->dyn_addr, sizeof(*mwl)); + if (!mwl) + { + return -ENOMEM; + } + + i3c_ccc_cmd_init(&cmd, true, I3C_CCC_GETMWL, &dest, 1); + ret = i3c_master_send_ccc_cmd_locked(master, &cmd); + if (ret) + { + goto out; + } + + if (dest.payload.len != sizeof(*mwl)) + { + ret = -EIO; + goto out; + } + + info->max_write_len = ntohs(mwl->len); + +out: + i3c_ccc_cmd_dest_cleanup(&dest); + + return ret; +} + +static int i3c_master_getmxds_locked( + FAR struct i3c_master_controller *master, + FAR struct i3c_device_info *info) +{ + FAR struct i3c_ccc_getmxds *getmaxds; + struct i3c_ccc_cmd_dest dest; + struct i3c_ccc_cmd cmd; + int ret; + + getmaxds = i3c_ccc_cmd_dest_init(&dest, info->dyn_addr, + sizeof(*getmaxds)); + if (!getmaxds) + { + return -ENOMEM; + } + + i3c_ccc_cmd_init(&cmd, true, I3C_CCC_GETMXDS, &dest, 1); + ret = i3c_master_send_ccc_cmd_locked(master, &cmd); + if (ret) + { + goto out; + } + + if (dest.payload.len != 2 && dest.payload.len != 5) + { + ret = -EIO; + goto out; + } + + info->max_read_ds = getmaxds->maxrd; + info->max_write_ds = getmaxds->maxwr; + if (dest.payload.len == 5) + { + info->max_read_turnaround = getmaxds->maxrdturn[0] | + ((uint32_t)getmaxds->maxrdturn[1] << 8) | + ((uint32_t)getmaxds->maxrdturn[2] << 16); + } + +out: + i3c_ccc_cmd_dest_cleanup(&dest); + + return ret; +} + +static int i3c_master_gethdrcap_locked( + FAR struct i3c_master_controller *master, + FAR struct i3c_device_info *info) +{ + FAR struct i3c_ccc_gethdrcap *gethdrcap; + struct i3c_ccc_cmd_dest dest; + struct i3c_ccc_cmd cmd; + int ret; + + gethdrcap = i3c_ccc_cmd_dest_init(&dest, info->dyn_addr, + sizeof(*gethdrcap)); + if (!gethdrcap) + { + return -ENOMEM; + } + + i3c_ccc_cmd_init(&cmd, true, I3C_CCC_GETHDRCAP, &dest, 1); + ret = i3c_master_send_ccc_cmd_locked(master, &cmd); + if (ret) + { + goto out; + } + + if (dest.payload.len != 1) + { + ret = -EIO; + goto out; + } + + info->hdr_cap = gethdrcap->modes; + +out: + i3c_ccc_cmd_dest_cleanup(&dest); + + return ret; +} + +static int i3c_master_getpid_locked(FAR struct i3c_master_controller *master, + FAR struct i3c_device_info *info) +{ + FAR struct i3c_ccc_getpid *getpid; + struct i3c_ccc_cmd_dest dest; + struct i3c_ccc_cmd cmd; + int ret; + int i; + + getpid = i3c_ccc_cmd_dest_init(&dest, info->dyn_addr, sizeof(*getpid)); + if (!getpid) + { + return -ENOMEM; + } + + i3c_ccc_cmd_init(&cmd, true, I3C_CCC_GETPID, &dest, 1); + ret = i3c_master_send_ccc_cmd_locked(master, &cmd); + if (ret) + { + goto out; + } + + info->pid = 0; + for (i = 0; i < sizeof(getpid->pid); i++) + { + int sft = (sizeof(getpid->pid) - i - 1) * 8; + info->pid |= (uint64_t)getpid->pid[i] << sft; + } + +out: + i3c_ccc_cmd_dest_cleanup(&dest); + + return ret; +} + +static int i3c_master_getbcr_locked(FAR struct i3c_master_controller *master, + FAR struct i3c_device_info *info) +{ + FAR struct i3c_ccc_getbcr *getbcr; + struct i3c_ccc_cmd_dest dest; + struct i3c_ccc_cmd cmd; + int ret; + + getbcr = i3c_ccc_cmd_dest_init(&dest, info->dyn_addr, sizeof(*getbcr)); + if (!getbcr) + { + return -ENOMEM; + } + + i3c_ccc_cmd_init(&cmd, true, I3C_CCC_GETBCR, &dest, 1); + ret = i3c_master_send_ccc_cmd_locked(master, &cmd); + if (ret) + { + goto out; + } + + info->bcr = getbcr->bcr; + +out: + i3c_ccc_cmd_dest_cleanup(&dest); + + return ret; +} + +static int i3c_master_getdcr_locked(FAR struct i3c_master_controller *master, + FAR struct i3c_device_info *info) +{ + FAR struct i3c_ccc_getdcr *getdcr; + struct i3c_ccc_cmd_dest dest; + struct i3c_ccc_cmd cmd; + int ret; + + getdcr = i3c_ccc_cmd_dest_init(&dest, info->dyn_addr, sizeof(*getdcr)); + if (!getdcr) + { + return -ENOMEM; + } + + i3c_ccc_cmd_init(&cmd, true, I3C_CCC_GETDCR, &dest, 1); + ret = i3c_master_send_ccc_cmd_locked(master, &cmd); + if (ret) + { + goto out; + } + + info->dcr = getdcr->dcr; + +out: + i3c_ccc_cmd_dest_cleanup(&dest); + + return ret; +} + +static int i3c_master_retrieve_dev_info(FAR struct i3c_dev_desc *dev) +{ + FAR struct i3c_master_controller *master = i3c_dev_get_master(dev); + enum i3c_addr_slot_status slot_status; + int ret; + + if (!dev->info.dyn_addr) + { + return -EINVAL; + } + + slot_status = i3c_bus_get_addr_slot_status(&master->bus, + dev->info.dyn_addr); + if (slot_status == I3C_ADDR_SLOT_RSVD) + { + return -EINVAL; + } + + ret = i3c_master_getpid_locked(master, &dev->info); + if (ret) + { + return ret; + } + + ret = i3c_master_getbcr_locked(master, &dev->info); + if (ret) + { + return ret; + } + + ret = i3c_master_getdcr_locked(master, &dev->info); + if (ret) + { + return ret; + } + + if (dev->info.bcr & I3C_BCR_MAX_DATA_SPEED_LIM) + { + ret = i3c_master_getmxds_locked(master, &dev->info); + if (ret) + { + return ret; + } + } + + if (dev->info.bcr & I3C_BCR_IBI_PAYLOAD) + { + dev->info.max_ibi_len = 1; + } + + i3c_master_getmrl_locked(master, &dev->info); + i3c_master_getmwl_locked(master, &dev->info); + + if (dev->info.bcr & I3C_BCR_HDR_CAP) + { + ret = i3c_master_gethdrcap_locked(master, &dev->info); + if (ret) + { + return ret; + } + } + + return 0; +} + +static void i3c_master_put_i3c_addrs(FAR struct i3c_dev_desc *dev) +{ + FAR struct i3c_master_controller *master = i3c_dev_get_master(dev); + + if (dev->info.dyn_addr) + { + i3c_bus_set_addr_slot_status(&master->bus, dev->info.dyn_addr, + I3C_ADDR_SLOT_FREE); + } +} + +static int i3c_master_get_i3c_addrs(FAR struct i3c_dev_desc *dev) +{ + FAR struct i3c_master_controller *master = i3c_dev_get_master(dev); + enum i3c_addr_slot_status status; + + if (!dev->info.dyn_addr) + { + return 0; + } + + /* ->init_dyn_addr should have been reserved before that, so, if we're + * trying to apply a pre-reserved dynamic address, we should not try + * to reserve the address slot a second time. + */ + + if (dev->info.dyn_addr) + { + status = i3c_bus_get_addr_slot_status(&master->bus, + dev->info.dyn_addr); + if (status != I3C_ADDR_SLOT_FREE) + { + return -EBUSY; + } + + i3c_bus_set_addr_slot_status(&master->bus, dev->info.dyn_addr, + I3C_ADDR_SLOT_I3C_DEV); + } + + return 0; +} + +static int i3c_master_attach_i3c_dev( + FAR struct i3c_master_controller *master, + FAR struct i3c_dev_desc *dev) +{ + int ret; + + /* We don't attach devices to the controller until they are + * addressable on the bus. + */ + + if (!dev->info.dyn_addr) + { + return 0; + } + + ret = i3c_master_get_i3c_addrs(dev); + if (ret) + { + return ret; + } + + /* Do not attach the master device itself. */ + + if (master->this != dev && master->ops->attach_i3c_dev) + { + ret = master->ops->attach_i3c_dev(dev); + if (ret) + { + i3c_master_put_i3c_addrs(dev); + return ret; + } + } + + list_add_tail(&master->bus.devs.i3c, &dev->common.node); + + return 0; +} + +static int i3c_master_reattach_i3c_dev(FAR struct i3c_dev_desc *dev, + unsigned char old_dyn_addr) +{ + FAR struct i3c_master_controller *master = i3c_dev_get_master(dev); + enum i3c_addr_slot_status status; + int ret; + + if (dev->info.dyn_addr != old_dyn_addr) + { + status = i3c_bus_get_addr_slot_status(&master->bus, + dev->info.dyn_addr); + if (status != I3C_ADDR_SLOT_FREE) + { + return -EBUSY; + } + + i3c_bus_set_addr_slot_status(&master->bus, + dev->info.dyn_addr, + I3C_ADDR_SLOT_I3C_DEV); + } + + if (master->ops->reattach_i3c_dev) + { + ret = master->ops->reattach_i3c_dev(dev, old_dyn_addr); + if (ret) + { + i3c_master_put_i3c_addrs(dev); + return ret; + } + } + + return 0; +} + +static void i3c_master_detach_i3c_dev(FAR struct i3c_dev_desc *dev) +{ + FAR struct i3c_master_controller *master = i3c_dev_get_master(dev); + + /* Do not detach the master device itself. */ + + if (master->this != dev && master->ops->detach_i3c_dev) + { + master->ops->detach_i3c_dev(dev); + } + + i3c_master_put_i3c_addrs(dev); + list_delete(&dev->common.node); +} + +static void +i3c_master_register_new_i3c_devs(FAR struct i3c_master_controller *master) +{ + FAR struct i3c_dev_desc *desc; + + if (!master->init_done) + { + return; + } + + i3c_bus_for_each_i3cdev(&master->bus, desc) + { + if (desc->dev || !desc->info.dyn_addr || desc == master->this) + { + continue; + } + + desc->dev = kmm_zalloc(sizeof(*desc->dev)); + if (!desc->dev) + { + continue; + } + + desc->dev->bus = &master->bus; + desc->dev->desc = desc; + } +} + +static void i3c_master_detach_free_devs( + FAR struct i3c_master_controller *master) +{ + FAR struct i3c_dev_desc *i3cdev; + FAR struct i3c_dev_desc *i3ctmp; + + list_for_every_entry_safe(&master->bus.devs.i3c, i3cdev, i3ctmp, + struct i3c_dev_desc, common.node) + { + i3c_master_detach_i3c_dev(i3cdev); + kmm_free(i3cdev); + } +} + +/**************************************************************************** + * Name: i3c_master_bus_init + * + * Description: + * Initialize an I3C bus + * + * This function is following all initialisation steps described in the I3C + * specification: + * + * 1. Attach I2C devs to the master so that the master can fill its + * internal device table appropriately + * + * 2. Call &i3c_master_controller_ops->bus_init() method to initialize + * the master controller. That's usually where the bus mode is selected + * (pure bus or mixed fast/slow bus) + * + * 3. Instruct all devices on the bus to drop their dynamic address. This + * is particularly important when the bus was previously configured by + * someone else (for example the bootloader) + * + * 4. Disable all slave events. + * + * 5. Reserve address slots for I3C devices with init_dyn_addr. And if + * devices also have static_addr, try to pre-assign dynamic addresses + * requested by the FW with SETDASA and attach corresponding statically + * defined I3C devices to the master. + * + * 6. Do a DAA (Dynamic Address Assignment) to assign dynamic addresses to + * all remaining I3C devices + * + * Once this is done, all I3C and I2C devices should be usable. + * + * Input Parameters: + * master - main master initializing the bus + * + * Returned Value: + * A 0 in case of success, an negative error code otherwise. + ****************************************************************************/ + +static int i3c_master_bus_init(FAR struct i3c_master_controller *master) +{ + int ret; + + /* Now execute the controller specific ->bus_init() routine, which + * might configure its internal logic to match the bus limitations. + */ + + ret = master->ops->bus_init(master); + if (ret) + { + goto err_detach_devs; + } + + /* The master device should have been instantiated in ->bus_init(), + * complain if this was not the case. + */ + + if (!master->this) + { + i3cerr("master_set_info() was not called in ->bus_init()\n"); + ret = -EINVAL; + goto err_bus_cleanup; + } + + /* Reset all dynamic address that may have been assigned before + * (assigned by the bootloader for example). + */ + + ret = i3c_master_rstdaa_locked(master, I3C_BROADCAST_ADDR); + if (ret && ret != I3C_ERROR_M2) + { + goto err_bus_cleanup; + } + + /* Disable all slave events before starting DAA. */ + + ret = i3c_master_disec_locked(master, I3C_BROADCAST_ADDR, + I3C_CCC_EVENT_SIR | I3C_CCC_EVENT_MR | + I3C_CCC_EVENT_HJ); + if (ret && ret != I3C_ERROR_M2) + { + goto err_bus_cleanup; + } + + /* Reserve init_dyn_addr first, and then try to pre-assign dynamic + * address and retrieve device information if needed. + * In case pre-assign dynamic address fails, setting dynamic address to + * the requested init_dyn_addr is retried after DAA is done in + * i3c_master_add_i3c_dev_locked(). + */ + + ret = i3c_master_do_daa(master); + if (ret) + { + goto err_rstdaa; + } + + return 0; + +err_rstdaa: + i3c_master_rstdaa_locked(master, I3C_BROADCAST_ADDR); + +err_bus_cleanup: + if (master->ops->bus_cleanup) + { + master->ops->bus_cleanup(master); + } + +err_detach_devs: + i3c_master_detach_free_devs(master); + + return ret; +} + +static void i3c_master_bus_cleanup(FAR struct i3c_master_controller *master) +{ + if (master->ops->bus_cleanup) + { + master->ops->bus_cleanup(master); + } + + i3c_master_detach_free_devs(master); +} + +static FAR struct i3c_dev_desc * +i3c_master_search_i3c_dev_duplicate(FAR struct i3c_dev_desc *refdev) +{ + FAR struct i3c_master_controller *master = i3c_dev_get_master(refdev); + FAR struct i3c_dev_desc *i3cdev; + + i3c_bus_for_each_i3cdev(&master->bus, i3cdev) + { + if (i3cdev != refdev && i3cdev->info.pid == refdev->info.pid) + { + return i3cdev; + } + } + + return NULL; +} + +static int i3c_master_i2c_adapter_xfer(FAR struct i2c_master_s *i2c, + FAR struct i2c_msg_s *xfers, int nxfers) +{ + FAR struct i3c_master_controller *master = i2c_adapter_to_i3c_master(i2c); + int i; + int ret; + uint16_t addr; + + if (!xfers || !master || nxfers <= 0) + { + return -EINVAL; + } + + if (!master->ops->i2c_xfers) + { + return -ENOTSUP; + } + + /* Doing transfers to different devices is not supported. */ + + addr = xfers[0].addr; + for (i = 1; i < nxfers; i++) + { + if (addr != xfers[i].addr) + { + return -ENOTSUP; + } + } + + i3c_bus_normaluse_lock(&master->bus); + ret = master->ops->i2c_xfers(master, xfers, nxfers); + i3c_bus_normaluse_unlock(&master->bus); + + return ret ? ret : nxfers; +} + +static struct i2c_ops_s i3c_master_i2c_algo = +{ + .transfer = i3c_master_i2c_adapter_xfer, +}; + +static void i3c_master_unregister_i3c_devs( + FAR struct i3c_master_controller *master) +{ + FAR struct i3c_dev_desc *i3cdev; + + i3c_bus_for_each_i3cdev(&master->bus, i3cdev) + { + if (!i3cdev->dev) + { + continue; + } + + i3cdev->dev->desc = NULL; + i3cdev->dev->bus = NULL; + kmm_free(i3cdev->dev); + i3cdev->dev = NULL; + } +} + +static void i3c_master_handle_ibi(FAR void *arg) +{ + FAR struct i3c_ibi_slot *slot = (struct i3c_ibi_slot *)arg; + FAR struct i3c_dev_desc *dev = slot->dev; + FAR struct i3c_master_controller *master = i3c_dev_get_master(dev); + struct i3c_ibi_payload payload; + + payload.data = slot->data; + payload.len = slot->len; + + if (dev->dev) + { + dev->ibi->handler(dev->dev, &payload); + } + + master->ops->recycle_ibi_slot(dev, slot); + atomic_fetch_sub(&dev->ibi->pending_ibis, 1); + if (!atomic_load(&dev->ibi->pending_ibis)) + { + sem_post(&dev->ibi->all_ibis_handled); + } +} + +static void i3c_master_init_ibi_slot(FAR struct i3c_dev_desc *dev, + FAR struct i3c_ibi_slot *slot) +{ + slot->dev = dev; +} + +static int i3c_master_check_ops( + FAR const struct i3c_master_controller_ops *ops) +{ + if (!ops || !ops->bus_init || !ops->priv_xfers || + !ops->send_ccc_cmd || !ops->do_daa || !ops->i2c_xfers) + { + return -EINVAL; + } + + if (ops->request_ibi && + (!ops->enable_ibi || !ops->disable_ibi || !ops->free_ibi || + !ops->recycle_ibi_slot)) + { + return -EINVAL; + } + + return 0; +} + +/**************************************************************************** + * Name: i2c_unregister_driver + * + * Description: + * Perform an I2C driver unregister operation. + * + * Input Parameters: + * master - I3C master object. + * + ****************************************************************************/ + +static void i2c_unregister_driver(FAR struct i3c_master_controller *master) +{ + char devname[12]; + int i2c_bus_id = i3c_master_to_i2c_bus_number(master); + + snprintf(devname, sizeof(devname), "/dev/i2c%d", i2c_bus_id); + nx_unlink(devname); +} + +/**************************************************************************** + * Name: i3c_unregister_driver + * + * Description: + * Perform an I3C driver unregister operation. + * + * Input Parameters: + * master - I3C master object. + * + ****************************************************************************/ + +static void i3c_unregister_driver(FAR struct i3c_master_controller *master) +{ + char devname[12]; + + snprintf(devname, sizeof(devname), "/dev/i3c%d", + i3c_master_to_i3c_bus_number(master)); + nx_unlink(devname); +} + +/**************************************************************************** + * Public Functions + ****************************************************************************/ + +/**************************************************************************** + * Name: i3c_bus_normaluse_lock + * + * Description: + * I3C bus to take the lock on. + * + * This function takes the bus lock for any operation that is not a + * maintenance operation (see i3c_bus_maintenance_lock() for + * non-exhaustive list of maintenance operations). Basically all + * communications with I3C devices are normal operations (HDR, SDR + * transfers or CCC commands that do not change bus state or I3C dynamic + * address). + * + * Input Parameters: + * bus - I3C bus to release the lock on. + * + ****************************************************************************/ + +void i3c_bus_normaluse_lock(FAR struct i3c_bus *bus) +{ + nxmutex_lock(&bus->lock); +} + +/**************************************************************************** + * Name: i3c_bus_normaluse_unlock + * + * Description: + * Release the bus lock after a normal operation. + * + * Should be called when a normal operation is done. See + * i3c_bus_normaluse_lock() for more details on what these + * normal operations are. + * + * Input Parameters: + * bus - I3C bus to release the lock on. + * + * + ****************************************************************************/ + +void i3c_bus_normaluse_unlock(FAR struct i3c_bus *bus) +{ + nxmutex_unlock(&bus->lock); +} + +/**************************************************************************** + * Name: i3c_master_get_free_addr + * + * Description: + * Get a free address on the bus. + * + * This function must be called with the bus lock held in write mode. + * + * Input Parameters: + * master - I3C master object. + * start_addr - Where to start searching. + * + * Returned Value: + * The first free address starting at @start_addr (included) or -ENOMEM + * if there's no more address available. + * + ****************************************************************************/ + +int i3c_master_get_free_addr(FAR struct i3c_master_controller *master, + unsigned char start_addr) +{ + return i3c_bus_get_free_addr(&master->bus, start_addr); +} + +/**************************************************************************** + * Name: i3c_master_do_daa + * + * Description: + * Do a DAA (Dynamic Address Assignment) + * + * This function is instantiating an I3C device object and adding it to + * the I3C device list. All device information are automatically retrieved + * using standard CCC commands. + * + * The I3C device object is returned in case the master wants to attach + * private data to it using i3c_dev_set_master_data(). + * + * This function must be called with the bus lock held in write mode. + * + * Input Parameters: + * master - Master doing the DAA + * + * Returned Value: + * A 0 in case of success, an negative error code otherwise. + * + ****************************************************************************/ + +int i3c_master_do_daa(FAR struct i3c_master_controller *master) +{ + int ret; + + i3c_bus_maintenance_lock(&master->bus); + ret = master->ops->do_daa(master); + i3c_bus_maintenance_unlock(&master->bus); + + if (ret) + { + return ret; + } + + i3c_bus_normaluse_lock(&master->bus); + i3c_master_register_new_i3c_devs(master); + i3c_bus_normaluse_unlock(&master->bus); + + return 0; +} + +/**************************************************************************** + * Name: i3c_master_enec_locked + * + * Description: + * Send an ENEC CCC command + * + * Sends an ENEC CCC command to enable some or all events coming from a + * specific slave, or all devices if @addr is %I3C_BROADCAST_ADDR. + * + * This function must be called with the bus lock held in write mode. + * + * Input Parameters: + * master - Master used to send frames on the bus. + * addr - A valid I3C slave address or %I3C_BROADCAST_ADDR + * evts - Events to enable + * + * Returned Value: + * 0 in case of success, a positive I3C error code if the error is + * one of the official Mx error codes, and a negative error code otherwise. + * + ****************************************************************************/ + +int i3c_master_enec_locked(FAR struct i3c_master_controller *master, + unsigned char addr, unsigned char evts) +{ + return i3c_master_enec_disec_locked(master, addr, true, evts); +} + +/**************************************************************************** + * Name: i3c_master_entdaa_locked + * + * Description: + * Start a DAA (Dynamic Address Assignment) procedure + * + * This function must be called with the bus lock held in write mode. + * + * Note that this function only sends the ENTDAA CCC command, all the logic + * behind dynamic address assignment has to be handled in the I3C master + * driver. + * + * Input Parameters: + * master - Master used to send frames on the bus. + * + * Returned Value: + * 0 in case of success, a positive I3C error code if the error is one of + * the official Mx error codes, and a negative error code otherwise. + * + ****************************************************************************/ + +int i3c_master_entdaa_locked(FAR struct i3c_master_controller *master) +{ + struct i3c_ccc_cmd_dest dest; + struct i3c_ccc_cmd cmd; + int ret; + + i3c_ccc_cmd_dest_init(&dest, I3C_BROADCAST_ADDR, 0); + i3c_ccc_cmd_init(&cmd, false, I3C_CCC_ENTDAA, &dest, 1); + ret = i3c_master_send_ccc_cmd_locked(master, &cmd); + i3c_ccc_cmd_dest_cleanup(&dest); + + return ret; +} + +/**************************************************************************** + * Name: i3c_master_disec_locked + * + * Description: + * Send a DISEC CCC command + * + * Send a DISEC CCC command to disable some or all events coming from a + * specific slave, or all devices if @addr is %I3C_BROADCAST_ADDR. + * + * This function must be called with the bus lock held in write mode. + * + * Input Parameters: + * master - Master used to send frames on the bus. + * addr - A valid I3C slave address or %I3C_BROADCAST_ADDR + * evts - Events to disable + * + * Returned Value: + * 0 in case of success, a positive I3C error code if the error is one of + * the official Mx error codes, and a negative error code otherwise. + * + ****************************************************************************/ + +int i3c_master_disec_locked(FAR struct i3c_master_controller *master, + unsigned char addr, unsigned char evts) +{ + return i3c_master_enec_disec_locked(master, addr, false, evts); +} + +/**************************************************************************** + * Name: i3c_master_set_info + * + * Description: + * Set master device information + * + * Set master device info. This should be called from + * &i3c_master_controller_ops->bus_init(). + * + * Not all &i3c_device_info fields are meaningful for a master device. + * Here is a list of fields that should be properly filled: + * + * - &i3c_device_info->dyn_addr + * - &i3c_device_info->bcr + * - &i3c_device_info->dcr + * - &i3c_device_info->pid + * - &i3c_device_info->hdr_cap if %I3C_BCR_HDR_CAP bit is set in + * &i3c_device_info->bcr + * + * This function must be called with the bus lock held in maintenance mode. + * + * Input Parameters: + * master - Master used to send frames on the bus + * info - I3C device information + * + * Returned Value: + * 0 if @info contains valid information (not every piece of + * information can be checked, but we can at least make sure info->dyn_addr + * and @info->bcr are correct), -EINVAL otherwise. + * + ****************************************************************************/ + +int i3c_master_set_info(FAR struct i3c_master_controller *master, + FAR const struct i3c_device_info *info) +{ + FAR struct i3c_dev_desc *i3cdev; + int ret; + + if (!i3c_bus_dev_addr_is_avail(&master->bus, info->dyn_addr)) + { + return -EINVAL; + } + + if (I3C_BCR_DEVICE_ROLE(info->bcr) == I3C_BCR_I3C_MASTER && + master->secondary) + { + return -EINVAL; + } + + if (master->this) + { + return -EINVAL; + } + + i3cdev = i3c_master_alloc_i3c_dev(master, info); + if (i3cdev == NULL) + { + return -ENOMEM; + } + + master->this = i3cdev; + master->bus.cur_master = master->this; + + ret = i3c_master_attach_i3c_dev(master, i3cdev); + if (ret) + { + goto err_free_dev; + } + + return 0; + +err_free_dev: + kmm_free(i3cdev); + + return ret; +} + +/**************************************************************************** + * Name: i3c_master_add_i3c_dev_locked + * + * Description: + * Add an I3C slave to the bus + * + * This function is instantiating an I3C device object and adding it to + * the I3C device list. All device information are automatically retrieved + * using standard CCC commands. + * + * The I3C device object is returned in case the master wants to attach + * private data to it using i3c_dev_set_master_data(). + * + * This function must be called with the bus lock held in write mode. + * + * Input Parameters: + * master - Master used to send frames on the bus + * addr - I3C slave dynamic address assigned to the device + * + * Returned Value: + * A 0 in case of success, an negative error code otherwise. + * + ****************************************************************************/ + +int i3c_master_add_i3c_dev_locked(FAR struct i3c_master_controller *master, + unsigned char addr) +{ + struct i3c_device_info info = + { + .dyn_addr = addr + }; + + FAR struct i3c_dev_desc *newdev; + FAR struct i3c_dev_desc *olddev; + unsigned char old_dyn_addr = addr; + unsigned char expected_dyn_addr; + struct i3c_ibi_setup ibireq; + bool enable_ibi = false; + int ret; + + memset(&ibireq, 0, sizeof(struct i3c_ibi_setup)); + if (!master) + { + return -EINVAL; + } + + newdev = i3c_master_alloc_i3c_dev(master, &info); + if (newdev == NULL) + { + return -ENOMEM; + } + + ret = i3c_master_attach_i3c_dev(master, newdev); + if (ret) + { + goto err_free_dev; + } + + ret = i3c_master_retrieve_dev_info(newdev); + if (ret) + { + goto err_detach_dev; + } + + olddev = i3c_master_search_i3c_dev_duplicate(newdev); + if (olddev) + { + newdev->dev = olddev->dev; + if (newdev->dev) + { + newdev->dev->desc = newdev; + } + + /* We need to restore the IBI state too, so let's save the + * IBI information and try to restore them after olddev has + * been detached+released and its IBI has been stopped and + * the associated resources have been freed. + */ + + nxmutex_lock(&olddev->ibi_lock); + if (olddev->ibi) + { + ibireq.handler = olddev->ibi->handler; + ibireq.max_payload_len = olddev->ibi->max_payload_len; + ibireq.num_slots = olddev->ibi->num_slots; + + if (olddev->ibi->enabled) + { + enable_ibi = true; + i3c_dev_disable_ibi_locked(olddev); + } + + i3c_dev_free_ibi_locked(olddev); + } + + nxmutex_unlock(&olddev->ibi_lock); + + old_dyn_addr = olddev->info.dyn_addr; + + i3c_master_detach_i3c_dev(olddev); + kmm_free(olddev); + } + + ret = i3c_master_reattach_i3c_dev(newdev, old_dyn_addr); + if (ret) + { + goto err_detach_dev; + } + + /* Depending on our previous state, the expected dynamic address might + * differ: + * - if the device already had a dynamic address assigned, let's try to + * re-apply this one + * - if the device did not have a dynamic address and the firmware + * requested a specific address, pick this one + * - in any other case, keep the address automatically assigned by the + * master + */ + + if (old_dyn_addr && old_dyn_addr != newdev->info.dyn_addr) + { + expected_dyn_addr = old_dyn_addr; + } + else + { + expected_dyn_addr = newdev->info.dyn_addr; + } + + if (newdev->info.dyn_addr != expected_dyn_addr) + { + /* Try to apply the expected dynamic address. If it fails, keep + * the address assigned by the master. + */ + + ret = i3c_master_setnewda_locked(master, + newdev->info.dyn_addr, + expected_dyn_addr); + if (!ret) + { + old_dyn_addr = newdev->info.dyn_addr; + newdev->info.dyn_addr = expected_dyn_addr; + i3c_master_reattach_i3c_dev(newdev, old_dyn_addr); + } + else + { + i3cerr("Failed to assign reserved/old address%d%"PRIx64"\n", + master->bus.id, newdev->info.pid); + } + } + + /* Now is time to try to restore the IBI setup. If we're lucky, + * everything works as before, otherwise, all we can do is complain. + * FIXME: maybe we should add callback to inform the driver that it + * should request the IBI again instead of trying to hide that from + * him. + */ + + if (ibireq.handler) + { + nxmutex_lock(&newdev->ibi_lock); + ret = i3c_dev_request_ibi_locked(newdev, &ibireq); + if (ret) + { + i3cerr("Failed to request IBI on device %d-%"PRIx64"\n", + master->bus.id, newdev->info.pid); + } + else if (enable_ibi) + { + ret = i3c_dev_enable_ibi_locked(newdev); + if (ret) + { + i3cerr("Failed to re-enable IBI on device %d-%"PRIx64"\n", + master->bus.id, newdev->info.pid); + } + } + + nxmutex_unlock(&newdev->ibi_lock); + } + + return 0; + +err_detach_dev: + if (newdev->dev && newdev->dev->desc) + { + newdev->dev->desc = NULL; + } + + i3c_master_detach_i3c_dev(newdev); + +err_free_dev: + kmm_free(newdev); + + return ret; +} + +/**************************************************************************** + * Name: i3c_master_queue_ibi + * + * Description: + * Queue an IBI + * + * Queue an IBI to the controller workqueue. The IBI handler attached + * to the dev will be called from a workqueue context. + * + * Input Parameters: + * dev - The device this IBI is coming from + * slot - The IBI slot used to store the payload + * + ****************************************************************************/ + +void i3c_master_queue_ibi(FAR struct i3c_dev_desc *dev, + FAR struct i3c_ibi_slot *slot) +{ + atomic_fetch_add(&dev->ibi->pending_ibis, 1); + work_queue(HPWORK, &slot->work, i3c_master_handle_ibi, slot, 0); +} + +/**************************************************************************** + * Name: i3c_generic_ibi_free_pool + * + * Description: + * Free a generic IBI pool + * + * Free all IBI slots allated by a generic IBI pool. + * + * Input Parameters: + * pool - The IBI pool to free + * + ****************************************************************************/ + +void i3c_generic_ibi_free_pool(FAR struct i3c_generic_ibi_pool *pool) +{ + FAR struct i3c_generic_ibi_slot *slot; + unsigned int nslots = 0; + + while (!list_is_empty(&pool->free_slots)) + { + slot = list_first_entry(&pool->free_slots, + struct i3c_generic_ibi_slot, node); + list_delete(&slot->node); + nslots++; + } + + if (nslots != pool->num_slots) + { + i3cwarn("freed slots num is not equal to allocated slots num\n"); + } + + /* If the number of freed slots is not equal to the number of allocated + * slots we have a leak somewhere. + */ + + kmm_free(pool->payload_buf); + kmm_free(pool->slots); + kmm_free(pool); +} + +/**************************************************************************** + * Name: i3c_generic_ibi_alloc_pool + * + * Description: + * Create a generic IBI pool + * + * Create a generic IBI pool based on the information provided in @req. + * + * Input Parameters: + * dev - The device this pool will be used for + * req - IBI setup request describing what the device driver expects + * + * Returned Value: + * A valid IBI pool in case of success, an ERR_PTR() otherwise. + ****************************************************************************/ + +FAR struct i3c_generic_ibi_pool * +i3c_generic_ibi_alloc_pool(FAR struct i3c_dev_desc *dev, + FAR const struct i3c_ibi_setup *req) +{ + FAR struct i3c_generic_ibi_pool *pool; + FAR struct i3c_generic_ibi_slot *slot; + unsigned int i; + + struct i3c_generic_ibi_pool *ret; + + pool = kmm_zalloc(sizeof(*pool)); + if (!pool) + { + return NULL; + } + + list_initialize(&pool->free_slots); + list_initialize(&pool->pending); + + pool->slots = kmm_calloc(req->num_slots, sizeof(*slot)); + if (!pool->slots) + { + ret = NULL; + goto err_free_pool; + } + + if (req->max_payload_len) + { + pool->payload_buf = kmm_calloc(req->num_slots, + req->max_payload_len); + if (!pool->payload_buf) + { + ret = NULL; + goto err_free_pool; + } + } + + for (i = 0; i < req->num_slots; i++) + { + slot = &pool->slots[i]; + i3c_master_init_ibi_slot(dev, &slot->base); + + if (req->max_payload_len) + { + slot->base.data = pool->payload_buf + + (i * req->max_payload_len); + } + + list_add_tail(&pool->free_slots, &slot->node); + pool->num_slots++; + } + + return pool; + +err_free_pool: + i3c_generic_ibi_free_pool(pool); + return ret; +} + +/**************************************************************************** + * Name: i3c_generic_ibi_get_free_slot + * + * Description: + * Get a free slot from a generic IBI pool + * + * Search for a free slot in a generic IBI pool. + * The slot should be returned to the pool using + * i3c_generic_ibi_recycle_slot() + * when it's no longer needed. + * + * Input Parameters: + * pool - The pool to query an IBI slot on + * + * Returned Value: + * A pointer to a free slot, or NULL if there's no free slot available. + * + ****************************************************************************/ + +FAR struct i3c_ibi_slot * +i3c_generic_ibi_get_free_slot(FAR struct i3c_generic_ibi_pool *pool) +{ + FAR struct i3c_generic_ibi_slot *slot = NULL; + unsigned long flags; + + flags = spin_lock_irqsave(&pool->lock); + if (!list_is_empty(&pool->free_slots)) + { + slot = list_first_entry(&pool->free_slots, + struct i3c_generic_ibi_slot, node); + if (slot) + { + list_delete(&slot->node); + } + } + + spin_unlock_irqrestore(&pool->lock, flags); + + return slot ? &slot->base : NULL; +} + +/**************************************************************************** + * Name: i3c_generic_ibi_recycle_slot + * + * Description: + * Return a slot to a generic IBI pool + * + * Add an IBI slot back to its generic IBI pool. Should be called from the + * master driver struct_master_controller_ops->recycle_ibi() method. + * + * Input Parameters: + * pool - The pool to return the IBI slot to + * s - IBI slot to recycle + * + ****************************************************************************/ + +void i3c_generic_ibi_recycle_slot(FAR struct i3c_generic_ibi_pool *pool, + FAR struct i3c_ibi_slot *s) +{ + FAR struct i3c_generic_ibi_slot *slot; + unsigned long flags; + + if (!s) + { + return; + } + + slot = container_of(s, struct i3c_generic_ibi_slot, base); + flags = spin_lock_irqsave(&pool->lock); + list_add_tail(&pool->free_slots, &slot->node); + spin_unlock_irqrestore(&pool->lock, flags); +} + +int i3c_dev_do_priv_xfers_locked(FAR struct i3c_dev_desc *dev, + FAR struct i3c_priv_xfer *xfers, + int nxfers) +{ + FAR struct i3c_master_controller *master; + + if (!dev) + { + return -ENOENT; + } + + master = i3c_dev_get_master(dev); + if (!master || !xfers) + { + return -EINVAL; + } + + if (!master->ops->priv_xfers) + { + return -ENOTSUP; + } + + return master->ops->priv_xfers(dev, xfers, nxfers); +} + +int i3c_dev_disable_ibi_locked(FAR struct i3c_dev_desc *dev) +{ + FAR struct i3c_master_controller *master; + int ret; + + if (!dev->ibi) + { + return -EINVAL; + } + + master = i3c_dev_get_master(dev); + ret = master->ops->disable_ibi(dev); + if (ret) + { + return ret; + } + + if (atomic_load(&dev->ibi->pending_ibis)) + { + sem_wait(&dev->ibi->all_ibis_handled); + } + + dev->ibi->enabled = false; + sem_destroy(&dev->ibi->all_ibis_handled); + + return 0; +} + +int i3c_dev_enable_ibi_locked(FAR struct i3c_dev_desc *dev) +{ + FAR struct i3c_master_controller *master = i3c_dev_get_master(dev); + int ret; + + if (!dev->ibi) + { + return -EINVAL; + } + + ret = master->ops->enable_ibi(dev); + if (!ret) + { + dev->ibi->enabled = true; + } + + return ret; +} + +int i3c_dev_request_ibi_locked(FAR struct i3c_dev_desc *dev, + FAR const struct i3c_ibi_setup *req) +{ + FAR struct i3c_master_controller *master = i3c_dev_get_master(dev); + FAR struct i3c_device_ibi_info *ibi; + int ret; + + if (!master->ops->request_ibi) + { + return -ENOTSUP; + } + + if (dev->ibi) + { + return -EBUSY; + } + + ibi = kmm_zalloc(sizeof(*ibi)); + if (!ibi) + { + return -ENOMEM; + } + + atomic_init(&ibi->pending_ibis, 0); + sem_init(&ibi->all_ibis_handled, 0, 1); + ibi->handler = req->handler; + ibi->max_payload_len = req->max_payload_len; + ibi->num_slots = req->num_slots; + + dev->ibi = ibi; + ret = master->ops->request_ibi(dev, req); + if (ret) + { + kmm_free(ibi); + dev->ibi = NULL; + } + + return ret; +} + +void i3c_dev_free_ibi_locked(FAR struct i3c_dev_desc *dev) +{ + FAR struct i3c_master_controller *master = i3c_dev_get_master(dev); + + if (!dev->ibi) + { + return; + } + + master->ops->free_ibi(dev); + kmm_free(dev->ibi); + dev->ibi = NULL; +} + +int i3c_master_i2c_attach(FAR struct i3c_master_controller *master, + FAR struct i2c_config_s *config) +{ + int ret; + + i3c_bus_normaluse_lock(&master->bus); + + if (master->ops->attach_i2c_dev) + { + ret = master->ops->attach_i2c_dev(master, config); + if (ret < 0) + { + i3c_bus_normaluse_unlock(&master->bus); + return ret; + } + } + + i3c_bus_normaluse_unlock(&master->bus); + + return 0; +} + +void i3c_master_detach_i2c_dev(FAR struct i3c_master_controller *master, + FAR struct i2c_config_s *config) +{ + i3c_bus_normaluse_lock(&master->bus); + + if (master->ops->detach_i2c_dev) + { + master->ops->detach_i2c_dev(master, config); + } + + i3c_bus_normaluse_unlock(&master->bus); +} + +/**************************************************************************** + * Name: i3c_master_register + * + * Description: + * Register an I3C master. + * + * This function takes care of everything for you: + * - creates and initializes the I3C bus. + * - registers all I3C charactor driver that supports I3C transfer. + * - registers the I2C charactor driver that supports I2C transfer. + * + * Input Parameters: + * master - Master used to send frames on the bus. + * ops - The master controller operations + * secondary - True if you are registering a secondary master. Will return + * -ENOTSUP if set to true since secondary masters are not yet supported + * + * return: + * OK if the driver was successfully register; A negated errno value is + * returned on any failure. + * + ****************************************************************************/ + +int i3c_master_register(FAR struct i3c_master_controller *master, + FAR const struct i3c_master_controller_ops *ops, + bool secondary) +{ + unsigned long i2c_scl_rate = I3C_BUS_I2C_FM_PLUS_SCL_RATE; + FAR struct i3c_bus *i3cbus = i3c_master_get_bus(master); + enum i3c_bus_mode mode = I3C_BUS_MODE_PURE; + int ret; + + /* We do not support secondary masters yet. */ + + if (secondary) + { + return -ENOTSUP; + } + + ret = i3c_master_check_ops(ops); + if (ret) + { + return ret; + } + + master->ops = ops; + master->secondary = secondary; + + i3c_bus_init(i3cbus); + + if (master->mode) + { + mode = master->mode; + } + + if (master->max_i2c_scl_rate) + { + i2c_scl_rate = master->max_i2c_scl_rate; + } + + ret = i3c_bus_set_mode(i3cbus, mode, i2c_scl_rate); + if (ret != 0) + { + return ret; + } + + ret = i3c_master_bus_init(master); + if (ret != 0) + { + return ret; + } + + /* Expose I2C driver node so by the i2c_driver on our I3C Bus */ + + master->i2c.ops = &i3c_master_i2c_algo; + i2c_register(&master->i2c, master->i2c_bus_id); + if (ret < 0) + { + i3cerr("ERROR: Failed to register I2C%d.\n", master->i2c_bus_id); + goto err_cleanup_bus; + } + + /* We're done initializing the bus and the controller, we can now + * register I3C devices discovered during the initial DAA. + */ + + master->init_done = true; + i3c_bus_normaluse_lock(&master->bus); + i3c_master_register_new_i3c_devs(master); + + /* Expose I3C driver node by the i3c_driver on our I3C Bus, i3c driver id + * equal to i3c bus id. + */ + + ret = i3c_register(master, master->i3c_bus_id); + if (ret < 0) + { + i3cerr("ERROR: Failed to register I2C%d.\n", master->i3c_bus_id); + goto err_del_dev; + } + + i3c_bus_normaluse_unlock(&master->bus); + + return 0; + +err_del_dev: + i2c_unregister_driver(master); + +err_cleanup_bus: + i3c_master_bus_cleanup(master); + + return ret; +} + +/**************************************************************************** + * Name: i3c_master_unregister + * + * Description: + * Unregister an I3C master. + * + * Basically undo everything done in i3c_master_register(). + * + * Input Parameters: + * master - Master used to send frames on the bus. + * + ****************************************************************************/ + +void i3c_master_unregister(FAR struct i3c_master_controller *master) +{ + i2c_unregister_driver(master); + i3c_master_unregister_i3c_devs(master); + i3c_master_bus_cleanup(master); + i3c_unregister_driver(master); +} diff --git a/include/debug.h b/include/debug.h index bfe42a199e..1783d20664 100644 --- a/include/debug.h +++ b/include/debug.h @@ -596,6 +596,24 @@ # define i2sinfo _none #endif +#ifdef CONFIG_DEBUG_I3C_ERROR +# define i3cerr _err +#else +# define i3cerr _none +#endif + +#ifdef CONFIG_DEBUG_I3C_WARN +# define i3cwarn _warn +#else +# define i3cwarn _none +#endif + +#ifdef CONFIG_DEBUG_I3C_INFO +# define i3cinfo _info +#else +# define i3cinfo _none +#endif + #ifdef CONFIG_DEBUG_PWM_ERROR # define pwmerr _err #else @@ -1192,6 +1210,14 @@ # define i2sinfodumpbuffer(m,b,n) #endif +#ifdef CONFIG_DEBUG_I3C +# define i3cerrdumpbuffer(m,b,n) errdumpbuffer(m,b,n) +# define i3cinfodumpbuffer(m,b,n) infodumpbuffer(m,b,n) +#else +# define i3cerrdumpbuffer(m,b,n) +# define i3cinfodumpbuffer(m,b,n) +#endif + #ifdef CONFIG_DEBUG_PWM # define pwmerrdumpbuffer(m,b,n) errdumpbuffer(m,b,n) # define pwminfodumpbuffer(m,b,n) infodumpbuffer(m,b,n) diff --git a/include/nuttx/fs/ioctl.h b/include/nuttx/fs/ioctl.h index 4d6c4b4853..17cb8d5c4f 100644 --- a/include/nuttx/fs/ioctl.h +++ b/include/nuttx/fs/ioctl.h @@ -103,6 +103,7 @@ #define _FFIOCBASE (0x3f00) /* Force feedback ioctl commands */ #define _PINCTRLBASE (0x4000) /* Pinctrl driver ioctl commands */ #define _PCIBASE (0x4100) /* Pci ioctl commands */ +#define _I3CBASE (0x4200) /* I3C driver ioctl commands */ #define _WLIOCBASE (0x8b00) /* Wireless modules ioctl network commands */ /* boardctl() commands share the same number space */ @@ -726,6 +727,13 @@ #define _PCIIOCVALID(c) (_IOC_TYPE(c)==_PCIBASE) #define _PCIIOC(nr) _IOC(_PCIBASE,nr) +/* I3C driver ioctl definitions *********************************************/ + +/* see nuttx/include/i3c/i3c_driver.h */ + +#define _I3CIOCVALID(c) (_IOC_TYPE(c)==_I3CBASE) +#define _I3CIOC(nr) _IOC(_I3CBASE,nr) + /* Force Feedback driver command definitions ********************************/ /* see nuttx/include/input/ff.h */ diff --git a/include/nuttx/i3c/ccc.h b/include/nuttx/i3c/ccc.h new file mode 100644 index 0000000000..229f321011 --- /dev/null +++ b/include/nuttx/i3c/ccc.h @@ -0,0 +1,443 @@ +/**************************************************************************** + * include/nuttx/i3c/ccc.h + * + * 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. + * + ****************************************************************************/ + +#ifndef __INCLUDE_NUTTX_I3C_CCC_H +#define __INCLUDE_NUTTX_I3C_CCC_H + +/**************************************************************************** + * Included Files + ****************************************************************************/ + +#include + +#include +#include +#include + +/**************************************************************************** + * Pre-processor Definitions + ****************************************************************************/ + +/* I3C CCC (Common Command Codes) related definitions */ + +#define I3C_CCC_DIRECT I3C_BIT(7) + +#define I3C_CCC_ID(id, broadcast) \ + ((id) | ((broadcast) ? 0 : I3C_CCC_DIRECT)) + +/* Commands valid in both broadcast and unicast modes */ + +#define I3C_CCC_ENEC(broadcast) I3C_CCC_ID(0x0, broadcast) +#define I3C_CCC_DISEC(broadcast) I3C_CCC_ID(0x1, broadcast) +#define I3C_CCC_ENTAS(as, broadcast) I3C_CCC_ID(0x2 + (as), broadcast) +#define I3C_CCC_RSTDAA(broadcast) I3C_CCC_ID(0x6, broadcast) +#define I3C_CCC_SETMWL(broadcast) I3C_CCC_ID(0x9, broadcast) +#define I3C_CCC_SETMRL(broadcast) I3C_CCC_ID(0xa, broadcast) +#define I3C_CCC_SETXTIME(broadcast) ((broadcast) ? 0x28 : 0x98) +#define I3C_CCC_VENDOR(id, broadcast) ((id) + ((broadcast) ? 0x61 : 0xe0)) + +/* Broadcast-only commands */ + +#define I3C_CCC_ENTDAA I3C_CCC_ID(0x7, true) +#define I3C_CCC_DEFSLVS I3C_CCC_ID(0x8, true) +#define I3C_CCC_ENTTM I3C_CCC_ID(0xb, true) +#define I3C_CCC_ENTHDR(x) I3C_CCC_ID(0x20 + (x), true) + +/* Unicast-only commands */ + +#define I3C_CCC_SETDASA I3C_CCC_ID(0x7, false) +#define I3C_CCC_SETNEWDA I3C_CCC_ID(0x8, false) +#define I3C_CCC_GETMWL I3C_CCC_ID(0xb, false) +#define I3C_CCC_GETMRL I3C_CCC_ID(0xc, false) +#define I3C_CCC_GETPID I3C_CCC_ID(0xd, false) +#define I3C_CCC_GETBCR I3C_CCC_ID(0xe, false) +#define I3C_CCC_GETDCR I3C_CCC_ID(0xf, false) +#define I3C_CCC_GETSTATUS I3C_CCC_ID(0x10, false) +#define I3C_CCC_GETACCMST I3C_CCC_ID(0x11, false) +#define I3C_CCC_SETBRGTGT I3C_CCC_ID(0x13, false) +#define I3C_CCC_GETMXDS I3C_CCC_ID(0x14, false) +#define I3C_CCC_GETHDRCAP I3C_CCC_ID(0x15, false) +#define I3C_CCC_GETXTIME I3C_CCC_ID(0x19, false) + +#define I3C_CCC_EVENT_SIR I3C_BIT(0) +#define I3C_CCC_EVENT_MR I3C_BIT(1) +#define I3C_CCC_EVENT_HJ I3C_BIT(3) + +#define I3C_CCC_STATUS_PENDING_INT(status) ((status) & I3C_GENMASK(3, 0)) +#define I3C_CCC_STATUS_PROTOCOL_ERROR I3C_BIT(5) +#define I3C_CCC_STATUS_ACTIVITY_MODE(status) \ + (((status) & I3C_GENMASK(7, 6)) >> 6) + +#define I3C_CCC_MAX_SDR_FSCL_MASK I3C_GENMASK(2, 0) +#define I3C_CCC_MAX_SDR_FSCL(x) ((x) & I3C_CCC_MAX_SDR_FSCL_MASK) + +#define I3C_CCC_HDR_MODE(mode) I3C_BIT(mode) + +#define I3C_CCC_GETXTIME_SYNC_MODE I3C_BIT(0) +#define I3C_CCC_GETXTIME_ASYNC_MODE(x) I3C_BIT((x) + 1) +#define I3C_CCC_GETXTIME_OVERFLOW I3C_BIT(7) + +/**************************************************************************** + * Public Types + ****************************************************************************/ + +/* struct i3c_ccc_events - payload passed to ENEC/DISEC CCC + * + * @events: bitmask of I3C_CCC_EVENT_xxx events. + * + * Depending on the CCC command, the specific events coming from all devices + * (broadcast version) or a specific device (unicast version) will be + * enabled (ENEC) or disabled (DISEC). + */ + +struct i3c_ccc_events +{ + uint8_t events; +}; + +/* struct i3c_ccc_mwl - payload passed to SETMWL/GETMWL CCC + * + * @len: maximum write length in bytes + * + * The maximum write length is only applicable to SDR private messages or + * extended Write CCCs (like SETXTIME). + */ + +struct i3c_ccc_mwl +{ + uint16_t len; +}; + +/* struct i3c_ccc_mrl - payload passed to SETMRL/GETMRL CCC + * + * @len: maximum read length in bytes + * @ibi_len: maximum IBI payload length + * + * The maximum read length is only applicable to SDR private messages or + * extended Read CCCs (like GETXTIME). + * The IBI length is only valid if the I3C slave is IBI capable + * (%I3C_BCR_IBI_REQ_CAP is set). + */ + +begin_packed_struct struct i3c_ccc_mrl +{ + uint16_t read_len; + uint8_t ibi_len; +} end_packed_struct; + +/* struct i3c_ccc_dev_desc - I3C/I2C device descriptor used for DEFSLVS + * + * @dyn_addr: dynamic address assigned to the I3C slave or 0 if the entry is + * describing an I2C slave. + * @dcr: DCR value (not applicable to entries describing I2C devices) + * @lvr: LVR value (not applicable to entries describing I3C devices) + * @bcr: BCR value or 0 if this entry is describing an I2C slave + * @static_addr: static address or 0 if the device does not have a static + * address + * + * The DEFSLVS command should be passed an array of i3c_ccc_dev_desc + * descriptors (one entry per I3C/I2C dev controlled by the master). + */ + +struct i3c_ccc_dev_desc +{ + uint8_t dyn_addr; + union + { + uint8_t dcr; + uint8_t lvr; + }; + uint8_t bcr; + uint8_t static_addr; +}; + +/* struct i3c_ccc_defslvs - payload passed to DEFSLVS CCC + * + * @count: number of dev descriptors + * @master: descriptor describing the current master + * @slaves: array of descriptors describing slaves controlled by the + * current master + * + * Information passed to the broadcast DEFSLVS to propagate device + * information to all masters currently acting as slaves on the bus. + * This is only meaningful if you have more than one master. + */ + +begin_packed_struct struct i3c_ccc_defslvs +{ + uint8_t count; + struct i3c_ccc_dev_desc master; + struct i3c_ccc_dev_desc slaves[0]; +} end_packed_struct; + +/* enum i3c_ccc_test_mode - enum listing all available test modes + * + * @I3C_CCC_EXIT_TEST_MODE: exit test mode + * @I3C_CCC_VENDOR_TEST_MODE: enter vendor test mode + */ + +enum i3c_ccc_test_mode +{ + I3C_CCC_EXIT_TEST_MODE, + I3C_CCC_VENDOR_TEST_MODE, +}; + +/* struct i3c_ccc_enttm - payload passed to ENTTM CCC + * + * @mode: one of the &enum i3c_ccc_test_mode modes + * + * Information passed to the ENTTM CCC to instruct an I3C device to enter a + * specific test mode. + */ + +struct i3c_ccc_enttm +{ + uint8_t mode; +}; + +/* struct i3c_ccc_setda - payload passed to SETNEWDA and SETDASA CCCs + * + * @addr: dynamic address to assign to an I3C device + * + * Information passed to the SETNEWDA and SETDASA CCCs to assign/change the + * dynamic address of an I3C device. + */ + +struct i3c_ccc_setda +{ + uint8_t addr; +}; + +/* struct i3c_ccc_getpid - payload passed to GETPID CCC + * + * @pid: 48 bits PID in big endian + */ + +struct i3c_ccc_getpid +{ + uint8_t pid[6]; +}; + +/* struct i3c_ccc_getbcr - payload passed to GETBCR CCC + * + * @bcr: BCR (Bus Characteristic Register) value + */ + +struct i3c_ccc_getbcr +{ + uint8_t bcr; +}; + +/* struct i3c_ccc_getdcr - payload passed to GETDCR CCC + * + * @dcr: DCR (Device Characteristic Register) value + */ + +struct i3c_ccc_getdcr +{ + uint8_t dcr; +}; + +/* struct i3c_ccc_getstatus - payload passed to GETSTATUS CCC + * + * @status: status of the I3C slave (see I3C_CCC_STATUS_xxx macros for more + * information). + */ + +struct i3c_ccc_getstatus +{ + uint16_t status; +}; + +/* struct i3c_ccc_getaccmst - payload passed to GETACCMST CCC + * + * @newmaster: address of the master taking bus ownership + */ + +struct i3c_ccc_getaccmst +{ + uint8_t newmaster; +}; + +/* struct i3c_ccc_bridged_slave_desc - bridged slave descriptor + * + * @addr: dynamic address of the bridged device + * @id: ID of the slave device behind the bridge + */ + +begin_packed_struct struct i3c_ccc_bridged_slave_desc +{ + uint8_t addr; + uint16_t id; +} end_packed_struct; + +/* struct i3c_ccc_setbrgtgt - payload passed to SETBRGTGT CCC + * + * @count: number of bridged slaves + * @bslaves: bridged slave descriptors + */ + +begin_packed_struct struct i3c_ccc_setbrgtgt +{ + uint8_t count; + struct i3c_ccc_bridged_slave_desc bslaves[0]; +} end_packed_struct; + +/* enum i3c_sdr_max_data_rate - max data rate values for private + * SDR transfers + */ + +enum i3c_sdr_max_data_rate +{ + I3C_SDR0_FSCL_MAX, + I3C_SDR1_FSCL_8MHZ, + I3C_SDR2_FSCL_6MHZ, + I3C_SDR3_FSCL_4MHZ, + I3C_SDR4_FSCL_2MHZ, +}; + +/* enum i3c_tsco - clock to data turn-around */ + +enum i3c_tsco +{ + I3C_TSCO_8NS, + I3C_TSCO_9NS, + I3C_TSCO_10NS, + I3C_TSCO_11NS, + I3C_TSCO_12NS, +}; + +/* struct i3c_ccc_getmxds - payload passed to GETMXDS CCC + * + * @maxwr: write limitations + * @maxrd: read limitations + * @maxrdturn: maximum read turn-around expressed micro-seconds and + * little-endian formatted + */ + +begin_packed_struct struct i3c_ccc_getmxds +{ + uint8_t maxwr; + uint8_t maxrd; + uint8_t maxrdturn[3]; +} end_packed_struct; + +/* struct i3c_ccc_gethdrcap - payload passed to GETHDRCAP CCC + * + * @modes: bitmap of supported HDR modes + */ + +begin_packed_struct struct i3c_ccc_gethdrcap +{ + uint8_t modes; +} end_packed_struct; + +/* enum i3c_ccc_setxtime_subcmd - SETXTIME sub-commands */ + +enum i3c_ccc_setxtime_subcmd +{ + I3C_CCC_SETXTIME_ST = 0x7f, + I3C_CCC_SETXTIME_DT = 0xbf, + I3C_CCC_SETXTIME_ENTER_ASYNC_MODE0 = 0xdf, + I3C_CCC_SETXTIME_ENTER_ASYNC_MODE1 = 0xef, + I3C_CCC_SETXTIME_ENTER_ASYNC_MODE2 = 0xf7, + I3C_CCC_SETXTIME_ENTER_ASYNC_MODE3 = 0xfb, + I3C_CCC_SETXTIME_ASYNC_TRIGGER = 0xfd, + I3C_CCC_SETXTIME_TPH = 0x3f, + I3C_CCC_SETXTIME_TU = 0x9f, + I3C_CCC_SETXTIME_ODR = 0x8f, +}; + +/* struct i3c_ccc_setxtime - payload passed to SETXTIME CCC + * + * @subcmd: one of the sub-commands ddefined in &enum i3c_ccc_setxtime_subcmd + * @data: sub-command payload. Amount of data is determined by + * &i3c_ccc_setxtime->subcmd + */ + +begin_packed_struct struct i3c_ccc_setxtime +{ + uint8_t subcmd; + uint8_t data[0]; +} end_packed_struct; + +/* struct i3c_ccc_getxtime - payload retrieved from GETXTIME CCC + * + * @supported_modes: bitmap describing supported XTIME modes + * @state: current status (enabled mode and overflow status) + * @frequency: slave's internal oscillator frequency in 500KHz steps + * @inaccuracy: slave's internal oscillator inaccuracy in 0.1% steps + */ + +begin_packed_struct struct i3c_ccc_getxtime +{ + uint8_t supported_modes; + uint8_t state; + uint8_t frequency; + uint8_t inaccuracy; +}end_packed_struct; + +/* struct i3c_ccc_cmd_payload - CCC payload + * + * @len: payload length + * @data: payload data. This buffer must be DMA-able + */ + +struct i3c_ccc_cmd_payload +{ + uint16_t len; + FAR void *data; +}; + +/* struct i3c_ccc_cmd_dest - CCC command destination + * + * @addr: can be an I3C device address or the broadcast address if this is a + * broadcast CCC + * @payload: payload to be sent to this device or broadcasted + */ + +struct i3c_ccc_cmd_dest +{ + uint8_t addr; + struct i3c_ccc_cmd_payload payload; +}; + +/* struct i3c_ccc_cmd - CCC command + * + * @rnw: true if the CCC should retrieve data from the device. Only valid + * for unicast commands + * @id: CCC command id + * @ndests: number of destinations. Should always be one for broadcast + * commands + * @dests: array of destinations and associated payload for this CCC. Most + * of the time, only one destination is provided + * @err: I3C error code + */ + +struct i3c_ccc_cmd +{ + uint8_t rnw; + uint8_t id; + unsigned int ndests; + FAR struct i3c_ccc_cmd_dest *dests; + enum i3c_error_code err; +}; + +#endif /* __INCLUDE_NUTTX_I3C_CCC_H */ diff --git a/include/nuttx/i3c/device.h b/include/nuttx/i3c/device.h new file mode 100644 index 0000000000..2dcb6fff76 --- /dev/null +++ b/include/nuttx/i3c/device.h @@ -0,0 +1,420 @@ +/**************************************************************************** + * include/nuttx/i3c/device.h + * + * 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. + * + ****************************************************************************/ + +#ifndef __INCLUDE_NUTTX_I3C_DEV_H +#define __INCLUDE_NUTTX_I3C_DEV_H + +/**************************************************************************** + * Included Files + ****************************************************************************/ + +#include +#include +#include + +/**************************************************************************** + * Pre-processor Definitions + ****************************************************************************/ + +#define I3C_PID_MANUF_ID(pid) (((pid) & I3C_GENMASK_ULL(47, 33)) >> 33) +#define I3C_PID_RND_LOWER_32BITS(pid) (!!((pid) & BIT_ULL(32))) +#define I3C_PID_RND_VAL(pid) ((pid) & I3C_GENMASK_ULL(31, 0)) +#define I3C_PID_PART_ID(pid) (((pid) & I3C_GENMASK_ULL(31, 16)) >> 16) +#define I3C_PID_INSTANCE_ID(pid) (((pid) & I3C_GENMASK_ULL(15, 12)) >> 12) +#define I3C_PID_EXTRA_INFO(pid) ((pid) & I3C_GENMASK_ULL(11, 0)) + +#define I3C_BCR_DEVICE_ROLE(bcr) ((bcr) & I3C_GENMASK(7, 6)) +#define I3C_BCR_I3C_SLAVE (0 << 6) +#define I3C_BCR_I3C_MASTER (1 << 6) +#define I3C_BCR_HDR_CAP I3C_BIT(5) +#define I3C_BCR_BRIDGE I3C_BIT(4) +#define I3C_BCR_OFFLINE_CAP I3C_BIT(3) +#define I3C_BCR_IBI_PAYLOAD I3C_BIT(2) +#define I3C_BCR_IBI_REQ_CAP I3C_BIT(1) +#define I3C_BCR_MAX_DATA_SPEED_LIM I3C_BIT(0) + +/* i3c */ + +#define I3C_MATCH_DCR 0x1 +#define I3C_MATCH_MANUF 0x2 +#define I3C_MATCH_PART 0x4 +#define I3C_MATCH_EXTRA_INFO 0x8 + +/* These macros should be used to i3c_device_id entries. */ + +#define I3C_MATCH_MANUF_AND_PART (I3C_MATCH_MANUF | I3C_MATCH_PART) + +#define I3C_DEVICE(_manufid, _partid, _drvdata) \ + { \ + .match_flags = I3C_MATCH_MANUF_AND_PART, \ + .manuf_id = _manufid, \ + .part_id = _partid, \ + .data = _drvdata, \ + } + +#define I3C_DEVICE_EXTRA_INFO(_manufid, _partid, _info, _drvdata) \ + { \ + .match_flags = I3C_MATCH_MANUF_AND_PART | \ + I3C_MATCH_EXTRA_INFO, \ + .manuf_id = _manufid, \ + .part_id = _partid, \ + .extra_info = _info, \ + .data = _drvdata, \ + } + +#define I3C_CLASS(_dcr, _drvdata) \ + { \ + .match_flags = I3C_MATCH_DCR, \ + .dcr = _dcr, \ + } + +/**************************************************************************** + * Public Types + ****************************************************************************/ + +struct i3c_device; + +struct i3c_device_id +{ + uint8_t match_flags; + uint8_t dcr; + uint16_t manuf_id; + uint16_t part_id; + uint16_t extra_info; + + FAR const void *data; +}; + +/* enum i3c_error_code - I3C error codes + * + * These are the standard error codes as defined by the I3C specification. + * When -EIO is returned by the i3c_device_do_priv_xfers() or + * i3c_device_send_hdr_cmds() one can check the error code in + * &struct_i3c_priv_xfer.err or &struct i3c_hdr_cmd.err to get a better + * idea of what went wrong. + * + * @I3C_ERROR_UNKNOWN: unknown error, usually means the error is not I3C + * related + * @I3C_ERROR_M0: M0 error + * @I3C_ERROR_M1: M1 error + * @I3C_ERROR_M2: M2 error + */ + +enum i3c_error_code +{ + I3C_ERROR_UNKNOWN = 0, + I3C_ERROR_M0 = 1, + I3C_ERROR_M1, + I3C_ERROR_M2, +}; + +/* enum i3c_hdr_mode - HDR mode ids + * @I3C_HDR_DDR: DDR mode + * @I3C_HDR_TSP: TSP mode + * @I3C_HDR_TSL: TSL mode + */ + +enum i3c_hdr_mode +{ + I3C_HDR_DDR, + I3C_HDR_TSP, + I3C_HDR_TSL, +}; + +/* struct i3c_priv_xfer - I3C SDR private transfer + * @rnw: encodes the transfer direction. true for a read, false for a write + * @len: transfer length in bytes of the transfer + * @data: input/output buffer + * @data.in: input buffer. Must point to a DMA-able buffer + * @data.out: output buffer. Must point to a DMA-able buffer + * @err: I3C error code + */ + +struct i3c_priv_xfer +{ + unsigned char rnw; + uint16_t len; + union + { + FAR void *in; + FAR const void *out; + } data; + enum i3c_error_code err; +}; + +/* enum i3c_dcr - I3C DCR values + * @I3C_DCR_GENERIC_DEVICE: generic I3C device + */ + +enum i3c_dcr +{ + I3C_DCR_GENERIC_DEVICE = 0, +}; + +/* struct i3c_device_info - I3C device information + * @pid: Provisional ID + * @bcr: Bus Characteristic Register + * @dcr: Device Characteristic Register + * @static_addr: static/I2C address + * @dyn_addr: dynamic address + * @hdr_cap: supported HDR modes + * @max_read_ds: max read speed information + * @max_write_ds: max write speed information + * @max_ibi_len: max IBI payload length + * @max_read_turnaround: max read turn-around time in micro-seconds + * @max_read_len: max private SDR read length in bytes + * @max_write_len: max private SDR write length in bytes + * + * These are all basic information that should be advertised by an I3C + * device. + * Some of them are optional depending on the device type and device + * capabilities. + * For each I3C slave attached to a master with + * i3c_master_add_i3c_dev_locked(), the core will send the relevant CCC + * command to retrieve these data. + */ + +struct i3c_device_info +{ + uint64_t pid; + uint8_t bcr; + uint8_t dcr; + uint8_t static_addr; + uint8_t dyn_addr; + uint8_t hdr_cap; + uint8_t max_read_ds; + uint8_t max_write_ds; + uint8_t max_ibi_len; + uint32_t max_read_turnaround; + uint16_t max_read_len; + uint16_t max_write_len; +}; + +/* I3C device internals are kept hidden from I3C device users. It's just + * simpler to refactor things when everything goes through getter/setters, + * and I3C device drivers should not have to worry about internal + * representation anyway. + */ + +struct i3c_ibi_payload +{ + unsigned int len; + FAR const void *data; +}; + +/* struct i3c_ibi_setup - IBI setup object + * @max_payload_len: maximum length of the payload associated to an IBI. + * If one IBI appears to have a payload that is bigger than this + * number, the IBI will be rejected. + * @num_slots: number of pre-allocated IBI slots. This should be chosen so + * that the system never runs out of IBI slots, otherwise you'll + * lose IBIs. + * @handler: IBI handler, every time an IBI is received. This handler is + * called in a workqueue context. It is allowed to sleep and send new + * messages on the bus, though it's recommended to keep the + * processing done there as fast as possible to avoid delaying + * processing of other queued on the same workqueue. + * + * Temporary structure used to pass information to i3c_device_request_ibi(). + * This object can be allocated on the stack since i3c_device_request_ibi() + * copies every bit of information and do not use it after + * i3c_device_request_ibi() has returned. + */ + +struct i3c_ibi_setup +{ + unsigned int max_payload_len; + unsigned int num_slots; + CODE void (*handler)(FAR struct i3c_device *dev, + FAR const struct i3c_ibi_payload *payload); +}; + +/**************************************************************************** + * Public Functions Definitions + ****************************************************************************/ + +/**************************************************************************** + * Name: i3c_device_do_priv_xfers + * + * Description: + * Do I3C SDR private transfers directed to a specific device. + * + * Initiate one or several private SDR transfers with @dev. + * + * This function can sleep and thus cannot be called in atomic context. + * + * Input Parameters: + * desc - An I3C device descriptor will be used for + * xfers - Array of transfers + * nxfers - Number of transfers + * + * Returned Value: + * 0 in case of success, a negative error core otherwise. + * + ****************************************************************************/ + +int i3c_device_do_priv_xfers(FAR const struct i3c_device *dev, + FAR struct i3c_priv_xfer *xfers, + int nxfers); + +/**************************************************************************** + * Name: i3c_device_get_info + * get I3C device information, Retrieve I3C dev info. + * + * Input Parameters: + * dev - A device we want information on. + * info - The information object to fill in. + * + ****************************************************************************/ + +void i3c_device_get_info(FAR const struct i3c_device *dev, + FAR struct i3c_device_info *info); + +/**************************************************************************** + * Name: i3c_device_disable_ibi + * + * Description: + * Disable IBIs coming from a specific device. + * + * This function disable IBIs coming from a specific device and wait for + * all pending IBIs to be processed. + * + * Input Parameters: + * dev - A device on which IBIs should be disabled + * + * Returned Value: + * 0 in case of success, a negative error core otherwise. + * + ****************************************************************************/ + +int i3c_device_disable_ibi(FAR const struct i3c_device *dev); + +/**************************************************************************** + * Name: i3c_device_enable_ibi + * + * Description: + * Enable IBIs coming from a specific device. + * + * This function enable IBIs coming from a specific device and wait for + * all pending IBIs to be processed. This should be called on a device + * where i3c_device_request_ibi() has succeeded. + * + * Note that IBIs from this device might be received before this function + * returns to its caller. + * + * Input Parameters: + * dev - A device on which IBIs should be enabled + * + * Returned Value: + * 0 in case of success, a negative error core otherwise. + * + ****************************************************************************/ + +int i3c_device_enable_ibi(FAR const struct i3c_device *dev); + +/**************************************************************************** + * Name: i3c_device_request_ibi + * + * Description: + * Request an IBI. + * + * This function is responsible for pre-allocating all resources needed to + * process IBIs coming from @dev. When this function returns, the IBI is + * not enabled until i3c_device_enable_ibi() is called. + * + * Input Parameters: + * dev - An I3C device descriptor will be used for. + * req - setup requested for this IBI. + * + * Returned Value: + * 0 in case of success, a negative error core otherwise. + * + ****************************************************************************/ + +int i3c_device_request_ibi(FAR const struct i3c_device *dev, + FAR const struct i3c_ibi_setup *req); + +/**************************************************************************** + * Name: i3c_device_free_ibi + * + * Description: + * Free all resources needed for IBI handling. + * + * This function is responsible for de-allocating resources previously + * allocated by i3c_device_request_ibi(). It should be called after + * disabling IBIs with i3c_device_disable_ibi(). + * + * Input Parameters: + * dev - Device on which you want to release IBI resources + * + ****************************************************************************/ + +void i3c_device_free_ibi(FAR const struct i3c_device *dev); + +/**************************************************************************** + * Name: i3c_master_i2c_attach + * + * Description: + * Config an i2c device address to controller driver. + * + * Input Parameters: + * master - The master used to get i3c_device on the bus + * config - An i2c device information to add + * + * Returned Value: + * Return 0 if success, otherwise a negative number. + ****************************************************************************/ + +int i3c_master_i2c_attach(FAR struct i3c_master_controller *master, + FAR struct i2c_config_s *config); + +/**************************************************************************** + * Name: i3c_master_detach_i2c_dev + * + * Description: + * Delete an i2c device address in controller driver. . + * + * Input Parameters: + * master - The master used to get i3c_device on the bus + * config - An i2c device information to delete + ****************************************************************************/ + +void i3c_master_detach_i2c_dev(FAR struct i3c_master_controller *master, + FAR struct i2c_config_s *config); + +/**************************************************************************** + * Name: i3c_master_find_i3c_dev + * + * Description: + * This function is used to be find a i3c_device address by master handle + * and provisional ID. + * + * Input Parameters: + * master - The master used to get i3c_device on the bus + * id - An instance of i3c_device_id, include manufid,partid and so on. + * Returned Value: + * Struct i3c_device var in case of success, NULL otherwise. + ****************************************************************************/ + +FAR const struct i3c_device *i3c_master_find_i3c_dev( + FAR struct i3c_master_controller *master, + FAR const struct i3c_device_id *id); + +#endif /* __INCLUDE_NUTTX_I3C_DEV_H */ diff --git a/include/nuttx/i3c/i3c_driver.h b/include/nuttx/i3c/i3c_driver.h new file mode 100644 index 0000000000..d1e0f548be --- /dev/null +++ b/include/nuttx/i3c/i3c_driver.h @@ -0,0 +1,177 @@ +/**************************************************************************** + * include/nuttx/i3c/i3c_driver.h + * + * 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. + * + ****************************************************************************/ + +#ifndef _INCLUDE_NUTTX_I3C_DRIVER_H +#define _INCLUDE_NUTTX_I3C_DRIVER_H + +/**************************************************************************** + * Included Files + ****************************************************************************/ + +#include + +#include +#include +#include +#include + +/**************************************************************************** + * Pre-processor Definitions + ****************************************************************************/ + +/* I3C Character Driver IOCTL Commands **************************************/ + +/* The I3C driver is intended to support application testing of the I3C bus. + * The I3C driver simply wraps an instance of struct i3c_driver_s and then + * provides the following IOCTL commands to access each method of the I3c + * interface. + */ + +/* Command: I3CIOC_PRIV_XFERS + * Description: Perform an I3C transfer + * Argument: A reference to an instance of struct i3c_transfer_s. + * Dependencies: + */ + +#define I3CIOC_PRIV_XFERS _I3CIOC(0x0001) + +/* Command: I3CIOC_EN_IBI + * Description: Perform an I3C bus IBI enabled operation + * + * Argument: None + * Dependencies: + */ + +#define I3CIOC_EN_IBI _I3CIOC(0x0002) + +/* Command: I3CIOC_DIS_IBI + * Description: Perform an I3C bus IBI disabled operation + * + * Argument: None + * Dependencies: + */ + +#define I3CIOC_DIS_IBI _I3CIOC(0x0003) + +/* Command: I3CIOC_REQ_IBI + * Description: Perform an I3C bus IBI requested operation + * + * Argument: None + * Dependencies: + */ + +#define I3CIOC_REQ_IBI _I3CIOC(0x0004) + +/* Command: I3CIOC_FREE_IBI + * Description: Perform an I3C bus IBI free operation + * + * Argument: None + * Dependencies: + */ + +#define I3CIOC_FREE_IBI _I3CIOC(0x0005) + +/* Command: I3CIOC_GET_DEVINFO + * Description: Get an I3C bus dev infomation + * + * Argument: None + * Dependencies: + */ + +#define I3CIOC_GET_DEVINFO _I3CIOC(0x0006) + +/**************************************************************************** + * Public Types + ****************************************************************************/ + +struct i3c_master_s; +struct i3c_priv_xfer; +struct i3c_ibi_setup; +struct i3c_master_controller; + +/* This structure is used to communicate with the I3C character driver in + * order to perform IOCTL transfers. + */ + +struct i3c_transfer_s +{ + /* manufID and partID is used to attach to i3c_dev_desc, it's */ + + uint16_t manufid; + uint16_t partid; + + /* Number of messages in the array. */ + + size_t nxfers; + + /* Array of I3C messages for the transfer */ + + FAR struct i3c_priv_xfer *xfers; + + FAR struct i3c_ibi_setup *req; + + /* I3C device information */ + + FAR struct i3c_device_info *info; +}; + +/**************************************************************************** + * Public Functions Definitions + ****************************************************************************/ + +#ifdef __cplusplus +#define EXTERN extern "C" +extern "C" +{ +#else +#define EXTERN extern +#endif + +/**************************************************************************** + * Name: i3c_register + * + * Description: + * Create and register the I3C character driver. + * + * The I3C character driver is a simple character driver that supports I3C + * transfers. The intent of this driver is to support I3C testing. It is + * not suitable for use in any real driver application. + * + * Input Parameters: + * master - An instance of the lower half I3C core driver. + * bus - The I3C bus number. This will be used as the I3C device minor + * number.The I3C character device will be registered as /dev/i3cN + * where N is the minor number. + * + * Returned Value: + * OK if the driver was successfully register; A negated errno value is + * returned on any failure. + * + ****************************************************************************/ + +#ifdef CONFIG_I3C_DRIVER +int i3c_register(FAR struct i3c_master_controller *master, int bus); +#endif + +#undef EXTERN +#if defined(__cplusplus) +} +#endif +#endif /* _INCLUDE_NUTTX_I3C_DRIVER_H */ diff --git a/include/nuttx/i3c/master.h b/include/nuttx/i3c/master.h new file mode 100644 index 0000000000..945338abdf --- /dev/null +++ b/include/nuttx/i3c/master.h @@ -0,0 +1,1150 @@ +/**************************************************************************** + * include/nuttx/i3c/master.h + * + * 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. + * + ****************************************************************************/ + +#ifndef __INCLUDE_NUTTX_I3C_MASTER_H +#define __INCLUDE_NUTTX_I3C_MASTER_H + +/**************************************************************************** + * Included Files + ****************************************************************************/ + +#include +#include + +#include +#include +#include +#include +#include + +#include +#include +#include +#include + +/**************************************************************************** + * Pre-processor Definitions + ****************************************************************************/ + +#define I3C_BIT(n) (1ul << (n)) +#define I3C_BITS_PER_LONG BITS_PER_LONG +#define I3C_BITS_PER_LONG_LONG BITS_PER_LONG_LONG +#define I3C_GENMASK(h, l) GENMASK(h, l) +#define I3C_GENMASK_ULL(h, l) GENMASK_ULL(h, l) + +#define I3C_HOT_JOIN_ADDR 0x2 +#define I3C_BROADCAST_ADDR 0x7e +#define I3C_MAX_ADDR I3C_GENMASK(6, 0) + +#define I3C_LVR_I2C_INDEX_MASK I3C_GENMASK(7, 5) +#define I3C_LVR_I2C_INDEX(x) ((x) << 5) +#define I3C_LVR_I2C_FM_MODE I3C_BIT(4) + +#define I3C_I2C_MAX_ADDR I3C_GENMASK(6, 0) + +/* use ten bit chip address */ + +#define I3C_I2C_CLIENT_TEN 0x10 + +/* The I3C specification says the maximum number of devices connected on the + * bus is 11, but this number depends on external parameters like trace + * length, capacitive load per Device, and the types of Devices present on + * the Bus. + * I3C master can also have limitations, so this number is just here as a + * reference and should be adjusted on a per-controller/per-board basis. + */ + +#define I3C_BUS_MAX_DEVS 11 + +#define I3C_BUS_MAX_I3C_SCL_RATE 12900000 +#define I3C_BUS_TYP_I3C_SCL_RATE 12500000 +#define I3C_BUS_I2C_FM_PLUS_SCL_RATE 1000000 +#define I3C_BUS_I2C_FM_SCL_RATE 400000 +#define I3C_BUS_TLOW_OD_MIN_NS 200 + +/* i3c_bus_for_each_i3cdev() - iterate over all I3C devices present on the + * bus + * @bus: the I3C bus + * @dev: and I3C device descriptor pointer updated to point to the current + * slot + * at each iteration of the loop + * + * Iterate over all I3C devs present on the bus. + */ + +#define i3c_bus_for_each_i3cdev(bus, dev) \ + list_for_every_entry(&(bus)->devs.i3c, dev, struct i3c_dev_desc, common.node) + +/**************************************************************************** + * Public Types + ****************************************************************************/ + +struct i3c_master_controller; +struct i3c_bus; +struct i3c_device; +struct i3c_dev_desc; +struct i3c_device_info; +struct i3c_generic_ibi_pool; + +/* struct i3c_i2c_dev_desc - Common part of the I3C/I2C device descriptor + * @node: node element used to insert the slot into the I2C or I3C device + * list + * @master: I3C master that instantiated this device. Will be used to do + * I2C/I3C transfers + * @master_priv: master private data assigned to the device. Can be used + * to add master specific information + * + * This structure is describing common I3C/I2C dev information. + */ + +struct i3c_i2c_dev_desc +{ + struct list_node node; + FAR struct i3c_master_controller *master; + FAR void *master_priv; +}; + +struct i2c_board_info +{ + uint32_t i2c_scl; + uint16_t addr; + uint16_t addrlen; +}; + +/* struct i2c_dev_boardinfo - I2C device board information + * @node: used to insert the boardinfo object in the I2C boardinfo list + * @base: regular I2C board information + * @lvr: LVR (Legacy Virtual Register) needed by the I3C core to know about + * the I2C device limitations + * + * This structure is used to attach board-level information to an I2C device. + * Each I2C device connected on the I3C bus should have one. + */ + +struct i2c_dev_boardinfo +{ + struct list_node node; + struct i2c_board_info base; + unsigned char lvr; +}; + +/* struct i2c_dev_desc - I2C device descriptor + * @common: common part of the I2C device descriptor + * @boardinfo: pointer to the boardinfo attached to this I2C device + * @addr: I2C device address + * @lvr: LVR (Legacy Virtual Register) needed by the I3C core to know about + * the I2C device limitations + * + * Each I2C device connected on the bus will have an i2c_dev_desc. + * This object is created by the core and later attached to the controller + * using &struct_i3c_master_controller->ops->attach_i2c_dev(). + * + * &struct_i2c_dev_desc is the internal representation of an I2C device + * connected on an I3C bus. This object is also passed to all + * &struct_i3c_master_controller_ops hooks. + */ + +struct i2c_dev_desc +{ + struct i3c_i2c_dev_desc common; + FAR const struct i2c_dev_boardinfo *boardinfo; + uint16_t addr; + unsigned char lvr; +}; + +/* struct i3c_ibi_slot - I3C IBI (In-Band Interrupt) slot + * @work: work associated to this slot. The IBI handler will be called + * from there + * @dev: the I3C device that has generated this IBI + * @len: length of the payload associated to this IBI + * @data: payload buffer + * + * An IBI slot is an object pre-allocated by the controller and used when + * an IBI comes in. + * Every time an IBI comes in, the I3C master driver should find a free IBI + * slot in its IBI slot pool, retrieve the IBI payload and queue the IBI + * using i3c_master_queue_ibi(). + * + * How IBI slots are allocated is left to the I3C master driver, though, + * for simple kmalloc-based allocation, the generic IBI slot pool can be + * used. + */ + +struct i3c_ibi_slot +{ + struct work_s work; + FAR struct i3c_dev_desc *dev; + unsigned int len; + FAR void *data; +}; + +/* struct i3c_device_ibi_info - IBI information attached to a specific device + * @all_ibis_handled: used to be informed when no more IBIs are waiting to be + * processed. Used by i3c_device_disable_ibi() to wait for + * all IBIs to be dequeued + * @pending_ibis: count the number of pending IBIs. Each pending IBI has its + * work element queued to the controller workqueue + * @max_payload_len: maximum payload length for an IBI coming from this + * device. + * this value is specified when calling + * i3c_device_request_ibi() and should not change at run + * time. All messages IBIs exceeding this limit should be + * rejected by the master + * @num_slots: number of IBI slots reserved for this device + * @enabled: reflect the IBI status + * @handler: IBI handler specified at i3c_device_request_ibi() call time. + * This handler will be called from the controller workqueue, and as + * such is allowed to sleep (though it is recommended to process the + * IBI as fast as possible to not stall processing of other IBIs queued + * on the same workqueue). + * New I3C messages can be sent from the IBI handler + * + * The &struct_i3c_device_ibi_info object is allocated when + * i3c_device_request_ibi() is called and attached to a specific device. This + * object is here to manage IBIs coming from a specific I3C device. + * + * Note that this structure is the generic view of the IBI management + * infrastructure. I3C master drivers may have their own internal + * representation which they can associate to the device using + * controller-private data. + */ + +struct i3c_device_ibi_info +{ + sem_t all_ibis_handled; + atomic_int pending_ibis; + unsigned int max_payload_len; + unsigned int num_slots; + unsigned int enabled; + CODE void (*handler)(FAR struct i3c_device *dev, + const struct i3c_ibi_payload *payload); +}; + +/* struct i3c_dev_boardinfo - I3C device board information + * @node: used to insert the boardinfo object in the I3C boardinfo list + * @init_dyn_addr: initial dynamic address requested by the FW. We provide + * no guarantee that the device will end up using this address, + * but try our best to assign this specific address to the + * device + * @static_addr: static address the I3C device listen on before it's been + * assigned a dynamic address by the master. Will be used during + * bus initialization to assign it a specific dynamic address + * before starting DAA (Dynamic Address Assignment) + * @pid: I3C Provisional ID exposed by the device. This is a unique + * identifier that may be used to attach boardinfo to i3c_dev_desc when + * the device does not have a static address + * + * This structure is used to attach board-level information to an I3C device. + * Not all I3C devices connected on the bus will have a boardinfo. It's only + * needed if you want to attach extra resources to a device or assign it a + * specific dynamic address. + */ + +struct i3c_dev_boardinfo +{ + struct list_node node; + unsigned char init_dyn_addr; + unsigned char static_addr; + uint64_t pid; +}; + +/* struct i3c_dev_desc - I3C device descriptor + * @common: common part of the I3C device descriptor + * @info: I3C device information. Will be automatically filled when you + * create your device with i3c_master_add_i3c_dev_locked() + * @ibi_lock: lock used to protect the &struct_i3c_device->ibi + * @ibi: IBI info attached to a device. Should be NULL until + * i3c_device_request_ibi() is called + * @dev: pointer to the I3C device object exposed to I3C device drivers. This + * should never be accessed from I3C master controller drivers. Only core + * code should manipulate it in when updating the dev <-> desc link or + * when propagating IBI events to the driver + * @boardinfo: pointer to the boardinfo attached to this I3C device + * + * Internal representation of an I3C device. This object is only used by the + * core and passed to I3C master controller drivers when they're requested to + * do some operations on the device. + * The core maintains the link between the internal I3C dev descriptor and + * the object exposed to the I3C device drivers (&struct_i3c_device). + */ + +struct i3c_dev_desc +{ + struct i3c_i2c_dev_desc common; + struct i3c_device_info info; + mutex_t ibi_lock; + FAR struct i3c_device_ibi_info *ibi; + FAR struct i3c_device *dev; + FAR const struct i3c_dev_boardinfo *boardinfo; +}; + +/* struct i3c_device - I3C device object + * @desc: pointer to an i3c device descriptor object. This link is updated + * every time the I3C device is rediscovered with a different dynamic + * address assigned + * @bus: I3C bus this device is attached to + * + * I3C device object exposed to I3C device drivers. The takes care of linking + * this object to the relevant &struct_i3c_dev_desc one. + * All I3C devs on the I3C bus are represented, including I3C masters. For + * each of them, we have an instance of &struct i3c_device. + */ + +struct i3c_device +{ + FAR struct i3c_dev_desc *desc; + FAR struct i3c_bus *bus; +}; + +/* enum i3c_bus_mode - I3C bus mode + * @I3C_BUS_MODE_PURE: only I3C devices are connected to the bus. + * No limitation expected + * @I3C_BUS_MODE_MIXED_FAST: I2C devices with 50ns spike filter are present + * on the bus. The only impact in this mode is that the + * high SCL pulse has to stay below 50ns to trick I2C + * devices when transmitting I3C frames + * @I3C_BUS_MODE_MIXED_LIMITED: I2C devices without 50ns spike filter are + * present on the bus. However they allow + * compliance up to the maximum SDR SCL clock + * frequency. + * @I3C_BUS_MODE_MIXED_SLOW: I2C devices without 50ns spike filter are + * present on the bus + */ + +enum i3c_bus_mode +{ + I3C_BUS_MODE_PURE, + I3C_BUS_MODE_MIXED_FAST, + I3C_BUS_MODE_MIXED_LIMITED, + I3C_BUS_MODE_MIXED_SLOW, +}; + +/* enum i3c_addr_slot_status - I3C address slot status + * @I3C_ADDR_SLOT_FREE: address is free + * @I3C_ADDR_SLOT_RSVD: address is reserved + * @I3C_ADDR_SLOT_I2C_DEV: address is assigned to an I2C device + * @I3C_ADDR_SLOT_I3C_DEV: address is assigned to an I3C device + * @I3C_ADDR_SLOT_STATUS_MASK: address slot mask + * + * On an I3C bus, addresses are assigned dynamically, and we need to know + * which addresses are free to use and which ones are already assigned. + * + * Addresses marked as reserved are those reserved by the I3C protocol + * (broadcast address, ...). + */ + +enum i3c_addr_slot_status +{ + I3C_ADDR_SLOT_FREE, + I3C_ADDR_SLOT_RSVD, + I3C_ADDR_SLOT_I2C_DEV, + I3C_ADDR_SLOT_I3C_DEV, + I3C_ADDR_SLOT_STATUS_MASK = 3, +}; + +/* struct i3c_bus - I3C bus object + * @cur_master: I3C master currently driving the bus. Since I3C is + * multi-master this can change over the time. Will be used to let + * a master know whether it needs to request bus ownership before + * sending a frame or not + * @id: bus ID. Assigned by the framework when register the bus + * @addrslots: a bitmap with 2-bits per-slot to encode the address status + * and ease the DAA (Dynamic Address Assignment) procedure (see + * &enum i3c_addr_slot_status) + * @mode: bus mode (see &enum i3c_bus_mode) + * @scl_rate.i3c: maximum rate for the clock signal when doing I3C SDR/priv + * transfers + * @scl_rate.i2c: maximum rate for the clock signal when doing I2C transfers + * @scl_rate: SCL signal rate for I3C and I2C mode + * @devs.i3c: contains a list of I3C device descriptors representing I3C + * devices connected on the bus and successfully attached to the + * I3C master + * @devs.i2c: contains a list of I2C device descriptors representing I2C + * devices connected on the bus and successfully attached to the + * I3C master + * @devs: 2 lists containing all I3C/I2C devices connected to the bus + * @lock: read/write lock on the bus. This is needed to protect against + * operations that have an impact on the whole bus and the devices + * connected to it. For example, when asking slaves to drop their + * dynamic address (RSTDAA CCC), we need to make sure no one is trying + * to send I3C frames to these devices. + * Note that this lock does not protect against concurrency between + * devices: several drivers can send different I3C/I2C frames through + * the same master in parallel. This is the responsibility of the + * master to guarantee that frames are actually sent sequentially and + * not interlaced + * + * The I3C bus is represented with its own object and not implicitly + * described by the I3C master to cope with the multi-master functionality, + * where one bus can be shared amongst several masters, each of them + * requesting bus ownership when they need to. + */ + +struct i3c_bus +{ + FAR struct i3c_dev_desc *cur_master; + int id; + uint32_t addrslots[((I3C_I2C_MAX_ADDR + 1) * 2) / I3C_BITS_PER_LONG]; + enum i3c_bus_mode mode; + struct + { + unsigned long i3c; + unsigned long i2c; + } scl_rate; + struct + { + struct list_node i3c; + struct list_node i2c; + } devs; + mutex_t lock; +}; + +/* struct i3c_master_controller_ops - I3C master methods + * @bus_init: hook responsible for the I3C bus initialization. You should + * at least call master_set_info() from there and set the bus mode. + * You can also put controller specific initialization in there. + * This method is mandatory. + * @bus_cleanup: cleanup everything done in + * &i3c_master_controller_ops->bus_init(). + * This method is optional. + * @attach_i3c_dev: called every time an I3C device is attached to the bus. + * It can be after a DAA or when a device is statically declared + * by the FW, in which case it will only have a static address + * and the dynamic address will be 0. + * When this function is called, device information have not + * been retrieved yet. + * This is a good place to attach master controller specific + * data to I3C devices. + * This method is optional. + * @reattach_i3c_dev: called every time an I3C device has its addressed + * changed. It can be because the device has been powered + * down and has lost its address, or it can happen when a + * device had a static address and has been assigned a + * dynamic address with SETDASA. + * This method is optional. + * @detach_i3c_dev: called when an I3C device is detached from the bus. + * Usually happens when the master device is unregistered. + * This method is optional. + * @do_daa: do a DAA (Dynamic Address Assignment) procedure. This is + * procedure should send an ENTDAA CCC command and then add all + * devices discovered sure the DAA using + * i3c_master_add_i3c_dev_locked(). + * Add devices added with i3c_master_add_i3c_dev_locked() will then be + * attached or re-attached to the controller. + * This method is mandatory. + * @supports_ccc_cmd: should return true if the CCC command is supported, + * false otherwise. + * This method is optional, if not provided the core assumes + * all CCC commands are supported. + * @send_ccc_cmd: send a CCC command + * This method is mandatory. + * @priv_xfers: do one or several private I3C SDR transfers + * This method is mandatory. + * @attach_i2c_dev: called every time an I2C device is attached to the bus. + * @detach_i2c_dev: called when an I2C device is detached from the bus. + * @i2c_xfers: do one or several I2C transfers. Note that, unlike i3c + * transfers, the core does not guarantee that buffers attached to + * the transfers are DMA-safe. If drivers want to have DMA-safe + * buffers, they should use the i2c_get_dma_safe_msg_buf() + * and i2c_put_dma_safe_msg_buf() helpers provided by the I2C + * framework. + * This method is mandatory. + * @request_ibi: attach an IBI handler to an I3C device. This implies + * defining an IBI handler and the constraints of the IBI (maximum + * payload length and number of pre-allocated slots). + * Some controllers support less IBI-capable devices than regular + * devices, so this method might return -%EBUSY if there's no + * more space for an extra IBI registration + * This method is optional. + * @free_ibi: free an IBI previously requested with ->request_ibi(). The IBI + * should have been disabled with ->disable_irq() prior to that + * This method is mandatory only if ->request_ibi is not NULL. + * @enable_ibi: enable the IBI. Only valid if ->request_ibi() has been called + * prior to ->enable_ibi(). The controller should first enable + * the IBI on the controller end (for example, unmask the hardware + * IRQ) and then send the ENEC CCC command (with the IBI flag set) + * to the I3C device. + * This method is mandatory only if ->request_ibi is not NULL. + * @disable_ibi: disable an IBI. First send the DISEC CCC command with the + * IBI flag set and then deactivate the hardware IRQ on the + * controller end. + * This method is mandatory only if ->request_ibi is not NULL. + * @recycle_ibi_slot: recycle an IBI slot. Called every time an IBI has been + * processed by its handler. The IBI slot should be put back + * in the IBI slot pool so that the controller can re-use it + * for a future IBI + * This method is mandatory only if ->request_ibi is not + * NULL. + */ + +struct i3c_master_controller_ops +{ + CODE int (*bus_init)(FAR struct i3c_master_controller *master); + CODE void (*bus_cleanup)(FAR struct i3c_master_controller *master); + CODE int (*attach_i3c_dev)(FAR struct i3c_dev_desc *dev); + CODE int (*reattach_i3c_dev)(FAR struct i3c_dev_desc *dev, + unsigned char old_dyn_addr); + CODE void (*detach_i3c_dev)(FAR struct i3c_dev_desc *dev); + CODE int (*do_daa)(FAR struct i3c_master_controller *master); + CODE bool (*supports_ccc_cmd)(FAR struct i3c_master_controller *master, + FAR const struct i3c_ccc_cmd *cmd); + CODE int (*send_ccc_cmd)(FAR struct i3c_master_controller *master, + FAR struct i3c_ccc_cmd *cmd); + CODE int (*priv_xfers)(FAR struct i3c_dev_desc *dev, + FAR struct i3c_priv_xfer *xfers, + int nxfers); + CODE int (*attach_i2c_dev)(FAR struct i3c_master_controller *master, + FAR const struct i2c_config_s *config); + CODE int (*detach_i2c_dev)(FAR struct i3c_master_controller *master, + FAR const struct i2c_config_s *config); + CODE int (*i2c_xfers)(FAR struct i3c_master_controller *master, + FAR const struct i2c_msg_s *xfers, int nxfers); + CODE int (*request_ibi)(FAR struct i3c_dev_desc *dev, + FAR const struct i3c_ibi_setup *req); + CODE void (*free_ibi)(FAR struct i3c_dev_desc *dev); + CODE int (*enable_ibi)(FAR struct i3c_dev_desc *dev); + CODE int (*disable_ibi)(FAR struct i3c_dev_desc *dev); + CODE void (*recycle_ibi_slot)(FAR struct i3c_dev_desc *dev, + FAR struct i3c_ibi_slot *slot); +}; + +/* struct i3c_master_controller - I3C master controller object + * @i3c_bus_id: the master id registered to the i3c bus + * @i2c_bus_id: the i2c driver id registered to this master + * @mode: mode selection by i2c device feature. + * @max_i2c_scl_rate: max i2c scl rate in all i2c device + * @ops: master operations. See &struct i3c_master_controller_ops + * @this: an I3C device object representing this master. This device will + * be added to the list of I3C devs available on the bus + * @i2c: I2C driver used for backward compatibility. This adapter is + * registered to the I2C subsystem to be as transparent as possible to + * existing I2C drivers + + * @secondary: true if the master is a secondary master + * @init_done: true when the bus initialization is done + * @bus: I3C bus exposed by this master + * + * A &struct i3c_master_controller has to be registered to the I3C subsystem + * through i3c_master_register(). None of &struct i3c_master_controller + * fields should be set manually, just pass appropriate values to + * i3c_master_register(). + */ + +struct i3c_master_controller +{ + /* External implementation */ + + int i3c_bus_id; /* indicate a i3c bus id */ + int i2c_bus_id; /* indicate a i2c bus id */ + enum i3c_bus_mode mode; /* select i3c bus mode by all device */ + unsigned long max_i2c_scl_rate; /* select max i2c scl rate by all i2c device */ + + /* Internal implementation */ + + FAR const struct i3c_master_controller_ops *ops; /* operation callback implemented in IP driver */ + FAR struct i3c_dev_desc *this; + struct i2c_master_s i2c; + unsigned int secondary : 1; + unsigned int init_done : 1; + struct i3c_bus bus; +}; + +/* struct i3c_generic_ibi_slot - an I3C generic IBI slot structure + * @node: used to insert generic IBI slot list. + * @base: an I3C IBI slot. + * + * This structure is struct i3c_ibi_slot list. + */ + +struct i3c_generic_ibi_slot +{ + struct list_node node; + struct i3c_ibi_slot base; +}; + +/* struct i3c_generic_ibi_pool - I3C master controller object + * @lock: used to protect share resource. + * @num_slots: the number of struct i3c_generic_ibi_slot. + * @slots: the general slot used to manager payload infomation in pool. + * @payload_buf: pending process messages from IBI handler. + * @free_slots: a free slot list from a generic IBI pool. + * @pending: a pending slots list from a generic IBI pool. + * + * This structure is used to manager all general ibi pool data,such as + * pending slots or free slots. + */ + +struct i3c_generic_ibi_pool +{ + spinlock_t lock; + unsigned int num_slots; + FAR struct i3c_generic_ibi_slot *slots; + FAR void *payload_buf; + struct list_node free_slots; + struct list_node pending; +}; + +/**************************************************************************** + * Inline Functions + ****************************************************************************/ + +/**************************************************************************** + * Name: i3c_dev_get_master_data + * + * Description: + * Get master private data attached to an I3C device descriptor. + * + * This functions allows a master controller to attach per-device private + * data which can then be retrieved with i3c_dev_get_master_data(). + * + * Input Parameters: + * dev - The I3C device descriptor to get private data from. + * + * Returned Value: + * The private data previously attached with i3c_dev_set_master_data() or + * NULL if no data has been attached to the device. + ****************************************************************************/ + +static inline FAR void * +i3c_dev_get_master_data(FAR const struct i3c_dev_desc *dev) +{ + return dev->common.master_priv; +} + +/**************************************************************************** + * Name: i3c_dev_set_master_data + * + * Description: + * Attach master private data to an I3C device descriptor. + * + * This functions allows a master controller to attach per-device + * private data which can then be retrieved with i3c_dev_get_master_data(). + * + * Input Parameters: + * dev - The I3C device descriptor to attach private data to. + * data - Private data. + ****************************************************************************/ + +static inline void +i3c_dev_set_master_data(FAR struct i3c_dev_desc *dev, FAR void *data) +{ + dev->common.master_priv = data; +} + +/**************************************************************************** + * Name: i2c_dev_get_master_data + * + * Description: + * get Master private data attached to an I2C device descriptor. + * + * Input Parameters: + * dev - The I2C device descriptor to get private data from. + * + * Returned Value: + * The private data previously attached with i2c_dev_set_master_data() or + * NULL if no data has been attached to the device. + ****************************************************************************/ + +static inline FAR void * +i2c_dev_get_master_data(FAR const struct i2c_dev_desc *dev) +{ + return dev->common.master_priv; +} + +/**************************************************************************** + * Name: i2c_dev_set_master_data + * + * Description: + * Attach master private data to an I2C device descriptor. + * + * Input Parameters: + * dev - The I2C device descriptor to attach private data to. + * data - Private data. + ****************************************************************************/ + +static inline void +i2c_dev_set_master_data(FAR struct i2c_dev_desc *dev, FAR void *data) +{ + dev->common.master_priv = data; +} + +/**************************************************************************** + * Name: i3c_dev_get_master + * + * Description: + * Get master used to communicate with a device + * + * Input Parameters: + * dev - I3C dev. + * + * Returned Value: + * The master controller driving @dev. + * + ****************************************************************************/ + +static inline FAR struct i3c_master_controller * +i3c_dev_get_master(FAR struct i3c_dev_desc *dev) +{ + return dev->common.master; +} + +/**************************************************************************** + * Name: i2c_dev_get_master + * + * Description: + * Get master used to communicate with a device. + * + * Input Parameters: + * dev - I2C dev. + * + * Returned Value: + * The master controller driving dev. + ****************************************************************************/ + +static inline FAR struct i3c_master_controller * +i2c_dev_get_master(FAR struct i2c_dev_desc *dev) +{ + return dev->common.master; +} + +/**************************************************************************** + * Public Functions Definitions + ****************************************************************************/ + +/**************************************************************************** + * Name: i3c_master_get_bus + * + * Description: + * Get the bus attached to a master. + * + * + * Input Parameters: + * dev - Master object. + * + * Returned Value: + * The I3C bus @master is connected to. + * + ****************************************************************************/ + +static inline FAR struct i3c_bus * +i3c_master_get_bus(FAR struct i3c_master_controller *master) +{ + return &master->bus; +} + +/**************************************************************************** + * Name: i3c_bus_normaluse_lock + * + * Description: + * I3C bus to take the lock on. + * + * This function takes the bus lock for any operation that is not a + * maintenance operation (see i3c_bus_maintenance_lock() for + * non-exhaustive list of maintenance operations). Basically all + * communications with I3C devices are normal operations (HDR, SDR + * transfers or CCC commands that do not change bus state or I3C dynamic + * address). + * + * Input Parameters: + * bus - I3C bus to release the lock on. + * + ****************************************************************************/ + +void i3c_bus_normaluse_lock(FAR struct i3c_bus *bus); + +/**************************************************************************** + * Name: i3c_bus_normaluse_unlock + * + * Description: + * Release the bus lock after a normal operation. + * + * Should be called when a normal operation is done. See + * i3c_bus_normaluse_lock() for more details on what these + * normal operations are. + * + * Input Parameters: + * bus - I3C bus to release the lock on. + * + * + ****************************************************************************/ + +void i3c_bus_normaluse_unlock(FAR struct i3c_bus *bus); + +/**************************************************************************** + * Name: i3c_generic_ibi_alloc_pool + * + * Description: + * Create a generic IBI pool + * + * Create a generic IBI pool based on the information provided in @req. + * + * Input Parameters: + * dev - The device this pool will be used for + * req - IBI setup request describing what the device driver expects + * + * Returned Value: + * A valid IBI pool in case of success, an ERR_PTR() otherwise. + ****************************************************************************/ + +FAR struct i3c_generic_ibi_pool * +i3c_generic_ibi_alloc_pool(FAR struct i3c_dev_desc *dev, + FAR const struct i3c_ibi_setup *req); + +/**************************************************************************** + * Name: i3c_generic_ibi_free_pool + * + * Description: + * Free a generic IBI pool + * + * Free all IBI slots allated by a generic IBI pool. + * + * Input Parameters: + * pool - The IBI pool to free + * + ****************************************************************************/ + +void i3c_generic_ibi_free_pool(FAR struct i3c_generic_ibi_pool *pool); + +/**************************************************************************** + * Name: i3c_generic_ibi_get_free_slot + * + * Description: + * Get a free slot from a generic IBI pool + * + * Search for a free slot in a generic IBI pool. + * The slot should be returned to the pool using + * i3c_generic_ibi_recycle_slot + * when it's no longer needed. + * + * Input Parameters: + * pool - The pool to query an IBI slot on + * + * Returned Value: + * A pointer to a free slot, or NULL if there's no free slot available. + * + ****************************************************************************/ + +FAR struct i3c_ibi_slot * +i3c_generic_ibi_get_free_slot(FAR struct i3c_generic_ibi_pool *pool); + +/**************************************************************************** + * Name: i3c_generic_ibi_recycle_slot + * + * Description: + * Return a slot to a generic IBI pool + * + * Add an IBI slot back to its generic IBI pool. Should be called from the + * master driver struct_master_controller_ops->recycle_ibi() method. + * + * Input Parameters: + * pool - The pool to return the IBI slot to + * slot - IBI slot to recycle + * + ****************************************************************************/ + +void i3c_generic_ibi_recycle_slot(FAR struct i3c_generic_ibi_pool *pool, + FAR struct i3c_ibi_slot *slot); + +/**************************************************************************** + * Name: i3c_master_queue_ibi + * + * Description: + * Queue an IBI + * + * Queue an IBI to the controller workqueue. The IBI handler attached + * to the dev will be called from a workqueue context. + * + * Input Parameters: + * dev - The device this IBI is coming from + * slot - The IBI slot used to store the payload + * + ****************************************************************************/ + +void i3c_master_queue_ibi(FAR struct i3c_dev_desc *dev, + FAR struct i3c_ibi_slot *slot); + +/**************************************************************************** + * Name: i3c_master_get_free_ibi_slot + * + * Description: + * Return a slot to a free IBI pool + * + * Input Parameters: + * dev - The device this IBI is coming from + * + ****************************************************************************/ + +FAR struct i3c_ibi_slot *i3c_master_get_free_ibi_slot( + FAR struct i3c_dev_desc *dev); + +/**************************************************************************** + * Name: i3c_master_register + * + * Description: + * Register an I3C master. + * + * This function takes care of everything for you: + * - Creates and initializes the I3C bus. + * - Registers all I3C charactor driver that supports I3C transfer. + * - Registers the I2C charactor driver that supports I2C transfer. + * + * Input Parameters: + * master - Master used to send frames on the bus. + * ops - The master controller operations + * secondary - True if you are registering a secondary master. Will return + * -ENOTSUP if set to true since secondary masters are not yet supported + * + * return: + * OK if the driver was successfully register; A negated errno value is + * returned on any failure. + * + ****************************************************************************/ + +int i3c_master_register(FAR struct i3c_master_controller *master, + FAR const struct i3c_master_controller_ops *ops, + bool secondary); + +/**************************************************************************** + * Name: i3c_master_unregister + * + * Description: + * Unregister an I3C master. + * + * Basically undo everything done in i3c_master_register(). + * + * Input Parameters: + * master - Master used to send frames on the bus. + * + ****************************************************************************/ + +void i3c_master_unregister(FAR struct i3c_master_controller *master); + +/**************************************************************************** + * Name: i3c_master_disec_locked + * + * Description: + * Send a DISEC CCC command + * + * Send a DISEC CCC command to disable some or all events coming from a + * Specific slave, or all devices if @addr is %I3C_BROADCAST_ADDR. + * + * This function must be called with the bus lock held in write mode. + * + * Input Parameters: + * master - Master used to send frames on the bus. + * addr - A valid I3C slave address or %I3C_BROADCAST_ADDR + * evts - Events to disable + * + * Returned Value: + * 0 in case of success, a positive I3C error code if the error is + * one of the official Mx error codes, and a negative error code otherwise + * + ****************************************************************************/ + +int i3c_master_disec_locked(FAR struct i3c_master_controller *master, + unsigned char addr, unsigned char evts); + +/**************************************************************************** + * Name: i3c_master_enec_locked + * + * Description: + * Send an ENEC CCC command + * + * Sends an ENEC CCC command to enable some or all events coming from a + * specific slave, or all devices if @addr is %I3C_BROADCAST_ADDR. + * + * This function must be called with the bus lock held in write mode. + * + * Input Parameters: + * master - Master used to send frames on the bus. + * addr - A valid I3C slave address or %I3C_BROADCAST_ADDR + * evts - Events to enable + * + * Returned Value: + * 0 in case of success, a positive I3C error code if the error is + * one of the official Mx error codes, and a negative error code otherwise. + * + ****************************************************************************/ + +int i3c_master_enec_locked(FAR struct i3c_master_controller *master, + unsigned char addr, unsigned char evts); + +/**************************************************************************** + * Name: i3c_master_entdaa_locked + * + * Description: + * Start a DAA (Dynamic Address Assignment) procedure + * + * This function must be called with the bus lock held in write mode. + * + * Note that this function only sends the ENTDAA CCC command, all the logic + * behind dynamic address assignment has to be handled in the I3C master + * driver. + * + * Input Parameters: + * master - Master used to send frames on the bus. + * + * Returned Value: + * 0 in case of success, a positive I3C error code if the error is + * one of the official Mx error codes, and a negative error code otherwise. + * + ****************************************************************************/ + +int i3c_master_entdaa_locked(FAR struct i3c_master_controller *master); + +/**************************************************************************** + * Name: i3c_master_defslvs_locked + * + * Description: + * Send a DEFSLVS CCC command. + * + * Send a DEFSLVS CCC command containing all the devices known to the + * master. + * This is useful when you have secondary masters on the bus to + * propagate device information. + * + * This should be called after all I3C devices have been discovered (in + * other words, after the DAA procedure has finished) and instantiated in + * &i3c_master_controller_ops->bus_init(). + * It should also be called if a master ACKed an Hot-Join request and + * assigneda dynamic address to the device joining the bus. + * + * This function must be called with the bus lock held in write mode. + * + * Input Parameters: + * master - Master used to send frames on the bus. + * + * Returned Value: + * 0 in case of success, a positive I3C error code if the error is + * one of the official Mx error codes, and a negative error code otherwise. + * + ****************************************************************************/ + +int i3c_master_defslvs_locked(FAR struct i3c_master_controller *master); + +/**************************************************************************** + * Name: i3c_master_get_free_addr + * + * Description: + * Get a free address on the bus + * + * This function must be called with the bus lock held in write mode. + * + * Input Parameters: + * master - I3C master object. + * start_addr - Where to start searching. + * + * Returned Value: + * The first free address starting at @start_addr (included) or -ENOMEM + * if there's no more address available. + * + ****************************************************************************/ + +int i3c_master_get_free_addr(FAR struct i3c_master_controller *master, + unsigned char start_addr); + +/**************************************************************************** + * Name: i3c_master_add_i3c_dev_locked + * + * Description: + * Add an I3C slave to the bus + * + * This function is instantiating an I3C device object and adding it to + * the I3C device list. All device information are automatically retrieved + * using standard CCC commands. + * + * The I3C device object is returned in case the master wants to attach + * private data to it using i3c_dev_set_master_data(). + * + * This function must be called with the bus lock held in write mode. + * + * Input Parameters: + * master - Master used to send frames on the bus + * addr - I3C slave dynamic address assigned to the device + * + * Returned Value: + * 0 in case of success, an negative error code otherwise. + * + ****************************************************************************/ + +int i3c_master_add_i3c_dev_locked(FAR struct i3c_master_controller *master, + unsigned char addr); + +/**************************************************************************** + * Name: i3c_master_do_daa + * + * Description: + * Do a DAA (Dynamic Address Assignment) + * + * This function is instantiating an I3C device object and adding it to + * the I3C device list. All device information are automatically retrieved + * using standard CCC commands. + * + * The I3C device object is returned in case the master wants to attach + * private data to it using i3c_dev_set_master_data(). + * + * This function must be called with the bus lock held in write mode. + * + * Input Parameters: + * master - Master doing the DAA + * + * Returned Value: + * 0 in case of success, an negative error code otherwise. + * + ****************************************************************************/ + +int i3c_master_do_daa(FAR struct i3c_master_controller *master); + +/**************************************************************************** + * Name: i3c_master_set_info + * + * Description: + * Set master device information + * + * Set master device info. This should be called from + * &i3c_master_controller_ops->bus_init(). + * + * Not all &i3c_device_info fields are meaningful for a master device. + * Here is a list of fields that should be properly filled: + * + * - &i3c_device_info->dyn_addr + * - &i3c_device_info->bcr + * - &i3c_device_info->dcr + * - &i3c_device_info->pid + * - &i3c_device_info->hdr_cap if %I3C_BCR_HDR_CAP bit is set in + * &i3c_device_info->bcr + * + * This function must be called with the bus lock held in maintenance mode. + * + * Input Parameters: + * master - Master used to send frames on the bus + * info - I3C device information + * + * Returned Value: + * 0 if @info contains valid information (not every piece of + * information can be checked, but we can at least make sure info->dyn_addr + * and @info->bcr are correct), -EINVAL otherwise. + * + ****************************************************************************/ + +int i3c_master_set_info(FAR struct i3c_master_controller *master, + FAR const struct i3c_device_info *info); + +#endif /* __INCLUDE_NUTTX_I3C_MASTER_H */