include/linux/i2c.h

1 /* SPDX-License-Identifier: GPL-2.0-or-later */
3  * i2c.h - definitions for the Linux i2c bus interface
4  * Copyright (C) 1995-2000 Simon G. Vogl
5  * Copyright (C) 2013-2019 Wolfram Sang <wsa@kernel.org>
28 /* --- General options ------------------------------------------------	*/
65  * i2c_master_recv - issue a single I2C message in master receive mode
79  * i2c_master_recv_dmasafe - issue a single I2C message in master receive mode
95  * i2c_master_send - issue a single I2C message in master transmit mode
109  * i2c_master_send_dmasafe - issue a single I2C message in master transmit mode
189  * struct i2c_device_identity - i2c client device identification
190  * @manufacturer_id: 0 - 4095, database maintained by NXP
191  * @part_id: 0 - 511, according to manufacturer
192  * @die_revision: 0 - 7, according to manufacturer
221  * struct i2c_driver - represent an I2C device driver
223  * @probe: Callback for device binding - soon to be deprecated
228  * @command: Callback for bus-wide signaling (optional)
233  * @clients: List of detected clients we created (for i2c-core use only)
275 	 * 16-bit payload data reported by the slave device acting as master.
296  * struct i2c_client - represent an I2C slave device
300  *	generic enough to hide second-sourcing and compatible revisions.
305  * @detected: member of an i2c_driver.clients list or i2c-core's
307  * @slave_cb: Callback when I2C slave mode of an adapter is used. The adapter
325 	unsigned short addr;		/* chip address - NOTE: 7bit	*/
335 	i2c_slave_cb_t slave_cb;	/* callback for slave mode	*/
353 	return dev_get_drvdata(&client->dev);  in i2c_get_clientdata()
358 	dev_set_drvdata(&client->dev, data);  in i2c_set_clientdata()
379 	return client->slave_cb(client, event, val);  in i2c_slave_event()
386  * struct i2c_board_info - template for device creation
390  * @dev_name: Overrides the default <busnr>-<addr> dev_name if set
407  * bus numbers identify adapters that aren't yet available.  For add-on boards,
425  * I2C_BOARD_INFO - macro used to list an i2c device and its address
431  * fields (such as associated irq, or device-specific platform_data)
440  * Add-on boards should register/unregister their devices; e.g. a board
478  * Modules for add-on boards must use other calls.
494  * struct i2c_algorithm - represent I2C transfer method
507  * @reg_slave: Register given client to I2C slave mode of this adapter
508  * @unreg_slave: Unregister given client from I2C slave mode of this adapter
512  * be addressed using the same bus algorithms - i.e. bit-banging or the PCF8584
517  * Kernel Documentation file Documentation/i2c/fault-codes.rst.
521 	 * If an adapter algorithm can't do I2C-level access, set master_xfer
550  * struct i2c_lock_operations - represent I2C locking operations
564  * struct i2c_timings - I2C timing information
588  * struct i2c_bus_recovery_info - I2C bus recovery information
592  *      recovery. Populated internally for generic GPIO recovery.
593  * @set_scl: This sets/clears the SCL line. Mandatory for generic SCL recovery.
594  *      Populated internally for generic GPIO recovery.
596  *	for generic SCL recovery. Populated internally, if sda_gpio is a valid
597  *	GPIO, for generic GPIO recovery.
599  *	generic SCL recovery. Populated internally, if sda_gpio is a valid GPIO,
600  *	for generic GPIO recovery.
603  * @prepare_recovery: This will be called before starting recovery. Platform may
605  * @unprepare_recovery: This will be called after completing recovery. Platform
607  * @scl_gpiod: gpiod of the SCL line. Only required for GPIO recovery.
608  * @sda_gpiod: gpiod of the SDA line. Only required for GPIO recovery.
609  * @pinctrl: pinctrl used by GPIO recovery to change the state of the I2C pins.
612  *      to the I2C bus. Optional. Populated internally for GPIO recovery, if
614  * @pins_gpio: recovery pinctrl state of SCL/SDA lines, when they are used as
615  *      GPIOs. Optional. Populated internally for GPIO recovery, if this state
616  *      is called "gpio" or "recovery" and pinctrl is valid.
630 	/* gpio recovery */
640 /* Generic recovery routines */
644  * struct i2c_adapter_quirks - describe flaws of an i2c adapter
653  * per transfer, plus something called combined message or write-then-read.
656  * to support this mode. It implies max_num_msg = 2 and does the length checks
657  * with max_comb_*_len because combined message mode usually has its own
659  * write-then-anything or other variants. To support that, write-then-read has
660  * been broken out into smaller bits like write-first and read-second which can
681 /* convenience macro for typical write-then read case */
729 	return dev_get_drvdata(&adap->dev);  in i2c_get_adapdata()
734 	dev_set_drvdata(&adap->dev, data);  in i2c_set_adapdata()
741 	struct device *parent = adapter->dev.parent;  in i2c_parent_is_i2c_adapter()
743 	if (parent != NULL && parent->type == &i2c_adapter_type)  in i2c_parent_is_i2c_adapter()
757  * i2c_lock_bus - Get exclusive access to an I2C bus segment
765 	adapter->lock_ops->lock_bus(adapter, flags);  in i2c_lock_bus()
769  * i2c_trylock_bus - Try to get exclusive access to an I2C bus segment
779 	return adapter->lock_ops->trylock_bus(adapter, flags);  in i2c_trylock_bus()
783  * i2c_unlock_bus - Release exclusive access to an I2C bus segment
791 	adapter->lock_ops->unlock_bus(adapter, flags);  in i2c_unlock_bus()
795  * i2c_mark_adapter_suspended - Report suspended state of the adapter to the core
807 	set_bit(I2C_ALF_IS_SUSPENDED, &adap->locked_flags);  in i2c_mark_adapter_suspended()
812  * i2c_mark_adapter_resumed - Report resumed state of the adapter to the core
822 	clear_bit(I2C_ALF_IS_SUSPENDED, &adap->locked_flags);  in i2c_mark_adapter_resumed()
836 /* Construct an I2C_CLIENT_END-terminated array of i2c addresses */
841 /* ----- functions exported by i2c.o */
859 	return !IS_ERR_OR_NULL(client) && client->dev.driver;  in i2c_client_has_driver()
862 /* call the i2c_client->command() of all attached clients with
876 	return adap->algo->functionality(adap);  in i2c_get_functionality()
886  * i2c_check_quirks() - Function for checking the quirk flags in an i2c adapter
894 	if (!adap->quirks)  in i2c_check_quirks()
896 	return (adap->quirks->flags & quirks) == quirks;  in i2c_check_quirks()
902 	return adap->nr;  in i2c_adapter_id()
907 	return (msg->addr << 1) | (msg->flags & I2C_M_RD ? 1 : 0);  in i2c_8bit_addr_from_msg()
915  * module_i2c_driver() - Helper macro for registering a modular I2C driver
927  * builtin_i2c_driver() - Helper macro for registering a builtin I2C driver
984 	return -ENOTSUPP;  in of_i2c_get_board_info()
1012 	return ERR_PTR(-ENODEV);  in i2c_acpi_new_device()