Lines Matching +full:part +full:- +full:2 +full:- +full:pins
9 - Enumerating and naming controllable pins
11 - Multiplexing of pins, pads, fingers (etc) see below for details
13 - Configuration of pins, pads, fingers (etc), such as software-controlled
14 biasing and driving mode specific pins, such as pull-up/down, open drain,
17 Top-level interface
22 - A pin controller is a piece of hardware, usually a set of registers, that
23 can control PINs. It may be able to multiplex, bias, set load capacitance,
24 set drive strength, etc. for individual pins or groups of pins.
28 - PINS are equal to pads, fingers, balls or whatever packaging input or
32 be sparse - i.e. there may be gaps in the space with numbers where no
37 describing the pins handled by this specific pin controller.
55 2 o o o o o o o o
59 To register a pin controller and name all the pins on this package we can do
67 PINCTRL_PIN(2, "C8"),
76 .pins = foo_pins,
98 See for example arch/arm/mach-ux500/Kconfig for an example.
100 Pins usually have fancier names than this. You can find these in the datasheet
103 the pins from 0 in the upper left corner to 63 in the lower right corner.
110 For a padring with 467 pads, as opposed to actual pins, I used an enumeration
126 Many controllers need to deal with groups of pins, so the pin controller
127 subsystem has a mechanism for enumerating groups of pins and retrieving the
128 actual enumerated pins that are part of a certain group.
130 For example, say that we have a group of pins dealing with an SPI interface
131 on { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins
141 const unsigned int *pins;
151 .pins = spi0_pins,
156 .pins = i2c0_pins,
174 const unsigned **pins,
177 *pins = (unsigned *) foo_groups[selector].pins;
196 to retrieve the name and pins of the group. Maintaining the data structure of
197 the groups is up to the driver, this is just a simple example - in practice you
205 Pins can sometimes be software-configured in various ways, mostly related
209 using a certain resistor value - pull up and pull down - so that the pin has a
281 physical pins that are also registered as pin controller pins.
286 situations a cross-subsystem mapping between pins and GPIOs is needed.
291 may be muxing several GPIO ranges (typically SoCs that have one set of pins,
325 GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and
338 - GPIO range : [32 .. 47]
339 - pin range : [32 .. 47]
341 - GPIO range : [48 .. 55]
342 - pin range : [64 .. 71]
344 The above examples assume the mapping between the GPIOs and pins is
348 static const unsigned range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 };
354 .pins = &range_pins,
360 group is known, the pins and npins elements of the above structure can be
364 pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins,
367 When GPIO-specific functions in the pin control subsystem are called, these
370 pin controller handling the matching range is found, GPIO-specific functions
407 +---+
413 +---+---+
415 +---+---+ +---+
420 2 o o o o o o | o | o
421 +-------+-------+-------+---+---+
423 +-------+-------+-------+---+---+
426 are chessboard-like, big ones have "holes" in some arrangement according to
428 pins you see some will be taken by things like a few VCC and GND to feed power
430 memory interface. The remaining pins will often be subject to pin multiplexing.
433 to its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using
436 In this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port
437 (these are four pins: CLK, RXD, TXD, FRM). In that case, pin B5 can be used as
438 some general-purpose GPIO pin. However, in another setting, pins { A5, B5 } can
439 be used as an I2C port (these are just two pins: SCL, SDA). Needless to say,
442 out on pins { G4, G3, G2, G1 }.
445 special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will
446 consume 2, 4 or 8 pins respectively, so either { A1, B1 } are taken or
448 port on pins { G4, G3, G2, G1 } of course.
453 different pins by pinmux settings.
455 Since general-purpose I/O pins (GPIO) are typically always in shortage, it is
471 - FUNCTIONS can be switched in and out by a driver residing with the pin
476 - FUNCTIONS are assumed to be enumerable from zero in a one-dimensional array.
480 - FUNCTIONS have PIN GROUPS as defined on the generic level - so a certain
483 function i2c is associated with the pins { A5, B5 }, enumerated as
493 - The combination of a FUNCTION and a PIN GROUP determine a certain function
494 for a certain set of pins. The knowledge of the functions and pin groups
495 and their machine-specific particulars are kept inside the pinmux driver,
499 - The name of a function with a certain selector (>= 0)
500 - A list of groups associated with a certain function
501 - That a certain group in that list to be activated for a certain function
503 As already described above, pin groups are in turn self-descriptive, so
507 - FUNCTIONS and GROUPS on a certain PIN CONTROLLER are MAPPED to a certain
511 the set of pins to be used by a certain device. (If only one possible group
512 of pins is available for the function, no group name need to be supplied -
521 {"map-spi0", spi0, pinctrl0, fspi0, gspi0},
522 {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0}
526 function. The group is not compulsory - if it is omitted the first group
532 a certain pin controller may use different sets of pins in different
535 - PINS for a certain FUNCTION using a certain PIN GROUP on a certain
536 PIN CONTROLLER are provided on a first-come first-serve basis, so if some
542 pads (or "fingers") rather than pins - these are the soldering surfaces on the
544 pins/balls underneath the capsule. Pick some enumeration that makes sense to
545 you. Define enumerators only for the pins you can control if that makes sense.
562 The pinmux core takes care of preventing conflicts on pins and calling
575 A simple driver for the above example will work by setting bits 0, 1, 2, 3 or 4
577 group of pins would work something like this::
584 const unsigned int *pins;
598 .pins = spi0_0_pins,
603 .pins = spi0_1_pins,
608 .pins = i2c0_pins,
613 .pins = mmc0_1_pins,
618 .pins = mmc0_2_pins,
623 .pins = mmc0_3_pins,
641 const unsigned ** pins,
644 *pins = (unsigned *) foo_groups[selector].pins;
731 pins and who is using them, it will already have denied an impossible
733 things - when it gets a selector passed in, the pinmux subsystem makes
735 pins. Thus bits 0 and 1 in the control register will never be set at the
753 gpiolib-based drivers as part of their gpio_request() and
758 NOTE that platforms and individual drivers shall *NOT* request GPIO pins to be
760 that driver request proper muxing and other control for its pins.
763 individual pin into a GPIO pin independent of any other pins, and then try
774 controller core, so you know which GPIO pins are being affected by the request
786 special GPIO-handler is registered.
802 software-control a few electrical properties of the pin that you would
813 | +- SPI
814 Physical pins --- pad --- pinmux -+- I2C
815 | +- mmc
816 | +- GPIO
845 | +- SPI
846 Physical pins --- pad --- pinmux -+- I2C
847 | | +- mmc
861 In some pin controllers, although the physical pins are designed in the same
869 - Registers (or fields within registers) that control electrical
873 - Registers (or fields within registers) that control muxing of signals
874 from various other HW blocks (e.g. I2C, MMC, or GPIO) onto pins should
877 - Registers (or fields within registers) that control GPIO functionality
885 co-ordinate register settings across HW modules. In particular, this may
891 may be placed at some pin-specific register in all cases or as part
898 If you make a 1-to-1 map to the GPIO subsystem for this pin, you may start
904 wake up and maybe even gpio_request/gpio_free as part of this cycle. This
909 a certain pin config setting. Look in e.g. <linux/pinctrl/pinconf-generic.h>
917 line low as part of the usual pin control map. So for example your UART
926 pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT);
927 pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP);
935 --------------------------------------------------
948 PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
950 PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
952 PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
953 "u0_group", "gpio-mode"),
954 PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
962 Here the pins we want to control are in the "u0_group" and there is some
963 function called "u0" that can be enabled on this group of pins, and then
965 named "gpio-mode" that can be mapped onto the same pins to move them into
972 by that UART device to control the pins that pertain to that very UART
974 kernel sense are just some 1-bit line, and is a different use case.
977 configuration and the muxing of the "u0" or "gpio-mode" group onto these
978 pins is a question for the driver.
994 part of this.
1004 .dev_name = "foo-spi.0",
1007 .ctrl_dev_name = "pinctrl-foo",
1011 .dev_name = "foo-i2c.0",
1014 .ctrl_dev_name = "pinctrl-foo",
1018 .dev_name = "foo-mmc.0",
1021 .ctrl_dev_name = "pinctrl-foo",
1038 it even more compact which assumes you want to use pinctrl-foo and position
1042 PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT,
1043 "pinctrl-foo", NULL, "i2c0"),
1062 PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
1063 "pinctrl-foo", "i2c0", "i2c0"),
1064 PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
1065 "pinctrl-foo", "i2c0", i2c_grp_configs),
1066 PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
1067 "pinctrl-foo", "i2c0scl", i2c_pin_configs),
1068 PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
1069 "pinctrl-foo", "i2c0sda", i2c_pin_configs),
1080 PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),
1087 As it is possible to map a function to different groups of pins an optional
1092 .dev_name = "foo-spi.0",
1093 .name = "spi0-pos-A",
1095 .ctrl_dev_name = "pinctrl-foo",
1100 .dev_name = "foo-spi.0",
1101 .name = "spi0-pos-B",
1103 .ctrl_dev_name = "pinctrl-foo",
1113 groups of pins, say for example in the mmc0 example above, where you can
1114 additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all
1115 three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the
1120 .dev_name = "foo-mmc.0",
1121 .name = "2bit"
1123 .ctrl_dev_name = "pinctrl-foo",
1128 .dev_name = "foo-mmc.0",
1131 .ctrl_dev_name = "pinctrl-foo",
1136 .dev_name = "foo-mmc.0",
1139 .ctrl_dev_name = "pinctrl-foo",
1144 .dev_name = "foo-mmc.0",
1147 .ctrl_dev_name = "pinctrl-foo",
1152 .dev_name = "foo-mmc.0",
1155 .ctrl_dev_name = "pinctrl-foo",
1160 .dev_name = "foo-mmc.0",
1163 .ctrl_dev_name = "pinctrl-foo",
1193 of the type found below. However when doing fine-grained state selection
1197 So if you just want to put the pins for a certain device into the default
1208 A typical case is if a driver needs to switch bias of pins from normal
1210 PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save
1229 foo->p = devm_pinctrl_get(&device);
1230 if (IS_ERR(foo->p)) {
1232 return PTR_ERR(foo->p);
1235 foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);
1236 if (IS_ERR(foo->s)) {
1238 return PTR_ERR(foo->s);
1241 ret = pinctrl_select_state(foo->s);
1254 - pinctrl_get() is called in process context to obtain a handle to all pinctrl
1259 - devm_pinctrl_get() is a variant of pinctrl_get() that causes pinctrl_put()
1264 - pinctrl_lookup_state() is called in process context to obtain a handle to a
1267 - pinctrl_select_state() programs pin controller hardware according to the
1269 fast-path operation, since it only involved blasting some register settings
1271 registers on a slow/IRQ-based bus, so client devices should not assume they
1272 can call pinctrl_select_state() from non-blocking contexts.
1274 - pinctrl_put() frees all information associated with a pinctrl handle.
1276 - devm_pinctrl_put() is a variant of pinctrl_put() that may be used to
1288 the associated pins, whereas select_state pass on to the pin controller
1292 The pins are allocated for your device when you issue the devm_pinctrl_get()
1294 pins.
1296 NOTE: the pinctrl system will return -EPROBE_DEFER if it cannot find the
1324 mux in and bias pins in a certain way before the GPIO subsystems starts to
1328 setting up the config and muxing for the pins right before the device is
1333 back-end. This is when the GPIO driver may call out to the functions
1335 above. This only involves per-pin multiplexing, and will be completely
1339 If a pin control driver and a GPIO driver is dealing with the same pins
1341 as a back-end for the GPIO driver like this, unless your hardware design
1359 .dev_name = "pinctrl-foo",
1362 .ctrl_dev_name = "pinctrl-foo",
1366 Since it may be common to request the core to hog a few always-applicable
1370 PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */,
1380 an SPI port from one set of pins to another set of pins. Say for example for
1381 spi0 in the example above, we expose two different groups of pins for the same
1384 "pos-A" and "pos-B".
1387 then muxes the function in the pins defined by group A, and finally muxes it in
1388 on the pins defined by group B::
1402 s1 = pinctrl_lookup_state(foo->p, "pos-A");
1406 s2 = pinctrl_lookup_state(foo->p, "pos-B");
1428 The above has to be done from process context. The reservation of the pins
1437 - ``pinctrl-devices``: prints each pin controller device along with columns to
1440 - ``pinctrl-handles``: prints each configured pin controller handle and the
1443 - ``pinctrl-maps``: print all pinctrl maps
1445 A sub-directory is created inside of ``/sys/kernel/debug/pinctrl`` for each pin
1448 - ``pins``: prints a line for each pin registered on the pin controller. The
1451 - ``gpio-ranges``: print ranges that map gpio lines to pins on the controller
1453 - ``pingroups``: print all pin groups registered on the pin controller
1455 - ``pinconf-pins``: print pin config settings for each pin
1457 - ``pinconf-groups``: print pin config settings per pin group
1459 - ``pinmux-functions``: print each pin function along with the pin groups that
1462 - ``pinmux-pins``: iterate through all pins and print mux owner, gpio owner
1465 - ``pinmux-select``: write to this file to activate a pin function for a group::
1467 echo "<group-name function-name>" > pinmux-select