pinctrl: pinctrl.txt: standardize document format

===============================

PINCTRL (PIN CONTROL) subsystem

===============================

This document outlines the pin control subsystem in Linux

This subsystem deals with:

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:

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

        A   B   C   D   E   F   G   H

   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:

this in our driver::

	#include <linux/pinctrl/pinctrl.h>

		struct pinctrl_dev *pctl;

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

		error = pinctrl_register_and_init(&foo_desc, <PARENT>,

						  NULL, &pctl);

		if (error)

			return error;

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):

standard too (all these pads had names, too)::

     0 ..... 104

on { 24, 25 }.

These two groups are presented to the pin control subsystem by implementing

some generic pinctrl_ops like this:

some generic pinctrl_ops like this::

	#include <linux/pinctrl/pinctrl.h>

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:

configuration in the pin controller ops like this::

	#include <linux/pinctrl/pinctrl.h>

	#include <linux/pinctrl/pinconf.h>

may be muxing several GPIO ranges (typically SoCs that have one set of pins,

but internally several GPIO silicon blocks, each modelled as a struct

gpio_chip) any number of GPIO ranges can be added to a pin controller instance

like this:

like this::

	struct gpio_chip chip_a;

	struct gpio_chip chip_b;

The above examples assume the mapping between the GPIOs and pins is

linear. If the mapping is sparse or haphazard, an array of arbitrary pin

numbers can be encoded in the range like this:

numbers can be encoded in the range like this::

	static const unsigned range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 };

In this case the pin_base property will be ignored. If the name of a pin

group is known, the pins and npins elements of the above structure can be

initialised using the function pinctrl_get_group_pins(), e.g. for pin

group "foo":

group "foo"::

pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins, &gpio_range.npins);

	pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins,

			       &gpio_range.npins);

When GPIO-specific functions in the pin control subsystem are called, these

ranges will be used to look up the appropriate pin controller by inspecting

system, even though the framework makes it possible to also change the function

at runtime.

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

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

        A   B   C   D   E   F   G   H

      +---+

  In the example case we can define that this particular machine shall

  use device spi0 with pinmux function fspi0 group gspi0 and i2c0 on function

  fi2c0 group gi2c0, on the primary pin controller, we get mappings

  like these:

  like these::

	{

		{"map-spi0", spi0, pinctrl0, fspi0, gspi0},

A simple driver for the above example will work by setting bits 0, 1, 2, 3 or 4

into some register named MUX to select a certain function with a certain

group of pins would work something like this:

group of pins would work something like this::

	#include <linux/pinctrl/pinctrl.h>

	#include <linux/pinctrl/pinmux.h>

The GPIO portions of a pin and its relation to a certain pin controller

configuration and muxing logic can be constructed in several ways. Here

are two examples:

are two examples::

     (A)

                       pin config

consumers on hardware of this type. The pinctrl driver should set this flag

accordingly.

::

     (B)

                       pin config

a certain pin config setting. Look in e.g. <linux/pinctrl/pinconf-generic.h>

and you find this in the documentation:

  PIN_CONFIG_OUTPUT: this will configure the pin in output, use argument

  PIN_CONFIG_OUTPUT:

     this will configure the pin in output, use argument

     1 to indicate high level, argument 0 to indicate low level.

So it is perfectly possible to push a pin into "GPIO mode" and drive the

line low as part of the usual pin control map. So for example your UART

driver may look like this:

driver may look like this::

	#include <linux/pinctrl/consumer.h>

And your machine configuration may look like this:

--------------------------------------------------

::

	static unsigned long uart_default_mode[] = {

		PIN_CONF_PACKED(PIN_CONFIG_DRIVE_PUSH_PULL, 0),

	};

Board/machine configuration

==================================

===========================

Boards and machines define how a certain complete running system is put

together, including how GPIOs and devices are muxed, how regulators are

A pin controller configuration for a machine looks pretty much like a simple

regulator configuration, so for the example array above we want to enable i2c

and spi on the second function mapping:

and spi on the second function mapping::

	#include <linux/pinctrl/machine.h>

As you can see we may have several pin controllers on the system and thus

we need to specify which one of them contains the functions we wish to map.

You register this pinmux mapping to the pinmux subsystem by simply:

You register this pinmux mapping to the pinmux subsystem by simply::

       ret = pinctrl_register_mappings(mapping, ARRAY_SIZE(mapping));

Since the above construct is pretty common there is a helper macro to make

it even more compact which assumes you want to use pinctrl-foo and position

0 for mapping, for example:

0 for mapping, for example::

	static struct pinctrl_map mapping[] __initdata = {

	PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT, "pinctrl-foo", NULL, "i2c0"),

		PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT,

				  "pinctrl-foo", NULL, "i2c0"),

	};

The mapping table may also contain pin configuration entries. It's common for

each pin/group to have a number of configuration entries that affect it, so

the table entries for configuration reference an array of config parameters

and values. An example using the convenience macros is shown below:

and values. An example using the convenience macros is shown below::

	static unsigned long i2c_grp_configs[] = {

		FOO_PIN_DRIVEN,

	};

	static struct pinctrl_map mapping[] __initdata = {

	PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", "i2c0"),

	PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", i2c_grp_configs),

	PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0scl", i2c_pin_configs),

	PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0sda", i2c_pin_configs),

		PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,

				  "pinctrl-foo", "i2c0", "i2c0"),

		PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,

				      "pinctrl-foo", "i2c0", i2c_grp_configs),

		PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,

				    "pinctrl-foo", "i2c0scl", i2c_pin_configs),

		PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,

				    "pinctrl-foo", "i2c0sda", i2c_pin_configs),

	};

Finally, some devices expect the mapping table to contain certain specific

configuration, the mapping table must still contain those named states, in

order to explicitly indicate that the states were provided and intended to

be empty. Table entry macro PIN_MAP_DUMMY_STATE serves the purpose of defining

a named state without causing any pin controller to be programmed:

a named state without causing any pin controller to be programmed::

	static struct pinctrl_map mapping[] __initdata = {

		PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),

================

As it is possible to map a function to different groups of pins an optional

.group can be specified like this:

.group can be specified like this::

	...

	{

groups of pins, say for example in the mmc0 example above, where you can

additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all

three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the

case), we define a mapping like this:

case), we define a mapping like this::

	...

	{

	...

The result of grabbing this mapping from the device with something like

this (see next paragraph):

this (see next paragraph)::

	p = devm_pinctrl_get(dev);

	s = pinctrl_lookup_state(p, "8bit");

	ret = pinctrl_select_state(p, s);

or more simply:

or more simply::

	p = devm_pinctrl_get_select(dev, "8bit");

current in sleep mode.

A driver may request a certain control state to be activated, usually just the

default state like this:

default state like this::

	#include <linux/pinctrl/consumer.h>

Again, it is discouraged to let drivers lookup and select pin control states

themselves, but again sometimes this is unavoidable.

So say that your driver is fetching its resources like this:

So say that your driver is fetching its resources like this::

	#include <linux/pinctrl/consumer.h>

	#include <linux/gpio.h>

device has been registered.

This occurs for mapping table entries where the client device name is equal

to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT.

to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT::

	{

		.dev_name = "pinctrl-foo",

Since it may be common to request the core to hog a few always-applicable

mux settings on the primary pin controller, there is a convenience macro for

this:

this::

PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */, "power_func")

	PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */,

				      "power_func")

This gives the exact same result as the above construction.

This snippet first initializes a state object for both groups (in foo_probe()),

then muxes the function in the pins defined by group A, and finally muxes it in

on the pins defined by group B:

on the pins defined by group B::

	#include <linux/pinctrl/consumer.h>