Commit 2744e8af authored by Linus Walleij's avatar Linus Walleij Committed by Linus Walleij

drivers: create a pin control subsystem

This creates a subsystem for handling of pin control devices.
These are devices that control different aspects of package

Currently it handles pinmuxing, i.e. assigning electronic
functions to groups of pins on primarily PGA and BGA type of
chip packages which are common in embedded systems.

The plan is to also handle other I/O pin control aspects
such as biasing, driving, input properties such as
schmitt-triggering, load capacitance etc within this
subsystem, to remove a lot of ARM arch code as well as
feature-creepy GPIO drivers which are implementing the same
thing over and over again.

This is being done to depopulate the arch/arm/* directory
of such custom drivers and try to abstract the infrastructure
they all need. See the Documentation/pinctrl.txt file that is
part of this patch for more details.

ChangeLog v1->v2:

- Various minor fixes from Joe's and Stephens review comments
- Added a pinmux_config() that can invoke custom configuration
  with arbitrary data passed in or out to/from the pinmux driver

ChangeLog v2->v3:

- Renamed subsystem folder to "pinctrl" since we will likely
  want to keep other pin control such as biasing in this
  subsystem too, so let us keep to something generic even though
  we're mainly doing pinmux now.
- As a consequence, register pins as an abstract entity separate
  from the pinmux. The muxing functions will claim pins out of the
  pin pool and make sure they do not collide. Pins can now be
  named by the pinctrl core.
- Converted the pin lookup from a static array into a radix tree,
  I agreed with Grant Likely to try to avoid any static allocation
  (which is crap for device tree stuff) so I just rewrote this
  to be dynamic, just like irq number descriptors. The
  platform-wide definition of number of pins goes away - this is
  now just the sum total of the pins registered to the subsystem.
- Make sure mappings with only a function name and no device
  works properly.

ChangeLog v3->v4:

- Define a number space per controller instead of globally,
  Stephen and Grant requested the same thing so now maps need to
  define target controller, and the radix tree of pin descriptors
  is a property on each pin controller device.
- Add a compulsory pinctrl device entry to the pinctrl mapping
  table. This must match the pinctrl device, like "pinctrl.0"
- Split the file core.c in two: core.c and pinmux.c where the
  latter carry all pinmux stuff, the core is for generic pin
  control, and use local headers to access functionality between
  files. It is now possible to implement a "blank" pin controller
  without pinmux capabilities. This split will make new additions
  like pindrive.c, pinbias.c etc possible for combined drivers
  and chunks of functionality which is a GoodThing(TM).
- Rewrite the interaction with the GPIO subsystem - the pin
  controller descriptor now handles this by defining an offset
  into the GPIO numberspace for its handled pin range. This is
  used to look up the apropriate pin controller for a GPIO pin.
  Then that specific GPIO range is matched 1-1 for the target
  controller instance.
- Fixed a number of review comments from Joe Perches.
- Broke out a header file pinctrl.h for the core pin handling
  stuff that will be reused by other stuff than pinmux.
- Fixed some erroneous EXPORT() stuff.
- Remove mispatched U300 Kconfig and Makefile entries
- Fixed a number of review comments from Stephen Warren, not all
  of them - still WIP. But I think the new mapping that will
  specify which function goes to which pin mux controller address
  50% of your concerns (else beat me up).

ChangeLog v4->v5:

- Defined a "position" for each function, so the pin controller now
  tracks a function in a certain position, and the pinmux maps define
  what position you want the function in. (Feedback from Stephen
  Warren and Sascha Hauer).
- Since we now need to request a combined function+position from
  the machine mapping table that connect mux settings to drivers,
  it was extended with a position field and a name field. The
  name field is now used if you e.g. need to switch between two
  mux map settings at runtime.
- Switched from a class device to using struct bus_type for this
  subsystem. Verified sysfs functionality: seems to work fine.
  (Feedback from Arnd Bergmann and Greg Kroah-Hartman)
- Define a per pincontroller list of GPIO ranges from the GPIO
  pin space that can be handled by the pin controller. These can
  be added one by one at runtime. (Feedback from Barry Song)
- Expanded documentation of regulator_[get|enable|disable|put]
- Fixed a number of review comments from Barry Song. (Thanks!)

ChangeLog v5->v6:

- Create an abstract pin group concept that can sort pins into
  named and enumerated groups no matter what the use of these
  groups may be, one possible usecase is a group of pins being
  muxed in or so. The intention is however to also use these
  groups for other pin control activities.
- Make it compulsory for pinmux functions to associate with
  at least one group, so the abstract pin group concept is used
  to define the groups of pins affected by a pinmux function.
  The pinmux driver interface has been altered so as to enforce
  a function to list applicable groups per function.
- Provide an optional .group entry in the pinmux machine map
  so the map can select beteween different available groups
  to be used with a certain function.
- Consequent changes all over the place so that e.g. debugfs
  present reasonable information about the world.
- Drop the per-pin mux (*config) function in the pinmux_ops
  struct - I was afraid that this would start to be used for
  things totally unrelated to muxing, we can introduce that to
  the generic struct pinctrl_ops if needed. I want to keep
  muxing orthogonal to other pin control subjects and not mix
  these things up.

ChangeLog v6->v7:

- Make it possible to have several map entries matching the
  same device, pin controller and function, but using
  a different group, and alter the semantics so that
  pinmux_get() will pick all matching map entries, and
  store the associated groups in a list. The list will
  then be iterated over at pinmux_enable()/pinmux_disable()
  and corresponding driver functions called for each
  defined group. Notice that you're only allowed to map
  multiple *groups* to the same
  { device, pin controller, function } triplet, attempts
  to map the same device to multiple pin controllers will
  for example fail. This is hopefully the crucial feature
  requested by Stephen Warren.
- Add a pinmux hogging field to the pinmux mapping entries,
  and enable the pinmux core to hog pinmux map entries.
  This currently only works for pinmuxes without assigned
  devices as it looks now, but with device trees we can
  look up the corresponding struct device * entries when
  we register the pinmux driver, and have it hog each
  pinmux map in turn, for a simple approach to
  non-dynamic pin muxing. This addresses an issue from
  Grant Likely that the machine should take care of as
  much of the pinmux setup as possible, not the devices.
  By supplying a list of hogs, it can now instruct the
  core to take care of any static mappings.
- Switch pinmux group retrieveal function to grab an
  array of strings representing the groups rather than an
  array of unsigned and rewrite accordingly.
- Alter debugfs to show the grouplist handled by each
  pinmux. Also add a list of hogs.
- Dynamically allocate a struct pinmux at pinmux_get() and
  free it at pinmux_put(), then add these to the global
  list of pinmuxes active as we go along.
- Go over the list of pinmux maps at pinmux_get() time
  and repeatedly apply matches.
- Retrieve applicable groups per function from the driver
  as a string array rather than a unsigned array, then
  lookup the enumerators.
- Make the device to pinmux map a singleton - only allow the
  mapping table to be registered once and even tag the
  registration function with __init so it surely won't be
- Create a separate debugfs file to view the pinmux map at
- Introduce a spin lock to the pin descriptor struct, lock it
  when modifying pin status entries. Reported by Stijn Devriendt.
- Fix up the documentation after review from Stephen Warren.
- Let the GPIO ranges give names as const char * instead of some
  fixed-length string.
- add a function to unregister GPIO ranges to mirror the
  registration function.
- Privatized the struct pinctrl_device and removed it from the
  <linux/pinctrl/pinctrl.h> API, the drivers do not need to know
  the members of this struct. It is now in the local header
- Rename the concept of "anonymous" mux maps to "system" muxes
  and add convenience macros and documentation.

ChangeLog v7->v8:

- Delete the leftover pinmux_config() function from the
 <linux/pinctrl/pinmux.h> header.
- Fix a race condition found by Stijn Devriendt in pin_request()

ChangeLog v8->v9:

- Drop the bus_type and the sysfs attributes and all, we're not on
  the clear about how this should be used for e.g. userspace
  interfaces so let us save this for the future.
- Use the right name in MAINTAINERS, PIN CONTROL rather than
- Don't kfree() the device state holder, let the .remove() callback
  handle this.
- Fix up numerous kerneldoc headers to have one line for the function
  description and more verbose documentation below the parameters

ChangeLog v9->v10:
- pinctrl: EXPORT_SYMBOL needs export.h, folded in a patch
  from Steven Rothwell
- fix pinctrl_register error handling, folded in a patch from
  Axel Lin
- Various fixes to documentation text so that it's consistent.
- Removed pointless comment from drivers/Kconfig
- Removed dependency on SYSFS since we removed the bus in
- Renamed hopelessly abbreviated pctldev_* functions to the
  more verbose pinctrl_dev_*
- Drop mutex properly when looking up GPIO ranges
- Return NULL instead of ERR_PTR() errors on registration of
  pin controllers, using cast pointers is fragile. We can
  live without the detailed error codes for sure.

Cc: Stijn Devriendt <>
Cc: Joe Perches <>
Cc: Russell King <>
Acked-by: default avatarGrant Likely <>
Acked-by: default avatarStephen Warren <>
Tested-by: default avatarBarry Song <>
Signed-off-by: default avatarLinus Walleij <>
parent a102a9ec
This diff is collapsed.
......@@ -5010,6 +5010,11 @@ L:
S: Maintained
F: drivers/mtd/devices/phram.c
M: Linus Walleij <>
S: Maintained
F: drivers/pinmux/
M: Peter Osterlund <>
S: Maintained
......@@ -56,6 +56,8 @@ source "drivers/pps/Kconfig"
source "drivers/ptp/Kconfig"
source "drivers/pinctrl/Kconfig"
source "drivers/gpio/Kconfig"
source "drivers/w1/Kconfig"
......@@ -5,6 +5,8 @@
# Rewritten to use lists instead of if-statements.
# GPIO must come after pinctrl as gpios may need to mux pins etc
obj-y += pinctrl/
obj-y += gpio/
obj-$(CONFIG_PCI) += pci/
obj-$(CONFIG_PARISC) += parisc/
# PINCTRL infrastructure and drivers
menuconfig PINCTRL
bool "PINCTRL Support"
This enables the PINCTRL subsystem for controlling pins
on chip packages, for example multiplexing pins on primarily
PGA and BGA packages for systems on chip.
If unsure, say N.
config PINMUX
bool "Support pinmux controllers"
Say Y here if you want the pincontrol subsystem to handle pin
multiplexing drivers.
bool "Debug PINCTRL calls"
depends on DEBUG_KERNEL
Say Y here to add some extra checks and diagnostics to PINCTRL calls.
# generic pinmux support
obj-$(CONFIG_PINCTRL) += core.o
obj-$(CONFIG_PINMUX) += pinmux.o
* Core driver for the pin control subsystem
* Copyright (C) 2011 ST-Ericsson SA
* Written on behalf of Linaro for ST-Ericsson
* Based on bits of regulator core, gpio core and clk core
* Author: Linus Walleij <>
* License terms: GNU General Public License (GPL) version 2
#define pr_fmt(fmt) "pinctrl core: " fmt
#include <linux/kernel.h>
#include <linux/init.h>
#include <linux/device.h>
#include <linux/slab.h>
#include <linux/radix-tree.h>
#include <linux/err.h>
#include <linux/list.h>
#include <linux/mutex.h>
#include <linux/spinlock.h>
#include <linux/sysfs.h>
#include <linux/debugfs.h>
#include <linux/seq_file.h>
#include <linux/pinctrl/pinctrl.h>
#include <linux/pinctrl/machine.h>
#include "core.h"
#include "pinmux.h"
/* Global list of pin control devices */
static DEFINE_MUTEX(pinctrldev_list_mutex);
static LIST_HEAD(pinctrldev_list);
static void pinctrl_dev_release(struct device *dev)
struct pinctrl_dev *pctldev = dev_get_drvdata(dev);
const char *pinctrl_dev_get_name(struct pinctrl_dev *pctldev)
/* We're not allowed to register devices without name */
return pctldev->desc->name;
void *pinctrl_dev_get_drvdata(struct pinctrl_dev *pctldev)
return pctldev->driver_data;
* get_pinctrl_dev_from_dev() - look up pin controller device
* @dev: a device pointer, this may be NULL but then devname needs to be
* defined instead
* @devname: the name of a device instance, as returned by dev_name(), this
* may be NULL but then dev needs to be defined instead
* Looks up a pin control device matching a certain device name or pure device
* pointer, the pure device pointer will take precedence.
struct pinctrl_dev *get_pinctrl_dev_from_dev(struct device *dev,
const char *devname)
struct pinctrl_dev *pctldev = NULL;
bool found = false;
list_for_each_entry(pctldev, &pinctrldev_list, node) {
if (dev && &pctldev->dev == dev) {
/* Matched on device pointer */
found = true;
if (devname &&
!strcmp(dev_name(&pctldev->dev), devname)) {
/* Matched on device name */
found = true;
return found ? pctldev : NULL;
struct pin_desc *pin_desc_get(struct pinctrl_dev *pctldev, int pin)
struct pin_desc *pindesc;
unsigned long flags;
spin_lock_irqsave(&pctldev->pin_desc_tree_lock, flags);
pindesc = radix_tree_lookup(&pctldev->pin_desc_tree, pin);
spin_unlock_irqrestore(&pctldev->pin_desc_tree_lock, flags);
return pindesc;
* pin_is_valid() - check if pin exists on controller
* @pctldev: the pin control device to check the pin on
* @pin: pin to check, use the local pin controller index number
* This tells us whether a certain pin exist on a certain pin controller or
* not. Pin lists may be sparse, so some pins may not exist.
bool pin_is_valid(struct pinctrl_dev *pctldev, int pin)
struct pin_desc *pindesc;
if (pin < 0)
return false;
pindesc = pin_desc_get(pctldev, pin);
if (pindesc == NULL)
return false;
return true;
/* Deletes a range of pin descriptors */
static void pinctrl_free_pindescs(struct pinctrl_dev *pctldev,
const struct pinctrl_pin_desc *pins,
unsigned num_pins)
int i;
for (i = 0; i < num_pins; i++) {
struct pin_desc *pindesc;
pindesc = radix_tree_lookup(&pctldev->pin_desc_tree,
if (pindesc != NULL) {
static int pinctrl_register_one_pin(struct pinctrl_dev *pctldev,
unsigned number, const char *name)
struct pin_desc *pindesc;
pindesc = pin_desc_get(pctldev, number);
if (pindesc != NULL) {
pr_err("pin %d already registered on %s\n", number,
return -EINVAL;
pindesc = kzalloc(sizeof(*pindesc), GFP_KERNEL);
if (pindesc == NULL)
return -ENOMEM;
/* Set owner */
pindesc->pctldev = pctldev;
/* Copy optional basic pin info */
if (name)
strlcpy(pindesc->name, name, sizeof(pindesc->name));
radix_tree_insert(&pctldev->pin_desc_tree, number, pindesc);
pr_debug("registered pin %d (%s) on %s\n",
number, name ? name : "(unnamed)", pctldev->desc->name);
return 0;
static int pinctrl_register_pins(struct pinctrl_dev *pctldev,
struct pinctrl_pin_desc const *pins,
unsigned num_descs)
unsigned i;
int ret = 0;
for (i = 0; i < num_descs; i++) {
ret = pinctrl_register_one_pin(pctldev,
pins[i].number, pins[i].name);
if (ret)
return ret;
return 0;
* pinctrl_match_gpio_range() - check if a certain GPIO pin is in range
* @pctldev: pin controller device to check
* @gpio: gpio pin to check taken from the global GPIO pin space
* Tries to match a GPIO pin number to the ranges handled by a certain pin
* controller, return the range or NULL
static struct pinctrl_gpio_range *
pinctrl_match_gpio_range(struct pinctrl_dev *pctldev, unsigned gpio)
struct pinctrl_gpio_range *range = NULL;
/* Loop over the ranges */
list_for_each_entry(range, &pctldev->gpio_ranges, node) {
/* Check if we're in the valid range */
if (gpio >= range->base &&
gpio < range->base + range->npins) {
return range;
return NULL;
* pinctrl_get_device_gpio_range() - find device for GPIO range
* @gpio: the pin to locate the pin controller for
* @outdev: the pin control device if found
* @outrange: the GPIO range if found
* Find the pin controller handling a certain GPIO pin from the pinspace of
* the GPIO subsystem, return the device and the matching GPIO range. Returns
* negative if the GPIO range could not be found in any device.
int pinctrl_get_device_gpio_range(unsigned gpio,
struct pinctrl_dev **outdev,
struct pinctrl_gpio_range **outrange)
struct pinctrl_dev *pctldev = NULL;
/* Loop over the pin controllers */
list_for_each_entry(pctldev, &pinctrldev_list, node) {
struct pinctrl_gpio_range *range;
range = pinctrl_match_gpio_range(pctldev, gpio);
if (range != NULL) {
*outdev = pctldev;
*outrange = range;
return 0;
return -EINVAL;
* pinctrl_add_gpio_range() - register a GPIO range for a controller
* @pctldev: pin controller device to add the range to
* @range: the GPIO range to add
* This adds a range of GPIOs to be handled by a certain pin controller. Call
* this to register handled ranges after registering your pin controller.
void pinctrl_add_gpio_range(struct pinctrl_dev *pctldev,
struct pinctrl_gpio_range *range)
list_add(&range->node, &pctldev->gpio_ranges);
* pinctrl_remove_gpio_range() - remove a range of GPIOs fro a pin controller
* @pctldev: pin controller device to remove the range from
* @range: the GPIO range to remove
void pinctrl_remove_gpio_range(struct pinctrl_dev *pctldev,
struct pinctrl_gpio_range *range)
static int pinctrl_pins_show(struct seq_file *s, void *what)
struct pinctrl_dev *pctldev = s->private;
const struct pinctrl_ops *ops = pctldev->desc->pctlops;
unsigned pin;
seq_printf(s, "registered pins: %d\n", pctldev->desc->npins);
seq_printf(s, "max pin number: %d\n", pctldev->desc->maxpin);
/* The highest pin number need to be included in the loop, thus <= */
for (pin = 0; pin <= pctldev->desc->maxpin; pin++) {
struct pin_desc *desc;
desc = pin_desc_get(pctldev, pin);
/* Pin space may be sparse */
if (desc == NULL)
seq_printf(s, "pin %d (%s) ", pin,
desc->name ? desc->name : "unnamed");
/* Driver-specific info per pin */
if (ops->pin_dbg_show)
ops->pin_dbg_show(pctldev, s, pin);
seq_puts(s, "\n");
return 0;
static int pinctrl_groups_show(struct seq_file *s, void *what)
struct pinctrl_dev *pctldev = s->private;
const struct pinctrl_ops *ops = pctldev->desc->pctlops;
unsigned selector = 0;
/* No grouping */
if (!ops)
return 0;
seq_puts(s, "registered pin groups:\n");
while (ops->list_groups(pctldev, selector) >= 0) {
unsigned *pins;
unsigned num_pins;
const char *gname = ops->get_group_name(pctldev, selector);
int ret;
int i;
ret = ops->get_group_pins(pctldev, selector,
&pins, &num_pins);
if (ret)
seq_printf(s, "%s [ERROR GETTING PINS]\n",
else {
seq_printf(s, "group: %s, pins = [ ", gname);
for (i = 0; i < num_pins; i++)
seq_printf(s, "%d ", pins[i]);
seq_puts(s, "]\n");
return 0;
static int pinctrl_gpioranges_show(struct seq_file *s, void *what)
struct pinctrl_dev *pctldev = s->private;
struct pinctrl_gpio_range *range = NULL;
seq_puts(s, "GPIO ranges handled:\n");
/* Loop over the ranges */
list_for_each_entry(range, &pctldev->gpio_ranges, node) {
seq_printf(s, "%u: %s [%u - %u]\n", range->id, range->name,
range->base, (range->base + range->npins - 1));
return 0;
static int pinctrl_devices_show(struct seq_file *s, void *what)
struct pinctrl_dev *pctldev;
seq_puts(s, "name [pinmux]\n");
list_for_each_entry(pctldev, &pinctrldev_list, node) {
seq_printf(s, "%s ", pctldev->desc->name);
if (pctldev->desc->pmxops)
seq_puts(s, "yes");
seq_puts(s, "no");
seq_puts(s, "\n");
return 0;
static int pinctrl_pins_open(struct inode *inode, struct file *file)
return single_open(file, pinctrl_pins_show, inode->i_private);
static int pinctrl_groups_open(struct inode *inode, struct file *file)
return single_open(file, pinctrl_groups_show, inode->i_private);
static int pinctrl_gpioranges_open(struct inode *inode, struct file *file)
return single_open(file, pinctrl_gpioranges_show, inode->i_private);
static int pinctrl_devices_open(struct inode *inode, struct file *file)
return single_open(file, pinctrl_devices_show, NULL);
static const struct file_operations pinctrl_pins_ops = {
.open = pinctrl_pins_open,
.read = seq_read,
.llseek = seq_lseek,
.release = single_release,
static const struct file_operations pinctrl_groups_ops = {
.open = pinctrl_groups_open,
.read = seq_read,
.llseek = seq_lseek,
.release = single_release,
static const struct file_operations pinctrl_gpioranges_ops = {
.open = pinctrl_gpioranges_open,
.read = seq_read,
.llseek = seq_lseek,
.release = single_release,
static const struct file_operations pinctrl_devices_ops = {
.open = pinctrl_devices_open,
.read = seq_read,
.llseek = seq_lseek,
.release = single_release,
static struct dentry *debugfs_root;
static void pinctrl_init_device_debugfs(struct pinctrl_dev *pctldev)
static struct dentry *device_root;
device_root = debugfs_create_dir(dev_name(&pctldev->dev),
if (IS_ERR(device_root) || !device_root) {
pr_warn("failed to create debugfs directory for %s\n",
debugfs_create_file("pins", S_IFREG | S_IRUGO,
device_root, pctldev, &pinctrl_pins_ops);
debugfs_create_file("pingroups", S_IFREG | S_IRUGO,
device_root, pctldev, &pinctrl_groups_ops);
debugfs_create_file("gpio-ranges", S_IFREG | S_IRUGO,
device_root, pctldev, &pinctrl_gpioranges_ops);
pinmux_init_device_debugfs(device_root, pctldev);
static void pinctrl_init_debugfs(void)
debugfs_root = debugfs_create_dir("pinctrl", NULL);
if (IS_ERR(debugfs_root) || !debugfs_root) {
pr_warn("failed to create debugfs directory\n");
debugfs_root = NULL;
debugfs_create_file("pinctrl-devices", S_IFREG | S_IRUGO,
debugfs_root, NULL, &pinctrl_devices_ops);
#else /* CONFIG_DEBUG_FS */
static void pinctrl_init_device_debugfs(struct pinctrl_dev *pctldev)
static void pinctrl_init_debugfs(void)
* pinctrl_register() - register a pin controller device
* @pctldesc: descriptor for this pin controller
* @dev: parent device for this pin controller
* @driver_data: private pin controller data for this pin controller
struct pinctrl_dev *pinctrl_register(struct pinctrl_desc *pctldesc,
struct device *dev, void *driver_data)
static atomic_t pinmux_no = ATOMIC_INIT(0);
struct pinctrl_dev *pctldev;
int ret;
if (pctldesc == NULL)
return NULL;
if (pctldesc->name == NULL)
return NULL;
/* If we're implementing pinmuxing, check the ops for sanity */
if (pctldesc->pmxops) {
ret = pinmux_check_ops(pctldesc->pmxops);
if (ret) {
pr_err("%s pinmux ops lacks necessary functions\n",
return NULL;
pctldev = kzalloc(sizeof(struct pinctrl_dev), GFP_KERNEL);
if (pctldev == NULL)
return NULL;
/* Initialize pin control device struct */
pctldev->owner = pctldesc->owner;
pctldev->desc = pctldesc;
pctldev->driver_data = driver_data;
INIT_RADIX_TREE(&pctldev->pin_desc_tree, GFP_KERNEL);
/* Register device */
pctldev->dev.parent = dev;
dev_set_name(&pctldev->dev, "pinctrl.%d",
atomic_inc_return(&pinmux_no) - 1);
pctldev->dev.release = pinctrl_dev_release;
ret = device_register(&pctldev->dev);
if (ret != 0) {
pr_err("error in device registration\n");
goto out_reg_dev_err;
dev_set_drvdata(&pctldev->dev, pctldev);
/* Register all the pins */
pr_debug("try to register %d pins on %s...\n",
pctldesc->npins, pctldesc->name);
ret = pinctrl_register_pins(pctldev, pctldesc->pins, pctldesc->npins);
if (ret) {
pr_err("error during pin registration\n");
pinctrl_free_pindescs(pctldev, pctldesc->pins,
goto out_reg_pins_err;
list_add(&pctldev->node, &pinctrldev_list);
return pctldev;
return NULL;
* pinctrl_unregister() - unregister pinmux
* @pctldev: pin controller to unregister