1 /* SPDX-License-Identifier: GPL-2.0-or-later */ 2 /* 3 * Definitions for the Linux I2C OF component prober 4 * 5 * Copyright (C) 2024 Google LLC 6 */ 7 8 #ifndef _LINUX_I2C_OF_PROBER_H 9 #define _LINUX_I2C_OF_PROBER_H 10 11 #include <linux/kconfig.h> 12 #include <linux/types.h> 13 14 struct device; 15 struct device_node; 16 17 /** 18 * struct i2c_of_probe_ops - I2C OF component prober callbacks 19 * 20 * A set of callbacks to be used by i2c_of_probe_component(). 21 * 22 * All callbacks are optional. Callbacks are called only once per run, and are 23 * used in the order they are defined in this structure. 24 * 25 * All callbacks that have return values shall return %0 on success, 26 * or a negative error number on failure. 27 * 28 * The @dev parameter passed to the callbacks is the same as @dev passed to 29 * i2c_of_probe_component(). It should only be used for dev_printk() calls 30 * and nothing else, especially not managed device resource (devres) APIs. 31 */ 32 struct i2c_of_probe_ops { 33 /** 34 * @enable: Retrieve and enable resources so that the components respond to probes. 35 * 36 * It is OK for this callback to return -EPROBE_DEFER since the intended use includes 37 * retrieving resources and enables them. Resources should be reverted to their initial 38 * state and released before returning if this fails. 39 */ 40 int (*enable)(struct device *dev, struct device_node *bus_node, void *data); 41 42 /** 43 * @cleanup_early: Release exclusive resources prior to calling probe() on a 44 * detected component. 45 * 46 * Only called if a matching component is actually found. If none are found, 47 * resources that would have been released in this callback should be released in 48 * @free_resourcs_late instead. 49 */ 50 void (*cleanup_early)(struct device *dev, void *data); 51 52 /** 53 * @cleanup: Opposite of @enable to balance refcounts and free resources after probing. 54 * 55 * Should check if resources were already freed by @cleanup_early. 56 */ 57 void (*cleanup)(struct device *dev, void *data); 58 }; 59 60 /** 61 * struct i2c_of_probe_cfg - I2C OF component prober configuration 62 * @ops: Callbacks for the prober to use. 63 * @type: A string to match the device node name prefix to probe for. 64 */ 65 struct i2c_of_probe_cfg { 66 const struct i2c_of_probe_ops *ops; 67 const char *type; 68 }; 69 70 #if IS_ENABLED(CONFIG_OF_DYNAMIC) 71 72 int i2c_of_probe_component(struct device *dev, const struct i2c_of_probe_cfg *cfg, void *ctx); 73 74 /** 75 * DOC: I2C OF component prober simple helpers 76 * 77 * Components such as trackpads are commonly connected to a devices baseboard 78 * with a 6-pin ribbon cable. That gives at most one voltage supply and one 79 * GPIO (commonly a "enable" or "reset" line) besides the I2C bus, interrupt 80 * pin, and common ground. Touchscreens, while integrated into the display 81 * panel's connection, typically have the same set of connections. 82 * 83 * A simple set of helpers are provided here for use with the I2C OF component 84 * prober. This implementation targets such components, allowing for at most 85 * one regulator supply. 86 * 87 * The following helpers are provided: 88 * * i2c_of_probe_simple_enable() 89 * * i2c_of_probe_simple_cleanup_early() 90 * * i2c_of_probe_simple_cleanup() 91 */ 92 93 /** 94 * struct i2c_of_probe_simple_opts - Options for simple I2C component prober callbacks 95 * @res_node_compatible: Compatible string of device node to retrieve resources from. 96 * @supply_name: Name of regulator supply. 97 * @gpio_name: Name of GPIO. NULL if no GPIO line is used. Empty string ("") if GPIO 98 * line is unnamed. 99 * @post_power_on_delay_ms: Delay after regulators are powered on. Passed to msleep(). 100 * @post_gpio_config_delay_ms: Delay after GPIO is configured. Passed to msleep(). 101 * @gpio_assert_to_enable: %true if GPIO should be asserted, i.e. set to logical high, 102 * to enable the component. 103 * 104 * This describes power sequences common for the class of components supported by the 105 * simple component prober: 106 * * @gpio_name is configured to the non-active setting according to @gpio_assert_to_enable. 107 * * @supply_name regulator supply is enabled. 108 * * Wait for @post_power_on_delay_ms to pass. 109 * * @gpio_name is configured to the active setting according to @gpio_assert_to_enable. 110 * * Wait for @post_gpio_config_delay_ms to pass. 111 */ 112 struct i2c_of_probe_simple_opts { 113 const char *res_node_compatible; 114 const char *supply_name; 115 const char *gpio_name; 116 unsigned int post_power_on_delay_ms; 117 unsigned int post_gpio_config_delay_ms; 118 bool gpio_assert_to_enable; 119 }; 120 121 struct gpio_desc; 122 struct regulator; 123 124 struct i2c_of_probe_simple_ctx { 125 /* public: provided by user before helpers are used. */ 126 const struct i2c_of_probe_simple_opts *opts; 127 /* private: internal fields for helpers. */ 128 struct regulator *supply; 129 struct gpio_desc *gpiod; 130 }; 131 132 int i2c_of_probe_simple_enable(struct device *dev, struct device_node *bus_node, void *data); 133 void i2c_of_probe_simple_cleanup_early(struct device *dev, void *data); 134 void i2c_of_probe_simple_cleanup(struct device *dev, void *data); 135 136 extern struct i2c_of_probe_ops i2c_of_probe_simple_ops; 137 138 #endif /* IS_ENABLED(CONFIG_OF_DYNAMIC) */ 139 140 #endif /* _LINUX_I2C_OF_PROBER_H */ 141