~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/include/linux/i2c.h

Version: ~ [ linux-4.16-rc2 ] ~ [ linux-4.15.4 ] ~ [ linux-4.14.20 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.82 ] ~ [ linux-4.8.17 ] ~ [ linux-4.7.10 ] ~ [ linux-4.6.7 ] ~ [ linux-4.5.7 ] ~ [ linux-4.4.116 ] ~ [ linux-4.3.6 ] ~ [ linux-4.2.8 ] ~ [ linux-4.1.49 ] ~ [ linux-4.0.9 ] ~ [ linux-3.19.8 ] ~ [ linux-3.18.95 ] ~ [ linux-3.17.8 ] ~ [ linux-3.16.54 ] ~ [ linux-3.15.10 ] ~ [ linux-3.14.79 ] ~ [ linux-3.13.11 ] ~ [ linux-3.12.74 ] ~ [ linux-3.11.10 ] ~ [ linux-3.10.108 ] ~ [ linux-3.9.11 ] ~ [ linux-3.8.13 ] ~ [ linux-3.7.10 ] ~ [ linux-3.6.11 ] ~ [ linux-3.5.7 ] ~ [ linux-3.4.113 ] ~ [ linux-3.3.8 ] ~ [ linux-3.2.99 ] ~ [ linux-3.1.10 ] ~ [ linux-3.0.101 ] ~ [ linux-2.6.39.4 ] ~ [ linux-2.6.38.8 ] ~ [ linux-2.6.37.6 ] ~ [ linux-2.6.36.4 ] ~ [ linux-2.6.35.14 ] ~ [ linux-2.6.34.15 ] ~ [ linux-2.6.33.20 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.27.62 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.5 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

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

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | Wiki (Japanese) | Wiki (English) | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

osdn.jp