- A pin controller is a piece of hardware, usually a set of registers, that
can control PINs. It may be able to multiplex, bias, set load capacitance,
- set drive strength etc for individual pins or groups of pins.
+ set drive strength, etc. for individual pins or groups of pins.
Definition of PIN:
.name = "foo",
.pins = foo_pins,
.npins = ARRAY_SIZE(foo_pins),
- .maxpin = 63,
.owner = THIS_MODULE,
};
struct pinctrl_dev *pctl;
pctl = pinctrl_register(&foo_desc, <PARENT>, NULL);
- if (IS_ERR(pctl))
+ if (!pctl)
pr_err("could not register foo pin driver\n");
}
since these are so tightly integrated with the machines they are used on.
See for example arch/arm/mach-u300/Kconfig for an example.
-Pins usually have fancier names than this. You can find these in the dataheet
+Pins usually have fancier names than this. You can find these in the datasheet
for your chip. Notice that the core pinctrl.h file provides a fancy macro
called PINCTRL_PIN() to create the struct entries. As you can see I enumerated
the pins from 0 in the upper left corner to 63 in the lower right corner.
}
static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
- unsigned ** const pins,
- unsigned * const num_pins)
+ const unsigned **pins,
+ unsigned *num_pins)
{
*pins = (unsigned *) foo_groups[selector].pins;
*num_pins = foo_groups[selector].num_pins;
};
The pin control subsystem will call the .get_groups_count() function to
-determine total number of legal selectors, then it will call the other functions
+determine the total number of legal selectors, then it will call the other functions
to retrieve the name and pins of the group. Maintaining the data structure of
the groups is up to the driver, this is just a simple example - in practice you
may need more entries in your group structure, for example specific register
Pin configuration
=================
-Pins can sometimes be software-configured in an various ways, mostly related
+Pins can sometimes be software-configured in various ways, mostly related
to their electronic properties when used as inputs or outputs. For example you
may be able to make an output pin high impedance, or "tristate" meaning it is
effectively disconnected. You may be able to connect an input pin to VDD or GND
controller we need a mapping so that the pin control subsystem can figure out
which pin controller handles control of a certain GPIO pin. Since a single
pin controller may be muxing several GPIO ranges (typically SoCs that have
-one set of pins but internally several GPIO silicon blocks, each modeled as
+one set of pins, but internally several GPIO silicon blocks, each modelled as
a struct gpio_chip) any number of GPIO ranges can be added to a pin controller
instance like this:
- GPIO range : [48 .. 55]
- pin range : [64 .. 71]
+The above examples assume the mapping between the GPIOs and pins is
+linear. If the mapping is sparse or haphazard, an array of arbitrary pin
+numbers can be encoded in the range like this:
+
+static const unsigned range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 };
+
+static struct pinctrl_gpio_range gpio_range = {
+ .name = "chip",
+ .id = 0,
+ .base = 32,
+ .pins = &range_pins,
+ .npins = ARRAY_SIZE(range_pins),
+ .gc = &chip;
+};
+
+In this case the pin_base property will be ignored. If the name of a pin
+group is known, the pins and npins elements of the above structure can be
+initialised using the function pinctrl_get_group_pins(), e.g. for pin
+group "foo":
+
+pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins, &gpio_range.npins);
+
When GPIO-specific functions in the pin control subsystem are called, these
ranges will be used to look up the appropriate pin controller by inspecting
and matching the pin to the pin ranges across all controllers. When a
will be called on that specific pin controller.
For all functionalities dealing with pin biasing, pin muxing etc, the pin
-controller subsystem will subtract the range's .base offset from the passed
-in gpio number, and add the ranges's .pin_base offset to retrive a pin number.
-After that, the subsystem passes it on to the pin control driver, so the driver
-will get an pin number into its handled number range. Further it is also passed
+controller subsystem will look up the corresponding pin number from the passed
+in gpio number, and use the range's internals to retrieve a pin number. After
+that, the subsystem passes it on to the pin control driver, so the driver
+will get a pin number into its handled number range. Further it is also passed
the range ID value, so that the pin controller knows which range it should
deal with.
section 2.1 of Documentation/devicetree/bindings/gpio/gpio.txt on how to bind
pinctrl and gpio drivers.
+
PINMUX interfaces
=================
to the chip, and quite a few will be taken by large ports like an external
memory interface. The remaining pins will often be subject to pin multiplexing.
-The example 8x8 PGA package above will have pin numbers 0 thru 63 assigned to
-its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using
+The example 8x8 PGA package above will have pin numbers 0 through 63 assigned
+to its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using
pinctrl_register_pins() and a suitable data set as shown earlier.
In this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port
of the package the silicon performing the SPI logic can alternatively be routed
out on pins { G4, G3, G2, G1 }.
-On the botton row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something
+On the bottom row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something
special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will
consume 2, 4 or 8 pins respectively, so either { A1, B1 } are taken or
{ A1, B1, C1, D1 } or all of them. If we use all 8 bits, we cannot use the SPI
We assume that the number of possible function maps to pin groups is limited by
the hardware. I.e. we assume that there is no system where any function can be
-mapped to any pin, like in a phone exchange. So the available pins groups for
+mapped to any pin, like in a phone exchange. So the available pin groups for
a certain function will be limited to a few choices (say up to eight or so),
not hundreds or any amount of choices. This is the characteristic we have found
by inspecting available pinmux hardware, and a necessary assumption since we
the pin controller driver to execute different settings.
It is the responsibility of the pinmux driver to impose further restrictions
-(say for example infer electronic limitations due to load etc) to determine
+(say for example infer electronic limitations due to load, etc.) to determine
whether or not the requested function can actually be allowed, and in case it
is possible to perform the requested mux setting, poke the hardware so that
this happens.
Pinmux drivers are required to supply a few callback functions, some are
-optional. Usually the enable() and disable() functions are implemented,
-writing values into some certain registers to activate a certain mux setting
-for a certain pin.
+optional. Usually the set_mux() function is implemented, writing values into
+some certain registers to activate a certain mux setting for a certain pin.
A simple driver for the above example will work by setting bits 0, 1, 2, 3 or 4
into some register named MUX to select a certain function with a certain
},
};
-int foo_get_functions_count(struct pinctrl_dev *pctldev)
+static int foo_get_functions_count(struct pinctrl_dev *pctldev)
{
return ARRAY_SIZE(foo_functions);
}
-const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector)
+static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector)
{
return foo_functions[selector].name;
}
return 0;
}
-int foo_enable(struct pinctrl_dev *pctldev, unsigned selector,
+static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned selector,
unsigned group)
{
u8 regbit = (1 << selector + group);
return 0;
}
-void foo_disable(struct pinctrl_dev *pctldev, unsigned selector,
- unsigned group)
-{
- u8 regbit = (1 << selector + group);
-
- writeb((readb(MUX) & ~(regbit)), MUX)
- return 0;
-}
-
-struct pinmux_ops foo_pmxops = {
+static struct pinmux_ops foo_pmxops = {
.get_functions_count = foo_get_functions_count,
.get_function_name = foo_get_fname,
.get_function_groups = foo_get_groups,
- .enable = foo_enable,
- .disable = foo_disable,
+ .set_mux = foo_set_mux,
+ .strict = true,
};
/* Pinmux operations are handled by some pin controller */
Note that the following implies that the use case is to use a certain pin
from the Linux kernel using the API in <linux/gpio.h> with gpio_request()
and similar functions. There are cases where you may be using something
-that your datasheet calls "GPIO mode" but actually is just an electrical
+that your datasheet calls "GPIO mode", but actually is just an electrical
configuration for a certain device. See the section below named
"GPIO mode pitfalls" for more details on this scenario.
GPIO mode pitfalls
==================
-Sometime the developer may be confused by a datasheet talking about a pin
-being possible to set into "GPIO mode". It appears that what hardware
-engineers mean with "GPIO mode" is not necessarily the use case that is
-implied in the kernel interface <linux/gpio.h>: a pin that you grab from
-kernel code and then either listen for input or drive high/low to
-assert/deassert some external line.
+Due to the naming conventions used by hardware engineers, where "GPIO"
+is taken to mean different things than what the kernel does, the developer
+may be confused by a datasheet talking about a pin being possible to set
+into "GPIO mode". It appears that what hardware engineers mean with
+"GPIO mode" is not necessarily the use case that is implied in the kernel
+interface <linux/gpio.h>: a pin that you grab from kernel code and then
+either listen for input or drive high/low to assert/deassert some
+external line.
Rather hardware engineers think that "GPIO mode" means that you can
software-control a few electrical properties of the pin that you would
not be able to control if the pin was in some other mode, such as muxed in
for a device.
+The GPIO portions of a pin and its relation to a certain pin controller
+configuration and muxing logic can be constructed in several ways. Here
+are two examples:
+
+(A)
+ pin config
+ logic regs
+ | +- SPI
+ Physical pins --- pad --- pinmux -+- I2C
+ | +- mmc
+ | +- GPIO
+ pin
+ multiplex
+ logic regs
+
+Here some electrical properties of the pin can be configured no matter
+whether the pin is used for GPIO or not. If you multiplex a GPIO onto a
+pin, you can also drive it high/low from "GPIO" registers.
+Alternatively, the pin can be controlled by a certain peripheral, while
+still applying desired pin config properties. GPIO functionality is thus
+orthogonal to any other device using the pin.
+
+In this arrangement the registers for the GPIO portions of the pin controller,
+or the registers for the GPIO hardware module are likely to reside in a
+separate memory range only intended for GPIO driving, and the register
+range dealing with pin config and pin multiplexing get placed into a
+different memory range and a separate section of the data sheet.
+
+A flag "strict" in struct pinmux_ops is available to check and deny
+simultaneous access to the same pin from GPIO and pin multiplexing
+consumers on hardware of this type. The pinctrl driver should set this flag
+accordingly.
+
+(B)
+
+ pin config
+ logic regs
+ | +- SPI
+ Physical pins --- pad --- pinmux -+- I2C
+ | | +- mmc
+ | |
+ GPIO pin
+ multiplex
+ logic regs
+
+In this arrangement, the GPIO functionality can always be enabled, such that
+e.g. a GPIO input can be used to "spy" on the SPI/I2C/MMC signal while it is
+pulsed out. It is likely possible to disrupt the traffic on the pin by doing
+wrong things on the GPIO block, as it is never really disconnected. It is
+possible that the GPIO, pin config and pin multiplex registers are placed into
+the same memory range and the same section of the data sheet, although that
+need not be the case.
+
+In some pin controllers, although the physical pins are designed in the same
+way as (B), the GPIO function still can't be enabled at the same time as the
+peripheral functions. So again the "strict" flag should be set, denying
+simultaneous activation by GPIO and other muxed in devices.
+
+From a kernel point of view, however, these are different aspects of the
+hardware and shall be put into different subsystems:
+
+- Registers (or fields within registers) that control electrical
+ properties of the pin such as biasing and drive strength should be
+ exposed through the pinctrl subsystem, as "pin configuration" settings.
+
+- Registers (or fields within registers) that control muxing of signals
+ from various other HW blocks (e.g. I2C, MMC, or GPIO) onto pins should
+ be exposed through the pinctrl subsystem, as mux functions.
+
+- Registers (or fields within registers) that control GPIO functionality
+ such as setting a GPIO's output value, reading a GPIO's input value, or
+ setting GPIO pin direction should be exposed through the GPIO subsystem,
+ and if they also support interrupt capabilities, through the irqchip
+ abstraction.
+
+Depending on the exact HW register design, some functions exposed by the
+GPIO subsystem may call into the pinctrl subsystem in order to
+co-ordinate register settings across HW modules. In particular, this may
+be needed for HW with separate GPIO and pin controller HW modules, where
+e.g. GPIO direction is determined by a register in the pin controller HW
+module rather than the GPIO HW module.
+
+Electrical properties of the pin such as biasing and drive strength
+may be placed at some pin-specific register in all cases or as part
+of the GPIO register in case (B) especially. This doesn't mean that such
+properties necessarily pertain to what the Linux kernel calls "GPIO".
+
Example: a pin is usually muxed in to be used as a UART TX line. But during
system sleep, we need to put this pin into "GPIO mode" and ground it.
If you make a 1-to-1 map to the GPIO subsystem for this pin, you may start
-to think that you need to come up with something real complex, that the
+to think that you need to come up with something really complex, that the
pin shall be used for UART TX and GPIO at the same time, that you will grab
a pin control handle and set it to a certain state to enable UART TX to be
muxed in, then twist it over to GPIO mode and use gpio_direction_output()
PIN_CONF_PACKED(PIN_CONFIG_OUTPUT, 0),
};
-static struct pinctrl_map __initdata pinmap[] = {
+static struct pinctrl_map pinmap[] __initdata = {
PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
"u0_group", "u0"),
PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
This will give the desired effect without any bogus interaction with the
GPIO subsystem. It is just an electrical configuration used by that device
when going to sleep, it might imply that the pin is set into something the
-datasheet calls "GPIO mode" but that is not the point: it is still used
+datasheet calls "GPIO mode", but that is not the point: it is still used
by that UART device to control the pins that pertain to that very UART
driver, putting them into modes needed by the UART. GPIO in the Linux
kernel sense are just some 1-bit line, and is a different use case.
-How the registers are poked to attain the push/pull and output low
+How the registers are poked to attain the push or pull, and output low
configuration and the muxing of the "u0" or "gpio-mode" group onto these
pins is a question for the driver.
"low power mode" rather than anything to do with GPIO. This often means
the same thing electrically speaking, but in this latter case the
software engineers will usually quickly identify that this is some
-specific muxing/configuration rather than anything related to the GPIO
+specific muxing or configuration rather than anything related to the GPIO
API.
must match a function provided by the pinmux driver handling this pin range.
As you can see we may have several pin controllers on the system and thus
-we need to specify which one of them that contain the functions we wish
-to map.
+we need to specify which one of them contains the functions we wish to map.
You register this pinmux mapping to the pinmux subsystem by simply:
it even more compact which assumes you want to use pinctrl-foo and position
0 for mapping, for example:
-static struct pinctrl_map __initdata mapping[] = {
+static struct pinctrl_map mapping[] __initdata = {
PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT, "pinctrl-foo", NULL, "i2c0"),
};
FOO_SLEW_RATE_SLOW,
};
-static struct pinctrl_map __initdata mapping[] = {
+static struct pinctrl_map mapping[] __initdata = {
PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", "i2c0"),
PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", i2c_grp_configs),
PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0scl", i2c_pin_configs),
be empty. Table entry macro PIN_MAP_DUMMY_STATE serves the purpose of defining
a named state without causing any pin controller to be programmed:
-static struct pinctrl_map __initdata mapping[] = {
+static struct pinctrl_map mapping[] __initdata = {
PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),
};
pinctrl_get().
- pinctrl_lookup_state() is called in process context to obtain a handle to a
- specific state for a the client device. This operation may be slow too.
+ specific state for a client device. This operation may be slow, too.
- pinctrl_select_state() programs pin controller hardware according to the
- definition of the state as given by the mapping table. In theory this is a
+ definition of the state as given by the mapping table. In theory, this is a
fast-path operation, since it only involved blasting some register settings
into hardware. However, note that some pin controllers may have their
registers on a slow/IRQ-based bus, so client devices should not assume they
Usually the pin control core handled the get/put pair and call out to the
device drivers bookkeeping operations, like checking available functions and
-the associated pins, whereas the enable/disable pass on to the pin controller
+the associated pins, whereas select_state pass on to the pin controller
driver which takes care of activating and/or deactivating the mux setting by
quickly poking some registers.
probing, nevertheless orthogonal to the GPIO subsystem.
But there are also situations where it makes sense for the GPIO subsystem
-to communicate directly with with the pinctrl subsystem, using the latter
-as a back-end. This is when the GPIO driver may call out to the functions
+to communicate directly with the pinctrl subsystem, using the latter as a
+back-end. This is when the GPIO driver may call out to the functions
described in the section "Pin control interaction with the GPIO subsystem"
above. This only involves per-pin multiplexing, and will be completely
hidden behind the gpio_*() function namespace. In this case, the driver
"Advanced mapping" above. So that for an SPI device, we have two states named
"pos-A" and "pos-B".
-This snippet first muxes the function in the pins defined by group A, enables
-it, disables and releases it, and muxes it in on the pins defined by group B:
+This snippet first initializes a state object for both groups (in foo_probe()),
+then muxes the function in the pins defined by group A, and finally muxes it in
+on the pins defined by group B:
#include <linux/pinctrl/consumer.h>
projects / firefly-linux-kernel-4.4.55.git / blobdiff