^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) PINCTRL (PIN CONTROL) subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) This document outlines the pin control subsystem in Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) This subsystem deals with:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) - Enumerating and naming controllable pins
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) - Multiplexing of pins, pads, fingers (etc) see below for details
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) - Configuration of pins, pads, fingers (etc), such as software-controlled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) biasing and driving mode specific pins, such as pull-up/down, open drain,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) load capacitance etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) Top-level interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) Definition of PIN CONTROLLER:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) - A pin controller is a piece of hardware, usually a set of registers, that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) can control PINs. It may be able to multiplex, bias, set load capacitance,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) set drive strength, etc. for individual pins or groups of pins.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) Definition of PIN:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) - PINS are equal to pads, fingers, balls or whatever packaging input or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) output line you want to control and these are denoted by unsigned integers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) in the range 0..maxpin. This numberspace is local to each PIN CONTROLLER, so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) there may be several such number spaces in a system. This pin space may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) be sparse - i.e. there may be gaps in the space with numbers where no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) pin exists.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) When a PIN CONTROLLER is instantiated, it will register a descriptor to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) pin control framework, and this descriptor contains an array of pin descriptors
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) describing the pins handled by this specific pin controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) Here is an example of a PGA (Pin Grid Array) chip seen from underneath::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) A B C D E F G H
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) 8 o o o o o o o o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) 7 o o o o o o o o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) 6 o o o o o o o o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) 5 o o o o o o o o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) 4 o o o o o o o o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) 3 o o o o o o o o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) 2 o o o o o o o o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) 1 o o o o o o o o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) To register a pin controller and name all the pins on this package we can do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) this in our driver::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) #include <linux/pinctrl/pinctrl.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) const struct pinctrl_pin_desc foo_pins[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) PINCTRL_PIN(0, "A8"),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) PINCTRL_PIN(1, "B8"),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) PINCTRL_PIN(2, "C8"),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) PINCTRL_PIN(61, "F1"),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) PINCTRL_PIN(62, "G1"),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) PINCTRL_PIN(63, "H1"),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) static struct pinctrl_desc foo_desc = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) .name = "foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) .pins = foo_pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) .npins = ARRAY_SIZE(foo_pins),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) .owner = THIS_MODULE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) int __init foo_probe(void)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) int error;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) struct pinctrl_dev *pctl;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) error = pinctrl_register_and_init(&foo_desc, <PARENT>,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) NULL, &pctl);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) if (error)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) return error;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) return pinctrl_enable(pctl);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) To enable the pinctrl subsystem and the subgroups for PINMUX and PINCONF and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) selected drivers, you need to select them from your machine's Kconfig entry,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) since these are so tightly integrated with the machines they are used on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) See for example arch/arm/mach-u300/Kconfig for an example.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) Pins usually have fancier names than this. You can find these in the datasheet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) for your chip. Notice that the core pinctrl.h file provides a fancy macro
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) called PINCTRL_PIN() to create the struct entries. As you can see I enumerated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) the pins from 0 in the upper left corner to 63 in the lower right corner.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) This enumeration was arbitrarily chosen, in practice you need to think
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) through your numbering system so that it matches the layout of registers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) and such things in your driver, or the code may become complicated. You must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) also consider matching of offsets to the GPIO ranges that may be handled by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) the pin controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) For a padring with 467 pads, as opposed to actual pins, I used an enumeration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) like this, walking around the edge of the chip, which seems to be industry
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) standard too (all these pads had names, too)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) 0 ..... 104
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) 466 105
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) . .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) . .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) 358 224
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) 357 .... 225
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) Pin groups
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) Many controllers need to deal with groups of pins, so the pin controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) subsystem has a mechanism for enumerating groups of pins and retrieving the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) actual enumerated pins that are part of a certain group.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) For example, say that we have a group of pins dealing with an SPI interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) on { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) on { 24, 25 }.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) These two groups are presented to the pin control subsystem by implementing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) some generic pinctrl_ops like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) #include <linux/pinctrl/pinctrl.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) struct foo_group {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) const char *name;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) const unsigned int *pins;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) const unsigned num_pins;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) static const unsigned int spi0_pins[] = { 0, 8, 16, 24 };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) static const unsigned int i2c0_pins[] = { 24, 25 };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) static const struct foo_group foo_groups[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) .name = "spi0_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) .pins = spi0_pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) .num_pins = ARRAY_SIZE(spi0_pins),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) .name = "i2c0_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) .pins = i2c0_pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) .num_pins = ARRAY_SIZE(i2c0_pins),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) static int foo_get_groups_count(struct pinctrl_dev *pctldev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) return ARRAY_SIZE(foo_groups);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) unsigned selector)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) return foo_groups[selector].name;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) const unsigned **pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) unsigned *num_pins)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) *pins = (unsigned *) foo_groups[selector].pins;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) *num_pins = foo_groups[selector].num_pins;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) static struct pinctrl_ops foo_pctrl_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) .get_groups_count = foo_get_groups_count,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) .get_group_name = foo_get_group_name,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) .get_group_pins = foo_get_group_pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) static struct pinctrl_desc foo_desc = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) .pctlops = &foo_pctrl_ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) The pin control subsystem will call the .get_groups_count() function to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) determine the total number of legal selectors, then it will call the other functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) to retrieve the name and pins of the group. Maintaining the data structure of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) the groups is up to the driver, this is just a simple example - in practice you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) may need more entries in your group structure, for example specific register
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) ranges associated with each group and so on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) Pin configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) Pins can sometimes be software-configured in various ways, mostly related
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) to their electronic properties when used as inputs or outputs. For example you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) may be able to make an output pin high impedance, or "tristate" meaning it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) effectively disconnected. You may be able to connect an input pin to VDD or GND
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) using a certain resistor value - pull up and pull down - so that the pin has a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) stable value when nothing is driving the rail it is connected to, or when it's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) unconnected.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) Pin configuration can be programmed by adding configuration entries into the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) mapping table; see section "Board/machine configuration" below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) The format and meaning of the configuration parameter, PLATFORM_X_PULL_UP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) above, is entirely defined by the pin controller driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) The pin configuration driver implements callbacks for changing pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) configuration in the pin controller ops like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) #include <linux/pinctrl/pinctrl.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) #include <linux/pinctrl/pinconf.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) #include "platform_x_pindefs.h"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) static int foo_pin_config_get(struct pinctrl_dev *pctldev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) unsigned offset,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) unsigned long *config)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) struct my_conftype conf;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) ... Find setting for pin @ offset ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) *config = (unsigned long) conf;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) static int foo_pin_config_set(struct pinctrl_dev *pctldev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) unsigned offset,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) unsigned long config)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) struct my_conftype *conf = (struct my_conftype *) config;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) switch (conf) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) case PLATFORM_X_PULL_UP:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) static int foo_pin_config_group_get (struct pinctrl_dev *pctldev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) unsigned selector,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) unsigned long *config)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) static int foo_pin_config_group_set (struct pinctrl_dev *pctldev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) unsigned selector,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) unsigned long config)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) static struct pinconf_ops foo_pconf_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) .pin_config_get = foo_pin_config_get,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) .pin_config_set = foo_pin_config_set,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) .pin_config_group_get = foo_pin_config_group_get,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) .pin_config_group_set = foo_pin_config_group_set,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) /* Pin config operations are handled by some pin controller */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) static struct pinctrl_desc foo_desc = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) .confops = &foo_pconf_ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) Interaction with the GPIO subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) The GPIO drivers may want to perform operations of various types on the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) physical pins that are also registered as pin controller pins.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) First and foremost, the two subsystems can be used as completely orthogonal,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) see the section named "pin control requests from drivers" and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) "drivers needing both pin control and GPIOs" below for details. But in some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) situations a cross-subsystem mapping between pins and GPIOs is needed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) Since the pin controller subsystem has its pinspace local to the pin controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) we need a mapping so that the pin control subsystem can figure out which pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) controller handles control of a certain GPIO pin. Since a single pin controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) may be muxing several GPIO ranges (typically SoCs that have one set of pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) but internally several GPIO silicon blocks, each modelled as a struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) gpio_chip) any number of GPIO ranges can be added to a pin controller instance
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) struct gpio_chip chip_a;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) struct gpio_chip chip_b;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) static struct pinctrl_gpio_range gpio_range_a = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) .name = "chip a",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) .id = 0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) .base = 32,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) .pin_base = 32,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) .npins = 16,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) .gc = &chip_a;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) static struct pinctrl_gpio_range gpio_range_b = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) .name = "chip b",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) .id = 0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) .base = 48,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) .pin_base = 64,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) .npins = 8,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) .gc = &chip_b;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) struct pinctrl_dev *pctl;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) pinctrl_add_gpio_range(pctl, &gpio_range_a);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) pinctrl_add_gpio_range(pctl, &gpio_range_b);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) So this complex system has one pin controller handling two different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) "chip b" have different .pin_base, which means a start pin number of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) GPIO range.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) The GPIO range of "chip a" starts from the GPIO base of 32 and actual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) pin range also starts from 32. However "chip b" has different starting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) offset for the GPIO range and pin range. The GPIO range of "chip b" starts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) from GPIO number 48, while the pin range of "chip b" starts from 64.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) We can convert a gpio number to actual pin number using this "pin_base".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) They are mapped in the global GPIO pin space at:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) chip a:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) - GPIO range : [32 .. 47]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) - pin range : [32 .. 47]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) chip b:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) - GPIO range : [48 .. 55]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) - pin range : [64 .. 71]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) The above examples assume the mapping between the GPIOs and pins is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) linear. If the mapping is sparse or haphazard, an array of arbitrary pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) numbers can be encoded in the range like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) static const unsigned range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) static struct pinctrl_gpio_range gpio_range = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) .name = "chip",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) .id = 0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) .base = 32,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) .pins = &range_pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) .npins = ARRAY_SIZE(range_pins),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) .gc = &chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) In this case the pin_base property will be ignored. If the name of a pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) group is known, the pins and npins elements of the above structure can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) initialised using the function pinctrl_get_group_pins(), e.g. for pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) group "foo"::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) &gpio_range.npins);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) When GPIO-specific functions in the pin control subsystem are called, these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) ranges will be used to look up the appropriate pin controller by inspecting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) and matching the pin to the pin ranges across all controllers. When a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) pin controller handling the matching range is found, GPIO-specific functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) will be called on that specific pin controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) For all functionalities dealing with pin biasing, pin muxing etc, the pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) controller subsystem will look up the corresponding pin number from the passed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) in gpio number, and use the range's internals to retrieve a pin number. After
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) that, the subsystem passes it on to the pin control driver, so the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) will get a pin number into its handled number range. Further it is also passed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) the range ID value, so that the pin controller knows which range it should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) deal with.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) Calling pinctrl_add_gpio_range from pinctrl driver is DEPRECATED. Please see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) section 2.1 of Documentation/devicetree/bindings/gpio/gpio.txt on how to bind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) pinctrl and gpio drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) PINMUX interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) These calls use the pinmux_* naming prefix. No other calls should use that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) prefix.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) What is pinmuxing?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) PINMUX, also known as padmux, ballmux, alternate functions or mission modes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) is a way for chip vendors producing some kind of electrical packages to use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) a certain physical pin (ball, pad, finger, etc) for multiple mutually exclusive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) functions, depending on the application. By "application" in this context
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) we usually mean a way of soldering or wiring the package into an electronic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) system, even though the framework makes it possible to also change the function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) at runtime.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) Here is an example of a PGA (Pin Grid Array) chip seen from underneath::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) A B C D E F G H
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) +---+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) 8 | o | o o o o o o o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) 7 | o | o o o o o o o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) 6 | o | o o o o o o o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) +---+---+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) 5 | o | o | o o o o o o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) +---+---+ +---+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) 4 o o o o o o | o | o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) 3 o o o o o o | o | o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) 2 o o o o o o | o | o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) +-------+-------+-------+---+---+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) 1 | o o | o o | o o | o | o |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) +-------+-------+-------+---+---+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) This is not tetris. The game to think of is chess. Not all PGA/BGA packages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) are chessboard-like, big ones have "holes" in some arrangement according to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) different design patterns, but we're using this as a simple example. Of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) pins you see some will be taken by things like a few VCC and GND to feed power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) to the chip, and quite a few will be taken by large ports like an external
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) memory interface. The remaining pins will often be subject to pin multiplexing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) The example 8x8 PGA package above will have pin numbers 0 through 63 assigned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) to its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) pinctrl_register_pins() and a suitable data set as shown earlier.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) In this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) (these are four pins: CLK, RXD, TXD, FRM). In that case, pin B5 can be used as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) some general-purpose GPIO pin. However, in another setting, pins { A5, B5 } can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) be used as an I2C port (these are just two pins: SCL, SDA). Needless to say,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) we cannot use the SPI port and I2C port at the same time. However in the inside
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) of the package the silicon performing the SPI logic can alternatively be routed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) out on pins { G4, G3, G2, G1 }.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) On the bottom row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) consume 2, 4 or 8 pins respectively, so either { A1, B1 } are taken or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) { A1, B1, C1, D1 } or all of them. If we use all 8 bits, we cannot use the SPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) port on pins { G4, G3, G2, G1 } of course.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) This way the silicon blocks present inside the chip can be multiplexed "muxed"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) out on different pin ranges. Often contemporary SoC (systems on chip) will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) contain several I2C, SPI, SDIO/MMC, etc silicon blocks that can be routed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) different pins by pinmux settings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) Since general-purpose I/O pins (GPIO) are typically always in shortage, it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) common to be able to use almost any pin as a GPIO pin if it is not currently
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) in use by some other I/O port.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) Pinmux conventions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) The purpose of the pinmux functionality in the pin controller subsystem is to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) abstract and provide pinmux settings to the devices you choose to instantiate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) in your machine configuration. It is inspired by the clk, GPIO and regulator
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) subsystems, so devices will request their mux setting, but it's also possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) to request a single pin for e.g. GPIO.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) Definitions:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) - FUNCTIONS can be switched in and out by a driver residing with the pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) control subsystem in the drivers/pinctrl/* directory of the kernel. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) pin control driver knows the possible functions. In the example above you can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) identify three pinmux functions, one for spi, one for i2c and one for mmc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) - FUNCTIONS are assumed to be enumerable from zero in a one-dimensional array.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) In this case the array could be something like: { spi0, i2c0, mmc0 }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) for the three available functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) - FUNCTIONS have PIN GROUPS as defined on the generic level - so a certain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) function is *always* associated with a certain set of pin groups, could
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) be just a single one, but could also be many. In the example above the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) function i2c is associated with the pins { A5, B5 }, enumerated as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) { 24, 25 } in the controller pin space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) The Function spi is associated with pin groups { A8, A7, A6, A5 }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) and { G4, G3, G2, G1 }, which are enumerated as { 0, 8, 16, 24 } and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) { 38, 46, 54, 62 } respectively.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) Group names must be unique per pin controller, no two groups on the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) controller may have the same name.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) - The combination of a FUNCTION and a PIN GROUP determine a certain function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) for a certain set of pins. The knowledge of the functions and pin groups
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) and their machine-specific particulars are kept inside the pinmux driver,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) from the outside only the enumerators are known, and the driver core can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) request:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) - The name of a function with a certain selector (>= 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) - A list of groups associated with a certain function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) - That a certain group in that list to be activated for a certain function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) As already described above, pin groups are in turn self-descriptive, so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) the core will retrieve the actual pin range in a certain group from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) - FUNCTIONS and GROUPS on a certain PIN CONTROLLER are MAPPED to a certain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) device by the board file, device tree or similar machine setup configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) mechanism, similar to how regulators are connected to devices, usually by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) name. Defining a pin controller, function and group thus uniquely identify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) the set of pins to be used by a certain device. (If only one possible group
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) of pins is available for the function, no group name need to be supplied -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) the core will simply select the first and only group available.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) In the example case we can define that this particular machine shall
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) use device spi0 with pinmux function fspi0 group gspi0 and i2c0 on function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) fi2c0 group gi2c0, on the primary pin controller, we get mappings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) like these::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) {"map-spi0", spi0, pinctrl0, fspi0, gspi0},
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0}
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) Every map must be assigned a state name, pin controller, device and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) function. The group is not compulsory - if it is omitted the first group
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) presented by the driver as applicable for the function will be selected,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) which is useful for simple cases.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) It is possible to map several groups to the same combination of device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) pin controller and function. This is for cases where a certain function on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) a certain pin controller may use different sets of pins in different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) configurations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) - PINS for a certain FUNCTION using a certain PIN GROUP on a certain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) PIN CONTROLLER are provided on a first-come first-serve basis, so if some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) other device mux setting or GPIO pin request has already taken your physical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) pin, you will be denied the use of it. To get (activate) a new setting, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) old one has to be put (deactivated) first.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) Sometimes the documentation and hardware registers will be oriented around
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) pads (or "fingers") rather than pins - these are the soldering surfaces on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) silicon inside the package, and may or may not match the actual number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) pins/balls underneath the capsule. Pick some enumeration that makes sense to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) you. Define enumerators only for the pins you can control if that makes sense.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) Assumptions:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) We assume that the number of possible function maps to pin groups is limited by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) the hardware. I.e. we assume that there is no system where any function can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) mapped to any pin, like in a phone exchange. So the available pin groups for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) a certain function will be limited to a few choices (say up to eight or so),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) not hundreds or any amount of choices. This is the characteristic we have found
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) by inspecting available pinmux hardware, and a necessary assumption since we
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555) expect pinmux drivers to present *all* possible function vs pin group mappings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) to the subsystem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) Pinmux drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562) The pinmux core takes care of preventing conflicts on pins and calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) the pin controller driver to execute different settings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) It is the responsibility of the pinmux driver to impose further restrictions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) (say for example infer electronic limitations due to load, etc.) to determine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) whether or not the requested function can actually be allowed, and in case it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) is possible to perform the requested mux setting, poke the hardware so that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) this happens.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) Pinmux drivers are required to supply a few callback functions, some are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) optional. Usually the set_mux() function is implemented, writing values into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) some certain registers to activate a certain mux setting for a certain pin.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) A simple driver for the above example will work by setting bits 0, 1, 2, 3 or 4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) into some register named MUX to select a certain function with a certain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) group of pins would work something like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) #include <linux/pinctrl/pinctrl.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580) #include <linux/pinctrl/pinmux.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) struct foo_group {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) const char *name;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) const unsigned int *pins;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) const unsigned num_pins;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) static const unsigned spi0_0_pins[] = { 0, 8, 16, 24 };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) static const unsigned spi0_1_pins[] = { 38, 46, 54, 62 };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) static const unsigned i2c0_pins[] = { 24, 25 };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) static const unsigned mmc0_1_pins[] = { 56, 57 };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592) static const unsigned mmc0_2_pins[] = { 58, 59 };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) static const unsigned mmc0_3_pins[] = { 60, 61, 62, 63 };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) static const struct foo_group foo_groups[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) .name = "spi0_0_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) .pins = spi0_0_pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) .num_pins = ARRAY_SIZE(spi0_0_pins),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) .name = "spi0_1_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) .pins = spi0_1_pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) .num_pins = ARRAY_SIZE(spi0_1_pins),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607) .name = "i2c0_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608) .pins = i2c0_pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) .num_pins = ARRAY_SIZE(i2c0_pins),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) .name = "mmc0_1_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613) .pins = mmc0_1_pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) .num_pins = ARRAY_SIZE(mmc0_1_pins),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) .name = "mmc0_2_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618) .pins = mmc0_2_pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) .num_pins = ARRAY_SIZE(mmc0_2_pins),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) .name = "mmc0_3_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) .pins = mmc0_3_pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624) .num_pins = ARRAY_SIZE(mmc0_3_pins),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) static int foo_get_groups_count(struct pinctrl_dev *pctldev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631) return ARRAY_SIZE(foo_groups);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634) static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635) unsigned selector)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) return foo_groups[selector].name;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) const unsigned ** pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642) unsigned * num_pins)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) *pins = (unsigned *) foo_groups[selector].pins;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645) *num_pins = foo_groups[selector].num_pins;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649) static struct pinctrl_ops foo_pctrl_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650) .get_groups_count = foo_get_groups_count,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651) .get_group_name = foo_get_group_name,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652) .get_group_pins = foo_get_group_pins,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) struct foo_pmx_func {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656) const char *name;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657) const char * const *groups;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) const unsigned num_groups;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) static const char * const spi0_groups[] = { "spi0_0_grp", "spi0_1_grp" };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) static const char * const i2c0_groups[] = { "i2c0_grp" };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663) static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664) "mmc0_3_grp" };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666) static const struct foo_pmx_func foo_functions[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668) .name = "spi0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) .groups = spi0_groups,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670) .num_groups = ARRAY_SIZE(spi0_groups),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673) .name = "i2c0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674) .groups = i2c0_groups,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) .num_groups = ARRAY_SIZE(i2c0_groups),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678) .name = "mmc0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) .groups = mmc0_groups,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680) .num_groups = ARRAY_SIZE(mmc0_groups),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) static int foo_get_functions_count(struct pinctrl_dev *pctldev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686) return ARRAY_SIZE(foo_functions);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689) static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) return foo_functions[selector].name;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694) static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695) const char * const **groups,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) unsigned * const num_groups)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) *groups = foo_functions[selector].groups;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) *num_groups = foo_functions[selector].num_groups;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned selector,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704) unsigned group)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) u8 regbit = (1 << selector + group);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) writeb((readb(MUX)|regbit), MUX);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712) static struct pinmux_ops foo_pmxops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713) .get_functions_count = foo_get_functions_count,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714) .get_function_name = foo_get_fname,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715) .get_function_groups = foo_get_groups,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) .set_mux = foo_set_mux,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717) .strict = true,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) /* Pinmux operations are handled by some pin controller */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721) static struct pinctrl_desc foo_desc = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723) .pctlops = &foo_pctrl_ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) .pmxops = &foo_pmxops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727) In the example activating muxing 0 and 1 at the same time setting bits
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728) 0 and 1, uses one pin in common so they would collide.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730) The beauty of the pinmux subsystem is that since it keeps track of all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731) pins and who is using them, it will already have denied an impossible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732) request like that, so the driver does not need to worry about such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733) things - when it gets a selector passed in, the pinmux subsystem makes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734) sure no other device or GPIO assignment is already using the selected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735) pins. Thus bits 0 and 1 in the control register will never be set at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736) same time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738) All the above functions are mandatory to implement for a pinmux driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741) Pin control interaction with the GPIO subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742) ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744) Note that the following implies that the use case is to use a certain pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745) from the Linux kernel using the API in <linux/gpio.h> with gpio_request()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746) and similar functions. There are cases where you may be using something
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747) that your datasheet calls "GPIO mode", but actually is just an electrical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748) configuration for a certain device. See the section below named
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749) "GPIO mode pitfalls" for more details on this scenario.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751) The public pinmux API contains two functions named pinctrl_gpio_request()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) and pinctrl_gpio_free(). These two functions shall *ONLY* be called from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753) gpiolib-based drivers as part of their gpio_request() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754) gpio_free() semantics. Likewise the pinctrl_gpio_direction_[input|output]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755) shall only be called from within respective gpio_direction_[input|output]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756) gpiolib implementation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758) NOTE that platforms and individual drivers shall *NOT* request GPIO pins to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759) controlled e.g. muxed in. Instead, implement a proper gpiolib driver and have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760) that driver request proper muxing and other control for its pins.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762) The function list could become long, especially if you can convert every
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763) individual pin into a GPIO pin independent of any other pins, and then try
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764) the approach to define every pin as a function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766) In this case, the function array would become 64 entries for each GPIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767) setting and then the device functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769) For this reason there are two functions a pin control driver can implement
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770) to enable only GPIO on an individual pin: .gpio_request_enable() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 771) .gpio_disable_free().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 772)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 773) This function will pass in the affected GPIO range identified by the pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 774) controller core, so you know which GPIO pins are being affected by the request
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 775) operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 776)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 777) If your driver needs to have an indication from the framework of whether the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 778) GPIO pin shall be used for input or output you can implement the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 779) .gpio_set_direction() function. As described this shall be called from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 780) gpiolib driver and the affected GPIO range, pin offset and desired direction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 781) will be passed along to this function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 782)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 783) Alternatively to using these special functions, it is fully allowed to use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 784) named functions for each GPIO pin, the pinctrl_gpio_request() will attempt to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 785) obtain the function "gpioN" where "N" is the global GPIO pin number if no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 786) special GPIO-handler is registered.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 787)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 788)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 789) GPIO mode pitfalls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 790) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 791)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 792) Due to the naming conventions used by hardware engineers, where "GPIO"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 793) is taken to mean different things than what the kernel does, the developer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 794) may be confused by a datasheet talking about a pin being possible to set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 795) into "GPIO mode". It appears that what hardware engineers mean with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 796) "GPIO mode" is not necessarily the use case that is implied in the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 797) interface <linux/gpio.h>: a pin that you grab from kernel code and then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 798) either listen for input or drive high/low to assert/deassert some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 799) external line.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 800)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 801) Rather hardware engineers think that "GPIO mode" means that you can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 802) software-control a few electrical properties of the pin that you would
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 803) not be able to control if the pin was in some other mode, such as muxed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 804) for a device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 805)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 806) The GPIO portions of a pin and its relation to a certain pin controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 807) configuration and muxing logic can be constructed in several ways. Here
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 808) are two examples::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 809)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 810) (A)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 811) pin config
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 812) logic regs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 813) | +- SPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 814) Physical pins --- pad --- pinmux -+- I2C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 815) | +- mmc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 816) | +- GPIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 817) pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 818) multiplex
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 819) logic regs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 820)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 821) Here some electrical properties of the pin can be configured no matter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 822) whether the pin is used for GPIO or not. If you multiplex a GPIO onto a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 823) pin, you can also drive it high/low from "GPIO" registers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 824) Alternatively, the pin can be controlled by a certain peripheral, while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 825) still applying desired pin config properties. GPIO functionality is thus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 826) orthogonal to any other device using the pin.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 827)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 828) In this arrangement the registers for the GPIO portions of the pin controller,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 829) or the registers for the GPIO hardware module are likely to reside in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 830) separate memory range only intended for GPIO driving, and the register
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 831) range dealing with pin config and pin multiplexing get placed into a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 832) different memory range and a separate section of the data sheet.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 833)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 834) A flag "strict" in struct pinmux_ops is available to check and deny
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 835) simultaneous access to the same pin from GPIO and pin multiplexing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 836) consumers on hardware of this type. The pinctrl driver should set this flag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 837) accordingly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 838)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 839) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 840)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 841) (B)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 842)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 843) pin config
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 844) logic regs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 845) | +- SPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 846) Physical pins --- pad --- pinmux -+- I2C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 847) | | +- mmc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 848) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 849) GPIO pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 850) multiplex
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 851) logic regs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 852)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 853) In this arrangement, the GPIO functionality can always be enabled, such that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 854) e.g. a GPIO input can be used to "spy" on the SPI/I2C/MMC signal while it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 855) pulsed out. It is likely possible to disrupt the traffic on the pin by doing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 856) wrong things on the GPIO block, as it is never really disconnected. It is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 857) possible that the GPIO, pin config and pin multiplex registers are placed into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 858) the same memory range and the same section of the data sheet, although that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 859) need not be the case.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 860)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 861) In some pin controllers, although the physical pins are designed in the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 862) way as (B), the GPIO function still can't be enabled at the same time as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 863) peripheral functions. So again the "strict" flag should be set, denying
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 864) simultaneous activation by GPIO and other muxed in devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 865)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 866) From a kernel point of view, however, these are different aspects of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 867) hardware and shall be put into different subsystems:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 868)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 869) - Registers (or fields within registers) that control electrical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 870) properties of the pin such as biasing and drive strength should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 871) exposed through the pinctrl subsystem, as "pin configuration" settings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 872)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 873) - Registers (or fields within registers) that control muxing of signals
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 874) from various other HW blocks (e.g. I2C, MMC, or GPIO) onto pins should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 875) be exposed through the pinctrl subsystem, as mux functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 876)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 877) - Registers (or fields within registers) that control GPIO functionality
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 878) such as setting a GPIO's output value, reading a GPIO's input value, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 879) setting GPIO pin direction should be exposed through the GPIO subsystem,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 880) and if they also support interrupt capabilities, through the irqchip
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 881) abstraction.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 882)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 883) Depending on the exact HW register design, some functions exposed by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 884) GPIO subsystem may call into the pinctrl subsystem in order to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 885) co-ordinate register settings across HW modules. In particular, this may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 886) be needed for HW with separate GPIO and pin controller HW modules, where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 887) e.g. GPIO direction is determined by a register in the pin controller HW
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 888) module rather than the GPIO HW module.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 889)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 890) Electrical properties of the pin such as biasing and drive strength
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 891) may be placed at some pin-specific register in all cases or as part
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 892) of the GPIO register in case (B) especially. This doesn't mean that such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 893) properties necessarily pertain to what the Linux kernel calls "GPIO".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 894)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 895) Example: a pin is usually muxed in to be used as a UART TX line. But during
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 896) system sleep, we need to put this pin into "GPIO mode" and ground it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 897)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 898) If you make a 1-to-1 map to the GPIO subsystem for this pin, you may start
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 899) to think that you need to come up with something really complex, that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 900) pin shall be used for UART TX and GPIO at the same time, that you will grab
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 901) a pin control handle and set it to a certain state to enable UART TX to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 902) muxed in, then twist it over to GPIO mode and use gpio_direction_output()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 903) to drive it low during sleep, then mux it over to UART TX again when you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 904) wake up and maybe even gpio_request/gpio_free as part of this cycle. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 905) all gets very complicated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 906)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 907) The solution is to not think that what the datasheet calls "GPIO mode"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 908) has to be handled by the <linux/gpio.h> interface. Instead view this as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 909) a certain pin config setting. Look in e.g. <linux/pinctrl/pinconf-generic.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 910) and you find this in the documentation:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 911)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 912) PIN_CONFIG_OUTPUT:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 913) this will configure the pin in output, use argument
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 914) 1 to indicate high level, argument 0 to indicate low level.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 915)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 916) So it is perfectly possible to push a pin into "GPIO mode" and drive the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 917) line low as part of the usual pin control map. So for example your UART
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 918) driver may look like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 919)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 920) #include <linux/pinctrl/consumer.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 921)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 922) struct pinctrl *pinctrl;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 923) struct pinctrl_state *pins_default;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 924) struct pinctrl_state *pins_sleep;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 925)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 926) pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 927) pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 928)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 929) /* Normal mode */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 930) retval = pinctrl_select_state(pinctrl, pins_default);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 931) /* Sleep mode */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 932) retval = pinctrl_select_state(pinctrl, pins_sleep);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 933)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 934) And your machine configuration may look like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 935) --------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 936)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 937) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 938)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 939) static unsigned long uart_default_mode[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 940) PIN_CONF_PACKED(PIN_CONFIG_DRIVE_PUSH_PULL, 0),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 941) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 942)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 943) static unsigned long uart_sleep_mode[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 944) PIN_CONF_PACKED(PIN_CONFIG_OUTPUT, 0),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 945) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 946)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 947) static struct pinctrl_map pinmap[] __initdata = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 948) PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 949) "u0_group", "u0"),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 950) PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 951) "UART_TX_PIN", uart_default_mode),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 952) PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 953) "u0_group", "gpio-mode"),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 954) PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 955) "UART_TX_PIN", uart_sleep_mode),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 956) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 957)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 958) foo_init(void) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 959) pinctrl_register_mappings(pinmap, ARRAY_SIZE(pinmap));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 960) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 961)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 962) Here the pins we want to control are in the "u0_group" and there is some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 963) function called "u0" that can be enabled on this group of pins, and then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 964) everything is UART business as usual. But there is also some function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 965) named "gpio-mode" that can be mapped onto the same pins to move them into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 966) GPIO mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 967)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 968) This will give the desired effect without any bogus interaction with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 969) GPIO subsystem. It is just an electrical configuration used by that device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 970) when going to sleep, it might imply that the pin is set into something the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 971) datasheet calls "GPIO mode", but that is not the point: it is still used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 972) by that UART device to control the pins that pertain to that very UART
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 973) driver, putting them into modes needed by the UART. GPIO in the Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 974) kernel sense are just some 1-bit line, and is a different use case.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 975)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 976) How the registers are poked to attain the push or pull, and output low
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 977) configuration and the muxing of the "u0" or "gpio-mode" group onto these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 978) pins is a question for the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 979)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 980) Some datasheets will be more helpful and refer to the "GPIO mode" as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 981) "low power mode" rather than anything to do with GPIO. This often means
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 982) the same thing electrically speaking, but in this latter case the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 983) software engineers will usually quickly identify that this is some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 984) specific muxing or configuration rather than anything related to the GPIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 985) API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 986)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 987)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 988) Board/machine configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 989) ===========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 990)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 991) Boards and machines define how a certain complete running system is put
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 992) together, including how GPIOs and devices are muxed, how regulators are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 993) constrained and how the clock tree looks. Of course pinmux settings are also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 994) part of this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 995)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 996) A pin controller configuration for a machine looks pretty much like a simple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 997) regulator configuration, so for the example array above we want to enable i2c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 998) and spi on the second function mapping::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 999)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1000) #include <linux/pinctrl/machine.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1001)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1002) static const struct pinctrl_map mapping[] __initconst = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1003) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1004) .dev_name = "foo-spi.0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1005) .name = PINCTRL_STATE_DEFAULT,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1006) .type = PIN_MAP_TYPE_MUX_GROUP,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1007) .ctrl_dev_name = "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1008) .data.mux.function = "spi0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1009) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1010) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1011) .dev_name = "foo-i2c.0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1012) .name = PINCTRL_STATE_DEFAULT,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1013) .type = PIN_MAP_TYPE_MUX_GROUP,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1014) .ctrl_dev_name = "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1015) .data.mux.function = "i2c0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1016) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1017) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1018) .dev_name = "foo-mmc.0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1019) .name = PINCTRL_STATE_DEFAULT,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1020) .type = PIN_MAP_TYPE_MUX_GROUP,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1021) .ctrl_dev_name = "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1022) .data.mux.function = "mmc0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1023) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1024) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1025)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1026) The dev_name here matches to the unique device name that can be used to look
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1027) up the device struct (just like with clockdev or regulators). The function name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1028) must match a function provided by the pinmux driver handling this pin range.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1029)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1030) As you can see we may have several pin controllers on the system and thus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1031) we need to specify which one of them contains the functions we wish to map.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1032)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1033) You register this pinmux mapping to the pinmux subsystem by simply::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1034)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1035) ret = pinctrl_register_mappings(mapping, ARRAY_SIZE(mapping));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1036)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1037) Since the above construct is pretty common there is a helper macro to make
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1038) it even more compact which assumes you want to use pinctrl-foo and position
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1039) 0 for mapping, for example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1040)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1041) static struct pinctrl_map mapping[] __initdata = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1042) PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1043) "pinctrl-foo", NULL, "i2c0"),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1044) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1045)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1046) The mapping table may also contain pin configuration entries. It's common for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1047) each pin/group to have a number of configuration entries that affect it, so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1048) the table entries for configuration reference an array of config parameters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1049) and values. An example using the convenience macros is shown below::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1050)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1051) static unsigned long i2c_grp_configs[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1052) FOO_PIN_DRIVEN,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1053) FOO_PIN_PULLUP,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1054) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1055)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1056) static unsigned long i2c_pin_configs[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1057) FOO_OPEN_COLLECTOR,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1058) FOO_SLEW_RATE_SLOW,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1059) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1060)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1061) static struct pinctrl_map mapping[] __initdata = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1062) PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1063) "pinctrl-foo", "i2c0", "i2c0"),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1064) PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1065) "pinctrl-foo", "i2c0", i2c_grp_configs),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1066) PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1067) "pinctrl-foo", "i2c0scl", i2c_pin_configs),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1068) PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1069) "pinctrl-foo", "i2c0sda", i2c_pin_configs),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1070) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1071)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1072) Finally, some devices expect the mapping table to contain certain specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1073) named states. When running on hardware that doesn't need any pin controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1074) configuration, the mapping table must still contain those named states, in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1075) order to explicitly indicate that the states were provided and intended to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1076) be empty. Table entry macro PIN_MAP_DUMMY_STATE serves the purpose of defining
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1077) a named state without causing any pin controller to be programmed::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1078)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1079) static struct pinctrl_map mapping[] __initdata = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1080) PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1081) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1082)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1083)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1084) Complex mappings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1085) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1086)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1087) As it is possible to map a function to different groups of pins an optional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1088) .group can be specified like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1089)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1090) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1091) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1092) .dev_name = "foo-spi.0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1093) .name = "spi0-pos-A",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1094) .type = PIN_MAP_TYPE_MUX_GROUP,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1095) .ctrl_dev_name = "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1096) .function = "spi0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1097) .group = "spi0_0_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1098) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1099) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1100) .dev_name = "foo-spi.0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1101) .name = "spi0-pos-B",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1102) .type = PIN_MAP_TYPE_MUX_GROUP,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1103) .ctrl_dev_name = "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1104) .function = "spi0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1105) .group = "spi0_1_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1106) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1107) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1109) This example mapping is used to switch between two positions for spi0 at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1110) runtime, as described further below under the heading "Runtime pinmuxing".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1112) Further it is possible for one named state to affect the muxing of several
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1113) groups of pins, say for example in the mmc0 example above, where you can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1114) additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1115) three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1116) case), we define a mapping like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1118) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1119) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1120) .dev_name = "foo-mmc.0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1121) .name = "2bit"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1122) .type = PIN_MAP_TYPE_MUX_GROUP,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1123) .ctrl_dev_name = "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1124) .function = "mmc0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1125) .group = "mmc0_1_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1126) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1127) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1128) .dev_name = "foo-mmc.0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1129) .name = "4bit"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1130) .type = PIN_MAP_TYPE_MUX_GROUP,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1131) .ctrl_dev_name = "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1132) .function = "mmc0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1133) .group = "mmc0_1_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1134) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1135) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1136) .dev_name = "foo-mmc.0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1137) .name = "4bit"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1138) .type = PIN_MAP_TYPE_MUX_GROUP,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1139) .ctrl_dev_name = "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1140) .function = "mmc0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1141) .group = "mmc0_2_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1142) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1143) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1144) .dev_name = "foo-mmc.0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1145) .name = "8bit"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1146) .type = PIN_MAP_TYPE_MUX_GROUP,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1147) .ctrl_dev_name = "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1148) .function = "mmc0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1149) .group = "mmc0_1_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1150) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1151) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1152) .dev_name = "foo-mmc.0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1153) .name = "8bit"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1154) .type = PIN_MAP_TYPE_MUX_GROUP,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1155) .ctrl_dev_name = "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1156) .function = "mmc0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1157) .group = "mmc0_2_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1158) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1159) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1160) .dev_name = "foo-mmc.0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1161) .name = "8bit"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1162) .type = PIN_MAP_TYPE_MUX_GROUP,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1163) .ctrl_dev_name = "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1164) .function = "mmc0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1165) .group = "mmc0_3_grp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1166) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1167) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1168)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1169) The result of grabbing this mapping from the device with something like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1170) this (see next paragraph)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1172) p = devm_pinctrl_get(dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1173) s = pinctrl_lookup_state(p, "8bit");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1174) ret = pinctrl_select_state(p, s);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1176) or more simply::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1178) p = devm_pinctrl_get_select(dev, "8bit");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1179)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1180) Will be that you activate all the three bottom records in the mapping at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1181) once. Since they share the same name, pin controller device, function and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1182) device, and since we allow multiple groups to match to a single device, they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1183) all get selected, and they all get enabled and disable simultaneously by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1184) pinmux core.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1186)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1187) Pin control requests from drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1188) =================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1190) When a device driver is about to probe the device core will automatically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1191) attempt to issue pinctrl_get_select_default() on these devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1192) This way driver writers do not need to add any of the boilerplate code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1193) of the type found below. However when doing fine-grained state selection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1194) and not using the "default" state, you may have to do some device driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1195) handling of the pinctrl handles and states.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1197) So if you just want to put the pins for a certain device into the default
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1198) state and be done with it, there is nothing you need to do besides
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1199) providing the proper mapping table. The device core will take care of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1200) the rest.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1201)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1202) Generally it is discouraged to let individual drivers get and enable pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1203) control. So if possible, handle the pin control in platform code or some other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1204) place where you have access to all the affected struct device * pointers. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1205) some cases where a driver needs to e.g. switch between different mux mappings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1206) at runtime this is not possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1208) A typical case is if a driver needs to switch bias of pins from normal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1209) operation and going to sleep, moving from the PINCTRL_STATE_DEFAULT to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1210) PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1211) current in sleep mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1212)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1213) A driver may request a certain control state to be activated, usually just the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1214) default state like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1216) #include <linux/pinctrl/consumer.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1217)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1218) struct foo_state {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1219) struct pinctrl *p;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1220) struct pinctrl_state *s;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1221) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1222) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1223)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1224) foo_probe()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1225) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1226) /* Allocate a state holder named "foo" etc */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1227) struct foo_state *foo = ...;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1229) foo->p = devm_pinctrl_get(&device);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1230) if (IS_ERR(foo->p)) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1231) /* FIXME: clean up "foo" here */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1232) return PTR_ERR(foo->p);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1233) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1235) foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1236) if (IS_ERR(foo->s)) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1237) /* FIXME: clean up "foo" here */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1238) return PTR_ERR(s);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1239) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1240)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1241) ret = pinctrl_select_state(foo->s);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1242) if (ret < 0) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1243) /* FIXME: clean up "foo" here */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1244) return ret;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1245) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1246) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1247)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1248) This get/lookup/select/put sequence can just as well be handled by bus drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1249) if you don't want each and every driver to handle it and you know the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1250) arrangement on your bus.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1252) The semantics of the pinctrl APIs are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1254) - pinctrl_get() is called in process context to obtain a handle to all pinctrl
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1255) information for a given client device. It will allocate a struct from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1256) kernel memory to hold the pinmux state. All mapping table parsing or similar
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1257) slow operations take place within this API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1259) - devm_pinctrl_get() is a variant of pinctrl_get() that causes pinctrl_put()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1260) to be called automatically on the retrieved pointer when the associated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1261) device is removed. It is recommended to use this function over plain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1262) pinctrl_get().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1264) - pinctrl_lookup_state() is called in process context to obtain a handle to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1265) specific state for a client device. This operation may be slow, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1267) - pinctrl_select_state() programs pin controller hardware according to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1268) definition of the state as given by the mapping table. In theory, this is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1269) fast-path operation, since it only involved blasting some register settings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1270) into hardware. However, note that some pin controllers may have their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1271) registers on a slow/IRQ-based bus, so client devices should not assume they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1272) can call pinctrl_select_state() from non-blocking contexts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1273)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1274) - pinctrl_put() frees all information associated with a pinctrl handle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1275)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1276) - devm_pinctrl_put() is a variant of pinctrl_put() that may be used to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1277) explicitly destroy a pinctrl object returned by devm_pinctrl_get().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1278) However, use of this function will be rare, due to the automatic cleanup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1279) that will occur even without calling it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1280)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1281) pinctrl_get() must be paired with a plain pinctrl_put().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1282) pinctrl_get() may not be paired with devm_pinctrl_put().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1283) devm_pinctrl_get() can optionally be paired with devm_pinctrl_put().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1284) devm_pinctrl_get() may not be paired with plain pinctrl_put().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1285)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1286) Usually the pin control core handled the get/put pair and call out to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1287) device drivers bookkeeping operations, like checking available functions and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1288) the associated pins, whereas select_state pass on to the pin controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1289) driver which takes care of activating and/or deactivating the mux setting by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1290) quickly poking some registers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1292) The pins are allocated for your device when you issue the devm_pinctrl_get()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1293) call, after this you should be able to see this in the debugfs listing of all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1294) pins.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1295)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1296) NOTE: the pinctrl system will return -EPROBE_DEFER if it cannot find the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1297) requested pinctrl handles, for example if the pinctrl driver has not yet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1298) registered. Thus make sure that the error path in your driver gracefully
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1299) cleans up and is ready to retry the probing later in the startup process.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1300)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1302) Drivers needing both pin control and GPIOs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1303) ==========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1305) Again, it is discouraged to let drivers lookup and select pin control states
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1306) themselves, but again sometimes this is unavoidable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1307)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1308) So say that your driver is fetching its resources like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1309)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1310) #include <linux/pinctrl/consumer.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1311) #include <linux/gpio.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1313) struct pinctrl *pinctrl;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1314) int gpio;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1316) pinctrl = devm_pinctrl_get_select_default(&dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1317) gpio = devm_gpio_request(&dev, 14, "foo");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1318)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1319) Here we first request a certain pin state and then request GPIO 14 to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1320) used. If you're using the subsystems orthogonally like this, you should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1321) nominally always get your pinctrl handle and select the desired pinctrl
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1322) state BEFORE requesting the GPIO. This is a semantic convention to avoid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1323) situations that can be electrically unpleasant, you will certainly want to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1324) mux in and bias pins in a certain way before the GPIO subsystems starts to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1325) deal with them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1327) The above can be hidden: using the device core, the pinctrl core may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1328) setting up the config and muxing for the pins right before the device is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1329) probing, nevertheless orthogonal to the GPIO subsystem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1330)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1331) But there are also situations where it makes sense for the GPIO subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1332) to communicate directly with the pinctrl subsystem, using the latter as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1333) back-end. This is when the GPIO driver may call out to the functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1334) described in the section "Pin control interaction with the GPIO subsystem"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1335) above. This only involves per-pin multiplexing, and will be completely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1336) hidden behind the gpio_*() function namespace. In this case, the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1337) need not interact with the pin control subsystem at all.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1338)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1339) If a pin control driver and a GPIO driver is dealing with the same pins
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1340) and the use cases involve multiplexing, you MUST implement the pin controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1341) as a back-end for the GPIO driver like this, unless your hardware design
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1342) is such that the GPIO controller can override the pin controller's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1343) multiplexing state through hardware without the need to interact with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1344) pin control system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1345)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1346)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1347) System pin control hogging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1348) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1349)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1350) Pin control map entries can be hogged by the core when the pin controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1351) is registered. This means that the core will attempt to call pinctrl_get(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1352) lookup_state() and select_state() on it immediately after the pin control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1353) device has been registered.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1354)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1355) This occurs for mapping table entries where the client device name is equal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1356) to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1357)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1358) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1359) .dev_name = "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1360) .name = PINCTRL_STATE_DEFAULT,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1361) .type = PIN_MAP_TYPE_MUX_GROUP,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1362) .ctrl_dev_name = "pinctrl-foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1363) .function = "power_func",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1364) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1365)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1366) Since it may be common to request the core to hog a few always-applicable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1367) mux settings on the primary pin controller, there is a convenience macro for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1368) this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1369)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1370) PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1371) "power_func")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1372)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1373) This gives the exact same result as the above construction.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1374)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1375)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1376) Runtime pinmuxing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1377) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1378)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1379) It is possible to mux a certain function in and out at runtime, say to move
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1380) an SPI port from one set of pins to another set of pins. Say for example for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1381) spi0 in the example above, we expose two different groups of pins for the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1382) function, but with different named in the mapping as described under
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1383) "Advanced mapping" above. So that for an SPI device, we have two states named
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1384) "pos-A" and "pos-B".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1385)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1386) This snippet first initializes a state object for both groups (in foo_probe()),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1387) then muxes the function in the pins defined by group A, and finally muxes it in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1388) on the pins defined by group B::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1389)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1390) #include <linux/pinctrl/consumer.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1391)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1392) struct pinctrl *p;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1393) struct pinctrl_state *s1, *s2;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1394)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1395) foo_probe()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1396) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1397) /* Setup */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1398) p = devm_pinctrl_get(&device);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1399) if (IS_ERR(p))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1400) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1401)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1402) s1 = pinctrl_lookup_state(foo->p, "pos-A");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1403) if (IS_ERR(s1))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1404) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1405)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1406) s2 = pinctrl_lookup_state(foo->p, "pos-B");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1407) if (IS_ERR(s2))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1408) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1409) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1410)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1411) foo_switch()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1412) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1413) /* Enable on position A */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1414) ret = pinctrl_select_state(s1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1415) if (ret < 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1416) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1417)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1418) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1419)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1420) /* Enable on position B */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1421) ret = pinctrl_select_state(s2);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1422) if (ret < 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1423) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1424)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1425) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1426) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1427)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1428) The above has to be done from process context. The reservation of the pins
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1429) will be done when the state is activated, so in effect one specific pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1430) can be used by different functions at different times on a running system.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags