pinctrl: move generic functions to the pinctrl_ namespace

All the above functions are mandatory to implement for a pinmux driver.

Pinmux interaction with the GPIO subsystem

==========================================

Pin control interaction with the GPIO subsystem

===============================================

The public pinmux API contains two functions named pinmux_request_gpio()

and pinmux_free_gpio(). These two functions shall *ONLY* be called from

The public pinmux API contains two functions named pinctrl_request_gpio()

and pinctrl_free_gpio(). These two functions shall *ONLY* be called from

gpiolib-based drivers as part of their gpio_request() and

gpio_free() semantics. Likewise the pinmux_gpio_direction_[input|output]

gpio_free() semantics. Likewise the pinctrl_gpio_direction_[input|output]

shall only be called from within respective gpio_direction_[input|output]

gpiolib implementation.

NOTE that platforms and individual drivers shall *NOT* request GPIO pins to be

muxed in. Instead, implement a proper gpiolib driver and have that driver

request proper muxing for its pins.

controlled e.g. muxed in. Instead, implement a proper gpiolib driver and have

that driver request proper muxing and other control for its pins.

The function list could become long, especially if you can convert every

individual pin into a GPIO pin independent of any other pins, and then try

In this case, the function array would become 64 entries for each GPIO

setting and then the device functions.

For this reason there are two functions a pinmux driver can implement

For this reason there are two functions a pin control driver can implement

to enable only GPIO on an individual pin: .gpio_request_enable() and

.gpio_disable_free().

will be passed along to this function.

Alternatively to using these special functions, it is fully allowed to use

named functions for each GPIO pin, the pinmux_request_gpio() will attempt to

named functions for each GPIO pin, the pinctrl_request_gpio() will attempt to

obtain the function "gpioN" where "N" is the global GPIO pin number if no

special GPIO-handler is registered.

#include <linux/pinctrl/machine.h>

static const struct pinmux_map __initdata pmx_mapping[] = {

static const struct pinctrl_map __initdata mapping[] = {

	{

		.ctrl_dev_name = "pinctrl-foo",

		.function = "spi0",

You register this pinmux mapping to the pinmux subsystem by simply:

       ret = pinmux_register_mappings(pmx_mapping, ARRAY_SIZE(pmx_mapping));

       ret = pinctrl_register_mappings(mapping, ARRAY_SIZE(mapping));

Since the above construct is pretty common there is a helper macro to make

it even more compact which assumes you want to use pinctrl-foo and position

0 for mapping, for example:

static struct pinmux_map __initdata pmx_mapping[] = {

       PINMUX_MAP("I2CMAP", "pinctrl-foo", "i2c0", "foo-i2c.0"),

static struct pinctrl_map __initdata mapping[] = {

       PIN_MAP("I2CMAP", "pinctrl-foo", "i2c0", "foo-i2c.0"),

};

The result of grabbing this mapping from the device with something like

this (see next paragraph):

	pmx = pinmux_get(&device, "8bit");

	p = pinctrl_get(&device, "8bit");

Will be that you activate all the three bottom records in the mapping at

once. Since they share the same name, pin controller device, funcion and

Pinmux requests from drivers

============================

Generally it is discouraged to let individual drivers get and enable pinmuxes.

So if possible, handle the pinmuxes in platform code or some other place where

you have access to all the affected struct device * pointers. In some cases

where a driver needs to switch between different mux mappings at runtime

this is not possible.

Generally it is discouraged to let individual drivers get and enable pin

control. So if possible, handle the pin control in platform code or some other

place where you have access to all the affected struct device * pointers. In

some cases where a driver needs to e.g. switch between different mux mappings

at runtime this is not possible.

A driver may request a certain mux to be activated, usually just the default

mux like this:

A driver may request a certain control state to be activated, usually just the

default state like this:

#include <linux/pinctrl/consumer.h>

struct foo_state {

       struct pinmux *pmx;

       struct pinctrl *p;

       ...

};

foo_probe()

{

	/* Allocate a state holder named "state" etc */

	struct pinmux pmx;

	struct pinctrl p;

	pmx = pinmux_get(&device, NULL);

	if IS_ERR(pmx)

		return PTR_ERR(pmx);

	pinmux_enable(pmx);

	p = pinctrl_get(&device, NULL);

	if IS_ERR(p)

		return PTR_ERR(p);

	pinctrl_enable(p);

	state->pmx = pmx;

	state->p = p;

}

foo_remove()

{

	pinmux_disable(state->pmx);

	pinmux_put(state->pmx);

	pinctrl_disable(state->p);

	pinctrl_put(state->p);

}

If you want to grab a specific mux mapping and not just the first one found for

this device you can specify a specific mapping name, for example in the above

example the second i2c0 setting: pinmux_get(&device, "spi0-pos-B");

If you want to grab a specific control mapping and not just the first one

found for this device you can specify a specific mapping name, for example in

the above example the second i2c0 setting: pinctrl_get(&device, "spi0-pos-B");

This get/enable/disable/put sequence can just as well be handled by bus drivers

if you don't want each and every driver to handle it and you know the

The semantics of the get/enable respective disable/put is as follows:

- pinmux_get() is called in process context to reserve the pins affected with

- pinctrl_get() is called in process context to reserve the pins affected with

  a certain mapping and set up the pinmux core and the driver. It will allocate

  a struct from the kernel memory to hold the pinmux state.

- pinmux_enable()/pinmux_disable() is quick and can be called from fastpath

- pinctrl_enable()/pinctrl_disable() is quick and can be called from fastpath

  (irq context) when you quickly want to set up/tear down the hardware muxing

  when running a device driver. Usually it will just poke some values into a

  register.

- pinmux_disable() is called in process context to tear down the pin requests

  and release the state holder struct for the mux setting.

- pinctrl_disable() is called in process context to tear down the pin requests

  and release the state holder struct for the mux setting etc.

Usually the pinmux core handled the get/put pair and call out to the device

drivers bookkeeping operations, like checking available functions and the

associated pins, whereas the enable/disable pass on to the pin controller

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

driver which takes care of activating and/or deactivating the mux setting by

quickly poking some registers.

The pins are allocated for your device when you issue the pinmux_get() call,

The pins are allocated for your device when you issue the pinctrl_get() call,

after this you should be able to see this in the debugfs listing of all pins.

System pinmux hogging

=====================

System pin control hogging

==========================

A system pinmux map entry, i.e. a pinmux setting that does not have a device

associated with it, can be hogged by the core when the pin controller is

registered. This means that the core will attempt to call pinmux_get() and

pinmux_enable() on it immediately after the pin control device has been

A system pin control map entry, i.e. a pin control setting that does not have

a device associated with it, can be hogged by the core when the pin controller

is registered. This means that the core will attempt to call pinctrl_get() and

pinctrl_enable() on it immediately after the pin control device has been

registered.

This is enabled by simply setting the .hog_on_boot field in the map to true,

mux settings on the primary pin controller, there is a convenience macro for

this:

PINMUX_MAP_PRIMARY_SYS_HOG("POWERMAP", "power_func")

PIN_MAP_PRIMARY_SYS_HOG("POWERMAP", "power_func")

This gives the exact same result as the above construction.

foo_switch()

{

	struct pinmux *pmx;

	struct pinctrl *p;

	/* Enable on position A */

	pmx = pinmux_get(&device, "spi0-pos-A");

	if IS_ERR(pmx)

		return PTR_ERR(pmx);

	pinmux_enable(pmx);

	p = pinctrl_get(&device, "spi0-pos-A");

	if IS_ERR(p)

		return PTR_ERR(p);

	pinctrl_enable(p);

	/* This releases the pins again */

	pinmux_disable(pmx);

	pinmux_put(pmx);

	pinctrl_disable(p);

	pinctrl_put(p);

	/* Enable on position B */

	pmx = pinmux_get(&device, "spi0-pos-B");

	if IS_ERR(pmx)

		return PTR_ERR(pmx);

	pinmux_enable(pmx);

	p = pinctrl_get(&device, "spi0-pos-B");

	if IS_ERR(p)

		return PTR_ERR(p);

	pinctrl_enable(p);

	...

}

};

/* Pinmux settings */

static struct pinmux_map __initdata u300_pinmux_map[] = {

static struct pinctrl_map __initdata u300_pinmux_map[] = {

	/* anonymous maps for chip power and EMIFs */

	PINMUX_MAP_SYS_HOG("POWER", "pinmux-u300", "power"),

	PINMUX_MAP_SYS_HOG("EMIF0", "pinmux-u300", "emif0"),

	PINMUX_MAP_SYS_HOG("EMIF1", "pinmux-u300", "emif1"),

	PIN_MAP_SYS_HOG("POWER", "pinmux-u300", "power"),

	PIN_MAP_SYS_HOG("EMIF0", "pinmux-u300", "emif0"),

	PIN_MAP_SYS_HOG("EMIF1", "pinmux-u300", "emif1"),

	/* per-device maps for MMC/SD, SPI and UART */

	PINMUX_MAP("MMCSD", "pinmux-u300", "mmc0", "mmci"),

	PINMUX_MAP("SPI", "pinmux-u300", "spi0", "pl022"),

	PINMUX_MAP("UART0", "pinmux-u300", "uart0", "uart0"),

	PIN_MAP("MMCSD", "pinmux-u300", "mmc0", "mmci"),

	PIN_MAP("SPI", "pinmux-u300", "spi0", "pl022"),

	PIN_MAP("UART0", "pinmux-u300", "uart0", "uart0"),

};

struct u300_mux_hog {

	const char *name;

	struct device *dev;

	struct pinmux *pmx;

	struct pinctrl *p;

};

static struct u300_mux_hog u300_mux_hogs[] = {

	},

};

static int __init u300_pinmux_fetch(void)

static int __init u300_pinctrl_fetch(void)

{

	int i;

	for (i = 0; i < ARRAY_SIZE(u300_mux_hogs); i++) {

		struct pinmux *pmx;

		struct pinctrl *p;

		int ret;

		pmx = pinmux_get(u300_mux_hogs[i].dev, NULL);

		if (IS_ERR(pmx)) {

		p = pinctrl_get(u300_mux_hogs[i].dev, NULL);

		if (IS_ERR(p)) {

			pr_err("u300: could not get pinmux hog %s\n",

			       u300_mux_hogs[i].name);

			continue;

		}

		ret = pinmux_enable(pmx);

		ret = pinctrl_enable(p);

		if (ret) {

			pr_err("u300: could enable pinmux hog %s\n",

			       u300_mux_hogs[i].name);

			continue;

		}

		u300_mux_hogs[i].pmx = pmx;

		u300_mux_hogs[i].p = p;

	}

	return 0;

}

subsys_initcall(u300_pinmux_fetch);

subsys_initcall(u300_pinctrl_fetch);

/*

 * Notice that AMBA devices are initialized before platform devices.

	u300_assign_physmem();

	/* Initialize pinmuxing */

	pinmux_register_mappings(u300_pinmux_map,

	pinctrl_register_mappings(u300_pinmux_map,

				  ARRAY_SIZE(u300_pinmux_map));

	/* Register subdevices on the I2C buses */

	mutex_lock(&pinctrldev_list_mutex);

	list_add(&pctldev->node, &pinctrldev_list);

	mutex_unlock(&pinctrldev_list_mutex);

	pinmux_hog_maps(pctldev);

	pinctrl_hog_maps(pctldev);

	return pctldev;

out_err:

		return;

	pinctrl_remove_device_debugfs(pctldev);

	pinmux_unhog_maps(pctldev);

	pinctrl_unhog_maps(pctldev);

	/* TODO: check that no pinmuxes are still active? */

	mutex_lock(&pinctrldev_list_mutex);

	list_del(&pctldev->node);

 * @owner: module providing the pin controller, used for refcounting

 * @driver_data: driver data for drivers registering to the pin controller

 *	subsystem

 * @pinmux_hogs_lock: lock for the pinmux hog list

 * @pinmux_hogs: list of pinmux maps hogged by this device

 * @pinctrl_hogs_lock: lock for the pin control hog list

 * @pinctrl_hogs: list of pin control maps hogged by this device

 */

struct pinctrl_dev {

	struct list_head node;

	struct dentry *device_root;

#endif

#ifdef CONFIG_PINMUX

	struct mutex pinmux_hogs_lock;

	struct list_head pinmux_hogs;

	struct mutex pinctrl_hogs_lock;

	struct list_head pinctrl_hogs;

#endif

};

	 */

	int gpio = chip->base + offset;

	return pinmux_request_gpio(gpio);

	return pinctrl_request_gpio(gpio);

}

static void u300_gpio_free(struct gpio_chip *chip, unsigned offset)

{

	int gpio = chip->base + offset;

	pinmux_free_gpio(gpio);

	pinctrl_free_gpio(gpio);

}

static int u300_gpio_get(struct gpio_chip *chip, unsigned offset)