i2c.h 34.6 KB
Newer Older
Linus Torvalds's avatar
Linus Torvalds committed
1
/* ------------------------------------------------------------------------- */
2
/*									     */
Linus Torvalds's avatar
Linus Torvalds committed
3
/* i2c.h - definitions for the i2c-bus interface			     */
4
/*									     */
Linus Torvalds's avatar
Linus Torvalds committed
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
/* ------------------------------------------------------------------------- */
/*   Copyright (C) 1995-2000 Simon G. Vogl

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
20 21
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
    MA 02110-1301 USA.							     */
Linus Torvalds's avatar
Linus Torvalds committed
22 23
/* ------------------------------------------------------------------------- */

24
/* With some changes from Kyösti Mälkki <kmalkki@cc.hut.fi> and
Linus Torvalds's avatar
Linus Torvalds committed
25 26 27 28
   Frodo Looijaard <frodol@dds.nl> */
#ifndef _LINUX_I2C_H
#define _LINUX_I2C_H

29
#include <linux/mod_devicetable.h>
Linus Torvalds's avatar
Linus Torvalds committed
30
#include <linux/device.h>	/* for struct device */
31
#include <linux/sched.h>	/* for completion */
32
#include <linux/mutex.h>
33
#include <linux/rtmutex.h>
34
#include <linux/irqdomain.h>		/* for Host Notify IRQ */
35
#include <linux/of.h>		/* for struct device_node */
36
#include <linux/swab.h>		/* for swab16 */
37
#include <uapi/linux/i2c.h>
Linus Torvalds's avatar
Linus Torvalds committed
38

39
extern struct bus_type i2c_bus_type;
40
extern struct device_type i2c_adapter_type;
41
extern struct device_type i2c_client_type;
42

Linus Torvalds's avatar
Linus Torvalds committed
43 44 45 46 47 48 49
/* --- General options ------------------------------------------------	*/

struct i2c_msg;
struct i2c_algorithm;
struct i2c_adapter;
struct i2c_client;
struct i2c_driver;
50
struct i2c_device_identity;
Linus Torvalds's avatar
Linus Torvalds committed
51
union i2c_smbus_data;
52
struct i2c_board_info;
53 54
enum i2c_slave_event;
typedef int (*i2c_slave_cb_t)(struct i2c_client *, enum i2c_slave_event, u8 *);
Linus Torvalds's avatar
Linus Torvalds committed
55

56
struct module;
57
struct property_entry;
58

59
#if IS_ENABLED(CONFIG_I2C)
Linus Torvalds's avatar
Linus Torvalds committed
60 61
/*
 * The master routines are the ones normally used to transmit data to devices
62 63
 * on a bus (or read from them). Apart from two basic transfer functions to
 * transmit one message at a time, a more complex version can be used to
Linus Torvalds's avatar
Linus Torvalds committed
64
 * transmit an arbitrary number of messages without interruption.
65
 * @count must be be less than 64k since msg.len is u16.
Linus Torvalds's avatar
Linus Torvalds committed
66
 */
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
extern int i2c_transfer_buffer_flags(const struct i2c_client *client,
				     char *buf, int count, u16 flags);

/**
 * i2c_master_recv - issue a single I2C message in master receive mode
 * @client: Handle to slave device
 * @buf: Where to store data read from slave
 * @count: How many bytes to read, must be less than 64k since msg.len is u16
 *
 * Returns negative errno, or else the number of bytes read.
 */
static inline int i2c_master_recv(const struct i2c_client *client,
				  char *buf, int count)
{
	return i2c_transfer_buffer_flags(client, buf, count, I2C_M_RD);
};

84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99
/**
 * i2c_master_recv_dmasafe - issue a single I2C message in master receive mode
 *			     using a DMA safe buffer
 * @client: Handle to slave device
 * @buf: Where to store data read from slave, must be safe to use with DMA
 * @count: How many bytes to read, must be less than 64k since msg.len is u16
 *
 * Returns negative errno, or else the number of bytes read.
 */
static inline int i2c_master_recv_dmasafe(const struct i2c_client *client,
					  char *buf, int count)
{
	return i2c_transfer_buffer_flags(client, buf, count,
					 I2C_M_RD | I2C_M_DMA_SAFE);
};

100 101 102 103 104 105 106 107 108 109 110 111 112
/**
 * i2c_master_send - issue a single I2C message in master transmit mode
 * @client: Handle to slave device
 * @buf: Data that will be written to the slave
 * @count: How many bytes to write, must be less than 64k since msg.len is u16
 *
 * Returns negative errno, or else the number of bytes written.
 */
static inline int i2c_master_send(const struct i2c_client *client,
				  const char *buf, int count)
{
	return i2c_transfer_buffer_flags(client, (char *)buf, count, 0);
};
Linus Torvalds's avatar
Linus Torvalds committed
113

114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129
/**
 * i2c_master_send_dmasafe - issue a single I2C message in master transmit mode
 *			     using a DMA safe buffer
 * @client: Handle to slave device
 * @buf: Data that will be written to the slave, must be safe to use with DMA
 * @count: How many bytes to write, must be less than 64k since msg.len is u16
 *
 * Returns negative errno, or else the number of bytes written.
 */
static inline int i2c_master_send_dmasafe(const struct i2c_client *client,
					  const char *buf, int count)
{
	return i2c_transfer_buffer_flags(client, (char *)buf, count,
					 I2C_M_DMA_SAFE);
};

Linus Torvalds's avatar
Linus Torvalds committed
130 131
/* Transfer num messages.
 */
132 133
extern int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msgs,
			int num);
134 135 136
/* Unlocked flavor */
extern int __i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msgs,
			  int num);
Linus Torvalds's avatar
Linus Torvalds committed
137 138 139

/* This is the very generalized SMBus access routine. You probably do not
   want to use this, though; one of the functions below may be much easier,
140
   and probably just as fast.
Linus Torvalds's avatar
Linus Torvalds committed
141 142
   Note that we use i2c_adapter here, because you do not need a specific
   smbus adapter to call this function. */
143 144 145 146 147 148 149 150
s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
		   unsigned short flags, char read_write, u8 command,
		   int protocol, union i2c_smbus_data *data);

/* Unlocked flavor */
s32 __i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
		     unsigned short flags, char read_write, u8 command,
		     int protocol, union i2c_smbus_data *data);
Linus Torvalds's avatar
Linus Torvalds committed
151 152

/* Now follow the 'nice' access routines. These also document the calling
153
   conventions of i2c_smbus_xfer. */
Linus Torvalds's avatar
Linus Torvalds committed
154

155 156 157 158 159
extern s32 i2c_smbus_read_byte(const struct i2c_client *client);
extern s32 i2c_smbus_write_byte(const struct i2c_client *client, u8 value);
extern s32 i2c_smbus_read_byte_data(const struct i2c_client *client,
				    u8 command);
extern s32 i2c_smbus_write_byte_data(const struct i2c_client *client,
160
				     u8 command, u8 value);
161 162 163
extern s32 i2c_smbus_read_word_data(const struct i2c_client *client,
				    u8 command);
extern s32 i2c_smbus_write_word_data(const struct i2c_client *client,
164
				     u8 command, u16 value);
165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180

static inline s32
i2c_smbus_read_word_swapped(const struct i2c_client *client, u8 command)
{
	s32 value = i2c_smbus_read_word_data(client, command);

	return (value < 0) ? value : swab16(value);
}

static inline s32
i2c_smbus_write_word_swapped(const struct i2c_client *client,
			     u8 command, u16 value)
{
	return i2c_smbus_write_word_data(client, command, swab16(value));
}

181
/* Returns the number of read bytes */
182
extern s32 i2c_smbus_read_block_data(const struct i2c_client *client,
183
				     u8 command, u8 *values);
184
extern s32 i2c_smbus_write_block_data(const struct i2c_client *client,
185
				      u8 command, u8 length, const u8 *values);
186
/* Returns the number of read bytes */
187
extern s32 i2c_smbus_read_i2c_block_data(const struct i2c_client *client,
188
					 u8 command, u8 length, u8 *values);
189
extern s32 i2c_smbus_write_i2c_block_data(const struct i2c_client *client,
190
					  u8 command, u8 length,
191
					  const u8 *values);
192 193 194
extern s32
i2c_smbus_read_i2c_block_data_or_emulated(const struct i2c_client *client,
					  u8 command, u8 length, u8 *values);
195 196
int i2c_get_device_id(const struct i2c_client *client,
		      struct i2c_device_identity *id);
197
#endif /* I2C */
Linus Torvalds's avatar
Linus Torvalds committed
198

199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225
/**
 * struct i2c_device_identity - i2c client device identification
 * @manufacturer_id: 0 - 4095, database maintained by NXP
 * @part_id: 0 - 511, according to manufacturer
 * @die_revision: 0 - 7, according to manufacturer
 */
struct i2c_device_identity {
	u16 manufacturer_id;
#define I2C_DEVICE_ID_NXP_SEMICONDUCTORS                0
#define I2C_DEVICE_ID_NXP_SEMICONDUCTORS_1              1
#define I2C_DEVICE_ID_NXP_SEMICONDUCTORS_2              2
#define I2C_DEVICE_ID_NXP_SEMICONDUCTORS_3              3
#define I2C_DEVICE_ID_RAMTRON_INTERNATIONAL             4
#define I2C_DEVICE_ID_ANALOG_DEVICES                    5
#define I2C_DEVICE_ID_STMICROELECTRONICS                6
#define I2C_DEVICE_ID_ON_SEMICONDUCTOR                  7
#define I2C_DEVICE_ID_SPRINTEK_CORPORATION              8
#define I2C_DEVICE_ID_ESPROS_PHOTONICS_AG               9
#define I2C_DEVICE_ID_FUJITSU_SEMICONDUCTOR            10
#define I2C_DEVICE_ID_FLIR                             11
#define I2C_DEVICE_ID_O2MICRO                          12
#define I2C_DEVICE_ID_ATMEL                            13
#define I2C_DEVICE_ID_NONE                         0xffff
	u16 part_id;
	u8 die_revision;
};

226 227
enum i2c_alert_protocol {
	I2C_PROTOCOL_SMBUS_ALERT,
228
	I2C_PROTOCOL_SMBUS_HOST_NOTIFY,
229 230
};

231 232 233
/**
 * struct i2c_driver - represent an I2C device driver
 * @class: What kind of i2c device we instantiate (for detect)
234 235
 * @probe: Callback for device binding - soon to be deprecated
 * @probe_new: New callback for device binding
236
 * @remove: Callback for device unbinding
237
 * @shutdown: Callback for device shutdown
238
 * @alert: Alert callback, for example for the SMBus alert protocol
239 240 241
 * @command: Callback for bus-wide signaling (optional)
 * @driver: Device driver model driver
 * @id_table: List of I2C devices supported by this driver
242
 * @detect: Callback for device detection
243
 * @address_list: The I2C addresses to probe (for detect)
244
 * @clients: List of detected clients we created (for i2c-core use only)
245
 * @disable_i2c_core_irq_mapping: Tell the i2c-core to not do irq-mapping
246 247 248
 *
 * The driver.owner field should be set to the module owner of this driver.
 * The driver.name field should be set to the name of this driver.
249
 *
250
 * For automatic device detection, both @detect and @address_list must
251 252 253 254 255 256 257 258 259 260 261 262 263 264 265
 * be defined. @class should also be set, otherwise only devices forced
 * with module parameters will be created. The detect function must
 * fill at least the name field of the i2c_board_info structure it is
 * handed upon successful detection, and possibly also the flags field.
 *
 * If @detect is missing, the driver will still work fine for enumerated
 * devices. Detected devices simply won't be supported. This is expected
 * for the many I2C/SMBus devices which can't be detected reliably, and
 * the ones which can always be enumerated in practice.
 *
 * The i2c_client structure which is handed to the @detect callback is
 * not a real i2c_client. It is initialized just enough so that you can
 * call i2c_smbus_read_byte_data and friends on it. Don't do anything
 * else with it. In particular, calling dev_dbg and friends on it is
 * not allowed.
Linus Torvalds's avatar
Linus Torvalds committed
266 267 268 269
 */
struct i2c_driver {
	unsigned int class;

270
	/* Standard driver model interfaces */
271
	int (*probe)(struct i2c_client *, const struct i2c_device_id *);
272
	int (*remove)(struct i2c_client *);
273

274 275 276 277 278
	/* New driver model interface to aid the seamless removal of the
	 * current probe()'s, more commonly unused than used second parameter.
	 */
	int (*probe_new)(struct i2c_client *);

279 280 281
	/* driver model interfaces that don't relate to enumeration  */
	void (*shutdown)(struct i2c_client *);

282 283 284 285
	/* Alert callback, for example for the SMBus alert protocol.
	 * The format and meaning of the data value depends on the protocol.
	 * For the SMBus alert protocol, there is a single bit of data passed
	 * as the alert response's low bit ("event flag").
286 287
	 * For the SMBus Host Notify protocol, the data corresponds to the
	 * 16-bit payload data reported by the slave device acting as master.
288
	 */
289 290
	void (*alert)(struct i2c_client *, enum i2c_alert_protocol protocol,
		      unsigned int data);
291

Linus Torvalds's avatar
Linus Torvalds committed
292 293 294
	/* a ioctl like command that can be used to perform specific functions
	 * with the device.
	 */
295
	int (*command)(struct i2c_client *client, unsigned int cmd, void *arg);
Linus Torvalds's avatar
Linus Torvalds committed
296 297

	struct device_driver driver;
298
	const struct i2c_device_id *id_table;
299 300

	/* Device detection callback for automatic device creation */
301
	int (*detect)(struct i2c_client *, struct i2c_board_info *);
302
	const unsigned short *address_list;
303
	struct list_head clients;
304 305

	bool disable_i2c_core_irq_mapping;
Linus Torvalds's avatar
Linus Torvalds committed
306 307 308
};
#define to_i2c_driver(d) container_of(d, struct i2c_driver, driver)

309 310
/**
 * struct i2c_client - represent an I2C slave device
311 312
 * @flags: I2C_CLIENT_TEN indicates the device uses a ten bit chip address;
 *	I2C_CLIENT_PEC indicates it uses SMBus Packet Error Checking
313 314 315
 * @addr: Address used on the I2C bus connected to the parent adapter.
 * @name: Indicates the type of the device, usually a chip name that's
 *	generic enough to hide second-sourcing and compatible revisions.
316
 * @adapter: manages the bus segment hosting this I2C device
317
 * @dev: Driver model device node for the slave.
318
 * @irq: indicates the IRQ generated by this device (if any)
319 320
 * @detected: member of an i2c_driver.clients list or i2c-core's
 *	userspace_devices list
321 322
 * @slave_cb: Callback when I2C slave mode of an adapter is used. The adapter
 *	calls it to pass on slave events to the slave driver.
323 324
 *
 * An i2c_client identifies a single device (i.e. chip) connected to an
325 326
 * i2c bus. The behaviour exposed to Linux is defined by the driver
 * managing the device.
Linus Torvalds's avatar
Linus Torvalds committed
327 328
 */
struct i2c_client {
329
	unsigned short flags;		/* div., see below		*/
330
	unsigned short addr;		/* chip address - NOTE: 7bit	*/
Linus Torvalds's avatar
Linus Torvalds committed
331
					/* addresses are stored in the	*/
332
					/* _LOWER_ 7 bits		*/
333
	char name[I2C_NAME_SIZE];
Linus Torvalds's avatar
Linus Torvalds committed
334 335
	struct i2c_adapter *adapter;	/* the adapter we sit on	*/
	struct device dev;		/* the device structure		*/
336
	int irq;			/* irq issued by device		*/
337
	struct list_head detected;
338
#if IS_ENABLED(CONFIG_I2C_SLAVE)
339
	i2c_slave_cb_t slave_cb;	/* callback for slave mode	*/
340
#endif
Linus Torvalds's avatar
Linus Torvalds committed
341 342 343
};
#define to_i2c_client(d) container_of(d, struct i2c_client, dev)

344
extern struct i2c_client *i2c_verify_client(struct device *dev);
345
extern struct i2c_adapter *i2c_verify_adapter(struct device *dev);
346 347
extern const struct i2c_device_id *i2c_match_id(const struct i2c_device_id *id,
					const struct i2c_client *client);
348

349 350
static inline struct i2c_client *kobj_to_i2c_client(struct kobject *kobj)
{
351 352
	struct device * const dev = container_of(kobj, struct device, kobj);
	return to_i2c_client(dev);
353 354
}

355
static inline void *i2c_get_clientdata(const struct i2c_client *dev)
Linus Torvalds's avatar
Linus Torvalds committed
356
{
357
	return dev_get_drvdata(&dev->dev);
Linus Torvalds's avatar
Linus Torvalds committed
358 359
}

360
static inline void i2c_set_clientdata(struct i2c_client *dev, void *data)
Linus Torvalds's avatar
Linus Torvalds committed
361
{
362
	dev_set_drvdata(&dev->dev, data);
Linus Torvalds's avatar
Linus Torvalds committed
363 364
}

365 366
/* I2C slave support */

367
#if IS_ENABLED(CONFIG_I2C_SLAVE)
368
enum i2c_slave_event {
369 370 371 372
	I2C_SLAVE_READ_REQUESTED,
	I2C_SLAVE_WRITE_REQUESTED,
	I2C_SLAVE_READ_PROCESSED,
	I2C_SLAVE_WRITE_RECEIVED,
373 374 375 376 377
	I2C_SLAVE_STOP,
};

extern int i2c_slave_register(struct i2c_client *client, i2c_slave_cb_t slave_cb);
extern int i2c_slave_unregister(struct i2c_client *client);
378
extern bool i2c_detect_slave_mode(struct device *dev);
379 380 381 382 383 384

static inline int i2c_slave_event(struct i2c_client *client,
				  enum i2c_slave_event event, u8 *val)
{
	return client->slave_cb(client, event, val);
}
385 386
#else
static inline bool i2c_detect_slave_mode(struct device *dev) { return false; }
387
#endif
388

389 390
/**
 * struct i2c_board_info - template for device creation
391
 * @type: chip type, to initialize i2c_client.name
392 393
 * @flags: to initialize i2c_client.flags
 * @addr: stored in i2c_client.addr
394
 * @dev_name: Overrides the default <busnr>-<addr> dev_name if set
395
 * @platform_data: stored in i2c_client.dev.platform_data
396
 * @of_node: pointer to OpenFirmware device node
397
 * @fwnode: device node supplied by the platform firmware
398
 * @properties: additional device properties for the device
399 400
 * @resources: resources associated with the device
 * @num_resources: number of resources in the @resources array
401
 * @irq: stored in i2c_client.irq
402
 *
403 404 405 406 407 408
 * I2C doesn't actually support hardware probing, although controllers and
 * devices may be able to use I2C_SMBUS_QUICK to tell whether or not there's
 * a device at a given address.  Drivers commonly need more information than
 * that, such as chip type, configuration, associated IRQ, and so on.
 *
 * i2c_board_info is used to build tables of information listing I2C devices
409 410 411 412
 * that are present.  This information is used to grow the driver model tree.
 * For mainboards this is done statically using i2c_register_board_info();
 * bus numbers identify adapters that aren't yet available.  For add-on boards,
 * i2c_new_device() does this dynamically with the adapter already known.
413 414 415 416 417
 */
struct i2c_board_info {
	char		type[I2C_NAME_SIZE];
	unsigned short	flags;
	unsigned short	addr;
418
	const char	*dev_name;
419
	void		*platform_data;
420
	struct device_node *of_node;
421
	struct fwnode_handle *fwnode;
422
	const struct property_entry *properties;
423 424
	const struct resource *resources;
	unsigned int	num_resources;
425 426 427 428
	int		irq;
};

/**
429 430
 * I2C_BOARD_INFO - macro used to list an i2c device and its address
 * @dev_type: identifies the device type
431 432 433 434
 * @dev_addr: the device's address on the bus.
 *
 * This macro initializes essential fields of a struct i2c_board_info,
 * declaring what has been provided on a particular board.  Optional
435 436
 * fields (such as associated irq, or device-specific platform_data)
 * are provided using conventional syntax.
437
 */
438
#define I2C_BOARD_INFO(dev_type, dev_addr) \
439
	.type = dev_type, .addr = (dev_addr)
440 441


442
#if IS_ENABLED(CONFIG_I2C)
443 444 445 446 447 448 449
/* Add-on boards should register/unregister their devices; e.g. a board
 * with integrated I2C, a config eeprom, sensors, and a codec that's
 * used in conjunction with the primary hardware.
 */
extern struct i2c_client *
i2c_new_device(struct i2c_adapter *adap, struct i2c_board_info const *info);

450 451
/* If you don't know the exact address of an I2C device, use this variant
 * instead, which can probe for device presence in a list of possible
452 453 454
 * addresses. The "probe" callback function is optional. If it is provided,
 * it must return 1 on successful probe, 0 otherwise. If it is not provided,
 * a default probing method is used.
455 456 457 458
 */
extern struct i2c_client *
i2c_new_probed_device(struct i2c_adapter *adap,
		      struct i2c_board_info *info,
459 460
		      unsigned short const *addr_list,
		      int (*probe)(struct i2c_adapter *, unsigned short addr));
461

462 463 464
/* Common custom probe functions */
extern int i2c_probe_func_quick_read(struct i2c_adapter *, unsigned short addr);

465 466 467 468
/* For devices that use several addresses, use i2c_new_dummy() to make
 * client handles for the extra addresses.
 */
extern struct i2c_client *
469
i2c_new_dummy(struct i2c_adapter *adap, u16 address);
470

471 472 473 474 475
extern struct i2c_client *
i2c_new_secondary_device(struct i2c_client *client,
				const char *name,
				u16 default_addr);

476
extern void i2c_unregister_device(struct i2c_client *);
477
#endif /* I2C */
478 479 480 481 482

/* Mainboard arch_initcall() code should register all its I2C devices.
 * This is done at arch_initcall time, before declaring any i2c adapters.
 * Modules for add-on boards must use other calls.
 */
483
#ifdef CONFIG_I2C_BOARDINFO
484
extern int
485 486
i2c_register_board_info(int busnum, struct i2c_board_info const *info,
			unsigned n);
487 488
#else
static inline int
489 490
i2c_register_board_info(int busnum, struct i2c_board_info const *info,
			unsigned n)
491 492 493
{
	return 0;
}
494
#endif /* I2C_BOARDINFO */
495

496 497 498 499 500 501 502 503 504 505
/**
 * struct i2c_algorithm - represent I2C transfer method
 * @master_xfer: Issue a set of i2c transactions to the given I2C adapter
 *   defined by the msgs array, with num messages available to transfer via
 *   the adapter specified by adap.
 * @smbus_xfer: Issue smbus transactions to the given I2C adapter. If this
 *   is not present, then the bus layer will try and convert the SMBus calls
 *   into I2C transfers instead.
 * @functionality: Return the flags that this algorithm/adapter pair supports
 *   from the I2C_FUNC_* flags.
506 507
 * @reg_slave: Register given client to I2C slave mode of this adapter
 * @unreg_slave: Unregister given client from I2C slave mode of this adapter
508
 *
Linus Torvalds's avatar
Linus Torvalds committed
509 510 511 512
 * The following structs are for those who like to implement new bus drivers:
 * i2c_algorithm is the interface to a class of hardware solutions which can
 * be addressed using the same bus algorithms - i.e. bit-banging or the PCF8584
 * to name two of the most common.
513 514
 *
 * The return codes from the @master_xfer field should indicate the type of
515
 * error code that occurred during the transfer, as documented in the kernel
516
 * Documentation file Documentation/i2c/fault-codes.
Linus Torvalds's avatar
Linus Torvalds committed
517 518 519
 */
struct i2c_algorithm {
	/* If an adapter algorithm can't do I2C-level access, set master_xfer
520
	   to NULL. If an adapter algorithm can do SMBus access, set
Linus Torvalds's avatar
Linus Torvalds committed
521 522
	   smbus_xfer. If set to NULL, the SMBus protocol is simulated
	   using common I2C messages */
523 524
	/* master_xfer should return the number of messages successfully
	   processed, or a negative value on error */
525 526
	int (*master_xfer)(struct i2c_adapter *adap, struct i2c_msg *msgs,
			   int num);
527
	int (*smbus_xfer) (struct i2c_adapter *adap, u16 addr,
528 529
			   unsigned short flags, char read_write,
			   u8 command, int size, union i2c_smbus_data *data);
Linus Torvalds's avatar
Linus Torvalds committed
530 531 532

	/* To determine what the adapter supports */
	u32 (*functionality) (struct i2c_adapter *);
533

534
#if IS_ENABLED(CONFIG_I2C_SLAVE)
535 536
	int (*reg_slave)(struct i2c_client *client);
	int (*unreg_slave)(struct i2c_client *client);
537
#endif
Linus Torvalds's avatar
Linus Torvalds committed
538 539
};

540 541 542 543 544 545 546 547 548 549 550 551 552 553
/**
 * struct i2c_lock_operations - represent I2C locking operations
 * @lock_bus: Get exclusive access to an I2C bus segment
 * @trylock_bus: Try to get exclusive access to an I2C bus segment
 * @unlock_bus: Release exclusive access to an I2C bus segment
 *
 * The main operations are wrapped by i2c_lock_bus and i2c_unlock_bus.
 */
struct i2c_lock_operations {
	void (*lock_bus)(struct i2c_adapter *, unsigned int flags);
	int (*trylock_bus)(struct i2c_adapter *, unsigned int flags);
	void (*unlock_bus)(struct i2c_adapter *, unsigned int flags);
};

554 555 556 557 558 559 560
/**
 * struct i2c_timings - I2C timing information
 * @bus_freq_hz: the bus frequency in Hz
 * @scl_rise_ns: time SCL signal takes to rise in ns; t(r) in the I2C specification
 * @scl_fall_ns: time SCL signal takes to fall in ns; t(f) in the I2C specification
 * @scl_int_delay_ns: time IP core additionally needs to setup SCL in ns
 * @sda_fall_ns: time SDA signal takes to fall in ns; t(f) in the I2C specification
561
 * @sda_hold_ns: time IP core additionally needs to hold SDA in ns
562 563 564 565 566 567 568
 */
struct i2c_timings {
	u32 bus_freq_hz;
	u32 scl_rise_ns;
	u32 scl_fall_ns;
	u32 scl_int_delay_ns;
	u32 sda_fall_ns;
569
	u32 sda_hold_ns;
570 571
};

572 573 574
/**
 * struct i2c_bus_recovery_info - I2C bus recovery information
 * @recover_bus: Recover routine. Either pass driver's recover_bus() routine, or
575
 *	i2c_generic_scl_recovery().
576
 * @get_scl: This gets current value of SCL line. Mandatory for generic SCL
577 578 579
 *      recovery. Populated internally for generic GPIO recovery.
 * @set_scl: This sets/clears the SCL line. Mandatory for generic SCL recovery.
 *      Populated internally for generic GPIO recovery.
580 581 582 583 584 585
 * @get_sda: This gets current value of SDA line. This or set_sda() is mandatory
 *	for generic SCL recovery. Populated internally, if sda_gpio is a valid
 *	GPIO, for generic GPIO recovery.
 * @set_sda: This sets/clears the SDA line. This or get_sda() is mandatory for
 *	generic SCL recovery. Populated internally, if sda_gpio is a valid GPIO,
 *	for generic GPIO recovery.
586 587
 * @get_bus_free: Returns the bus free state as seen from the IP core in case it
 *	has a more complex internal logic than just reading SDA. Optional.
588 589 590 591
 * @prepare_recovery: This will be called before starting recovery. Platform may
 *	configure padmux here for SDA/SCL line or something else they want.
 * @unprepare_recovery: This will be called after completing recovery. Platform
 *	may configure padmux here for SDA/SCL line or something else they want.
592 593
 * @scl_gpiod: gpiod of the SCL line. Only required for GPIO recovery.
 * @sda_gpiod: gpiod of the SDA line. Only required for GPIO recovery.
594 595
 */
struct i2c_bus_recovery_info {
596
	int (*recover_bus)(struct i2c_adapter *adap);
597

598 599 600
	int (*get_scl)(struct i2c_adapter *adap);
	void (*set_scl)(struct i2c_adapter *adap, int val);
	int (*get_sda)(struct i2c_adapter *adap);
601
	void (*set_sda)(struct i2c_adapter *adap, int val);
602
	int (*get_bus_free)(struct i2c_adapter *adap);
603

604 605
	void (*prepare_recovery)(struct i2c_adapter *adap);
	void (*unprepare_recovery)(struct i2c_adapter *adap);
606 607

	/* gpio recovery */
608 609
	struct gpio_desc *scl_gpiod;
	struct gpio_desc *sda_gpiod;
610 611 612 613 614 615 616
};

int i2c_recover_bus(struct i2c_adapter *adap);

/* Generic recovery routines */
int i2c_generic_scl_recovery(struct i2c_adapter *adap);

617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657
/**
 * struct i2c_adapter_quirks - describe flaws of an i2c adapter
 * @flags: see I2C_AQ_* for possible flags and read below
 * @max_num_msgs: maximum number of messages per transfer
 * @max_write_len: maximum length of a write message
 * @max_read_len: maximum length of a read message
 * @max_comb_1st_msg_len: maximum length of the first msg in a combined message
 * @max_comb_2nd_msg_len: maximum length of the second msg in a combined message
 *
 * Note about combined messages: Some I2C controllers can only send one message
 * per transfer, plus something called combined message or write-then-read.
 * This is (usually) a small write message followed by a read message and
 * barely enough to access register based devices like EEPROMs. There is a flag
 * to support this mode. It implies max_num_msg = 2 and does the length checks
 * with max_comb_*_len because combined message mode usually has its own
 * limitations. Because of HW implementations, some controllers can actually do
 * write-then-anything or other variants. To support that, write-then-read has
 * been broken out into smaller bits like write-first and read-second which can
 * be combined as needed.
 */

struct i2c_adapter_quirks {
	u64 flags;
	int max_num_msgs;
	u16 max_write_len;
	u16 max_read_len;
	u16 max_comb_1st_msg_len;
	u16 max_comb_2nd_msg_len;
};

/* enforce max_num_msgs = 2 and use max_comb_*_len for length checks */
#define I2C_AQ_COMB			BIT(0)
/* first combined message must be write */
#define I2C_AQ_COMB_WRITE_FIRST		BIT(1)
/* second combined message must be read */
#define I2C_AQ_COMB_READ_SECOND		BIT(2)
/* both combined messages must have the same target address */
#define I2C_AQ_COMB_SAME_ADDR		BIT(3)
/* convenience macro for typical write-then read case */
#define I2C_AQ_COMB_WRITE_THEN_READ	(I2C_AQ_COMB | I2C_AQ_COMB_WRITE_FIRST | \
					 I2C_AQ_COMB_READ_SECOND | I2C_AQ_COMB_SAME_ADDR)
658 659
/* clock stretching is not supported */
#define I2C_AQ_NO_CLK_STRETCH		BIT(4)
660 661 662 663
/* message cannot have length of 0 */
#define I2C_AQ_NO_ZERO_LEN_READ		BIT(5)
#define I2C_AQ_NO_ZERO_LEN_WRITE	BIT(6)
#define I2C_AQ_NO_ZERO_LEN		(I2C_AQ_NO_ZERO_LEN_READ | I2C_AQ_NO_ZERO_LEN_WRITE)
664

Linus Torvalds's avatar
Linus Torvalds committed
665 666 667 668 669 670
/*
 * i2c_adapter is the structure used to identify a physical i2c bus along
 * with the access algorithms necessary to access it.
 */
struct i2c_adapter {
	struct module *owner;
671
	unsigned int class;		  /* classes to allow probing for */
672
	const struct i2c_algorithm *algo; /* the algorithm to access the bus */
Linus Torvalds's avatar
Linus Torvalds committed
673 674 675
	void *algo_data;

	/* data fields that are valid for all devices	*/
676
	const struct i2c_lock_operations *lock_ops;
677
	struct rt_mutex bus_lock;
678
	struct rt_mutex mux_lock;
Linus Torvalds's avatar
Linus Torvalds committed
679

680
	int timeout;			/* in jiffies */
Linus Torvalds's avatar
Linus Torvalds committed
681 682 683 684
	int retries;
	struct device dev;		/* the adapter device */

	int nr;
685
	char name[48];
Linus Torvalds's avatar
Linus Torvalds committed
686
	struct completion dev_released;
687

688
	struct mutex userspace_clients_lock;
689
	struct list_head userspace_clients;
690 691

	struct i2c_bus_recovery_info *bus_recovery_info;
692
	const struct i2c_adapter_quirks *quirks;
693 694

	struct irq_domain *host_notify_domain;
Linus Torvalds's avatar
Linus Torvalds committed
695
};
696
#define to_i2c_adapter(d) container_of(d, struct i2c_adapter, dev)
Linus Torvalds's avatar
Linus Torvalds committed
697

698
static inline void *i2c_get_adapdata(const struct i2c_adapter *dev)
Linus Torvalds's avatar
Linus Torvalds committed
699
{
700
	return dev_get_drvdata(&dev->dev);
Linus Torvalds's avatar
Linus Torvalds committed
701 702
}

703
static inline void i2c_set_adapdata(struct i2c_adapter *dev, void *data)
Linus Torvalds's avatar
Linus Torvalds committed
704
{
705
	dev_set_drvdata(&dev->dev, data);
Linus Torvalds's avatar
Linus Torvalds committed
706 707
}

708 709
static inline struct i2c_adapter *
i2c_parent_is_i2c_adapter(const struct i2c_adapter *adapter)
710
{
711
#if IS_ENABLED(CONFIG_I2C_MUX)
712 713 714 715 716
	struct device *parent = adapter->dev.parent;

	if (parent != NULL && parent->type == &i2c_adapter_type)
		return to_i2c_adapter(parent);
	else
717
#endif
718
		return NULL;
719 720
}

721 722
int i2c_for_each_dev(void *data, int (*fn)(struct device *, void *));

723
/* Adapter locking functions, exported for shared pin cases */
724 725 726 727 728 729 730 731 732 733 734 735
#define I2C_LOCK_ROOT_ADAPTER BIT(0)
#define I2C_LOCK_SEGMENT      BIT(1)

/**
 * i2c_lock_bus - Get exclusive access to an I2C bus segment
 * @adapter: Target I2C bus segment
 * @flags: I2C_LOCK_ROOT_ADAPTER locks the root i2c adapter, I2C_LOCK_SEGMENT
 *	locks only this branch in the adapter tree
 */
static inline void
i2c_lock_bus(struct i2c_adapter *adapter, unsigned int flags)
{
736
	adapter->lock_ops->lock_bus(adapter, flags);
737 738
}

739 740 741 742 743 744 745 746 747 748 749
/**
 * i2c_trylock_bus - Try to get exclusive access to an I2C bus segment
 * @adapter: Target I2C bus segment
 * @flags: I2C_LOCK_ROOT_ADAPTER tries to locks the root i2c adapter,
 *	I2C_LOCK_SEGMENT tries to lock only this branch in the adapter tree
 *
 * Return: true if the I2C bus segment is locked, false otherwise
 */
static inline int
i2c_trylock_bus(struct i2c_adapter *adapter, unsigned int flags)
{
750
	return adapter->lock_ops->trylock_bus(adapter, flags);
751 752
}

753 754 755 756 757 758 759 760 761
/**
 * i2c_unlock_bus - Release exclusive access to an I2C bus segment
 * @adapter: Target I2C bus segment
 * @flags: I2C_LOCK_ROOT_ADAPTER unlocks the root i2c adapter, I2C_LOCK_SEGMENT
 *	unlocks only this branch in the adapter tree
 */
static inline void
i2c_unlock_bus(struct i2c_adapter *adapter, unsigned int flags)
{
762
	adapter->lock_ops->unlock_bus(adapter, flags);
763 764
}

Linus Torvalds's avatar
Linus Torvalds committed
765
/*flags for the client struct: */
766 767
#define I2C_CLIENT_PEC		0x04	/* Use Packet Error Checking */
#define I2C_CLIENT_TEN		0x10	/* we have a ten bit chip address */
768
					/* Must equal I2C_M_TEN below */
769
#define I2C_CLIENT_SLAVE	0x20	/* we are the slave */
770
#define I2C_CLIENT_HOST_NOTIFY	0x40	/* We want to use I2C host notify */
771 772
#define I2C_CLIENT_WAKE		0x80	/* for board_info; true iff can wake */
#define I2C_CLIENT_SCCB		0x9000	/* Use Omnivision SCCB protocol */
Laurent Pinchart's avatar
Laurent Pinchart committed
773
					/* Must match I2C_M_STOP|IGNORE_NAK */
Linus Torvalds's avatar
Linus Torvalds committed
774 775 776

/* i2c adapter classes (bitmask) */
#define I2C_CLASS_HWMON		(1<<0)	/* lm_sensors, ... */
777
#define I2C_CLASS_DDC		(1<<3)	/* DDC bus on graphics adapters */
778
#define I2C_CLASS_SPD		(1<<7)	/* Memory modules */
779 780
/* Warn users that the adapter doesn't support classes anymore */
#define I2C_CLASS_DEPRECATED	(1<<8)
Linus Torvalds's avatar
Linus Torvalds committed
781 782 783 784

/* Internal numbers to terminate lists */
#define I2C_CLIENT_END		0xfffeU

785 786 787 788
/* Construct an I2C_CLIENT_END-terminated array of i2c addresses */
#define I2C_ADDRS(addr, addrs...) \
	((const unsigned short []){ addr, ## addrs, I2C_CLIENT_END })

Linus Torvalds's avatar
Linus Torvalds committed
789 790 791 792 793

/* ----- functions exported by i2c.o */

/* administration...
 */
794
#if IS_ENABLED(CONFIG_I2C)
Linus Torvalds's avatar
Linus Torvalds committed
795
extern int i2c_add_adapter(struct i2c_adapter *);
796
extern void i2c_del_adapter(struct i2c_adapter *);
797
extern int i2c_add_numbered_adapter(struct i2c_adapter *);
Linus Torvalds's avatar
Linus Torvalds committed
798

799
extern int i2c_register_driver(struct module *, struct i2c_driver *);
800
extern void i2c_del_driver(struct i2c_driver *);
Linus Torvalds's avatar
Linus Torvalds committed
801

802 803 804
/* use a define to avoid include chaining to get THIS_MODULE */
#define i2c_add_driver(driver) \
	i2c_register_driver(THIS_MODULE, driver)
805

806 807
extern struct i2c_client *i2c_use_client(struct i2c_client *client);
extern void i2c_release_client(struct i2c_client *client);
Linus Torvalds's avatar
Linus Torvalds committed
808 809 810 811 812 813

/* call the i2c_client->command() of all attached clients with
 * the given arguments */
extern void i2c_clients_command(struct i2c_adapter *adap,
				unsigned int cmd, void *arg);

814
extern struct i2c_adapter *i2c_get_adapter(int nr);
Linus Torvalds's avatar
Linus Torvalds committed
815
extern void i2c_put_adapter(struct i2c_adapter *adap);
816
extern unsigned int i2c_adapter_depth(struct i2c_adapter *adapter);
Linus Torvalds's avatar
Linus Torvalds committed
817

818
void i2c_parse_fw_timings(struct device *dev, struct i2c_timings *t, bool use_defaults);
Linus Torvalds's avatar
Linus Torvalds committed
819 820 821 822 823 824 825 826 827 828 829 830 831

/* Return the functionality mask */
static inline u32 i2c_get_functionality(struct i2c_adapter *adap)
{
	return adap->algo->functionality(adap);
}

/* Return 1 if adapter supports everything we need, 0 if not. */
static inline int i2c_check_functionality(struct i2c_adapter *adap, u32 func)
{
	return (func & i2c_get_functionality(adap)) == func;
}

832 833 834 835 836 837 838 839 840 841 842 843 844 845
/**
 * i2c_check_quirks() - Function for checking the quirk flags in an i2c adapter
 * @adap: i2c adapter
 * @quirks: quirk flags
 *
 * Return: true if the adapter has all the specified quirk flags, false if not
 */
static inline bool i2c_check_quirks(struct i2c_adapter *adap, u64 quirks)
{
	if (!adap->quirks)
		return false;
	return (adap->quirks->flags & quirks) == quirks;
}

846
/* Return the adapter number for a specific adapter */
847 848 849 850
static inline int i2c_adapter_id(struct i2c_adapter *adap)
{
	return adap->nr;
}
851

852 853 854 855 856
static inline u8 i2c_8bit_addr_from_msg(const struct i2c_msg *msg)
{
	return (msg->addr << 1) | (msg->flags & I2C_M_RD ? 1 : 0);
}

857
u8 *i2c_get_dma_safe_msg_buf(struct i2c_msg *msg, unsigned int threshold);
858
void i2c_put_dma_safe_msg_buf(u8 *buf, struct i2c_msg *msg, bool xferred);
859

860
int i2c_handle_smbus_host_notify(struct i2c_adapter *adap, unsigned short addr);
861
/**
862
 * module_i2c_driver() - Helper macro for registering a modular I2C driver
863 864 865 866 867 868 869 870 871 872
 * @__i2c_driver: i2c_driver struct
 *
 * Helper macro for I2C drivers which do not do anything special in module
 * init/exit. This eliminates a lot of boilerplate. Each module may only
 * use this macro once, and calling it replaces module_init() and module_exit()
 */
#define module_i2c_driver(__i2c_driver) \
	module_driver(__i2c_driver, i2c_add_driver, \
			i2c_del_driver)

873 874 875 876 877 878 879 880 881 882 883
/**
 * builtin_i2c_driver() - Helper macro for registering a builtin I2C driver
 * @__i2c_driver: i2c_driver struct
 *
 * Helper macro for I2C drivers which do not do anything special in their
 * init. This eliminates a lot of boilerplate. Each driver may only
 * use this macro once, and calling it replaces device_initcall().
 */
#define builtin_i2c_driver(__i2c_driver) \
	builtin_driver(__i2c_driver, i2c_add_driver)

884
#endif /* I2C */
885

886 887 888 889 890 891 892
#if IS_ENABLED(CONFIG_OF)
/* must call put_device() when done with returned i2c_client device */
extern struct i2c_client *of_find_i2c_device_by_node(struct device_node *node);

/* must call put_device() when done with returned i2c_adapter device */
extern struct i2c_adapter *of_find_i2c_adapter_by_node(struct device_node *node);

893 894
/* must call i2c_put_adapter() when done with returned i2c_adapter device */
struct i2c_adapter *of_get_i2c_adapter_by_node(struct device_node *node);
895

896 897 898 899
extern const struct of_device_id
*i2c_of_match_device(const struct of_device_id *matches,
		     struct i2c_client *client);

900 901 902
int of_i2c_get_board_info(struct device *dev, struct device_node *node,
			  struct i2c_board_info *info);

903 904 905 906 907 908 909 910 911 912 913
#else

static inline struct i2c_client *of_find_i2c_device_by_node(struct device_node *node)
{
	return NULL;
}

static inline struct i2c_adapter *of_find_i2c_adapter_by_node(struct device_node *node)
{
	return NULL;
}
914 915 916 917 918

static inline struct i2c_adapter *of_get_i2c_adapter_by_node(struct device_node *node)
{
	return NULL;
}
919 920 921 922 923 924 925 926

static inline const struct of_device_id
*i2c_of_match_device(const struct of_device_id *matches,
		     struct i2c_client *client)
{
	return NULL;
}

927 928 929 930 931 932 933
static inline int of_i2c_get_board_info(struct device *dev,
					struct device_node *node,
					struct i2c_board_info *info)
{
	return -ENOTSUPP;
}

934 935
#endif /* CONFIG_OF */

936 937
#if IS_ENABLED(CONFIG_ACPI)
u32 i2c_acpi_find_bus_speed(struct device *dev);
938 939
struct i2c_client *i2c_acpi_new_device(struct device *dev, int index,
				       struct i2c_board_info *info);
940 941 942 943 944
#else
static inline u32 i2c_acpi_find_bus_speed(struct device *dev)
{
	return 0;
}
945 946 947 948 949
static inline struct i2c_client *i2c_acpi_new_device(struct device *dev,
					int index, struct i2c_board_info *info)
{
	return NULL;
}
950 951
#endif /* CONFIG_ACPI */

Linus Torvalds's avatar
Linus Torvalds committed
952
#endif /* _LINUX_I2C_H */