1 /* SPDX-License-Identifier: GPL-2.0-or-later */ 2 /* 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> 6 * 7 * With some changes from Kyösti Mälkki <kmalkki@cc.hut.fi> and 8 * Frodo Looijaard <frodol@dds.nl> 9 */ 10 #ifndef _LINUX_I2C_H 11 #define _LINUX_I2C_H 12 13 #include <linux/acpi.h> /* for acpi_handle */ 14 #include <linux/bits.h> 15 #include <linux/mod_devicetable.h> 16 #include <linux/device.h> /* for struct device */ 17 #include <linux/sched.h> /* for completion */ 18 #include <linux/mutex.h> 19 #include <linux/regulator/consumer.h> 20 #include <linux/rtmutex.h> 21 #include <linux/irqdomain.h> /* for Host Notify IRQ */ 22 #include <linux/of.h> /* for struct device_node */ 23 #include <linux/swab.h> /* for swab16 */ 24 #include <uapi/linux/i2c.h> 25 26 extern struct bus_type i2c_bus_type; 27 extern struct device_type i2c_adapter_type; 28 extern struct device_type i2c_client_type; 29 30 /* --- General options ------------------------------------------------ */ 31 32 struct i2c_msg; 33 struct i2c_algorithm; 34 struct i2c_adapter; 35 struct i2c_client; 36 struct i2c_driver; 37 struct i2c_device_identity; 38 union i2c_smbus_data; 39 struct i2c_board_info; 40 enum i2c_slave_event; 41 typedef int (*i2c_slave_cb_t)(struct i2c_client *client, 42 enum i2c_slave_event event, u8 *val); 43 44 /* I2C Frequency Modes */ 45 #define I2C_MAX_STANDARD_MODE_FREQ 100000 46 #define I2C_MAX_FAST_MODE_FREQ 400000 47 #define I2C_MAX_FAST_MODE_PLUS_FREQ 1000000 48 #define I2C_MAX_TURBO_MODE_FREQ 1400000 49 #define I2C_MAX_HIGH_SPEED_MODE_FREQ 3400000 50 #define I2C_MAX_ULTRA_FAST_MODE_FREQ 5000000 51 52 struct module; 53 struct property_entry; 54 55 #if IS_ENABLED(CONFIG_I2C) 56 /* Return the Frequency mode string based on the bus frequency */ 57 const char *i2c_freq_mode_string(u32 bus_freq_hz); 58 59 /* 60 * The master routines are the ones normally used to transmit data to devices 61 * on a bus (or read from them). Apart from two basic transfer functions to 62 * transmit one message at a time, a more complex version can be used to 63 * transmit an arbitrary number of messages without interruption. 64 * @count must be less than 64k since msg.len is u16. 65 */ 66 int i2c_transfer_buffer_flags(const struct i2c_client *client, 67 char *buf, int count, u16 flags); 68 69 /** 70 * i2c_master_recv - issue a single I2C message in master receive mode 71 * @client: Handle to slave device 72 * @buf: Where to store data read from slave 73 * @count: How many bytes to read, must be less than 64k since msg.len is u16 74 * 75 * Returns negative errno, or else the number of bytes read. 76 */ 77 static inline int i2c_master_recv(const struct i2c_client *client, 78 char *buf, int count) 79 { 80 return i2c_transfer_buffer_flags(client, buf, count, I2C_M_RD); 81 }; 82 83 /** 84 * i2c_master_recv_dmasafe - issue a single I2C message in master receive mode 85 * using a DMA safe buffer 86 * @client: Handle to slave device 87 * @buf: Where to store data read from slave, must be safe to use with DMA 88 * @count: How many bytes to read, must be less than 64k since msg.len is u16 89 * 90 * Returns negative errno, or else the number of bytes read. 91 */ 92 static inline int i2c_master_recv_dmasafe(const struct i2c_client *client, 93 char *buf, int count) 94 { 95 return i2c_transfer_buffer_flags(client, buf, count, 96 I2C_M_RD | I2C_M_DMA_SAFE); 97 }; 98 99 /** 100 * i2c_master_send - issue a single I2C message in master transmit mode 101 * @client: Handle to slave device 102 * @buf: Data that will be written to the slave 103 * @count: How many bytes to write, must be less than 64k since msg.len is u16 104 * 105 * Returns negative errno, or else the number of bytes written. 106 */ 107 static inline int i2c_master_send(const struct i2c_client *client, 108 const char *buf, int count) 109 { 110 return i2c_transfer_buffer_flags(client, (char *)buf, count, 0); 111 }; 112 113 /** 114 * i2c_master_send_dmasafe - issue a single I2C message in master transmit mode 115 * using a DMA safe buffer 116 * @client: Handle to slave device 117 * @buf: Data that will be written to the slave, must be safe to use with DMA 118 * @count: How many bytes to write, must be less than 64k since msg.len is u16 119 * 120 * Returns negative errno, or else the number of bytes written. 121 */ 122 static inline int i2c_master_send_dmasafe(const struct i2c_client *client, 123 const char *buf, int count) 124 { 125 return i2c_transfer_buffer_flags(client, (char *)buf, count, 126 I2C_M_DMA_SAFE); 127 }; 128 129 /* Transfer num messages. 130 */ 131 int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msgs, int num); 132 /* Unlocked flavor */ 133 int __i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msgs, int num); 134 135 /* This is the very generalized SMBus access routine. You probably do not 136 want to use this, though; one of the functions below may be much easier, 137 and probably just as fast. 138 Note that we use i2c_adapter here, because you do not need a specific 139 smbus adapter to call this function. */ 140 s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr, 141 unsigned short flags, char read_write, u8 command, 142 int protocol, union i2c_smbus_data *data); 143 144 /* Unlocked flavor */ 145 s32 __i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr, 146 unsigned short flags, char read_write, u8 command, 147 int protocol, union i2c_smbus_data *data); 148 149 /* Now follow the 'nice' access routines. These also document the calling 150 conventions of i2c_smbus_xfer. */ 151 152 u8 i2c_smbus_pec(u8 crc, u8 *p, size_t count); 153 s32 i2c_smbus_read_byte(const struct i2c_client *client); 154 s32 i2c_smbus_write_byte(const struct i2c_client *client, u8 value); 155 s32 i2c_smbus_read_byte_data(const struct i2c_client *client, u8 command); 156 s32 i2c_smbus_write_byte_data(const struct i2c_client *client, 157 u8 command, u8 value); 158 s32 i2c_smbus_read_word_data(const struct i2c_client *client, u8 command); 159 s32 i2c_smbus_write_word_data(const struct i2c_client *client, 160 u8 command, u16 value); 161 162 static inline s32 163 i2c_smbus_read_word_swapped(const struct i2c_client *client, u8 command) 164 { 165 s32 value = i2c_smbus_read_word_data(client, command); 166 167 return (value < 0) ? value : swab16(value); 168 } 169 170 static inline s32 171 i2c_smbus_write_word_swapped(const struct i2c_client *client, 172 u8 command, u16 value) 173 { 174 return i2c_smbus_write_word_data(client, command, swab16(value)); 175 } 176 177 /* Returns the number of read bytes */ 178 s32 i2c_smbus_read_block_data(const struct i2c_client *client, 179 u8 command, u8 *values); 180 s32 i2c_smbus_write_block_data(const struct i2c_client *client, 181 u8 command, u8 length, const u8 *values); 182 /* Returns the number of read bytes */ 183 s32 i2c_smbus_read_i2c_block_data(const struct i2c_client *client, 184 u8 command, u8 length, u8 *values); 185 s32 i2c_smbus_write_i2c_block_data(const struct i2c_client *client, 186 u8 command, u8 length, const u8 *values); 187 s32 i2c_smbus_read_i2c_block_data_or_emulated(const struct i2c_client *client, 188 u8 command, u8 length, 189 u8 *values); 190 int i2c_get_device_id(const struct i2c_client *client, 191 struct i2c_device_identity *id); 192 const struct i2c_device_id *i2c_client_get_device_id(const struct i2c_client *client); 193 #endif /* I2C */ 194 195 /** 196 * struct i2c_device_identity - i2c client device identification 197 * @manufacturer_id: 0 - 4095, database maintained by NXP 198 * @part_id: 0 - 511, according to manufacturer 199 * @die_revision: 0 - 7, according to manufacturer 200 */ 201 struct i2c_device_identity { 202 u16 manufacturer_id; 203 #define I2C_DEVICE_ID_NXP_SEMICONDUCTORS 0 204 #define I2C_DEVICE_ID_NXP_SEMICONDUCTORS_1 1 205 #define I2C_DEVICE_ID_NXP_SEMICONDUCTORS_2 2 206 #define I2C_DEVICE_ID_NXP_SEMICONDUCTORS_3 3 207 #define I2C_DEVICE_ID_RAMTRON_INTERNATIONAL 4 208 #define I2C_DEVICE_ID_ANALOG_DEVICES 5 209 #define I2C_DEVICE_ID_STMICROELECTRONICS 6 210 #define I2C_DEVICE_ID_ON_SEMICONDUCTOR 7 211 #define I2C_DEVICE_ID_SPRINTEK_CORPORATION 8 212 #define I2C_DEVICE_ID_ESPROS_PHOTONICS_AG 9 213 #define I2C_DEVICE_ID_FUJITSU_SEMICONDUCTOR 10 214 #define I2C_DEVICE_ID_FLIR 11 215 #define I2C_DEVICE_ID_O2MICRO 12 216 #define I2C_DEVICE_ID_ATMEL 13 217 #define I2C_DEVICE_ID_NONE 0xffff 218 u16 part_id; 219 u8 die_revision; 220 }; 221 222 enum i2c_alert_protocol { 223 I2C_PROTOCOL_SMBUS_ALERT, 224 I2C_PROTOCOL_SMBUS_HOST_NOTIFY, 225 }; 226 227 /** 228 * enum i2c_driver_flags - Flags for an I2C device driver 229 * 230 * @I2C_DRV_ACPI_WAIVE_D0_PROBE: Don't put the device in D0 state for probe 231 */ 232 enum i2c_driver_flags { 233 I2C_DRV_ACPI_WAIVE_D0_PROBE = BIT(0), 234 }; 235 236 /** 237 * struct i2c_driver - represent an I2C device driver 238 * @class: What kind of i2c device we instantiate (for detect) 239 * @probe: Callback for device binding 240 * @probe_new: Transitional callback for device binding - do not use 241 * @remove: Callback for device unbinding 242 * @shutdown: Callback for device shutdown 243 * @alert: Alert callback, for example for the SMBus alert protocol 244 * @command: Callback for bus-wide signaling (optional) 245 * @driver: Device driver model driver 246 * @id_table: List of I2C devices supported by this driver 247 * @detect: Callback for device detection 248 * @address_list: The I2C addresses to probe (for detect) 249 * @clients: List of detected clients we created (for i2c-core use only) 250 * @flags: A bitmask of flags defined in &enum i2c_driver_flags 251 * 252 * The driver.owner field should be set to the module owner of this driver. 253 * The driver.name field should be set to the name of this driver. 254 * 255 * For automatic device detection, both @detect and @address_list must 256 * be defined. @class should also be set, otherwise only devices forced 257 * with module parameters will be created. The detect function must 258 * fill at least the name field of the i2c_board_info structure it is 259 * handed upon successful detection, and possibly also the flags field. 260 * 261 * If @detect is missing, the driver will still work fine for enumerated 262 * devices. Detected devices simply won't be supported. This is expected 263 * for the many I2C/SMBus devices which can't be detected reliably, and 264 * the ones which can always be enumerated in practice. 265 * 266 * The i2c_client structure which is handed to the @detect callback is 267 * not a real i2c_client. It is initialized just enough so that you can 268 * call i2c_smbus_read_byte_data and friends on it. Don't do anything 269 * else with it. In particular, calling dev_dbg and friends on it is 270 * not allowed. 271 */ 272 struct i2c_driver { 273 unsigned int class; 274 275 union { 276 /* Standard driver model interfaces */ 277 int (*probe)(struct i2c_client *client); 278 /* 279 * Legacy callback that was part of a conversion of .probe(). 280 * Today it has the same semantic as .probe(). Don't use for new 281 * code. 282 */ 283 int (*probe_new)(struct i2c_client *client); 284 }; 285 void (*remove)(struct i2c_client *client); 286 287 288 /* driver model interfaces that don't relate to enumeration */ 289 void (*shutdown)(struct i2c_client *client); 290 291 /* Alert callback, for example for the SMBus alert protocol. 292 * The format and meaning of the data value depends on the protocol. 293 * For the SMBus alert protocol, there is a single bit of data passed 294 * as the alert response's low bit ("event flag"). 295 * For the SMBus Host Notify protocol, the data corresponds to the 296 * 16-bit payload data reported by the slave device acting as master. 297 */ 298 void (*alert)(struct i2c_client *client, enum i2c_alert_protocol protocol, 299 unsigned int data); 300 301 /* a ioctl like command that can be used to perform specific functions 302 * with the device. 303 */ 304 int (*command)(struct i2c_client *client, unsigned int cmd, void *arg); 305 306 struct device_driver driver; 307 const struct i2c_device_id *id_table; 308 309 /* Device detection callback for automatic device creation */ 310 int (*detect)(struct i2c_client *client, struct i2c_board_info *info); 311 const unsigned short *address_list; 312 struct list_head clients; 313 314 u32 flags; 315 }; 316 #define to_i2c_driver(d) container_of(d, struct i2c_driver, driver) 317 318 /** 319 * struct i2c_client - represent an I2C slave device 320 * @flags: see I2C_CLIENT_* for possible flags 321 * @addr: Address used on the I2C bus connected to the parent adapter. 322 * @name: Indicates the type of the device, usually a chip name that's 323 * generic enough to hide second-sourcing and compatible revisions. 324 * @adapter: manages the bus segment hosting this I2C device 325 * @dev: Driver model device node for the slave. 326 * @init_irq: IRQ that was set at initialization 327 * @irq: indicates the IRQ generated by this device (if any) 328 * @detected: member of an i2c_driver.clients list or i2c-core's 329 * userspace_devices list 330 * @slave_cb: Callback when I2C slave mode of an adapter is used. The adapter 331 * calls it to pass on slave events to the slave driver. 332 * @devres_group_id: id of the devres group that will be created for resources 333 * acquired when probing this device. 334 * 335 * An i2c_client identifies a single device (i.e. chip) connected to an 336 * i2c bus. The behaviour exposed to Linux is defined by the driver 337 * managing the device. 338 */ 339 struct i2c_client { 340 unsigned short flags; /* div., see below */ 341 #define I2C_CLIENT_PEC 0x04 /* Use Packet Error Checking */ 342 #define I2C_CLIENT_TEN 0x10 /* we have a ten bit chip address */ 343 /* Must equal I2C_M_TEN below */ 344 #define I2C_CLIENT_SLAVE 0x20 /* we are the slave */ 345 #define I2C_CLIENT_HOST_NOTIFY 0x40 /* We want to use I2C host notify */ 346 #define I2C_CLIENT_WAKE 0x80 /* for board_info; true iff can wake */ 347 #define I2C_CLIENT_SCCB 0x9000 /* Use Omnivision SCCB protocol */ 348 /* Must match I2C_M_STOP|IGNORE_NAK */ 349 350 unsigned short addr; /* chip address - NOTE: 7bit */ 351 /* addresses are stored in the */ 352 /* _LOWER_ 7 bits */ 353 char name[I2C_NAME_SIZE]; 354 struct i2c_adapter *adapter; /* the adapter we sit on */ 355 struct device dev; /* the device structure */ 356 int init_irq; /* irq set at initialization */ 357 int irq; /* irq issued by device */ 358 struct list_head detected; 359 #if IS_ENABLED(CONFIG_I2C_SLAVE) 360 i2c_slave_cb_t slave_cb; /* callback for slave mode */ 361 #endif 362 void *devres_group_id; /* ID of probe devres group */ 363 }; 364 #define to_i2c_client(d) container_of(d, struct i2c_client, dev) 365 366 struct i2c_adapter *i2c_verify_adapter(struct device *dev); 367 const struct i2c_device_id *i2c_match_id(const struct i2c_device_id *id, 368 const struct i2c_client *client); 369 370 static inline struct i2c_client *kobj_to_i2c_client(struct kobject *kobj) 371 { 372 struct device * const dev = kobj_to_dev(kobj); 373 return to_i2c_client(dev); 374 } 375 376 static inline void *i2c_get_clientdata(const struct i2c_client *client) 377 { 378 return dev_get_drvdata(&client->dev); 379 } 380 381 static inline void i2c_set_clientdata(struct i2c_client *client, void *data) 382 { 383 dev_set_drvdata(&client->dev, data); 384 } 385 386 /* I2C slave support */ 387 388 enum i2c_slave_event { 389 I2C_SLAVE_READ_REQUESTED, 390 I2C_SLAVE_WRITE_REQUESTED, 391 I2C_SLAVE_READ_PROCESSED, 392 I2C_SLAVE_WRITE_RECEIVED, 393 I2C_SLAVE_STOP, 394 }; 395 396 int i2c_slave_register(struct i2c_client *client, i2c_slave_cb_t slave_cb); 397 int i2c_slave_unregister(struct i2c_client *client); 398 int i2c_slave_event(struct i2c_client *client, 399 enum i2c_slave_event event, u8 *val); 400 #if IS_ENABLED(CONFIG_I2C_SLAVE) 401 bool i2c_detect_slave_mode(struct device *dev); 402 #else 403 static inline bool i2c_detect_slave_mode(struct device *dev) { return false; } 404 #endif 405 406 /** 407 * struct i2c_board_info - template for device creation 408 * @type: chip type, to initialize i2c_client.name 409 * @flags: to initialize i2c_client.flags 410 * @addr: stored in i2c_client.addr 411 * @dev_name: Overrides the default <busnr>-<addr> dev_name if set 412 * @platform_data: stored in i2c_client.dev.platform_data 413 * @of_node: pointer to OpenFirmware device node 414 * @fwnode: device node supplied by the platform firmware 415 * @swnode: software node for the device 416 * @resources: resources associated with the device 417 * @num_resources: number of resources in the @resources array 418 * @irq: stored in i2c_client.irq 419 * 420 * I2C doesn't actually support hardware probing, although controllers and 421 * devices may be able to use I2C_SMBUS_QUICK to tell whether or not there's 422 * a device at a given address. Drivers commonly need more information than 423 * that, such as chip type, configuration, associated IRQ, and so on. 424 * 425 * i2c_board_info is used to build tables of information listing I2C devices 426 * that are present. This information is used to grow the driver model tree. 427 * For mainboards this is done statically using i2c_register_board_info(); 428 * bus numbers identify adapters that aren't yet available. For add-on boards, 429 * i2c_new_client_device() does this dynamically with the adapter already known. 430 */ 431 struct i2c_board_info { 432 char type[I2C_NAME_SIZE]; 433 unsigned short flags; 434 unsigned short addr; 435 const char *dev_name; 436 void *platform_data; 437 struct device_node *of_node; 438 struct fwnode_handle *fwnode; 439 const struct software_node *swnode; 440 const struct resource *resources; 441 unsigned int num_resources; 442 int irq; 443 }; 444 445 /** 446 * I2C_BOARD_INFO - macro used to list an i2c device and its address 447 * @dev_type: identifies the device type 448 * @dev_addr: the device's address on the bus. 449 * 450 * This macro initializes essential fields of a struct i2c_board_info, 451 * declaring what has been provided on a particular board. Optional 452 * fields (such as associated irq, or device-specific platform_data) 453 * are provided using conventional syntax. 454 */ 455 #define I2C_BOARD_INFO(dev_type, dev_addr) \ 456 .type = dev_type, .addr = (dev_addr) 457 458 459 #if IS_ENABLED(CONFIG_I2C) 460 /* 461 * Add-on boards should register/unregister their devices; e.g. a board 462 * with integrated I2C, a config eeprom, sensors, and a codec that's 463 * used in conjunction with the primary hardware. 464 */ 465 struct i2c_client * 466 i2c_new_client_device(struct i2c_adapter *adap, struct i2c_board_info const *info); 467 468 /* If you don't know the exact address of an I2C device, use this variant 469 * instead, which can probe for device presence in a list of possible 470 * addresses. The "probe" callback function is optional. If it is provided, 471 * it must return 1 on successful probe, 0 otherwise. If it is not provided, 472 * a default probing method is used. 473 */ 474 struct i2c_client * 475 i2c_new_scanned_device(struct i2c_adapter *adap, 476 struct i2c_board_info *info, 477 unsigned short const *addr_list, 478 int (*probe)(struct i2c_adapter *adap, unsigned short addr)); 479 480 /* Common custom probe functions */ 481 int i2c_probe_func_quick_read(struct i2c_adapter *adap, unsigned short addr); 482 483 struct i2c_client * 484 i2c_new_dummy_device(struct i2c_adapter *adapter, u16 address); 485 486 struct i2c_client * 487 devm_i2c_new_dummy_device(struct device *dev, struct i2c_adapter *adap, u16 address); 488 489 struct i2c_client * 490 i2c_new_ancillary_device(struct i2c_client *client, 491 const char *name, 492 u16 default_addr); 493 494 void i2c_unregister_device(struct i2c_client *client); 495 496 struct i2c_client *i2c_verify_client(struct device *dev); 497 #else 498 static inline struct i2c_client *i2c_verify_client(struct device *dev) 499 { 500 return NULL; 501 } 502 #endif /* I2C */ 503 504 /* Mainboard arch_initcall() code should register all its I2C devices. 505 * This is done at arch_initcall time, before declaring any i2c adapters. 506 * Modules for add-on boards must use other calls. 507 */ 508 #ifdef CONFIG_I2C_BOARDINFO 509 int 510 i2c_register_board_info(int busnum, struct i2c_board_info const *info, 511 unsigned n); 512 #else 513 static inline int 514 i2c_register_board_info(int busnum, struct i2c_board_info const *info, 515 unsigned n) 516 { 517 return 0; 518 } 519 #endif /* I2C_BOARDINFO */ 520 521 /** 522 * struct i2c_algorithm - represent I2C transfer method 523 * @master_xfer: Issue a set of i2c transactions to the given I2C adapter 524 * defined by the msgs array, with num messages available to transfer via 525 * the adapter specified by adap. 526 * @master_xfer_atomic: same as @master_xfer. Yet, only using atomic context 527 * so e.g. PMICs can be accessed very late before shutdown. Optional. 528 * @smbus_xfer: Issue smbus transactions to the given I2C adapter. If this 529 * is not present, then the bus layer will try and convert the SMBus calls 530 * into I2C transfers instead. 531 * @smbus_xfer_atomic: same as @smbus_xfer. Yet, only using atomic context 532 * so e.g. PMICs can be accessed very late before shutdown. Optional. 533 * @functionality: Return the flags that this algorithm/adapter pair supports 534 * from the ``I2C_FUNC_*`` flags. 535 * @reg_slave: Register given client to I2C slave mode of this adapter 536 * @unreg_slave: Unregister given client from I2C slave mode of this adapter 537 * 538 * The following structs are for those who like to implement new bus drivers: 539 * i2c_algorithm is the interface to a class of hardware solutions which can 540 * be addressed using the same bus algorithms - i.e. bit-banging or the PCF8584 541 * to name two of the most common. 542 * 543 * The return codes from the ``master_xfer{_atomic}`` fields should indicate the 544 * type of error code that occurred during the transfer, as documented in the 545 * Kernel Documentation file Documentation/i2c/fault-codes.rst. Otherwise, the 546 * number of messages executed should be returned. 547 */ 548 struct i2c_algorithm { 549 /* 550 * If an adapter algorithm can't do I2C-level access, set master_xfer 551 * to NULL. If an adapter algorithm can do SMBus access, set 552 * smbus_xfer. If set to NULL, the SMBus protocol is simulated 553 * using common I2C messages. 554 * 555 * master_xfer should return the number of messages successfully 556 * processed, or a negative value on error 557 */ 558 int (*master_xfer)(struct i2c_adapter *adap, struct i2c_msg *msgs, 559 int num); 560 int (*master_xfer_atomic)(struct i2c_adapter *adap, 561 struct i2c_msg *msgs, int num); 562 int (*smbus_xfer)(struct i2c_adapter *adap, u16 addr, 563 unsigned short flags, char read_write, 564 u8 command, int size, union i2c_smbus_data *data); 565 int (*smbus_xfer_atomic)(struct i2c_adapter *adap, u16 addr, 566 unsigned short flags, char read_write, 567 u8 command, int size, union i2c_smbus_data *data); 568 569 /* To determine what the adapter supports */ 570 u32 (*functionality)(struct i2c_adapter *adap); 571 572 #if IS_ENABLED(CONFIG_I2C_SLAVE) 573 int (*reg_slave)(struct i2c_client *client); 574 int (*unreg_slave)(struct i2c_client *client); 575 #endif 576 }; 577 578 /** 579 * struct i2c_lock_operations - represent I2C locking operations 580 * @lock_bus: Get exclusive access to an I2C bus segment 581 * @trylock_bus: Try to get exclusive access to an I2C bus segment 582 * @unlock_bus: Release exclusive access to an I2C bus segment 583 * 584 * The main operations are wrapped by i2c_lock_bus and i2c_unlock_bus. 585 */ 586 struct i2c_lock_operations { 587 void (*lock_bus)(struct i2c_adapter *adapter, unsigned int flags); 588 int (*trylock_bus)(struct i2c_adapter *adapter, unsigned int flags); 589 void (*unlock_bus)(struct i2c_adapter *adapter, unsigned int flags); 590 }; 591 592 /** 593 * struct i2c_timings - I2C timing information 594 * @bus_freq_hz: the bus frequency in Hz 595 * @scl_rise_ns: time SCL signal takes to rise in ns; t(r) in the I2C specification 596 * @scl_fall_ns: time SCL signal takes to fall in ns; t(f) in the I2C specification 597 * @scl_int_delay_ns: time IP core additionally needs to setup SCL in ns 598 * @sda_fall_ns: time SDA signal takes to fall in ns; t(f) in the I2C specification 599 * @sda_hold_ns: time IP core additionally needs to hold SDA in ns 600 * @digital_filter_width_ns: width in ns of spikes on i2c lines that the IP core 601 * digital filter can filter out 602 * @analog_filter_cutoff_freq_hz: threshold frequency for the low pass IP core 603 * analog filter 604 */ 605 struct i2c_timings { 606 u32 bus_freq_hz; 607 u32 scl_rise_ns; 608 u32 scl_fall_ns; 609 u32 scl_int_delay_ns; 610 u32 sda_fall_ns; 611 u32 sda_hold_ns; 612 u32 digital_filter_width_ns; 613 u32 analog_filter_cutoff_freq_hz; 614 }; 615 616 /** 617 * struct i2c_bus_recovery_info - I2C bus recovery information 618 * @recover_bus: Recover routine. Either pass driver's recover_bus() routine, or 619 * i2c_generic_scl_recovery(). 620 * @get_scl: This gets current value of SCL line. Mandatory for generic SCL 621 * recovery. Populated internally for generic GPIO recovery. 622 * @set_scl: This sets/clears the SCL line. Mandatory for generic SCL recovery. 623 * Populated internally for generic GPIO recovery. 624 * @get_sda: This gets current value of SDA line. This or set_sda() is mandatory 625 * for generic SCL recovery. Populated internally, if sda_gpio is a valid 626 * GPIO, for generic GPIO recovery. 627 * @set_sda: This sets/clears the SDA line. This or get_sda() is mandatory for 628 * generic SCL recovery. Populated internally, if sda_gpio is a valid GPIO, 629 * for generic GPIO recovery. 630 * @get_bus_free: Returns the bus free state as seen from the IP core in case it 631 * has a more complex internal logic than just reading SDA. Optional. 632 * @prepare_recovery: This will be called before starting recovery. Platform may 633 * configure padmux here for SDA/SCL line or something else they want. 634 * @unprepare_recovery: This will be called after completing recovery. Platform 635 * may configure padmux here for SDA/SCL line or something else they want. 636 * @scl_gpiod: gpiod of the SCL line. Only required for GPIO recovery. 637 * @sda_gpiod: gpiod of the SDA line. Only required for GPIO recovery. 638 * @pinctrl: pinctrl used by GPIO recovery to change the state of the I2C pins. 639 * Optional. 640 * @pins_default: default pinctrl state of SCL/SDA lines, when they are assigned 641 * to the I2C bus. Optional. Populated internally for GPIO recovery, if 642 * state with the name PINCTRL_STATE_DEFAULT is found and pinctrl is valid. 643 * @pins_gpio: recovery pinctrl state of SCL/SDA lines, when they are used as 644 * GPIOs. Optional. Populated internally for GPIO recovery, if this state 645 * is called "gpio" or "recovery" and pinctrl is valid. 646 */ 647 struct i2c_bus_recovery_info { 648 int (*recover_bus)(struct i2c_adapter *adap); 649 650 int (*get_scl)(struct i2c_adapter *adap); 651 void (*set_scl)(struct i2c_adapter *adap, int val); 652 int (*get_sda)(struct i2c_adapter *adap); 653 void (*set_sda)(struct i2c_adapter *adap, int val); 654 int (*get_bus_free)(struct i2c_adapter *adap); 655 656 void (*prepare_recovery)(struct i2c_adapter *adap); 657 void (*unprepare_recovery)(struct i2c_adapter *adap); 658 659 /* gpio recovery */ 660 struct gpio_desc *scl_gpiod; 661 struct gpio_desc *sda_gpiod; 662 struct pinctrl *pinctrl; 663 struct pinctrl_state *pins_default; 664 struct pinctrl_state *pins_gpio; 665 }; 666 667 int i2c_recover_bus(struct i2c_adapter *adap); 668 669 /* Generic recovery routines */ 670 int i2c_generic_scl_recovery(struct i2c_adapter *adap); 671 672 /** 673 * struct i2c_adapter_quirks - describe flaws of an i2c adapter 674 * @flags: see I2C_AQ_* for possible flags and read below 675 * @max_num_msgs: maximum number of messages per transfer 676 * @max_write_len: maximum length of a write message 677 * @max_read_len: maximum length of a read message 678 * @max_comb_1st_msg_len: maximum length of the first msg in a combined message 679 * @max_comb_2nd_msg_len: maximum length of the second msg in a combined message 680 * 681 * Note about combined messages: Some I2C controllers can only send one message 682 * per transfer, plus something called combined message or write-then-read. 683 * This is (usually) a small write message followed by a read message and 684 * barely enough to access register based devices like EEPROMs. There is a flag 685 * to support this mode. It implies max_num_msg = 2 and does the length checks 686 * with max_comb_*_len because combined message mode usually has its own 687 * limitations. Because of HW implementations, some controllers can actually do 688 * write-then-anything or other variants. To support that, write-then-read has 689 * been broken out into smaller bits like write-first and read-second which can 690 * be combined as needed. 691 */ 692 693 struct i2c_adapter_quirks { 694 u64 flags; 695 int max_num_msgs; 696 u16 max_write_len; 697 u16 max_read_len; 698 u16 max_comb_1st_msg_len; 699 u16 max_comb_2nd_msg_len; 700 }; 701 702 /* enforce max_num_msgs = 2 and use max_comb_*_len for length checks */ 703 #define I2C_AQ_COMB BIT(0) 704 /* first combined message must be write */ 705 #define I2C_AQ_COMB_WRITE_FIRST BIT(1) 706 /* second combined message must be read */ 707 #define I2C_AQ_COMB_READ_SECOND BIT(2) 708 /* both combined messages must have the same target address */ 709 #define I2C_AQ_COMB_SAME_ADDR BIT(3) 710 /* convenience macro for typical write-then read case */ 711 #define I2C_AQ_COMB_WRITE_THEN_READ (I2C_AQ_COMB | I2C_AQ_COMB_WRITE_FIRST | \ 712 I2C_AQ_COMB_READ_SECOND | I2C_AQ_COMB_SAME_ADDR) 713 /* clock stretching is not supported */ 714 #define I2C_AQ_NO_CLK_STRETCH BIT(4) 715 /* message cannot have length of 0 */ 716 #define I2C_AQ_NO_ZERO_LEN_READ BIT(5) 717 #define I2C_AQ_NO_ZERO_LEN_WRITE BIT(6) 718 #define I2C_AQ_NO_ZERO_LEN (I2C_AQ_NO_ZERO_LEN_READ | I2C_AQ_NO_ZERO_LEN_WRITE) 719 /* adapter cannot do repeated START */ 720 #define I2C_AQ_NO_REP_START BIT(7) 721 722 /* 723 * i2c_adapter is the structure used to identify a physical i2c bus along 724 * with the access algorithms necessary to access it. 725 */ 726 struct i2c_adapter { 727 struct module *owner; 728 unsigned int class; /* classes to allow probing for */ 729 const struct i2c_algorithm *algo; /* the algorithm to access the bus */ 730 void *algo_data; 731 732 /* data fields that are valid for all devices */ 733 const struct i2c_lock_operations *lock_ops; 734 struct rt_mutex bus_lock; 735 struct rt_mutex mux_lock; 736 737 int timeout; /* in jiffies */ 738 int retries; 739 struct device dev; /* the adapter device */ 740 unsigned long locked_flags; /* owned by the I2C core */ 741 #define I2C_ALF_IS_SUSPENDED 0 742 #define I2C_ALF_SUSPEND_REPORTED 1 743 744 int nr; 745 char name[48]; 746 struct completion dev_released; 747 748 struct mutex userspace_clients_lock; 749 struct list_head userspace_clients; 750 751 struct i2c_bus_recovery_info *bus_recovery_info; 752 const struct i2c_adapter_quirks *quirks; 753 754 struct irq_domain *host_notify_domain; 755 struct regulator *bus_regulator; 756 }; 757 #define to_i2c_adapter(d) container_of(d, struct i2c_adapter, dev) 758 759 static inline void *i2c_get_adapdata(const struct i2c_adapter *adap) 760 { 761 return dev_get_drvdata(&adap->dev); 762 } 763 764 static inline void i2c_set_adapdata(struct i2c_adapter *adap, void *data) 765 { 766 dev_set_drvdata(&adap->dev, data); 767 } 768 769 static inline struct i2c_adapter * 770 i2c_parent_is_i2c_adapter(const struct i2c_adapter *adapter) 771 { 772 #if IS_ENABLED(CONFIG_I2C_MUX) 773 struct device *parent = adapter->dev.parent; 774 775 if (parent != NULL && parent->type == &i2c_adapter_type) 776 return to_i2c_adapter(parent); 777 else 778 #endif 779 return NULL; 780 } 781 782 int i2c_for_each_dev(void *data, int (*fn)(struct device *dev, void *data)); 783 784 /* Adapter locking functions, exported for shared pin cases */ 785 #define I2C_LOCK_ROOT_ADAPTER BIT(0) 786 #define I2C_LOCK_SEGMENT BIT(1) 787 788 /** 789 * i2c_lock_bus - Get exclusive access to an I2C bus segment 790 * @adapter: Target I2C bus segment 791 * @flags: I2C_LOCK_ROOT_ADAPTER locks the root i2c adapter, I2C_LOCK_SEGMENT 792 * locks only this branch in the adapter tree 793 */ 794 static inline void 795 i2c_lock_bus(struct i2c_adapter *adapter, unsigned int flags) 796 { 797 adapter->lock_ops->lock_bus(adapter, flags); 798 } 799 800 /** 801 * i2c_trylock_bus - Try to get exclusive access to an I2C bus segment 802 * @adapter: Target I2C bus segment 803 * @flags: I2C_LOCK_ROOT_ADAPTER tries to locks the root i2c adapter, 804 * I2C_LOCK_SEGMENT tries to lock only this branch in the adapter tree 805 * 806 * Return: true if the I2C bus segment is locked, false otherwise 807 */ 808 static inline int 809 i2c_trylock_bus(struct i2c_adapter *adapter, unsigned int flags) 810 { 811 return adapter->lock_ops->trylock_bus(adapter, flags); 812 } 813 814 /** 815 * i2c_unlock_bus - Release exclusive access to an I2C bus segment 816 * @adapter: Target I2C bus segment 817 * @flags: I2C_LOCK_ROOT_ADAPTER unlocks the root i2c adapter, I2C_LOCK_SEGMENT 818 * unlocks only this branch in the adapter tree 819 */ 820 static inline void 821 i2c_unlock_bus(struct i2c_adapter *adapter, unsigned int flags) 822 { 823 adapter->lock_ops->unlock_bus(adapter, flags); 824 } 825 826 /** 827 * i2c_mark_adapter_suspended - Report suspended state of the adapter to the core 828 * @adap: Adapter to mark as suspended 829 * 830 * When using this helper to mark an adapter as suspended, the core will reject 831 * further transfers to this adapter. The usage of this helper is optional but 832 * recommended for devices having distinct handlers for system suspend and 833 * runtime suspend. More complex devices are free to implement custom solutions 834 * to reject transfers when suspended. 835 */ 836 static inline void i2c_mark_adapter_suspended(struct i2c_adapter *adap) 837 { 838 i2c_lock_bus(adap, I2C_LOCK_ROOT_ADAPTER); 839 set_bit(I2C_ALF_IS_SUSPENDED, &adap->locked_flags); 840 i2c_unlock_bus(adap, I2C_LOCK_ROOT_ADAPTER); 841 } 842 843 /** 844 * i2c_mark_adapter_resumed - Report resumed state of the adapter to the core 845 * @adap: Adapter to mark as resumed 846 * 847 * When using this helper to mark an adapter as resumed, the core will allow 848 * further transfers to this adapter. See also further notes to 849 * @i2c_mark_adapter_suspended(). 850 */ 851 static inline void i2c_mark_adapter_resumed(struct i2c_adapter *adap) 852 { 853 i2c_lock_bus(adap, I2C_LOCK_ROOT_ADAPTER); 854 clear_bit(I2C_ALF_IS_SUSPENDED, &adap->locked_flags); 855 i2c_unlock_bus(adap, I2C_LOCK_ROOT_ADAPTER); 856 } 857 858 /* i2c adapter classes (bitmask) */ 859 #define I2C_CLASS_HWMON (1<<0) /* lm_sensors, ... */ 860 #define I2C_CLASS_DDC (1<<3) /* DDC bus on graphics adapters */ 861 #define I2C_CLASS_SPD (1<<7) /* Memory modules */ 862 /* Warn users that the adapter doesn't support classes anymore */ 863 #define I2C_CLASS_DEPRECATED (1<<8) 864 865 /* Internal numbers to terminate lists */ 866 #define I2C_CLIENT_END 0xfffeU 867 868 /* Construct an I2C_CLIENT_END-terminated array of i2c addresses */ 869 #define I2C_ADDRS(addr, addrs...) \ 870 ((const unsigned short []){ addr, ## addrs, I2C_CLIENT_END }) 871 872 873 /* ----- functions exported by i2c.o */ 874 875 /* administration... 876 */ 877 #if IS_ENABLED(CONFIG_I2C) 878 int i2c_add_adapter(struct i2c_adapter *adap); 879 int devm_i2c_add_adapter(struct device *dev, struct i2c_adapter *adapter); 880 void i2c_del_adapter(struct i2c_adapter *adap); 881 int i2c_add_numbered_adapter(struct i2c_adapter *adap); 882 883 int i2c_register_driver(struct module *owner, struct i2c_driver *driver); 884 void i2c_del_driver(struct i2c_driver *driver); 885 886 /* use a define to avoid include chaining to get THIS_MODULE */ 887 #define i2c_add_driver(driver) \ 888 i2c_register_driver(THIS_MODULE, driver) 889 890 static inline bool i2c_client_has_driver(struct i2c_client *client) 891 { 892 return !IS_ERR_OR_NULL(client) && client->dev.driver; 893 } 894 895 /* call the i2c_client->command() of all attached clients with 896 * the given arguments */ 897 void i2c_clients_command(struct i2c_adapter *adap, 898 unsigned int cmd, void *arg); 899 900 struct i2c_adapter *i2c_get_adapter(int nr); 901 void i2c_put_adapter(struct i2c_adapter *adap); 902 unsigned int i2c_adapter_depth(struct i2c_adapter *adapter); 903 904 void i2c_parse_fw_timings(struct device *dev, struct i2c_timings *t, bool use_defaults); 905 906 /* Return the functionality mask */ 907 static inline u32 i2c_get_functionality(struct i2c_adapter *adap) 908 { 909 return adap->algo->functionality(adap); 910 } 911 912 /* Return 1 if adapter supports everything we need, 0 if not. */ 913 static inline int i2c_check_functionality(struct i2c_adapter *adap, u32 func) 914 { 915 return (func & i2c_get_functionality(adap)) == func; 916 } 917 918 /** 919 * i2c_check_quirks() - Function for checking the quirk flags in an i2c adapter 920 * @adap: i2c adapter 921 * @quirks: quirk flags 922 * 923 * Return: true if the adapter has all the specified quirk flags, false if not 924 */ 925 static inline bool i2c_check_quirks(struct i2c_adapter *adap, u64 quirks) 926 { 927 if (!adap->quirks) 928 return false; 929 return (adap->quirks->flags & quirks) == quirks; 930 } 931 932 /* Return the adapter number for a specific adapter */ 933 static inline int i2c_adapter_id(struct i2c_adapter *adap) 934 { 935 return adap->nr; 936 } 937 938 static inline u8 i2c_8bit_addr_from_msg(const struct i2c_msg *msg) 939 { 940 return (msg->addr << 1) | (msg->flags & I2C_M_RD ? 1 : 0); 941 } 942 943 u8 *i2c_get_dma_safe_msg_buf(struct i2c_msg *msg, unsigned int threshold); 944 void i2c_put_dma_safe_msg_buf(u8 *buf, struct i2c_msg *msg, bool xferred); 945 946 int i2c_handle_smbus_host_notify(struct i2c_adapter *adap, unsigned short addr); 947 /** 948 * module_i2c_driver() - Helper macro for registering a modular I2C driver 949 * @__i2c_driver: i2c_driver struct 950 * 951 * Helper macro for I2C drivers which do not do anything special in module 952 * init/exit. This eliminates a lot of boilerplate. Each module may only 953 * use this macro once, and calling it replaces module_init() and module_exit() 954 */ 955 #define module_i2c_driver(__i2c_driver) \ 956 module_driver(__i2c_driver, i2c_add_driver, \ 957 i2c_del_driver) 958 959 /** 960 * builtin_i2c_driver() - Helper macro for registering a builtin I2C driver 961 * @__i2c_driver: i2c_driver struct 962 * 963 * Helper macro for I2C drivers which do not do anything special in their 964 * init. This eliminates a lot of boilerplate. Each driver may only 965 * use this macro once, and calling it replaces device_initcall(). 966 */ 967 #define builtin_i2c_driver(__i2c_driver) \ 968 builtin_driver(__i2c_driver, i2c_add_driver) 969 970 #endif /* I2C */ 971 972 /* must call put_device() when done with returned i2c_client device */ 973 struct i2c_client *i2c_find_device_by_fwnode(struct fwnode_handle *fwnode); 974 975 /* must call put_device() when done with returned i2c_adapter device */ 976 struct i2c_adapter *i2c_find_adapter_by_fwnode(struct fwnode_handle *fwnode); 977 978 /* must call i2c_put_adapter() when done with returned i2c_adapter device */ 979 struct i2c_adapter *i2c_get_adapter_by_fwnode(struct fwnode_handle *fwnode); 980 981 #if IS_ENABLED(CONFIG_OF) 982 /* must call put_device() when done with returned i2c_client device */ 983 static inline struct i2c_client *of_find_i2c_device_by_node(struct device_node *node) 984 { 985 return i2c_find_device_by_fwnode(of_fwnode_handle(node)); 986 } 987 988 /* must call put_device() when done with returned i2c_adapter device */ 989 static inline struct i2c_adapter *of_find_i2c_adapter_by_node(struct device_node *node) 990 { 991 return i2c_find_adapter_by_fwnode(of_fwnode_handle(node)); 992 } 993 994 /* must call i2c_put_adapter() when done with returned i2c_adapter device */ 995 static inline struct i2c_adapter *of_get_i2c_adapter_by_node(struct device_node *node) 996 { 997 return i2c_get_adapter_by_fwnode(of_fwnode_handle(node)); 998 } 999 1000 const struct of_device_id 1001 *i2c_of_match_device(const struct of_device_id *matches, 1002 struct i2c_client *client); 1003 1004 int of_i2c_get_board_info(struct device *dev, struct device_node *node, 1005 struct i2c_board_info *info); 1006 1007 #else 1008 1009 static inline struct i2c_client *of_find_i2c_device_by_node(struct device_node *node) 1010 { 1011 return NULL; 1012 } 1013 1014 static inline struct i2c_adapter *of_find_i2c_adapter_by_node(struct device_node *node) 1015 { 1016 return NULL; 1017 } 1018 1019 static inline struct i2c_adapter *of_get_i2c_adapter_by_node(struct device_node *node) 1020 { 1021 return NULL; 1022 } 1023 1024 static inline const struct of_device_id 1025 *i2c_of_match_device(const struct of_device_id *matches, 1026 struct i2c_client *client) 1027 { 1028 return NULL; 1029 } 1030 1031 static inline int of_i2c_get_board_info(struct device *dev, 1032 struct device_node *node, 1033 struct i2c_board_info *info) 1034 { 1035 return -ENOTSUPP; 1036 } 1037 1038 #endif /* CONFIG_OF */ 1039 1040 struct acpi_resource; 1041 struct acpi_resource_i2c_serialbus; 1042 1043 #if IS_ENABLED(CONFIG_ACPI) 1044 bool i2c_acpi_get_i2c_resource(struct acpi_resource *ares, 1045 struct acpi_resource_i2c_serialbus **i2c); 1046 int i2c_acpi_client_count(struct acpi_device *adev); 1047 u32 i2c_acpi_find_bus_speed(struct device *dev); 1048 struct i2c_client *i2c_acpi_new_device_by_fwnode(struct fwnode_handle *fwnode, 1049 int index, 1050 struct i2c_board_info *info); 1051 struct i2c_adapter *i2c_acpi_find_adapter_by_handle(acpi_handle handle); 1052 bool i2c_acpi_waive_d0_probe(struct device *dev); 1053 #else 1054 static inline bool i2c_acpi_get_i2c_resource(struct acpi_resource *ares, 1055 struct acpi_resource_i2c_serialbus **i2c) 1056 { 1057 return false; 1058 } 1059 static inline int i2c_acpi_client_count(struct acpi_device *adev) 1060 { 1061 return 0; 1062 } 1063 static inline u32 i2c_acpi_find_bus_speed(struct device *dev) 1064 { 1065 return 0; 1066 } 1067 static inline struct i2c_client *i2c_acpi_new_device_by_fwnode( 1068 struct fwnode_handle *fwnode, int index, 1069 struct i2c_board_info *info) 1070 { 1071 return ERR_PTR(-ENODEV); 1072 } 1073 static inline struct i2c_adapter *i2c_acpi_find_adapter_by_handle(acpi_handle handle) 1074 { 1075 return NULL; 1076 } 1077 static inline bool i2c_acpi_waive_d0_probe(struct device *dev) 1078 { 1079 return false; 1080 } 1081 #endif /* CONFIG_ACPI */ 1082 1083 static inline struct i2c_client *i2c_acpi_new_device(struct device *dev, 1084 int index, 1085 struct i2c_board_info *info) 1086 { 1087 return i2c_acpi_new_device_by_fwnode(dev_fwnode(dev), index, info); 1088 } 1089 1090 #endif /* _LINUX_I2C_H */ 1091