mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-08-24 01:41:39 +00:00
951 lines
31 KiB
Text
951 lines
31 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
|
||
|
|
||
|
The intention is to also deal with:
|
||
|
|
||
|
- Software-controlled biasing and driving mode specific pins, such as
|
||
|
pull-up/down, open drain etc, load capacitance configuration when controlled
|
||
|
by software, 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 instatiated, 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 __refdata foo_pins[] = {
|
||
|
PINCTRL_PIN(0, "A1"),
|
||
|
PINCTRL_PIN(1, "A2"),
|
||
|
PINCTRL_PIN(2, "A3"),
|
||
|
...
|
||
|
PINCTRL_PIN(61, "H6"),
|
||
|
PINCTRL_PIN(62, "H7"),
|
||
|
PINCTRL_PIN(63, "H8"),
|
||
|
};
|
||
|
|
||
|
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 (IS_ERR(pctl))
|
||
|
pr_err("could not register foo pin driver\n");
|
||
|
}
|
||
|
|
||
|
Pins usually have fancier names than this. You can find these in the dataheet
|
||
|
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 unsigned int spi0_pins[] = { 0, 8, 16, 24 };
|
||
|
static 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_list_groups(struct pinctrl_dev *pctldev, unsigned selector)
|
||
|
{
|
||
|
if (selector >= ARRAY_SIZE(foo_groups))
|
||
|
return -EINVAL;
|
||
|
return 0;
|
||
|
}
|
||
|
|
||
|
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 = {
|
||
|
.list_groups = foo_list_groups,
|
||
|
.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 .list_groups() function repeatedly
|
||
|
beginning on 0 until it returns non-zero to determine 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.
|
||
|
|
||
|
|
||
|
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.
|
||
|
|
||
|
Since the pin controller subsystem have 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 modeled 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,
|
||
|
.npins = 16,
|
||
|
.gc = &chip_a;
|
||
|
};
|
||
|
|
||
|
static struct pinctrl_gpio_range gpio_range_a = {
|
||
|
.name = "chip b",
|
||
|
.id = 0,
|
||
|
.base = 48,
|
||
|
.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. They are mapped in
|
||
|
the global GPIO pin space at:
|
||
|
|
||
|
chip a: [32 .. 47]
|
||
|
chip b: [48 .. 55]
|
||
|
|
||
|
When GPIO-specific functions in the pin control subsystem are called, these
|
||
|
ranges will be used to look up the apropriate 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 subtract the range's .base offset from the passed
|
||
|
in gpio pin number, and pass that on to the pin control driver, so the driver
|
||
|
will get an offset 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.
|
||
|
|
||
|
For example: if a user issues pinctrl_gpio_set_foo(50), the pin control
|
||
|
subsystem will find that the second range on this pin controller matches,
|
||
|
subtract the base 48 and call the
|
||
|
pinctrl_driver_gpio_set_foo(pinctrl, range, 2) where the latter function has
|
||
|
this signature:
|
||
|
|
||
|
int pinctrl_driver_gpio_set_foo(struct pinctrl_dev *pctldev,
|
||
|
struct pinctrl_gpio_range *rangeid,
|
||
|
unsigned offset);
|
||
|
|
||
|
Now the driver knows that we want to do some GPIO-specific operation on the
|
||
|
second GPIO range handled by "chip b", at offset 2 in that specific range.
|
||
|
|
||
|
(If the GPIO subsystem is ever refactored to use a local per-GPIO controller
|
||
|
pin space, this mapping will need to be augmented accordingly.)
|
||
|
|
||
|
|
||
|
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 thru 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 botton 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
|
||
|
- Request 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 symbolic name, pin controller 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.
|
||
|
|
||
|
The device name is present in map entries tied to specific devices. Maps
|
||
|
without device names are referred to as SYSTEM pinmuxes, such as can be taken
|
||
|
by the machine implementation on boot and not tied to any specific device.
|
||
|
|
||
|
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 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 pins 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 enable() and disable() functions are 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_list_groups(struct pinctrl_dev *pctldev, unsigned selector)
|
||
|
{
|
||
|
if (selector >= ARRAY_SIZE(foo_groups))
|
||
|
return -EINVAL;
|
||
|
return 0;
|
||
|
}
|
||
|
|
||
|
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 = {
|
||
|
.list_groups = foo_list_groups,
|
||
|
.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_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),
|
||
|
},
|
||
|
};
|
||
|
|
||
|
int foo_list_funcs(struct pinctrl_dev *pctldev, unsigned selector)
|
||
|
{
|
||
|
if (selector >= ARRAY_SIZE(foo_functions))
|
||
|
return -EINVAL;
|
||
|
return 0;
|
||
|
}
|
||
|
|
||
|
const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector)
|
||
|
{
|
||
|
return myfuncs[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;
|
||
|
}
|
||
|
|
||
|
int foo_enable(struct pinctrl_dev *pctldev, unsigned selector,
|
||
|
unsigned group)
|
||
|
{
|
||
|
u8 regbit = (1 << group);
|
||
|
|
||
|
writeb((readb(MUX)|regbit), MUX)
|
||
|
return 0;
|
||
|
}
|
||
|
|
||
|
int foo_disable(struct pinctrl_dev *pctldev, unsigned selector,
|
||
|
unsigned group)
|
||
|
{
|
||
|
u8 regbit = (1 << group);
|
||
|
|
||
|
writeb((readb(MUX) & ~(regbit)), MUX)
|
||
|
return 0;
|
||
|
}
|
||
|
|
||
|
struct pinmux_ops foo_pmxops = {
|
||
|
.list_functions = foo_list_funcs,
|
||
|
.get_function_name = foo_get_fname,
|
||
|
.get_function_groups = foo_get_groups,
|
||
|
.enable = foo_enable,
|
||
|
.disable = foo_disable,
|
||
|
};
|
||
|
|
||
|
/* 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.
|
||
|
|
||
|
|
||
|
Pinmux interaction with the GPIO subsystem
|
||
|
==========================================
|
||
|
|
||
|
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 is an additional function a pinmux driver can implement
|
||
|
to enable only GPIO on an individual pin: .gpio_request_enable(). The same
|
||
|
.free() function as for other functions is assumed to be usable also for
|
||
|
GPIO pins.
|
||
|
|
||
|
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.
|
||
|
|
||
|
Alternatively it is fully allowed to use named functions for each GPIO
|
||
|
pin, the pinmux_request_gpio() will attempt to obtain the function "gpioN"
|
||
|
where "N" is the global GPIO pin number if no special GPIO-handler is
|
||
|
registered.
|
||
|
|
||
|
|
||
|
Pinmux 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 pinmux config 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 struct pinmux_map pmx_mapping[] = {
|
||
|
{
|
||
|
.ctrl_dev_name = "pinctrl.0",
|
||
|
.function = "spi0",
|
||
|
.dev_name = "foo-spi.0",
|
||
|
},
|
||
|
{
|
||
|
.ctrl_dev_name = "pinctrl.0",
|
||
|
.function = "i2c0",
|
||
|
.dev_name = "foo-i2c.0",
|
||
|
},
|
||
|
{
|
||
|
.ctrl_dev_name = "pinctrl.0",
|
||
|
.function = "mmc0",
|
||
|
.dev_name = "foo-mmc.0",
|
||
|
},
|
||
|
};
|
||
|
|
||
|
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 that contain the functions we wish
|
||
|
to map. The map can also use struct device * directly, so there is no
|
||
|
inherent need to use strings to specify .dev_name or .ctrl_dev_name, these
|
||
|
are for the situation where you do not have a handle to the struct device *,
|
||
|
for example if they are not yet instantiated or cumbersome to obtain.
|
||
|
|
||
|
You register this pinmux mapping to the pinmux subsystem by simply:
|
||
|
|
||
|
ret = pinmux_register_mappings(&pmx_mapping, ARRAY_SIZE(pmx_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.0 and position
|
||
|
0 for mapping, for example:
|
||
|
|
||
|
static struct pinmux_map pmx_mapping[] = {
|
||
|
PINMUX_MAP_PRIMARY("I2CMAP", "i2c0", "foo-i2c.0"),
|
||
|
};
|
||
|
|
||
|
|
||
|
Complex mappings
|
||
|
================
|
||
|
|
||
|
As it is possible to map a function to different groups of pins an optional
|
||
|
.group can be specified like this:
|
||
|
|
||
|
...
|
||
|
{
|
||
|
.name = "spi0-pos-A",
|
||
|
.ctrl_dev_name = "pinctrl.0",
|
||
|
.function = "spi0",
|
||
|
.group = "spi0_0_grp",
|
||
|
.dev_name = "foo-spi.0",
|
||
|
},
|
||
|
{
|
||
|
.name = "spi0-pos-B",
|
||
|
.ctrl_dev_name = "pinctrl.0",
|
||
|
.function = "spi0",
|
||
|
.group = "spi0_1_grp",
|
||
|
.dev_name = "foo-spi.0",
|
||
|
},
|
||
|
...
|
||
|
|
||
|
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 to match several groups of pins to the same function
|
||
|
for a single device, 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:
|
||
|
|
||
|
...
|
||
|
{
|
||
|
.name "2bit"
|
||
|
.ctrl_dev_name = "pinctrl.0",
|
||
|
.function = "mmc0",
|
||
|
.group = "mmc0_0_grp",
|
||
|
.dev_name = "foo-mmc.0",
|
||
|
},
|
||
|
{
|
||
|
.name "4bit"
|
||
|
.ctrl_dev_name = "pinctrl.0",
|
||
|
.function = "mmc0",
|
||
|
.group = "mmc0_0_grp",
|
||
|
.dev_name = "foo-mmc.0",
|
||
|
},
|
||
|
{
|
||
|
.name "4bit"
|
||
|
.ctrl_dev_name = "pinctrl.0",
|
||
|
.function = "mmc0",
|
||
|
.group = "mmc0_1_grp",
|
||
|
.dev_name = "foo-mmc.0",
|
||
|
},
|
||
|
{
|
||
|
.name "8bit"
|
||
|
.ctrl_dev_name = "pinctrl.0",
|
||
|
.function = "mmc0",
|
||
|
.group = "mmc0_0_grp",
|
||
|
.dev_name = "foo-mmc.0",
|
||
|
},
|
||
|
{
|
||
|
.name "8bit"
|
||
|
.ctrl_dev_name = "pinctrl.0",
|
||
|
.function = "mmc0",
|
||
|
.group = "mmc0_1_grp",
|
||
|
.dev_name = "foo-mmc.0",
|
||
|
},
|
||
|
{
|
||
|
.name "8bit"
|
||
|
.ctrl_dev_name = "pinctrl.0",
|
||
|
.function = "mmc0",
|
||
|
.group = "mmc0_2_grp",
|
||
|
.dev_name = "foo-mmc.0",
|
||
|
},
|
||
|
...
|
||
|
|
||
|
The result of grabbing this mapping from the device with something like
|
||
|
this (see next paragraph):
|
||
|
|
||
|
pmx = pinmux_get(&device, "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, funcion 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.
|
||
|
|
||
|
|
||
|
Pinmux requests from drivers
|
||
|
============================
|
||
|
|
||
|
Generally it is discouraged to let individual drivers get and enable pinmuxes.
|
||
|
So if possible, handle the pinmuxes 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 switch between different mux mappings at runtime
|
||
|
this is not possible.
|
||
|
|
||
|
A driver may request a certain mux to be activated, usually just the default
|
||
|
mux like this:
|
||
|
|
||
|
#include <linux/pinctrl/pinmux.h>
|
||
|
|
||
|
struct foo_state {
|
||
|
struct pinmux *pmx;
|
||
|
...
|
||
|
};
|
||
|
|
||
|
foo_probe()
|
||
|
{
|
||
|
/* Allocate a state holder named "state" etc */
|
||
|
struct pinmux pmx;
|
||
|
|
||
|
pmx = pinmux_get(&device, NULL);
|
||
|
if IS_ERR(pmx)
|
||
|
return PTR_ERR(pmx);
|
||
|
pinmux_enable(pmx);
|
||
|
|
||
|
state->pmx = pmx;
|
||
|
}
|
||
|
|
||
|
foo_remove()
|
||
|
{
|
||
|
pinmux_disable(state->pmx);
|
||
|
pinmux_put(state->pmx);
|
||
|
}
|
||
|
|
||
|
If you want to grab a specific mux mapping and not just the first one found for
|
||
|
this device you can specify a specific mapping name, for example in the above
|
||
|
example the second i2c0 setting: pinmux_get(&device, "spi0-pos-B");
|
||
|
|
||
|
This get/enable/disable/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 get/enable respective disable/put is as follows:
|
||
|
|
||
|
- pinmux_get() is called in process context to reserve the pins affected with
|
||
|
a certain mapping and set up the pinmux core and the driver. It will allocate
|
||
|
a struct from the kernel memory to hold the pinmux state.
|
||
|
|
||
|
- pinmux_enable()/pinmux_disable() is quick and can be called from fastpath
|
||
|
(irq context) when you quickly want to set up/tear down the hardware muxing
|
||
|
when running a device driver. Usually it will just poke some values into a
|
||
|
register.
|
||
|
|
||
|
- pinmux_disable() is called in process context to tear down the pin requests
|
||
|
and release the state holder struct for the mux setting.
|
||
|
|
||
|
Usually the pinmux core handled the get/put pair and call out to the device
|
||
|
drivers bookkeeping operations, like checking available functions and the
|
||
|
associated pins, whereas the enable/disable 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 pinmux_get() call,
|
||
|
after this you should be able to see this in the debugfs listing of all pins.
|
||
|
|
||
|
|
||
|
System pinmux hogging
|
||
|
=====================
|
||
|
|
||
|
A system pinmux map entry, i.e. a pinmux setting that does not have a device
|
||
|
associated with it, can be hogged by the core when the pin controller is
|
||
|
registered. This means that the core will attempt to call pinmux_get() and
|
||
|
pinmux_enable() on it immediately after the pin control device has been
|
||
|
registered.
|
||
|
|
||
|
This is enabled by simply setting the .hog_on_boot field in the map to true,
|
||
|
like this:
|
||
|
|
||
|
{
|
||
|
.name "POWERMAP"
|
||
|
.ctrl_dev_name = "pinctrl.0",
|
||
|
.function = "power_func",
|
||
|
.hog_on_boot = true,
|
||
|
},
|
||
|
|
||
|
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:
|
||
|
|
||
|
PINMUX_MAP_PRIMARY_SYS_HOG("POWERMAP", "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 we have two mappings named "spi0-pos-A" and
|
||
|
"spi0-pos-B".
|
||
|
|
||
|
This snippet first muxes the function in the pins defined by group A, enables
|
||
|
it, disables and releases it, and muxes it in on the pins defined by group B:
|
||
|
|
||
|
foo_switch()
|
||
|
{
|
||
|
struct pinmux pmx;
|
||
|
|
||
|
/* Enable on position A */
|
||
|
pmx = pinmux_get(&device, "spi0-pos-A");
|
||
|
if IS_ERR(pmx)
|
||
|
return PTR_ERR(pmx);
|
||
|
pinmux_enable(pmx);
|
||
|
|
||
|
/* This releases the pins again */
|
||
|
pinmux_disable(pmx);
|
||
|
pinmux_put(pmx);
|
||
|
|
||
|
/* Enable on position B */
|
||
|
pmx = pinmux_get(&device, "spi0-pos-B");
|
||
|
if IS_ERR(pmx)
|
||
|
return PTR_ERR(pmx);
|
||
|
pinmux_enable(pmx);
|
||
|
...
|
||
|
}
|
||
|
|
||
|
The above has to be done from process context.
|