mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-08-23 17:30:02 +00:00
![Andy Shevchenko](/assets/img/avatar_default.png)
Documentation incorrectly refers to struct pinctrl_desc, where no such flag is
available. Replace the name of the struct.
Fixes: commit 8c4c201634
("pinctrl: move strict option to pinmux_ops")
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
1419 lines
50 KiB
Text
1419 lines
50 KiB
Text
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)
|
|
{
|
|
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,
|
|
const unsigned **pins,
|
|
unsigned *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 some
|
|
group-level handling and then fall through to iterate over all pins, in which
|
|
case each individual pin will be treated by separate pin_config_set() calls as
|
|
well.
|
|
|
|
|
|
Interaction with the GPIO subsystem
|
|
===================================
|
|
|
|
The GPIO drivers may want to perform operations of various types on the same
|
|
physical pins that are also registered as pin controller pins.
|
|
|
|
First and foremost, the two subsystems can be used as completely orthogonal,
|
|
see the section named "pin control requests from drivers" and
|
|
"drivers needing both pin control and GPIOs" below for details. But in some
|
|
situations a cross-subsystem mapping between pins and GPIOs is needed.
|
|
|
|
Since the pin controller subsystem has its pinspace local to the pin controller
|
|
we need a mapping so that the pin control subsystem can figure out which pin
|
|
controller handles control of a certain GPIO pin. Since a single pin controller
|
|
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:
|
|
|
|
struct gpio_chip chip_a;
|
|
struct gpio_chip chip_b;
|
|
|
|
static struct pinctrl_gpio_range gpio_range_a = {
|
|
.name = "chip a",
|
|
.id = 0,
|
|
.base = 32,
|
|
.pin_base = 32,
|
|
.npins = 16,
|
|
.gc = &chip_a;
|
|
};
|
|
|
|
static struct pinctrl_gpio_range gpio_range_b = {
|
|
.name = "chip b",
|
|
.id = 0,
|
|
.base = 48,
|
|
.pin_base = 64,
|
|
.npins = 8,
|
|
.gc = &chip_b;
|
|
};
|
|
|
|
{
|
|
struct pinctrl_dev *pctl;
|
|
...
|
|
pinctrl_add_gpio_range(pctl, &gpio_range_a);
|
|
pinctrl_add_gpio_range(pctl, &gpio_range_b);
|
|
}
|
|
|
|
So this complex system has one pin controller handling two different
|
|
GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and
|
|
"chip b" have different .pin_base, which means a start pin number of the
|
|
GPIO range.
|
|
|
|
The GPIO range of "chip a" starts from the GPIO base of 32 and actual
|
|
pin range also starts from 32. However "chip b" has different starting
|
|
offset for the GPIO range and pin range. The GPIO range of "chip b" starts
|
|
from GPIO number 48, while the pin range of "chip b" starts from 64.
|
|
|
|
We can convert a gpio number to actual pin number using this "pin_base".
|
|
They are mapped in the global GPIO pin space at:
|
|
|
|
chip a:
|
|
- GPIO range : [32 .. 47]
|
|
- pin range : [32 .. 47]
|
|
chip b:
|
|
- GPIO range : [48 .. 55]
|
|
- pin range : [64 .. 71]
|
|
|
|
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:
|
|
|
|
static const unsigned range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 };
|
|
|
|
static struct pinctrl_gpio_range gpio_range = {
|
|
.name = "chip",
|
|
.id = 0,
|
|
.base = 32,
|
|
.pins = &range_pins,
|
|
.npins = ARRAY_SIZE(range_pins),
|
|
.gc = &chip;
|
|
};
|
|
|
|
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":
|
|
|
|
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
|
|
and matching the pin to the pin ranges across all controllers. When a
|
|
pin controller handling the matching range is found, GPIO-specific functions
|
|
will be called on that specific pin controller.
|
|
|
|
For all functionalities dealing with pin biasing, pin muxing etc, the pin
|
|
controller subsystem will look up the corresponding pin number from the passed
|
|
in gpio number, and use the range's internals to retrieve a pin number. After
|
|
that, the subsystem passes it on to the pin control driver, so the driver
|
|
will get a pin number into its handled number range. Further it is also passed
|
|
the range ID value, so that the pin controller knows which range it should
|
|
deal with.
|
|
|
|
Calling pinctrl_add_gpio_range from pinctrl driver is DEPRECATED. Please see
|
|
section 2.1 of Documentation/devicetree/bindings/gpio/gpio.txt on how to bind
|
|
pinctrl and gpio drivers.
|
|
|
|
|
|
PINMUX interfaces
|
|
=================
|
|
|
|
These calls use the pinmux_* naming prefix. No other calls should use that
|
|
prefix.
|
|
|
|
|
|
What is pinmuxing?
|
|
==================
|
|
|
|
PINMUX, also known as padmux, ballmux, alternate functions or mission modes
|
|
is a way for chip vendors producing some kind of electrical packages to use
|
|
a certain physical pin (ball, pad, finger, etc) for multiple mutually exclusive
|
|
functions, depending on the application. By "application" in this context
|
|
we usually mean a way of soldering or wiring the package into an electronic
|
|
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:
|
|
|
|
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 |
|
|
+-------+-------+-------+---+---+
|
|
|
|
This is not tetris. The game to think of is chess. Not all PGA/BGA packages
|
|
are chessboard-like, big ones have "holes" in some arrangement according to
|
|
different design patterns, but we're using this as a simple example. Of the
|
|
pins you see some will be taken by things like a few VCC and GND to feed power
|
|
to the chip, and quite a few will be taken by large ports like an external
|
|
memory interface. The remaining pins will often be subject to pin multiplexing.
|
|
|
|
The example 8x8 PGA package above will have pin numbers 0 through 63 assigned
|
|
to its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using
|
|
pinctrl_register_pins() and a suitable data set as shown earlier.
|
|
|
|
In this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port
|
|
(these are four pins: CLK, RXD, TXD, FRM). In that case, pin B5 can be used as
|
|
some general-purpose GPIO pin. However, in another setting, pins { A5, B5 } can
|
|
be used as an I2C port (these are just two pins: SCL, SDA). Needless to say,
|
|
we cannot use the SPI port and I2C port at the same time. However in the inside
|
|
of the package the silicon performing the SPI logic can alternatively be routed
|
|
out on pins { G4, G3, G2, G1 }.
|
|
|
|
On the bottom row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something
|
|
special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will
|
|
consume 2, 4 or 8 pins respectively, so either { A1, B1 } are taken or
|
|
{ A1, B1, C1, D1 } or all of them. If we use all 8 bits, we cannot use the SPI
|
|
port on pins { G4, G3, G2, G1 } of course.
|
|
|
|
This way the silicon blocks present inside the chip can be multiplexed "muxed"
|
|
out on different pin ranges. Often contemporary SoC (systems on chip) will
|
|
contain several I2C, SPI, SDIO/MMC, etc silicon blocks that can be routed to
|
|
different pins by pinmux settings.
|
|
|
|
Since general-purpose I/O pins (GPIO) are typically always in shortage, it is
|
|
common to be able to use almost any pin as a GPIO pin if it is not currently
|
|
in use by some other I/O port.
|
|
|
|
|
|
Pinmux conventions
|
|
==================
|
|
|
|
The purpose of the pinmux functionality in the pin controller subsystem is to
|
|
abstract and provide pinmux settings to the devices you choose to instantiate
|
|
in your machine configuration. It is inspired by the clk, GPIO and regulator
|
|
subsystems, so devices will request their mux setting, but it's also possible
|
|
to request a single pin for e.g. GPIO.
|
|
|
|
Definitions:
|
|
|
|
- FUNCTIONS can be switched in and out by a driver residing with the pin
|
|
control subsystem in the drivers/pinctrl/* directory of the kernel. The
|
|
pin control driver knows the possible functions. In the example above you can
|
|
identify three pinmux functions, one for spi, one for i2c and one for mmc.
|
|
|
|
- FUNCTIONS are assumed to be enumerable from zero in a one-dimensional array.
|
|
In this case the array could be something like: { spi0, i2c0, mmc0 }
|
|
for the three available functions.
|
|
|
|
- FUNCTIONS have PIN GROUPS as defined on the generic level - so a certain
|
|
function is *always* associated with a certain set of pin groups, could
|
|
be just a single one, but could also be many. In the example above the
|
|
function i2c is associated with the pins { A5, B5 }, enumerated as
|
|
{ 24, 25 } in the controller pin space.
|
|
|
|
The Function spi is associated with pin groups { A8, A7, A6, A5 }
|
|
and { G4, G3, G2, G1 }, which are enumerated as { 0, 8, 16, 24 } and
|
|
{ 38, 46, 54, 62 } respectively.
|
|
|
|
Group names must be unique per pin controller, no two groups on the same
|
|
controller may have the same name.
|
|
|
|
- The combination of a FUNCTION and a PIN GROUP determine a certain function
|
|
for a certain set of pins. The knowledge of the functions and pin groups
|
|
and their machine-specific particulars are kept inside the pinmux driver,
|
|
from the outside only the enumerators are known, and the driver core can
|
|
request:
|
|
|
|
- The name of a function with a certain selector (>= 0)
|
|
- A list of groups associated with a certain function
|
|
- That a certain group in that list to be activated for a certain function
|
|
|
|
As already described above, pin groups are in turn self-descriptive, so
|
|
the core will retrieve the actual pin range in a certain group from the
|
|
driver.
|
|
|
|
- FUNCTIONS and GROUPS on a certain PIN CONTROLLER are MAPPED to a certain
|
|
device by the board file, device tree or similar machine setup configuration
|
|
mechanism, similar to how regulators are connected to devices, usually by
|
|
name. Defining a pin controller, function and group thus uniquely identify
|
|
the set of pins to be used by a certain device. (If only one possible group
|
|
of pins is available for the function, no group name need to be supplied -
|
|
the core will simply select the first and only group available.)
|
|
|
|
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:
|
|
|
|
{
|
|
{"map-spi0", spi0, pinctrl0, fspi0, gspi0},
|
|
{"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0}
|
|
}
|
|
|
|
Every map must be assigned a state name, pin controller, device and
|
|
function. The group is not compulsory - if it is omitted the first group
|
|
presented by the driver as applicable for the function will be selected,
|
|
which is useful for simple cases.
|
|
|
|
It is possible to map several groups to the same combination of device,
|
|
pin controller and function. This is for cases where a certain function on
|
|
a certain pin controller may use different sets of pins in different
|
|
configurations.
|
|
|
|
- PINS for a certain FUNCTION using a certain PIN GROUP on a certain
|
|
PIN CONTROLLER are provided on a first-come first-serve basis, so if some
|
|
other device mux setting or GPIO pin request has already taken your physical
|
|
pin, you will be denied the use of it. To get (activate) a new setting, the
|
|
old one has to be put (deactivated) first.
|
|
|
|
Sometimes the documentation and hardware registers will be oriented around
|
|
pads (or "fingers") rather than pins - these are the soldering surfaces on the
|
|
silicon inside the package, and may or may not match the actual number of
|
|
pins/balls underneath the capsule. Pick some enumeration that makes sense to
|
|
you. Define enumerators only for the pins you can control if that makes sense.
|
|
|
|
Assumptions:
|
|
|
|
We assume that the number of possible function maps to pin groups is limited by
|
|
the hardware. I.e. we assume that there is no system where any function can be
|
|
mapped to any pin, like in a phone exchange. So the available pin groups for
|
|
a certain function will be limited to a few choices (say up to eight or so),
|
|
not hundreds or any amount of choices. This is the characteristic we have found
|
|
by inspecting available pinmux hardware, and a necessary assumption since we
|
|
expect pinmux drivers to present *all* possible function vs pin group mappings
|
|
to the subsystem.
|
|
|
|
|
|
Pinmux drivers
|
|
==============
|
|
|
|
The pinmux core takes care of preventing conflicts on pins and calling
|
|
the pin controller driver to execute different settings.
|
|
|
|
It is the responsibility of the pinmux driver to impose further restrictions
|
|
(say for example infer electronic limitations due to load, etc.) to determine
|
|
whether or not the requested function can actually be allowed, and in case it
|
|
is possible to perform the requested mux setting, poke the hardware so that
|
|
this happens.
|
|
|
|
Pinmux drivers are required to supply a few callback functions, some are
|
|
optional. Usually the set_mux() function is implemented, writing values into
|
|
some certain registers to activate a certain mux setting for a certain pin.
|
|
|
|
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:
|
|
|
|
#include <linux/pinctrl/pinctrl.h>
|
|
#include <linux/pinctrl/pinmux.h>
|
|
|
|
struct foo_group {
|
|
const char *name;
|
|
const unsigned int *pins;
|
|
const unsigned num_pins;
|
|
};
|
|
|
|
static const unsigned spi0_0_pins[] = { 0, 8, 16, 24 };
|
|
static const unsigned spi0_1_pins[] = { 38, 46, 54, 62 };
|
|
static const unsigned i2c0_pins[] = { 24, 25 };
|
|
static const unsigned mmc0_1_pins[] = { 56, 57 };
|
|
static const unsigned mmc0_2_pins[] = { 58, 59 };
|
|
static const unsigned mmc0_3_pins[] = { 60, 61, 62, 63 };
|
|
|
|
static const struct foo_group foo_groups[] = {
|
|
{
|
|
.name = "spi0_0_grp",
|
|
.pins = spi0_0_pins,
|
|
.num_pins = ARRAY_SIZE(spi0_0_pins),
|
|
},
|
|
{
|
|
.name = "spi0_1_grp",
|
|
.pins = spi0_1_pins,
|
|
.num_pins = ARRAY_SIZE(spi0_1_pins),
|
|
},
|
|
{
|
|
.name = "i2c0_grp",
|
|
.pins = i2c0_pins,
|
|
.num_pins = ARRAY_SIZE(i2c0_pins),
|
|
},
|
|
{
|
|
.name = "mmc0_1_grp",
|
|
.pins = mmc0_1_pins,
|
|
.num_pins = ARRAY_SIZE(mmc0_1_pins),
|
|
},
|
|
{
|
|
.name = "mmc0_2_grp",
|
|
.pins = mmc0_2_pins,
|
|
.num_pins = ARRAY_SIZE(mmc0_2_pins),
|
|
},
|
|
{
|
|
.name = "mmc0_3_grp",
|
|
.pins = mmc0_3_pins,
|
|
.num_pins = ARRAY_SIZE(mmc0_3_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,
|
|
};
|
|
|
|
struct foo_pmx_func {
|
|
const char *name;
|
|
const char * const *groups;
|
|
const unsigned num_groups;
|
|
};
|
|
|
|
static const char * const spi0_groups[] = { "spi0_0_grp", "spi0_1_grp" };
|
|
static const char * const i2c0_groups[] = { "i2c0_grp" };
|
|
static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp",
|
|
"mmc0_3_grp" };
|
|
|
|
static const struct foo_pmx_func foo_functions[] = {
|
|
{
|
|
.name = "spi0",
|
|
.groups = spi0_groups,
|
|
.num_groups = ARRAY_SIZE(spi0_groups),
|
|
},
|
|
{
|
|
.name = "i2c0",
|
|
.groups = i2c0_groups,
|
|
.num_groups = ARRAY_SIZE(i2c0_groups),
|
|
},
|
|
{
|
|
.name = "mmc0",
|
|
.groups = mmc0_groups,
|
|
.num_groups = ARRAY_SIZE(mmc0_groups),
|
|
},
|
|
};
|
|
|
|
static int foo_get_functions_count(struct pinctrl_dev *pctldev)
|
|
{
|
|
return ARRAY_SIZE(foo_functions);
|
|
}
|
|
|
|
static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector)
|
|
{
|
|
return foo_functions[selector].name;
|
|
}
|
|
|
|
static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector,
|
|
const char * const **groups,
|
|
unsigned * const num_groups)
|
|
{
|
|
*groups = foo_functions[selector].groups;
|
|
*num_groups = foo_functions[selector].num_groups;
|
|
return 0;
|
|
}
|
|
|
|
static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned selector,
|
|
unsigned group)
|
|
{
|
|
u8 regbit = (1 << selector + group);
|
|
|
|
writeb((readb(MUX)|regbit), MUX)
|
|
return 0;
|
|
}
|
|
|
|
static struct pinmux_ops foo_pmxops = {
|
|
.get_functions_count = foo_get_functions_count,
|
|
.get_function_name = foo_get_fname,
|
|
.get_function_groups = foo_get_groups,
|
|
.set_mux = foo_set_mux,
|
|
.strict = true,
|
|
};
|
|
|
|
/* Pinmux operations are handled by some pin controller */
|
|
static struct pinctrl_desc foo_desc = {
|
|
...
|
|
.pctlops = &foo_pctrl_ops,
|
|
.pmxops = &foo_pmxops,
|
|
};
|
|
|
|
In the example activating muxing 0 and 1 at the same time setting bits
|
|
0 and 1, uses one pin in common so they would collide.
|
|
|
|
The beauty of the pinmux subsystem is that since it keeps track of all
|
|
pins and who is using them, it will already have denied an impossible
|
|
request like that, so the driver does not need to worry about such
|
|
things - when it gets a selector passed in, the pinmux subsystem makes
|
|
sure no other device or GPIO assignment is already using the selected
|
|
pins. Thus bits 0 and 1 in the control register will never be set at the
|
|
same time.
|
|
|
|
All the above functions are mandatory to implement for a pinmux driver.
|
|
|
|
|
|
Pin control interaction with the GPIO subsystem
|
|
===============================================
|
|
|
|
Note that the following implies that the use case is to use a certain pin
|
|
from the Linux kernel using the API in <linux/gpio.h> with gpio_request()
|
|
and similar functions. There are cases where you may be using something
|
|
that your datasheet calls "GPIO mode", but actually is just an electrical
|
|
configuration for a certain device. See the section below named
|
|
"GPIO mode pitfalls" for more details on this scenario.
|
|
|
|
The public pinmux API contains two functions named pinctrl_request_gpio()
|
|
and pinctrl_free_gpio(). These two functions shall *ONLY* be called from
|
|
gpiolib-based drivers as part of their gpio_request() and
|
|
gpio_free() semantics. Likewise the pinctrl_gpio_direction_[input|output]
|
|
shall only be called from within respective gpio_direction_[input|output]
|
|
gpiolib implementation.
|
|
|
|
NOTE that platforms and individual drivers shall *NOT* request GPIO pins to be
|
|
controlled e.g. muxed in. Instead, implement a proper gpiolib driver and have
|
|
that driver request proper muxing and other control for its pins.
|
|
|
|
The function list could become long, especially if you can convert every
|
|
individual pin into a GPIO pin independent of any other pins, and then try
|
|
the approach to define every pin as a function.
|
|
|
|
In this case, the function array would become 64 entries for each GPIO
|
|
setting and then the device functions.
|
|
|
|
For this reason there are two functions a pin control driver can implement
|
|
to enable only GPIO on an individual pin: .gpio_request_enable() and
|
|
.gpio_disable_free().
|
|
|
|
This function will pass in the affected GPIO range identified by the pin
|
|
controller core, so you know which GPIO pins are being affected by the request
|
|
operation.
|
|
|
|
If your driver needs to have an indication from the framework of whether the
|
|
GPIO pin shall be used for input or output you can implement the
|
|
.gpio_set_direction() function. As described this shall be called from the
|
|
gpiolib driver and the affected GPIO range, pin offset and desired direction
|
|
will be passed along to this function.
|
|
|
|
Alternatively to using these special functions, it is fully allowed to use
|
|
named functions for each GPIO pin, the pinctrl_request_gpio() will attempt to
|
|
obtain the function "gpioN" where "N" is the global GPIO pin number if no
|
|
special GPIO-handler is registered.
|
|
|
|
|
|
GPIO mode pitfalls
|
|
==================
|
|
|
|
Due to the naming conventions used by hardware engineers, where "GPIO"
|
|
is taken to mean different things than what the kernel does, the developer
|
|
may be confused by a datasheet talking about a pin being possible to set
|
|
into "GPIO mode". It appears that what hardware engineers mean with
|
|
"GPIO mode" is not necessarily the use case that is implied in the kernel
|
|
interface <linux/gpio.h>: a pin that you grab from kernel code and then
|
|
either listen for input or drive high/low to assert/deassert some
|
|
external line.
|
|
|
|
Rather hardware engineers think that "GPIO mode" means that you can
|
|
software-control a few electrical properties of the pin that you would
|
|
not be able to control if the pin was in some other mode, such as muxed in
|
|
for a device.
|
|
|
|
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:
|
|
|
|
(A)
|
|
pin config
|
|
logic regs
|
|
| +- SPI
|
|
Physical pins --- pad --- pinmux -+- I2C
|
|
| +- mmc
|
|
| +- GPIO
|
|
pin
|
|
multiplex
|
|
logic regs
|
|
|
|
Here some electrical properties of the pin can be configured no matter
|
|
whether the pin is used for GPIO or not. If you multiplex a GPIO onto a
|
|
pin, you can also drive it high/low from "GPIO" registers.
|
|
Alternatively, the pin can be controlled by a certain peripheral, while
|
|
still applying desired pin config properties. GPIO functionality is thus
|
|
orthogonal to any other device using the pin.
|
|
|
|
In this arrangement the registers for the GPIO portions of the pin controller,
|
|
or the registers for the GPIO hardware module are likely to reside in a
|
|
separate memory range only intended for GPIO driving, and the register
|
|
range dealing with pin config and pin multiplexing get placed into a
|
|
different memory range and a separate section of the data sheet.
|
|
|
|
A flag "strict" in struct pinmux_ops is available to check and deny
|
|
simultaneous access to the same pin from GPIO and pin multiplexing
|
|
consumers on hardware of this type. The pinctrl driver should set this flag
|
|
accordingly.
|
|
|
|
(B)
|
|
|
|
pin config
|
|
logic regs
|
|
| +- SPI
|
|
Physical pins --- pad --- pinmux -+- I2C
|
|
| | +- mmc
|
|
| |
|
|
GPIO pin
|
|
multiplex
|
|
logic regs
|
|
|
|
In this arrangement, the GPIO functionality can always be enabled, such that
|
|
e.g. a GPIO input can be used to "spy" on the SPI/I2C/MMC signal while it is
|
|
pulsed out. It is likely possible to disrupt the traffic on the pin by doing
|
|
wrong things on the GPIO block, as it is never really disconnected. It is
|
|
possible that the GPIO, pin config and pin multiplex registers are placed into
|
|
the same memory range and the same section of the data sheet, although that
|
|
need not be the case.
|
|
|
|
In some pin controllers, although the physical pins are designed in the same
|
|
way as (B), the GPIO function still can't be enabled at the same time as the
|
|
peripheral functions. So again the "strict" flag should be set, denying
|
|
simultaneous activation by GPIO and other muxed in devices.
|
|
|
|
From a kernel point of view, however, these are different aspects of the
|
|
hardware and shall be put into different subsystems:
|
|
|
|
- Registers (or fields within registers) that control electrical
|
|
properties of the pin such as biasing and drive strength should be
|
|
exposed through the pinctrl subsystem, as "pin configuration" settings.
|
|
|
|
- Registers (or fields within registers) that control muxing of signals
|
|
from various other HW blocks (e.g. I2C, MMC, or GPIO) onto pins should
|
|
be exposed through the pinctrl subsystem, as mux functions.
|
|
|
|
- Registers (or fields within registers) that control GPIO functionality
|
|
such as setting a GPIO's output value, reading a GPIO's input value, or
|
|
setting GPIO pin direction should be exposed through the GPIO subsystem,
|
|
and if they also support interrupt capabilities, through the irqchip
|
|
abstraction.
|
|
|
|
Depending on the exact HW register design, some functions exposed by the
|
|
GPIO subsystem may call into the pinctrl subsystem in order to
|
|
co-ordinate register settings across HW modules. In particular, this may
|
|
be needed for HW with separate GPIO and pin controller HW modules, where
|
|
e.g. GPIO direction is determined by a register in the pin controller HW
|
|
module rather than the GPIO HW module.
|
|
|
|
Electrical properties of the pin such as biasing and drive strength
|
|
may be placed at some pin-specific register in all cases or as part
|
|
of the GPIO register in case (B) especially. This doesn't mean that such
|
|
properties necessarily pertain to what the Linux kernel calls "GPIO".
|
|
|
|
Example: a pin is usually muxed in to be used as a UART TX line. But during
|
|
system sleep, we need to put this pin into "GPIO mode" and ground it.
|
|
|
|
If you make a 1-to-1 map to the GPIO subsystem for this pin, you may start
|
|
to think that you need to come up with something really complex, that the
|
|
pin shall be used for UART TX and GPIO at the same time, that you will grab
|
|
a pin control handle and set it to a certain state to enable UART TX to be
|
|
muxed in, then twist it over to GPIO mode and use gpio_direction_output()
|
|
to drive it low during sleep, then mux it over to UART TX again when you
|
|
wake up and maybe even gpio_request/gpio_free as part of this cycle. This
|
|
all gets very complicated.
|
|
|
|
The solution is to not think that what the datasheet calls "GPIO mode"
|
|
has to be handled by the <linux/gpio.h> interface. Instead view this as
|
|
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
|
|
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:
|
|
|
|
#include <linux/pinctrl/consumer.h>
|
|
|
|
struct pinctrl *pinctrl;
|
|
struct pinctrl_state *pins_default;
|
|
struct pinctrl_state *pins_sleep;
|
|
|
|
pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT);
|
|
pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP);
|
|
|
|
/* Normal mode */
|
|
retval = pinctrl_select_state(pinctrl, pins_default);
|
|
/* Sleep mode */
|
|
retval = pinctrl_select_state(pinctrl, pins_sleep);
|
|
|
|
And your machine configuration may look like this:
|
|
--------------------------------------------------
|
|
|
|
static unsigned long uart_default_mode[] = {
|
|
PIN_CONF_PACKED(PIN_CONFIG_DRIVE_PUSH_PULL, 0),
|
|
};
|
|
|
|
static unsigned long uart_sleep_mode[] = {
|
|
PIN_CONF_PACKED(PIN_CONFIG_OUTPUT, 0),
|
|
};
|
|
|
|
static struct pinctrl_map pinmap[] __initdata = {
|
|
PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
|
|
"u0_group", "u0"),
|
|
PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
|
|
"UART_TX_PIN", uart_default_mode),
|
|
PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
|
|
"u0_group", "gpio-mode"),
|
|
PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
|
|
"UART_TX_PIN", uart_sleep_mode),
|
|
};
|
|
|
|
foo_init(void) {
|
|
pinctrl_register_mappings(pinmap, ARRAY_SIZE(pinmap));
|
|
}
|
|
|
|
Here the pins we want to control are in the "u0_group" and there is some
|
|
function called "u0" that can be enabled on this group of pins, and then
|
|
everything is UART business as usual. But there is also some function
|
|
named "gpio-mode" that can be mapped onto the same pins to move them into
|
|
GPIO mode.
|
|
|
|
This will give the desired effect without any bogus interaction with the
|
|
GPIO subsystem. It is just an electrical configuration used by that device
|
|
when going to sleep, it might imply that the pin is set into something the
|
|
datasheet calls "GPIO mode", but that is not the point: it is still used
|
|
by that UART device to control the pins that pertain to that very UART
|
|
driver, putting them into modes needed by the UART. GPIO in the Linux
|
|
kernel sense are just some 1-bit line, and is a different use case.
|
|
|
|
How the registers are poked to attain the push or pull, and output low
|
|
configuration and the muxing of the "u0" or "gpio-mode" group onto these
|
|
pins is a question for the driver.
|
|
|
|
Some datasheets will be more helpful and refer to the "GPIO mode" as
|
|
"low power mode" rather than anything to do with GPIO. This often means
|
|
the same thing electrically speaking, but in this latter case the
|
|
software engineers will usually quickly identify that this is some
|
|
specific muxing or configuration rather than anything related to the GPIO
|
|
API.
|
|
|
|
|
|
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
|
|
constrained and how the clock tree looks. Of course pinmux settings are also
|
|
part of this.
|
|
|
|
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:
|
|
|
|
#include <linux/pinctrl/machine.h>
|
|
|
|
static const struct pinctrl_map mapping[] __initconst = {
|
|
{
|
|
.dev_name = "foo-spi.0",
|
|
.name = PINCTRL_STATE_DEFAULT,
|
|
.type = PIN_MAP_TYPE_MUX_GROUP,
|
|
.ctrl_dev_name = "pinctrl-foo",
|
|
.data.mux.function = "spi0",
|
|
},
|
|
{
|
|
.dev_name = "foo-i2c.0",
|
|
.name = PINCTRL_STATE_DEFAULT,
|
|
.type = PIN_MAP_TYPE_MUX_GROUP,
|
|
.ctrl_dev_name = "pinctrl-foo",
|
|
.data.mux.function = "i2c0",
|
|
},
|
|
{
|
|
.dev_name = "foo-mmc.0",
|
|
.name = PINCTRL_STATE_DEFAULT,
|
|
.type = PIN_MAP_TYPE_MUX_GROUP,
|
|
.ctrl_dev_name = "pinctrl-foo",
|
|
.data.mux.function = "mmc0",
|
|
},
|
|
};
|
|
|
|
The dev_name here matches to the unique device name that can be used to look
|
|
up the device struct (just like with clockdev or regulators). The function name
|
|
must match a function provided by the pinmux driver handling this pin range.
|
|
|
|
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:
|
|
|
|
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:
|
|
|
|
static struct pinctrl_map mapping[] __initdata = {
|
|
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:
|
|
|
|
static unsigned long i2c_grp_configs[] = {
|
|
FOO_PIN_DRIVEN,
|
|
FOO_PIN_PULLUP,
|
|
};
|
|
|
|
static unsigned long i2c_pin_configs[] = {
|
|
FOO_OPEN_COLLECTOR,
|
|
FOO_SLEW_RATE_SLOW,
|
|
};
|
|
|
|
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),
|
|
};
|
|
|
|
Finally, some devices expect the mapping table to contain certain specific
|
|
named states. When running on hardware that doesn't need any pin controller
|
|
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:
|
|
|
|
static struct pinctrl_map mapping[] __initdata = {
|
|
PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),
|
|
};
|
|
|
|
|
|
Complex mappings
|
|
================
|
|
|
|
As it is possible to map a function to different groups of pins an optional
|
|
.group can be specified like this:
|
|
|
|
...
|
|
{
|
|
.dev_name = "foo-spi.0",
|
|
.name = "spi0-pos-A",
|
|
.type = PIN_MAP_TYPE_MUX_GROUP,
|
|
.ctrl_dev_name = "pinctrl-foo",
|
|
.function = "spi0",
|
|
.group = "spi0_0_grp",
|
|
},
|
|
{
|
|
.dev_name = "foo-spi.0",
|
|
.name = "spi0-pos-B",
|
|
.type = PIN_MAP_TYPE_MUX_GROUP,
|
|
.ctrl_dev_name = "pinctrl-foo",
|
|
.function = "spi0",
|
|
.group = "spi0_1_grp",
|
|
},
|
|
...
|
|
|
|
This example mapping is used to switch between two positions for spi0 at
|
|
runtime, as described further below under the heading "Runtime pinmuxing".
|
|
|
|
Further it is possible for one named state to affect the muxing of several
|
|
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:
|
|
|
|
...
|
|
{
|
|
.dev_name = "foo-mmc.0",
|
|
.name = "2bit"
|
|
.type = PIN_MAP_TYPE_MUX_GROUP,
|
|
.ctrl_dev_name = "pinctrl-foo",
|
|
.function = "mmc0",
|
|
.group = "mmc0_1_grp",
|
|
},
|
|
{
|
|
.dev_name = "foo-mmc.0",
|
|
.name = "4bit"
|
|
.type = PIN_MAP_TYPE_MUX_GROUP,
|
|
.ctrl_dev_name = "pinctrl-foo",
|
|
.function = "mmc0",
|
|
.group = "mmc0_1_grp",
|
|
},
|
|
{
|
|
.dev_name = "foo-mmc.0",
|
|
.name = "4bit"
|
|
.type = PIN_MAP_TYPE_MUX_GROUP,
|
|
.ctrl_dev_name = "pinctrl-foo",
|
|
.function = "mmc0",
|
|
.group = "mmc0_2_grp",
|
|
},
|
|
{
|
|
.dev_name = "foo-mmc.0",
|
|
.name = "8bit"
|
|
.type = PIN_MAP_TYPE_MUX_GROUP,
|
|
.ctrl_dev_name = "pinctrl-foo",
|
|
.function = "mmc0",
|
|
.group = "mmc0_1_grp",
|
|
},
|
|
{
|
|
.dev_name = "foo-mmc.0",
|
|
.name = "8bit"
|
|
.type = PIN_MAP_TYPE_MUX_GROUP,
|
|
.ctrl_dev_name = "pinctrl-foo",
|
|
.function = "mmc0",
|
|
.group = "mmc0_2_grp",
|
|
},
|
|
{
|
|
.dev_name = "foo-mmc.0",
|
|
.name = "8bit"
|
|
.type = PIN_MAP_TYPE_MUX_GROUP,
|
|
.ctrl_dev_name = "pinctrl-foo",
|
|
.function = "mmc0",
|
|
.group = "mmc0_3_grp",
|
|
},
|
|
...
|
|
|
|
The result of grabbing this mapping from the device with something like
|
|
this (see next paragraph):
|
|
|
|
p = devm_pinctrl_get(dev);
|
|
s = pinctrl_lookup_state(p, "8bit");
|
|
ret = pinctrl_select_state(p, s);
|
|
|
|
or more simply:
|
|
|
|
p = devm_pinctrl_get_select(dev, "8bit");
|
|
|
|
Will be that you activate all the three bottom records in the mapping at
|
|
once. Since they share the same name, pin controller device, function and
|
|
device, and since we allow multiple groups to match to a single device, they
|
|
all get selected, and they all get enabled and disable simultaneously by the
|
|
pinmux core.
|
|
|
|
|
|
Pin control requests from drivers
|
|
=================================
|
|
|
|
When a device driver is about to probe the device core will automatically
|
|
attempt to issue pinctrl_get_select_default() on these devices.
|
|
This way driver writers do not need to add any of the boilerplate code
|
|
of the type found below. However when doing fine-grained state selection
|
|
and not using the "default" state, you may have to do some device driver
|
|
handling of the pinctrl handles and states.
|
|
|
|
So if you just want to put the pins for a certain device into the default
|
|
state and be done with it, there is nothing you need to do besides
|
|
providing the proper mapping table. The device core will take care of
|
|
the rest.
|
|
|
|
Generally it is discouraged to let individual drivers get and enable pin
|
|
control. So if possible, handle the pin control in platform code or some other
|
|
place where you have access to all the affected struct device * pointers. In
|
|
some cases where a driver needs to e.g. switch between different mux mappings
|
|
at runtime this is not possible.
|
|
|
|
A typical case is if a driver needs to switch bias of pins from normal
|
|
operation and going to sleep, moving from the PINCTRL_STATE_DEFAULT to
|
|
PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save
|
|
current in sleep mode.
|
|
|
|
A driver may request a certain control state to be activated, usually just the
|
|
default state like this:
|
|
|
|
#include <linux/pinctrl/consumer.h>
|
|
|
|
struct foo_state {
|
|
struct pinctrl *p;
|
|
struct pinctrl_state *s;
|
|
...
|
|
};
|
|
|
|
foo_probe()
|
|
{
|
|
/* Allocate a state holder named "foo" etc */
|
|
struct foo_state *foo = ...;
|
|
|
|
foo->p = devm_pinctrl_get(&device);
|
|
if (IS_ERR(foo->p)) {
|
|
/* FIXME: clean up "foo" here */
|
|
return PTR_ERR(foo->p);
|
|
}
|
|
|
|
foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);
|
|
if (IS_ERR(foo->s)) {
|
|
/* FIXME: clean up "foo" here */
|
|
return PTR_ERR(s);
|
|
}
|
|
|
|
ret = pinctrl_select_state(foo->s);
|
|
if (ret < 0) {
|
|
/* FIXME: clean up "foo" here */
|
|
return ret;
|
|
}
|
|
}
|
|
|
|
This get/lookup/select/put sequence can just as well be handled by bus drivers
|
|
if you don't want each and every driver to handle it and you know the
|
|
arrangement on your bus.
|
|
|
|
The semantics of the pinctrl APIs are:
|
|
|
|
- pinctrl_get() is called in process context to obtain a handle to all pinctrl
|
|
information for a given client device. It will allocate a struct from the
|
|
kernel memory to hold the pinmux state. All mapping table parsing or similar
|
|
slow operations take place within this API.
|
|
|
|
- devm_pinctrl_get() is a variant of pinctrl_get() that causes pinctrl_put()
|
|
to be called automatically on the retrieved pointer when the associated
|
|
device is removed. It is recommended to use this function over plain
|
|
pinctrl_get().
|
|
|
|
- pinctrl_lookup_state() is called in process context to obtain a handle to a
|
|
specific state for a client device. This operation may be slow, too.
|
|
|
|
- pinctrl_select_state() programs pin controller hardware according to the
|
|
definition of the state as given by the mapping table. In theory, this is a
|
|
fast-path operation, since it only involved blasting some register settings
|
|
into hardware. However, note that some pin controllers may have their
|
|
registers on a slow/IRQ-based bus, so client devices should not assume they
|
|
can call pinctrl_select_state() from non-blocking contexts.
|
|
|
|
- pinctrl_put() frees all information associated with a pinctrl handle.
|
|
|
|
- devm_pinctrl_put() is a variant of pinctrl_put() that may be used to
|
|
explicitly destroy a pinctrl object returned by devm_pinctrl_get().
|
|
However, use of this function will be rare, due to the automatic cleanup
|
|
that will occur even without calling it.
|
|
|
|
pinctrl_get() must be paired with a plain pinctrl_put().
|
|
pinctrl_get() may not be paired with devm_pinctrl_put().
|
|
devm_pinctrl_get() can optionally be paired with devm_pinctrl_put().
|
|
devm_pinctrl_get() may not be paired with plain pinctrl_put().
|
|
|
|
Usually the pin control core handled the get/put pair and call out to the
|
|
device drivers bookkeeping operations, like checking available functions and
|
|
the associated pins, whereas select_state pass on to the pin controller
|
|
driver which takes care of activating and/or deactivating the mux setting by
|
|
quickly poking some registers.
|
|
|
|
The pins are allocated for your device when you issue the devm_pinctrl_get()
|
|
call, after this you should be able to see this in the debugfs listing of all
|
|
pins.
|
|
|
|
NOTE: the pinctrl system will return -EPROBE_DEFER if it cannot find the
|
|
requested pinctrl handles, for example if the pinctrl driver has not yet
|
|
registered. Thus make sure that the error path in your driver gracefully
|
|
cleans up and is ready to retry the probing later in the startup process.
|
|
|
|
|
|
Drivers needing both pin control and GPIOs
|
|
==========================================
|
|
|
|
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:
|
|
|
|
#include <linux/pinctrl/consumer.h>
|
|
#include <linux/gpio.h>
|
|
|
|
struct pinctrl *pinctrl;
|
|
int gpio;
|
|
|
|
pinctrl = devm_pinctrl_get_select_default(&dev);
|
|
gpio = devm_gpio_request(&dev, 14, "foo");
|
|
|
|
Here we first request a certain pin state and then request GPIO 14 to be
|
|
used. If you're using the subsystems orthogonally like this, you should
|
|
nominally always get your pinctrl handle and select the desired pinctrl
|
|
state BEFORE requesting the GPIO. This is a semantic convention to avoid
|
|
situations that can be electrically unpleasant, you will certainly want to
|
|
mux in and bias pins in a certain way before the GPIO subsystems starts to
|
|
deal with them.
|
|
|
|
The above can be hidden: using the device core, the pinctrl core may be
|
|
setting up the config and muxing for the pins right before the device is
|
|
probing, nevertheless orthogonal to the GPIO subsystem.
|
|
|
|
But there are also situations where it makes sense for the GPIO subsystem
|
|
to communicate directly with the pinctrl subsystem, using the latter as a
|
|
back-end. This is when the GPIO driver may call out to the functions
|
|
described in the section "Pin control interaction with the GPIO subsystem"
|
|
above. This only involves per-pin multiplexing, and will be completely
|
|
hidden behind the gpio_*() function namespace. In this case, the driver
|
|
need not interact with the pin control subsystem at all.
|
|
|
|
If a pin control driver and a GPIO driver is dealing with the same pins
|
|
and the use cases involve multiplexing, you MUST implement the pin controller
|
|
as a back-end for the GPIO driver like this, unless your hardware design
|
|
is such that the GPIO controller can override the pin controller's
|
|
multiplexing state through hardware without the need to interact with the
|
|
pin control system.
|
|
|
|
|
|
System pin control hogging
|
|
==========================
|
|
|
|
Pin control map entries can be hogged by the core when the pin controller
|
|
is registered. This means that the core will attempt to call pinctrl_get(),
|
|
lookup_state() and select_state() on it immediately after the pin control
|
|
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.
|
|
|
|
{
|
|
.dev_name = "pinctrl-foo",
|
|
.name = PINCTRL_STATE_DEFAULT,
|
|
.type = PIN_MAP_TYPE_MUX_GROUP,
|
|
.ctrl_dev_name = "pinctrl-foo",
|
|
.function = "power_func",
|
|
},
|
|
|
|
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:
|
|
|
|
PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */, "power_func")
|
|
|
|
This gives the exact same result as the above construction.
|
|
|
|
|
|
Runtime pinmuxing
|
|
=================
|
|
|
|
It is possible to mux a certain function in and out at runtime, say to move
|
|
an SPI port from one set of pins to another set of pins. Say for example for
|
|
spi0 in the example above, we expose two different groups of pins for the same
|
|
function, but with different named in the mapping as described under
|
|
"Advanced mapping" above. So that for an SPI device, we have two states named
|
|
"pos-A" and "pos-B".
|
|
|
|
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:
|
|
|
|
#include <linux/pinctrl/consumer.h>
|
|
|
|
struct pinctrl *p;
|
|
struct pinctrl_state *s1, *s2;
|
|
|
|
foo_probe()
|
|
{
|
|
/* Setup */
|
|
p = devm_pinctrl_get(&device);
|
|
if (IS_ERR(p))
|
|
...
|
|
|
|
s1 = pinctrl_lookup_state(foo->p, "pos-A");
|
|
if (IS_ERR(s1))
|
|
...
|
|
|
|
s2 = pinctrl_lookup_state(foo->p, "pos-B");
|
|
if (IS_ERR(s2))
|
|
...
|
|
}
|
|
|
|
foo_switch()
|
|
{
|
|
/* Enable on position A */
|
|
ret = pinctrl_select_state(s1);
|
|
if (ret < 0)
|
|
...
|
|
|
|
...
|
|
|
|
/* Enable on position B */
|
|
ret = pinctrl_select_state(s2);
|
|
if (ret < 0)
|
|
...
|
|
|
|
...
|
|
}
|
|
|
|
The above has to be done from process context. The reservation of the pins
|
|
will be done when the state is activated, so in effect one specific pin
|
|
can be used by different functions at different times on a running system.
|