path: root/Documentation/driver-api/pinctl.rst

===============================
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),
		.owner = THIS_MODULE,
	};

	int __init foo_probe(void)
	{
		int error;

		struct pinctrl_dev *pctl;

		error = pinctrl_register_and_init(&foo_desc, <PARENT>,
						  NULL, &pctl);
		if (error)
			return error;

		return pinctrl_enable(pctl);
	}

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,