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 <[email protected]>
24 #include <uapi/linux/i2c.h>
30 /* --- General options ------------------------------------------------	*/
43 /* I2C Frequency Modes */
55 /* Return the Frequency mode string based on the bus frequency */
60  * on a bus (or read from them). Apart from two basic transfer functions to
69  * i2c_master_recv - issue a single I2C message in master receive mode
83  * i2c_master_recv_dmasafe - issue a single I2C message in master receive mode
99  * i2c_master_send - issue a single I2C message in master transmit mode
113  * i2c_master_send_dmasafe - issue a single I2C message in master transmit mode
192 #endif /* I2C */
195  * struct i2c_device_identity - i2c client device identification
196  * @manufacturer_id: 0 - 4095, database maintained by NXP
197  * @part_id: 0 - 511, according to manufacturer
198  * @die_revision: 0 - 7, according to manufacturer
227  * enum i2c_driver_flags - Flags for an I2C device driver
236  * struct i2c_driver - represent an I2C device driver
237  * @class: What kind of i2c device we instantiate (for detect)
242  * @command: Callback for bus-wide signaling (optional)
244  * @id_table: List of I2C devices supported by this driver
246  * @address_list: The I2C addresses to probe (for detect)
247  * @clients: List of detected clients we created (for i2c-core use only)
251  * The driver.name field should be set to the name of this driver.
256  * fill at least the name field of the i2c_board_info structure it is
261  * for the many I2C/SMBus devices which can't be detected reliably, and
286 	 * 16-bit payload data reported by the slave device acting as master.
309  * struct i2c_client - represent an I2C slave device
311  * @addr: Address used on the I2C bus connected to the parent adapter.
312  * @name: Indicates the type of the device, usually a chip name that's
313  *	generic enough to hide second-sourcing and compatible revisions.
314  * @adapter: manages the bus segment hosting this I2C device
318  * @detected: member of an i2c_driver.clients list or i2c-core's
320  * @slave_cb: Callback when I2C slave mode of an adapter is used. The adapter
324  * @debugfs: pointer to the debugfs subdirectory which the I2C core created
328  * i2c bus. The behaviour exposed to Linux is defined by the driver
337 #define I2C_CLIENT_HOST_NOTIFY	0x40	/* We want to use I2C host notify */
342 	unsigned short addr;		/* chip address - NOTE: 7bit	*/
345 	char name[I2C_NAME_SIZE];  member
355 	struct dentry *debugfs;		/* per-client debugfs dir	*/
373 	return dev_get_drvdata(&client->dev);  in i2c_get_clientdata()
378 	dev_set_drvdata(&client->dev, data);  in i2c_set_clientdata()
381 /* I2C slave support */
402  * struct i2c_board_info - template for device creation
403  * @type: chip type, to initialize i2c_client.name
406  * @dev_name: Overrides the default <busnr>-<addr> dev_name if set
415  * I2C doesn't actually support hardware probing, although controllers and
420  * i2c_board_info is used to build tables of information listing I2C devices
423  * bus numbers identify adapters that aren't yet available.  For add-on boards,
441  * I2C_BOARD_INFO - macro used to list an i2c device and its address
443  * @dev_addr: the device's address on the bus.
447  * fields (such as associated irq, or device-specific platform_data)
456  * Add-on boards should register/unregister their devices; e.g. a board
457  * with integrated I2C, a config eeprom, sensors, and a codec that's
463 /* If you don't know the exact address of an I2C device, use this variant
486 			 const char *name,
497 #endif /* I2C */
499 /* Mainboard arch_initcall() code should register all its I2C devices.
500  * This is done at arch_initcall time, before declaring any i2c adapters.
501  * Modules for add-on boards must use other calls.
517  * struct i2c_algorithm - represent I2C transfer methods
522  * @smbus_xfer: Issue SMBus transactions to the given I2C adapter. If this
523  *   is not present, then the bus layer will try and convert the SMBus calls
524  *   into I2C transfers instead.
538  * be addressed using the same bus algorithms - i.e. bit-banging or the PCF8584
539  * to name two of the most common.
543  * Kernel Documentation file Documentation/i2c/fault-codes.rst. Otherwise, the
548 	 * If an adapter algorithm can't do I2C-level access, set xfer
551 	 * using common I2C messages.
588  * struct i2c_lock_operations - represent I2C locking operations
589  * @lock_bus: Get exclusive access to an I2C bus segment
590  * @trylock_bus: Try to get exclusive access to an I2C bus segment
591  * @unlock_bus: Release exclusive access to an I2C bus segment
602  * struct i2c_timings - I2C timing information
603  * @bus_freq_hz: the bus frequency in Hz
604  * @scl_rise_ns: time SCL signal takes to rise in ns; t(r) in the I2C specification
605  * @scl_fall_ns: time SCL signal takes to fall in ns; t(f) in the I2C specification
607  * @sda_fall_ns: time SDA signal takes to fall in ns; t(f) in the I2C specification
609  * @digital_filter_width_ns: width in ns of spikes on i2c lines that the IP core
626  * struct i2c_bus_recovery_info - I2C bus recovery information
639  * @get_bus_free: Returns the bus free state as seen from the IP core in case it
647  * @pinctrl: pinctrl used by GPIO recovery to change the state of the I2C pins.
650  *      to the I2C bus. Optional. Populated internally for GPIO recovery, if
651  *      state with the name PINCTRL_STATE_DEFAULT is found and pinctrl is valid.
682  * struct i2c_adapter_quirks - describe flaws of an i2c adapter
690  * Note about combined messages: Some I2C controllers can only send one message
691  * per transfer, plus something called combined message or write-then-read.
697  * write-then-anything or other variants. To support that, write-then-read has
698  * been broken out into smaller bits like write-first and read-second which can
719 /* convenience macro for typical write-then read case */
732  * i2c_adapter is the structure used to identify a physical i2c bus along
738 	const struct i2c_algorithm *algo; /* the algorithm to access the bus */
749 	unsigned long locked_flags;	/* owned by the I2C core */
754 	char name[48];  member
775 	return dev_get_drvdata(&adap->dev);  in i2c_get_adapdata()
780 	dev_set_drvdata(&adap->dev, data);  in i2c_set_adapdata()
787 	struct device *parent = adapter->dev.parent;  in i2c_parent_is_i2c_adapter()
789 	if (parent != NULL && parent->type == &i2c_adapter_type)  in i2c_parent_is_i2c_adapter()
803  * i2c_lock_bus - Get exclusive access to an I2C bus segment
804  * @adapter: Target I2C bus segment
805  * @flags: I2C_LOCK_ROOT_ADAPTER locks the root i2c adapter, I2C_LOCK_SEGMENT
811 	adapter->lock_ops->lock_bus(adapter, flags);  in i2c_lock_bus()
815  * i2c_trylock_bus - Try to get exclusive access to an I2C bus segment
816  * @adapter: Target I2C bus segment
817  * @flags: I2C_LOCK_ROOT_ADAPTER tries to locks the root i2c adapter,
820  * Return: true if the I2C bus segment is locked, false otherwise
825 	return adapter->lock_ops->trylock_bus(adapter, flags);  in i2c_trylock_bus()
829  * i2c_unlock_bus - Release exclusive access to an I2C bus segment
830  * @adapter: Target I2C bus segment
831  * @flags: I2C_LOCK_ROOT_ADAPTER unlocks the root i2c adapter, I2C_LOCK_SEGMENT
837 	adapter->lock_ops->unlock_bus(adapter, flags);  in i2c_unlock_bus()
841  * i2c_mark_adapter_suspended - Report suspended state of the adapter to the core
853 	set_bit(I2C_ALF_IS_SUSPENDED, &adap->locked_flags);  in i2c_mark_adapter_suspended()
858  * i2c_mark_adapter_resumed - Report resumed state of the adapter to the core
868 	clear_bit(I2C_ALF_IS_SUSPENDED, &adap->locked_flags);  in i2c_mark_adapter_resumed()
872 /* i2c adapter classes (bitmask) */
880 /* Construct an I2C_CLIENT_END-terminated array of i2c addresses */
885 /* ----- functions exported by i2c.o */
904 	return !IS_ERR_OR_NULL(client) && client->dev.driver;  in i2c_client_has_driver()
907 /* call the i2c_client->command() of all attached clients with
921 	return adap->algo->functionality(adap);  in i2c_get_functionality()
931  * i2c_check_quirks() - Function for checking the quirk flags in an i2c adapter
932  * @adap: i2c adapter
939 	if (!adap->quirks)  in i2c_check_quirks()
941 	return (adap->quirks->flags & quirks) == quirks;  in i2c_check_quirks()
947 	return adap->nr;  in i2c_adapter_id()
952 	return (msg->addr << 1) | (msg->flags & I2C_M_RD);  in i2c_8bit_addr_from_msg()
960  * module_i2c_driver() - Helper macro for registering a modular I2C driver
963  * Helper macro for I2C drivers which do not do anything special in module
972  * builtin_i2c_driver() - Helper macro for registering a builtin I2C driver
975  * Helper macro for I2C drivers which do not do anything special in their
991 #else /* I2C */
1011 #endif /* !I2C */
1067 	return -ENOTSUPP;  in of_i2c_get_board_info()
1077 			       struct acpi_resource_i2c_serialbus **i2c);
1087 					     struct acpi_resource_i2c_serialbus **i2c)  in i2c_acpi_get_i2c_resource()  argument
1103 	return ERR_PTR(-ENODEV);  in i2c_acpi_new_device_by_fwnode()