path: root/Documentation/pinctrl.txt

PINCTRL (PIN CONTROL) subsystem
This document outlines the pin control subsystem in Linux

This subsystem deals with:

- Enumerating and naming controllable pins

- Multiplexing of pins, pads, fingers (etc) see below for details

- Configuration of pins, pads, fingers (etc), such as software-controlled
  biasing and driving mode specific pins, such as pull-up/down, open drain,
  load capacitance etc.

Top-level interface
===================

Definition of PIN CONTROLLER:

- A pin controller is a piece of hardware, usually a set of registers, that
  can control PINs. It may be able to multiplex, bias, set load capacitance,
  set drive strength, etc. for individual pins or groups of pins.

Definition of PIN:

- PINS are equal to pads, fingers, balls or whatever packaging input or
  output line you want to control and these are denoted by unsigned integers
  in the range 0..maxpin. This numberspace is local to each PIN CONTROLLER, so
  there may be several such number spaces in a system. This pin space may
  be sparse - i.e. there may be gaps in the space with numbers where no
  pin exists.

When a PIN CONTROLLER is instantiated, it will register a descriptor to the
pin control framework, and this descriptor contains an array of pin descriptors
describing the pins handled by this specific pin controller.

Here is an example of a PGA (Pin Grid Array) chip seen from underneath:

        A   B   C   D   E   F   G   H

   8    o   o   o   o   o   o   o   o

   7    o   o   o   o   o   o   o   o

   6    o   o   o   o   o   o   o   o

   5    o   o   o   o   o   o   o   o

   4    o   o   o   o   o   o   o   o

   3    o   o   o   o   o   o   o   o

   2    o   o   o   o   o   o   o   o

   1    o   o   o   o   o   o   o   o

To register a pin controller and name all the pins on this package we can do
this in our driver:

#include <linux/pinctrl/pinctrl.h>

const struct pinctrl_pin_desc foo_pins[] = {
      PINCTRL_PIN(0, "A8"),
      PINCTRL_PIN(1, "B8"),
      PINCTRL_PIN(2, "C8"),
      ...
      PINCTRL_PIN(61, "F1"),
      PINCTRL_PIN(62, "G1"),
      PINCTRL_PIN(63, "H1"),
};

static struct pinctrl_desc foo_desc = {
	.name = "foo",
	.pins = foo_pins,
	.npins = ARRAY_SIZE(foo_pins),
	.maxpin = 63,
	.owner = THIS_MODULE,
};

int __init foo_probe(void)
{
	struct pinctrl_dev *pctl;

	pctl = pinctrl_register(&foo_desc, <PARENT>, NULL);
	if (!pctl)
		pr_err("could not register foo pin driver\n");
}

To enable the pinctrl subsystem and the subgroups for PINMUX and PINCONF and
selected drivers, you need to select them from your machine's Kconfig entry,
since these are so tightly integrated with the machines they are used on.
See for example arch/arm/mach-u300/Kconfig for an example.

Pins usually have fancier names than this. You can find these in the datasheet
for your chip. Notice that the core pinctrl.h file provides a fancy macro
called PINCTRL_PIN() to create the struct entries. As you can see I enumerated
the pins from 0 in the upper left corner to 63 in the lower right corner.
This enumeration was arbitrarily chosen, in practice you need to think
through your numbering system so that it matches the layout of registers
and such things in your driver, or the code may become complicated. You must
also consider matching of offsets to the GPIO ranges that may be handled by
the pin controller.

For a padring with 467 pads, as opposed to actual pins, I used an enumeration
like this, walking around the edge of the chip, which seems to be industry
standard too (all these pads had names, too):


     0 ..... 104
   466        105
     .        .
     .        .
   358        224
    357 .... 225


Pin groups
==========

Many controllers need to deal with groups of pins, so the pin controller
subsystem has a mechanism for enumerating groups of pins and retrieving the
actual enumerated pins that are part of a certain group.

For example, say that we have a group of pins dealing with an SPI interface
on { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins
on { 24, 25 }.

These two groups are presented to the pin control subsystem by implementing
some generic pinctrl_ops like this:

#include <linux/pinctrl/pinctrl.h>

struct foo_group {
	const char *name;
	const unsigned int *pins;
	const unsigned num_pins;
};

static const unsigned int spi0_pins[] = { 0, 8, 16, 24 };
static const unsigned int i2c0_pins[] = { 24, 25 };

static const struct foo_group foo_groups[] = {
	{
		.name = "spi0_grp",
		.pins = spi0_pins,
		.num_pins = ARRAY_SIZE(spi0_pins),
	},
	{
		.name = "i2c0_grp",
		.pins = i2c0_pins,
		.num_pins = ARRAY_SIZE(i2c0_pins),
	},
};


static int foo_get_groups_count(struct pinctrl_dev *pctldev)
{
	return ARRAY_SIZE(foo_groups);
}

static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
				       unsigned selector)
{
	return foo_groups[selector].name;
}

static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
			       unsigned ** const pins,
			       unsigned * const num_pins)
{
	*pins = (unsigned *) foo_groups[selector].pins;
	*num_pins = foo_groups[selector].num_pins;
	return 0;
}

static struct pinctrl_ops foo_pctrl_ops = {
	.get_groups_count = foo_get_groups_count,
	.get_group_name = foo_get_group_name,
	.get_group_pins = foo_get_group_pins,
};


static struct pinctrl_desc foo_desc = {
       ...
       .pctlops = &foo_pctrl_ops,
};

The pin control subsystem will call the .get_groups_count() function to
determine the total number of legal selectors, then it will call the other functions
to retrieve the name and pins of the group. Maintaining the data structure of
the groups is up to the driver, this is just a simple example - in practice you
may need more entries in your group structure, for example specific register
ranges associated with each group and so on.


Pin configuration
=================

Pins can sometimes be software-configured in various ways, mostly related
to their electronic properties when used as inputs or outputs. For example you
may be able to make an output pin high impedance, or "tristate" meaning it is
effectively disconnected. You may be able to connect an input pin to VDD or GND
using a certain resistor value - pull up and pull down - so that the pin has a
stable value when nothing is driving the rail it is connected to, or when it's
unconnected.

Pin configuration can be programmed by adding configuration entries into the
mapping table; see section "Board/machine configuration" below.

The format and meaning of the configuration parameter, PLATFORM_X_PULL_UP
above, is entirely defined by the pin controller driver.

The pin configuration driver implements callbacks for changing pin
configuration in the pin controller ops like this:

#include <linux/pinctrl/pinctrl.h>
#include <linux/pinctrl/pinconf.h>
#include "platform_x_pindefs.h"

static int foo_pin_config_get(struct pinctrl_dev *pctldev,
		    unsigned offset,
		    unsigned long *config)
{
	struct my_conftype conf;

	... Find setting for pin @ offset ...

	*config = (unsigned long) conf;
}

static int foo_pin_config_set(struct pinctrl_dev *pctldev,
		    unsigned offset,
		    unsigned long config)
{
	struct my_conftype *conf = (struct my_conftype *) config;

	switch (conf) {
		case PLATFORM_X_PULL_UP:
		...
		}
	}
}

static int foo_pin_config_group_get (struct pinctrl_dev *pctldev,
		    unsigned selector,
		    unsigned long *config)
{
	...
}

static int foo_pin_config_group_set (struct pinctrl_dev *pctldev,
		    unsigned selector,
		    unsigned long config)
{
	...
}

static struct pinconf_ops foo_pconf_ops = {
	.pin_config_get = foo_pin_config_get,
	.pin_config_set = foo_pin_config_set,
	.pin_config_group_get = foo_pin_config_group_get,
	.pin_config_group_set = foo_pin_config_group_set,
};

/* Pin config operations are handled by some pin controller */
static struct pinctrl_desc foo_desc = {
	...
	.confops = &foo_pconf_ops,
};

Since some controllers have special logic for handling entire groups of pins
they can exploit the special whole-group pin control function. The
pin_config_group_set() callback is allowed to return the error code -EAGAIN,
for groups it does not want to handle, or if it just wants to do so