linux/pinctrl/pinctrl.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * Interface the pinctrl subsystem
0004  *
0005  * Copyright (C) 2011 ST-Ericsson SA
0006  * Written on behalf of Linaro for ST-Ericsson
0007  * This interface is used in the core to keep track of pins.
0008  *
0009  * Author: Linus Walleij <linus.walleij@linaro.org>
0010  */
0011 #ifndef __LINUX_PINCTRL_PINCTRL_H
0012 #define __LINUX_PINCTRL_PINCTRL_H
0013
0014 #include <linux/radix-tree.h>
0015 #include <linux/list.h>
0016 #include <linux/seq_file.h>
0017 #include <linux/pinctrl/pinctrl-state.h>
0018 #include <linux/pinctrl/devinfo.h>
0019
0020 struct device;
0021 struct pinctrl_dev;
0022 struct pinctrl_map;
0023 struct pinmux_ops;
0024 struct pinconf_ops;
0025 struct pin_config_item;
0026 struct gpio_chip;
0027 struct device_node;
0028
0029 /**
0030  * struct pingroup - provides information on pingroup
0031  * @name: a name for pingroup
0032  * @pins: an array of pins in the pingroup
0033  * @npins: number of pins in the pingroup
0034  */
0035 struct pingroup {
0036     const char *name;
0037     const unsigned int *pins;
0038     size_t npins;
0039 };
0040
0041 /* Convenience macro to define a single named or anonymous pingroup */
0042 #define PINCTRL_PINGROUP(_name, _pins, _npins)  \
0043 (struct pingroup){              \
0044     .name = _name,              \
0045     .pins = _pins,              \
0046     .npins = _npins,            \
0047 }
0048
0049 /**
0050  * struct pinctrl_pin_desc - boards/machines provide information on their
0051  * pins, pads or other muxable units in this struct
0052  * @number: unique pin number from the global pin number space
0053  * @name: a name for this pin
0054  * @drv_data: driver-defined per-pin data. pinctrl core does not touch this
0055  */
0056 struct pinctrl_pin_desc {
0057     unsigned number;
0058     const char *name;
0059     void *drv_data;
0060 };
0061
0062 /* Convenience macro to define a single named or anonymous pin descriptor */
0063 #define PINCTRL_PIN(a, b) { .number = a, .name = b }
0064 #define PINCTRL_PIN_ANON(a) { .number = a }
0065
0066 /**
0067  * struct pinctrl_gpio_range - each pin controller can provide subranges of
0068  * the GPIO number space to be handled by the controller
0069  * @node: list node for internal use
0070  * @name: a name for the chip in this range
0071  * @id: an ID number for the chip in this range
0072  * @base: base offset of the GPIO range
0073  * @pin_base: base pin number of the GPIO range if pins == NULL
0074  * @npins: number of pins in the GPIO range, including the base number
0075  * @pins: enumeration of pins in GPIO range or NULL
0076  * @gc: an optional pointer to a gpio_chip
0077  */
0078 struct pinctrl_gpio_range {
0079     struct list_head node;
0080     const char *name;
0081     unsigned int id;
0082     unsigned int base;
0083     unsigned int pin_base;
0084     unsigned int npins;
0085     unsigned const *pins;
0086     struct gpio_chip *gc;
0087 };
0088
0089 /**
0090  * struct pinctrl_ops - global pin control operations, to be implemented by
0091  * pin controller drivers.
0092  * @get_groups_count: Returns the count of total number of groups registered.
0093  * @get_group_name: return the group name of the pin group
0094  * @get_group_pins: return an array of pins corresponding to a certain
0095  *  group selector @pins, and the size of the array in @num_pins
0096  * @pin_dbg_show: optional debugfs display hook that will provide per-device
0097  *  info for a certain pin in debugfs
0098  * @dt_node_to_map: parse a device tree "pin configuration node", and create
0099  *  mapping table entries for it. These are returned through the @map and
0100  *  @num_maps output parameters. This function is optional, and may be
0101  *  omitted for pinctrl drivers that do not support device tree.
0102  * @dt_free_map: free mapping table entries created via @dt_node_to_map. The
0103  *  top-level @map pointer must be freed, along with any dynamically
0104  *  allocated members of the mapping table entries themselves. This
0105  *  function is optional, and may be omitted for pinctrl drivers that do
0106  *  not support device tree.
0107  */
0108 struct pinctrl_ops {
0109     int (*get_groups_count) (struct pinctrl_dev *pctldev);
0110     const char *(*get_group_name) (struct pinctrl_dev *pctldev,
0111                        unsigned selector);
0112     int (*get_group_pins) (struct pinctrl_dev *pctldev,
0113                    unsigned selector,
0114                    const unsigned **pins,
0115                    unsigned *num_pins);
0116     void (*pin_dbg_show) (struct pinctrl_dev *pctldev, struct seq_file *s,
0117               unsigned offset);
0118     int (*dt_node_to_map) (struct pinctrl_dev *pctldev,
0119                    struct device_node *np_config,
0120                    struct pinctrl_map **map, unsigned *num_maps);
0121     void (*dt_free_map) (struct pinctrl_dev *pctldev,
0122                  struct pinctrl_map *map, unsigned num_maps);
0123 };
0124
0125 /**
0126  * struct pinctrl_desc - pin controller descriptor, register this to pin
0127  * control subsystem
0128  * @name: name for the pin controller
0129  * @pins: an array of pin descriptors describing all the pins handled by
0130  *  this pin controller
0131  * @npins: number of descriptors in the array, usually just ARRAY_SIZE()
0132  *  of the pins field above
0133  * @pctlops: pin control operation vtable, to support global concepts like
0134  *  grouping of pins, this is optional.
0135  * @pmxops: pinmux operations vtable, if you support pinmuxing in your driver
0136  * @confops: pin config operations vtable, if you support pin configuration in
0137  *  your driver
0138  * @owner: module providing the pin controller, used for refcounting
0139  * @num_custom_params: Number of driver-specific custom parameters to be parsed
0140  *  from the hardware description
0141  * @custom_params: List of driver_specific custom parameters to be parsed from
0142  *  the hardware description
0143  * @custom_conf_items: Information how to print @params in debugfs, must be
0144  *  the same size as the @custom_params, i.e. @num_custom_params
0145  * @link_consumers: If true create a device link between pinctrl and its
0146  *  consumers (i.e. the devices requesting pin control states). This is
0147  *  sometimes necessary to ascertain the right suspend/resume order for
0148  *  example.
0149  */
0150 struct pinctrl_desc {
0151     const char *name;
0152     const struct pinctrl_pin_desc *pins;
0153     unsigned int npins;
0154     const struct pinctrl_ops *pctlops;
0155     const struct pinmux_ops *pmxops;
0156     const struct pinconf_ops *confops;
0157     struct module *owner;
0158 #ifdef CONFIG_GENERIC_PINCONF
0159     unsigned int num_custom_params;
0160     const struct pinconf_generic_params *custom_params;
0161     const struct pin_config_item *custom_conf_items;
0162 #endif
0163     bool link_consumers;
0164 };
0165
0166 /* External interface to pin controller */
0167
0168 extern int pinctrl_register_and_init(struct pinctrl_desc *pctldesc,
0169                      struct device *dev, void *driver_data,
0170                      struct pinctrl_dev **pctldev);
0171 extern int pinctrl_enable(struct pinctrl_dev *pctldev);
0172
0173 /* Please use pinctrl_register_and_init() and pinctrl_enable() instead */
0174 extern struct pinctrl_dev *pinctrl_register(struct pinctrl_desc *pctldesc,
0175                 struct device *dev, void *driver_data);
0176
0177 extern void pinctrl_unregister(struct pinctrl_dev *pctldev);
0178
0179 extern int devm_pinctrl_register_and_init(struct device *dev,
0180                 struct pinctrl_desc *pctldesc,
0181                 void *driver_data,
0182                 struct pinctrl_dev **pctldev);
0183
0184 /* Please use devm_pinctrl_register_and_init() instead */
0185 extern struct pinctrl_dev *devm_pinctrl_register(struct device *dev,
0186                 struct pinctrl_desc *pctldesc,
0187                 void *driver_data);
0188
0189 extern void devm_pinctrl_unregister(struct device *dev,
0190                 struct pinctrl_dev *pctldev);
0191
0192 extern void pinctrl_add_gpio_range(struct pinctrl_dev *pctldev,
0193                 struct pinctrl_gpio_range *range);
0194 extern void pinctrl_add_gpio_ranges(struct pinctrl_dev *pctldev,
0195                 struct pinctrl_gpio_range *ranges,
0196                 unsigned nranges);
0197 extern void pinctrl_remove_gpio_range(struct pinctrl_dev *pctldev,
0198                 struct pinctrl_gpio_range *range);
0199
0200 extern struct pinctrl_dev *pinctrl_find_and_add_gpio_range(const char *devname,
0201         struct pinctrl_gpio_range *range);
0202 extern struct pinctrl_gpio_range *
0203 pinctrl_find_gpio_range_from_pin(struct pinctrl_dev *pctldev,
0204                  unsigned int pin);
0205 extern int pinctrl_get_group_pins(struct pinctrl_dev *pctldev,
0206                 const char *pin_group, const unsigned **pins,
0207                 unsigned *num_pins);
0208
0209 #if IS_ENABLED(CONFIG_OF) && IS_ENABLED(CONFIG_PINCTRL)
0210 extern struct pinctrl_dev *of_pinctrl_get(struct device_node *np);
0211 #else
0212 static inline
0213 struct pinctrl_dev *of_pinctrl_get(struct device_node *np)
0214 {
0215     return NULL;
0216 }
0217 #endif /* CONFIG_OF */
0218
0219 extern const char *pinctrl_dev_get_name(struct pinctrl_dev *pctldev);
0220 extern const char *pinctrl_dev_get_devname(struct pinctrl_dev *pctldev);
0221 extern void *pinctrl_dev_get_drvdata(struct pinctrl_dev *pctldev);
0222
0223 #endif /* __LINUX_PINCTRL_PINCTRL_H */