pinctrl: Fix some typos and grammar issues in the documentation

- 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:

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.

};

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 modelled 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:

For all functionalities dealing with pin biasing, pin muxing etc, the pin

controller subsystem will look up the corresponding pin number from the passed

in gpio number, and use the range's internals to retrive a pin number. After

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 an pin number into its handled number range. Further it is also passed

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.

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.

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.

- 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 subssytem, as mux functions.

  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

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()

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:

  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