i2c-of-prober.h

  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
 14struct device;
 15struct 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 */
 32struct 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 */
 65struct 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
 72int 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 */
112struct 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
121struct gpio_desc;
122struct regulator;
123
124struct 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
132int i2c_of_probe_simple_enable(struct device *dev, struct device_node *bus_node, void *data);
133void i2c_of_probe_simple_cleanup_early(struct device *dev, void *data);
134void i2c_of_probe_simple_cleanup(struct device *dev, void *data);
135
136extern 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 */