i2c.h 37 KB

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