drivers/pinctrl/core.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * Core private header for the pin control subsystem
0004  *
0005  * Copyright (C) 2011 ST-Ericsson SA
0006  * Written on behalf of Linaro for ST-Ericsson
0007  *
0008  * Author: Linus Walleij <linus.walleij@linaro.org>
0009  */
0010
0011 #include <linux/kref.h>
0012 #include <linux/mutex.h>
0013 #include <linux/radix-tree.h>
0014 #include <linux/pinctrl/pinconf.h>
0015 #include <linux/pinctrl/machine.h>
0016
0017 struct pinctrl_gpio_range;
0018
0019 /**
0020  * struct pinctrl_dev - pin control class device
0021  * @node: node to include this pin controller in the global pin controller list
0022  * @desc: the pin controller descriptor supplied when initializing this pin
0023  *  controller
0024  * @pin_desc_tree: each pin descriptor for this pin controller is stored in
0025  *  this radix tree
0026  * @pin_group_tree: optionally each pin group can be stored in this radix tree
0027  * @num_groups: optionally number of groups can be kept here
0028  * @pin_function_tree: optionally each function can be stored in this radix tree
0029  * @num_functions: optionally number of functions can be kept here
0030  * @gpio_ranges: a list of GPIO ranges that is handled by this pin controller,
0031  *  ranges are added to this list at runtime
0032  * @dev: the device entry for this pin controller
0033  * @owner: module providing the pin controller, used for refcounting
0034  * @driver_data: driver data for drivers registering to the pin controller
0035  *  subsystem
0036  * @p: result of pinctrl_get() for this device
0037  * @hog_default: default state for pins hogged by this device
0038  * @hog_sleep: sleep state for pins hogged by this device
0039  * @mutex: mutex taken on each pin controller specific action
0040  * @device_root: debugfs root for this device
0041  */
0042 struct pinctrl_dev {
0043     struct list_head node;
0044     struct pinctrl_desc *desc;
0045     struct radix_tree_root pin_desc_tree;
0046 #ifdef CONFIG_GENERIC_PINCTRL_GROUPS
0047     struct radix_tree_root pin_group_tree;
0048     unsigned int num_groups;
0049 #endif
0050 #ifdef CONFIG_GENERIC_PINMUX_FUNCTIONS
0051     struct radix_tree_root pin_function_tree;
0052     unsigned int num_functions;
0053 #endif
0054     struct list_head gpio_ranges;
0055     struct device *dev;
0056     struct module *owner;
0057     void *driver_data;
0058     struct pinctrl *p;
0059     struct pinctrl_state *hog_default;
0060     struct pinctrl_state *hog_sleep;
0061     struct mutex mutex;
0062 #ifdef CONFIG_DEBUG_FS
0063     struct dentry *device_root;
0064 #endif
0065 };
0066
0067 /**
0068  * struct pinctrl - per-device pin control state holder
0069  * @node: global list node
0070  * @dev: the device using this pin control handle
0071  * @states: a list of states for this device
0072  * @state: the current state
0073  * @dt_maps: the mapping table chunks dynamically parsed from device tree for
0074  *  this device, if any
0075  * @users: reference count
0076  */
0077 struct pinctrl {
0078     struct list_head node;
0079     struct device *dev;
0080     struct list_head states;
0081     struct pinctrl_state *state;
0082     struct list_head dt_maps;
0083     struct kref users;
0084 };
0085
0086 /**
0087  * struct pinctrl_state - a pinctrl state for a device
0088  * @node: list node for struct pinctrl's @states field
0089  * @name: the name of this state
0090  * @settings: a list of settings for this state
0091  */
0092 struct pinctrl_state {
0093     struct list_head node;
0094     const char *name;
0095     struct list_head settings;
0096 };
0097
0098 /**
0099  * struct pinctrl_setting_mux - setting data for MAP_TYPE_MUX_GROUP
0100  * @group: the group selector to program
0101  * @func: the function selector to program
0102  */
0103 struct pinctrl_setting_mux {
0104     unsigned group;
0105     unsigned func;
0106 };
0107
0108 /**
0109  * struct pinctrl_setting_configs - setting data for MAP_TYPE_CONFIGS_*
0110  * @group_or_pin: the group selector or pin ID to program
0111  * @configs: a pointer to an array of config parameters/values to program into
0112  *  hardware. Each individual pin controller defines the format and meaning
0113  *  of config parameters.
0114  * @num_configs: the number of entries in array @configs
0115  */
0116 struct pinctrl_setting_configs {
0117     unsigned group_or_pin;
0118     unsigned long *configs;
0119     unsigned num_configs;
0120 };
0121
0122 /**
0123  * struct pinctrl_setting - an individual mux or config setting
0124  * @node: list node for struct pinctrl_settings's @settings field
0125  * @type: the type of setting
0126  * @pctldev: pin control device handling to be programmed. Not used for
0127  *   PIN_MAP_TYPE_DUMMY_STATE.
0128  * @dev_name: the name of the device using this state
0129  * @data: Data specific to the setting type
0130  */
0131 struct pinctrl_setting {
0132     struct list_head node;
0133     enum pinctrl_map_type type;
0134     struct pinctrl_dev *pctldev;
0135     const char *dev_name;
0136     union {
0137         struct pinctrl_setting_mux mux;
0138         struct pinctrl_setting_configs configs;
0139     } data;
0140 };
0141
0142 /**
0143  * struct pin_desc - pin descriptor for each physical pin in the arch
0144  * @pctldev: corresponding pin control device
0145  * @name: a name for the pin, e.g. the name of the pin/pad/finger on a
0146  *  datasheet or such
0147  * @dynamic_name: if the name of this pin was dynamically allocated
0148  * @drv_data: driver-defined per-pin data. pinctrl core does not touch this
0149  * @mux_usecount: If zero, the pin is not claimed, and @owner should be NULL.
0150  *  If non-zero, this pin is claimed by @owner. This field is an integer
0151  *  rather than a boolean, since pinctrl_get() might process multiple
0152  *  mapping table entries that refer to, and hence claim, the same group
0153  *  or pin, and each of these will increment the @usecount.
0154  * @mux_owner: The name of device that called pinctrl_get().
0155  * @mux_setting: The most recent selected mux setting for this pin, if any.
0156  * @gpio_owner: If pinctrl_gpio_request() was called for this pin, this is
0157  *  the name of the GPIO that "owns" this pin.
0158  */
0159 struct pin_desc {
0160     struct pinctrl_dev *pctldev;
0161     const char *name;
0162     bool dynamic_name;
0163     void *drv_data;
0164     /* These fields only added when supporting pinmux drivers */
0165 #ifdef CONFIG_PINMUX
0166     unsigned mux_usecount;
0167     const char *mux_owner;
0168     const struct pinctrl_setting_mux *mux_setting;
0169     const char *gpio_owner;
0170 #endif
0171 };
0172
0173 /**
0174  * struct pinctrl_maps - a list item containing part of the mapping table
0175  * @node: mapping table list node
0176  * @maps: array of mapping table entries
0177  * @num_maps: the number of entries in @maps
0178  */
0179 struct pinctrl_maps {
0180     struct list_head node;
0181     const struct pinctrl_map *maps;
0182     unsigned num_maps;
0183 };
0184
0185 #ifdef CONFIG_GENERIC_PINCTRL_GROUPS
0186
0187 /**
0188  * struct group_desc - generic pin group descriptor
0189  * @name: name of the pin group
0190  * @pins: array of pins that belong to the group
0191  * @num_pins: number of pins in the group
0192  * @data: pin controller driver specific data
0193  */
0194 struct group_desc {
0195     const char *name;
0196     int *pins;
0197     int num_pins;
0198     void *data;
0199 };
0200
0201 int pinctrl_generic_get_group_count(struct pinctrl_dev *pctldev);
0202
0203 const char *pinctrl_generic_get_group_name(struct pinctrl_dev *pctldev,
0204                        unsigned int group_selector);
0205
0206 int pinctrl_generic_get_group_pins(struct pinctrl_dev *pctldev,
0207                    unsigned int group_selector,
0208                    const unsigned int **pins,
0209                    unsigned int *npins);
0210
0211 struct group_desc *pinctrl_generic_get_group(struct pinctrl_dev *pctldev,
0212                          unsigned int group_selector);
0213
0214 int pinctrl_generic_add_group(struct pinctrl_dev *pctldev, const char *name,
0215                   int *gpins, int ngpins, void *data);
0216
0217 int pinctrl_generic_remove_group(struct pinctrl_dev *pctldev,
0218                  unsigned int group_selector);
0219
0220 #endif  /* CONFIG_GENERIC_PINCTRL_GROUPS */
0221
0222 struct pinctrl_dev *get_pinctrl_dev_from_devname(const char *dev_name);
0223 struct pinctrl_dev *get_pinctrl_dev_from_of_node(struct device_node *np);
0224 int pin_get_from_name(struct pinctrl_dev *pctldev, const char *name);
0225 const char *pin_get_name(struct pinctrl_dev *pctldev, const unsigned pin);
0226 int pinctrl_get_group_selector(struct pinctrl_dev *pctldev,
0227                    const char *pin_group);
0228
0229 static inline struct pin_desc *pin_desc_get(struct pinctrl_dev *pctldev,
0230                         unsigned int pin)
0231 {
0232     return radix_tree_lookup(&pctldev->pin_desc_tree, pin);
0233 }
0234
0235 extern struct pinctrl_gpio_range *
0236 pinctrl_find_gpio_range_from_pin_nolock(struct pinctrl_dev *pctldev,
0237                     unsigned int pin);
0238
0239 extern int pinctrl_force_sleep(struct pinctrl_dev *pctldev);
0240 extern int pinctrl_force_default(struct pinctrl_dev *pctldev);
0241
0242 extern struct mutex pinctrl_maps_mutex;
0243 extern struct list_head pinctrl_maps;
0244
0245 #define for_each_maps(_maps_node_, _i_, _map_) \
0246     list_for_each_entry(_maps_node_, &pinctrl_maps, node) \
0247         for (_i_ = 0, _map_ = &_maps_node_->maps[_i_]; \
0248             _i_ < _maps_node_->num_maps; \
0249             _i_++, _map_ = &_maps_node_->maps[_i_])