1 /* SPDX-License-Identifier: GPL-2.0-only */
2 /*
3 * Interface the pinctrl subsystem
4 *
5 * Copyright (C) 2011 ST-Ericsson SA
6 * Written on behalf of Linaro for ST-Ericsson
7 * This interface is used in the core to keep track of pins.
8 *
9 * Author: Linus Walleij <linus.walleij@linaro.org>
10 */
11 #ifndef __LINUX_PINCTRL_PINCTRL_H
12 #define __LINUX_PINCTRL_PINCTRL_H
13
14 #include <linux/radix-tree.h>
15 #include <linux/list.h>
16 #include <linux/seq_file.h>
17 #include <linux/pinctrl/pinctrl-state.h>
18 #include <linux/pinctrl/devinfo.h>
19
20 struct device;
21 struct pinctrl_dev;
22 struct pinctrl_map;
23 struct pinmux_ops;
24 struct pinconf_ops;
25 struct pin_config_item;
26 struct gpio_chip;
27 struct device_node;
28
29 /**
30 * struct pinctrl_pin_desc - boards/machines provide information on their
31 * pins, pads or other muxable units in this struct
32 * @number: unique pin number from the global pin number space
33 * @name: a name for this pin
34 * @drv_data: driver-defined per-pin data. pinctrl core does not touch this
35 */
36 struct pinctrl_pin_desc {
37 unsigned number;
38 const char *name;
39 void *drv_data;
40 };
41
42 /* Convenience macro to define a single named or anonymous pin descriptor */
43 #define PINCTRL_PIN(a, b) { .number = a, .name = b }
44 #define PINCTRL_PIN_ANON(a) { .number = a }
45
46 /**
47 * struct pinctrl_gpio_range - each pin controller can provide subranges of
48 * the GPIO number space to be handled by the controller
49 * @node: list node for internal use
50 * @name: a name for the chip in this range
51 * @id: an ID number for the chip in this range
52 * @base: base offset of the GPIO range
53 * @pin_base: base pin number of the GPIO range if pins == NULL
54 * @pins: enumeration of pins in GPIO range or NULL
55 * @npins: number of pins in the GPIO range, including the base number
56 * @gc: an optional pointer to a gpio_chip
57 */
58 struct pinctrl_gpio_range {
59 struct list_head node;
60 const char *name;
61 unsigned int id;
62 unsigned int base;
63 unsigned int pin_base;
64 unsigned const *pins;
65 unsigned int npins;
66 struct gpio_chip *gc;
67 };
68
69 /**
70 * struct pinctrl_ops - global pin control operations, to be implemented by
71 * pin controller drivers.
72 * @get_groups_count: Returns the count of total number of groups registered.
73 * @get_group_name: return the group name of the pin group
74 * @get_group_pins: return an array of pins corresponding to a certain
75 * group selector @pins, and the size of the array in @num_pins
76 * @pin_dbg_show: optional debugfs display hook that will provide per-device
77 * info for a certain pin in debugfs
78 * @dt_node_to_map: parse a device tree "pin configuration node", and create
79 * mapping table entries for it. These are returned through the @map and
80 * @num_maps output parameters. This function is optional, and may be
81 * omitted for pinctrl drivers that do not support device tree.
82 * @dt_free_map: free mapping table entries created via @dt_node_to_map. The
83 * top-level @map pointer must be freed, along with any dynamically
84 * allocated members of the mapping table entries themselves. This
85 * function is optional, and may be omitted for pinctrl drivers that do
86 * not support device tree.
87 */
88 struct pinctrl_ops {
89 int (*get_groups_count) (struct pinctrl_dev *pctldev);
90 const char *(*get_group_name) (struct pinctrl_dev *pctldev,
91 unsigned selector);
92 int (*get_group_pins) (struct pinctrl_dev *pctldev,
93 unsigned selector,
94 const unsigned **pins,
95 unsigned *num_pins);
96 void (*pin_dbg_show) (struct pinctrl_dev *pctldev, struct seq_file *s,
97 unsigned offset);
98 int (*dt_node_to_map) (struct pinctrl_dev *pctldev,
99 struct device_node *np_config,
100 struct pinctrl_map **map, unsigned *num_maps);
101 void (*dt_free_map) (struct pinctrl_dev *pctldev,
102 struct pinctrl_map *map, unsigned num_maps);
103 };
104
105 /**
106 * struct pinctrl_desc - pin controller descriptor, register this to pin
107 * control subsystem
108 * @name: name for the pin controller
109 * @pins: an array of pin descriptors describing all the pins handled by
110 * this pin controller
111 * @npins: number of descriptors in the array, usually just ARRAY_SIZE()
112 * of the pins field above
113 * @pctlops: pin control operation vtable, to support global concepts like
114 * grouping of pins, this is optional.
115 * @pmxops: pinmux operations vtable, if you support pinmuxing in your driver
116 * @confops: pin config operations vtable, if you support pin configuration in
117 * your driver
118 * @owner: module providing the pin controller, used for refcounting
119 * @num_custom_params: Number of driver-specific custom parameters to be parsed
120 * from the hardware description
121 * @custom_params: List of driver_specific custom parameters to be parsed from
122 * the hardware description
123 * @custom_conf_items: Information how to print @params in debugfs, must be
124 * the same size as the @custom_params, i.e. @num_custom_params
125 * @link_consumers: If true create a device link between pinctrl and its
126 * consumers (i.e. the devices requesting pin control states). This is
127 * sometimes necessary to ascertain the right suspend/resume order for
128 * example.
129 */
130 struct pinctrl_desc {
131 const char *name;
132 const struct pinctrl_pin_desc *pins;
133 unsigned int npins;
134 const struct pinctrl_ops *pctlops;
135 const struct pinmux_ops *pmxops;
136 const struct pinconf_ops *confops;
137 struct module *owner;
138 #ifdef CONFIG_GENERIC_PINCONF
139 unsigned int num_custom_params;
140 const struct pinconf_generic_params *custom_params;
141 const struct pin_config_item *custom_conf_items;
142 #endif
143 bool link_consumers;
144 };
145
146 /* External interface to pin controller */
147
148 extern int pinctrl_register_and_init(struct pinctrl_desc *pctldesc,
149 struct device *dev, void *driver_data,
150 struct pinctrl_dev **pctldev);
151 extern int pinctrl_enable(struct pinctrl_dev *pctldev);
152
153 /* Please use pinctrl_register_and_init() and pinctrl_enable() instead */
154 extern struct pinctrl_dev *pinctrl_register(struct pinctrl_desc *pctldesc,
155 struct device *dev, void *driver_data);
156
157 extern void pinctrl_unregister(struct pinctrl_dev *pctldev);
158
159 extern int devm_pinctrl_register_and_init(struct device *dev,
160 struct pinctrl_desc *pctldesc,
161 void *driver_data,
162 struct pinctrl_dev **pctldev);
163
164 /* Please use devm_pinctrl_register_and_init() instead */
165 extern struct pinctrl_dev *devm_pinctrl_register(struct device *dev,
166 struct pinctrl_desc *pctldesc,
167 void *driver_data);
168
169 extern void devm_pinctrl_unregister(struct device *dev,
170 struct pinctrl_dev *pctldev);
171
172 extern void pinctrl_add_gpio_range(struct pinctrl_dev *pctldev,
173 struct pinctrl_gpio_range *range);
174 extern void pinctrl_add_gpio_ranges(struct pinctrl_dev *pctldev,
175 struct pinctrl_gpio_range *ranges,
176 unsigned nranges);
177 extern void pinctrl_remove_gpio_range(struct pinctrl_dev *pctldev,
178 struct pinctrl_gpio_range *range);
179
180 extern struct pinctrl_dev *pinctrl_find_and_add_gpio_range(const char *devname,
181 struct pinctrl_gpio_range *range);
182 extern struct pinctrl_gpio_range *
183 pinctrl_find_gpio_range_from_pin(struct pinctrl_dev *pctldev,
184 unsigned int pin);
185 extern int pinctrl_get_group_pins(struct pinctrl_dev *pctldev,
186 const char *pin_group, const unsigned **pins,
187 unsigned *num_pins);
188
189 #ifdef CONFIG_OF
190 extern struct pinctrl_dev *of_pinctrl_get(struct device_node *np);
191 #else
192 static inline
193 struct pinctrl_dev *of_pinctrl_get(struct device_node *np)
194 {
195 return NULL;
196 }
197 #endif /* CONFIG_OF */
198
199 extern const char *pinctrl_dev_get_name(struct pinctrl_dev *pctldev);
200 extern const char *pinctrl_dev_get_devname(struct pinctrl_dev *pctldev);
201 extern void *pinctrl_dev_get_drvdata(struct pinctrl_dev *pctldev);
202
203 #endif /* __LINUX_PINCTRL_PINCTRL_H */