pinctrl: API changes to support multiple states per device

This example mapping is used to switch between two positions for spi0 at

runtime, as described further below under the heading "Runtime pinmuxing".

Further it is possible to match several groups of pins to the same function

for a single device, say for example in the mmc0 example above, where you can

Further it is possible for one named state to affect the muxing of several

groups of pins, say for example in the mmc0 example above, where you can

additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all

three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the

case), we define a mapping like this:

	.dev_name = "foo-mmc.0",

	.name = "8bit"

	.ctrl_dev_name = "pinctrl-foo",

	.function = "mmc0",

	.group = "mmc0_1_grp",

},

{

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

this (see next paragraph):

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

	p = pinctrl_get(dev);

	s = pinctrl_lookup_state(p, "8bit");

	ret = pinctrl_select_state(p, s);

or more simply:

	p = pinctrl_get_select(dev, "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

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

device, and since we allow multiple groups to match to a single device, they

all get selected, and they all get enabled and disable simultaneously by the

pinmux core.

struct foo_state {

       struct pinctrl *p;

       struct pinctrl_state *s;

       ...

};

foo_probe()

{

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

	struct pinctrl p;

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

	struct foo_state *foo = ...;

	p = pinctrl_get(&device, PINCTRL_STATE_DEFAULT);

	if IS_ERR(p)

		return PTR_ERR(p);

	pinctrl_enable(p);

	foo->p = pinctrl_get(&device);

	if (IS_ERR(foo->p)) {

		/* FIXME: clean up "foo" here */

		return PTR_ERR(foo->p);

	}

	state->p = p;

	foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);

	if (IS_ERR(foo->s)) {

		pinctrl_put(foo->p);

		/* FIXME: clean up "foo" here */

		return PTR_ERR(s);

	}

	ret = pinctrl_select_state(foo->s);

	if (ret < 0) {

		pinctrl_put(foo->p);

		/* FIXME: clean up "foo" here */

		return ret;

	}

}

foo_remove()

{

	pinctrl_disable(state->p);

	pinctrl_put(state->p);

}

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

This get/lookup/select/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

arrangement on your bus.

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

The semantics of the pinctrl APIs are:

- pinctrl_get() is called in process context to obtain a handle to all pinctrl

  information for a given client device. It will allocate a struct from the

  kernel memory to hold the pinmux state. All mapping table parsing or similar

  slow operations take place within this API.

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

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

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

- 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

  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

  can call pinctrl_select_state() from non-blocking contexts.

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

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

- pinctrl_put() frees all information associated with a pinctrl handle.

Usually the pin control core handled the get/put pair and call out to the

device drivers bookkeeping operations, like checking available functions and

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

Pin control map entries 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.

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

lookup_state() and select_state() on it immediately after the pin control

device has been registered.

This is enabled by simply setting the .dev_name field in the map to the name

of the pin controller itself, like this:

This occurs for mapping table entries where the client device name is equal

to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT.

{

	.dev_name = "pinctrl-foo",

an SPI port from one set of pins to another set of pins. Say for example for

spi0 in the example above, we expose two different groups of pins for the same

function, but with different named in the mapping as described under

"Advanced mapping" above. So we have two mappings named "spi0-pos-A" and

"spi0-pos-B".

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

foo_switch()

{

	struct pinctrl *p;

	struct pinctrl_state *s1, *s2;

	/* Setup */

	p = pinctrl_get(&device);

	if (IS_ERR(p))

		...

	s1 = pinctrl_lookup_state(foo->p, "pos-A");

	if (IS_ERR(s1))

		...

	s2 = pinctrl_lookup_state(foo->p, "pos-B");

	if (IS_ERR(s2))

		...

	/* Enable on position A */

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

	if IS_ERR(p)

		return PTR_ERR(p);

	pinctrl_enable(p);

	ret = pinctrl_select_state(s1);

	if (ret < 0)

	    ...

	/* This releases the pins again */

	pinctrl_disable(p);

	pinctrl_put(p);

	...

	/* Enable on position B */

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

	if IS_ERR(p)

		return PTR_ERR(p);

	pinctrl_enable(p);

	ret = pinctrl_select_state(s2);

	if (ret < 0)

	    ...

	...

	pinctrl_put(p);

}

The above has to be done from process context.

};

struct u300_mux_hog {

	const char *name;

	struct device *dev;

	struct pinctrl *p;

};

static struct u300_mux_hog u300_mux_hogs[] = {

	{

		.name = "uart0",

		.dev = &uart0_device.dev,

	},

	{

		.name = "spi0",

		.dev = &pl022_device.dev,

	},

	{

		.name = "mmc0",

		.dev = &mmcsd_device.dev,

	},

};

		struct pinctrl *p;

		int ret;

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

		p = pinctrl_get_select_default(u300_mux_hogs[i].dev);

		if (IS_ERR(p)) {

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

			       u300_mux_hogs[i].name);

			continue;

		}

		ret = pinctrl_enable(p);

		if (ret) {

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

			       u300_mux_hogs[i].name);

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

			       dev_name(u300_mux_hogs[i].dev));

			continue;

		}

		u300_mux_hogs[i].p = p;

}

EXPORT_SYMBOL_GPL(pinctrl_gpio_direction_output);

static struct pinctrl *pinctrl_get_locked(struct device *dev, const char *name)

static struct pinctrl_state *find_state(struct pinctrl *p,

					const char *name)

{

	struct pinctrl_dev *pctldev;

	const char *devname;

	struct pinctrl *p;

	unsigned num_maps = 0;

	int ret;

	struct pinctrl_maps *maps_node;

	int i;

	struct pinctrl_map const *map;

	struct pinctrl_state *state;

	list_for_each_entry(state, &p->states, node)

		if (!strcmp(state->name, name))

			return state;

	return NULL;

}

static struct pinctrl_state *create_state(struct pinctrl *p,

					  const char *name)

{

	struct pinctrl_state *state;

	state = kzalloc(sizeof(*state), GFP_KERNEL);

	if (state == NULL) {

		dev_err(p->dev,

			"failed to alloc struct pinctrl_state\n");

		return ERR_PTR(-ENOMEM);

	}

	state->name = name;

	INIT_LIST_HEAD(&state->settings);

	list_add_tail(&state->node, &p->states);

	return state;

}

static int add_setting(struct pinctrl *p, struct pinctrl_map const *map)

{

	struct pinctrl_state *state;

	struct pinctrl_setting *setting;

	int ret;

	/* We must have both a dev and state name */

	if (WARN_ON(!dev || !name))

		return ERR_PTR(-EINVAL);

	state = find_state(p, map->name);

	if (!state)

		state = create_state(p, map->name);

	if (IS_ERR(state))

		return PTR_ERR(state);

	devname = dev_name(dev);

	setting = kzalloc(sizeof(*setting), GFP_KERNEL);

	if (setting == NULL) {

		dev_err(p->dev,

			"failed to alloc struct pinctrl_setting\n");

		return -ENOMEM;

	}

	dev_dbg(dev, "pinctrl_get() for device %s state %s\n", devname, name);

	setting->pctldev = get_pinctrl_dev_from_devname(map->ctrl_dev_name);

	if (setting->pctldev == NULL) {

		dev_err(p->dev, "unknown pinctrl device %s in map entry",

			map->ctrl_dev_name);

		kfree(setting);

		/* Eventually, this should trigger deferred probe */

		return -ENODEV;

	}

	ret = pinmux_map_to_setting(map, setting);

	if (ret < 0) {

		kfree(setting);

		return ret;

	}

	list_add_tail(&setting->node, &state->settings);

	return 0;

}

static struct pinctrl *find_pinctrl(struct device *dev)

{

	struct pinctrl *p;

	list_for_each_entry(p, &pinctrldev_list, node)

		if (p->dev == dev)

			return p;

	return NULL;

}

static void pinctrl_put_locked(struct pinctrl *p, bool inlist);

static struct pinctrl *create_pinctrl(struct device *dev)

{

	struct pinctrl *p;

	const char *devname;

	struct pinctrl_maps *maps_node;

	int i;

	struct pinctrl_map const *map;

	int ret;

	/*

	 * create the state cookie holder struct pinctrl for each

		return ERR_PTR(-ENOMEM);

	}

	p->dev = dev;

	p->state = name;

	INIT_LIST_HEAD(&p->settings);

	INIT_LIST_HEAD(&p->states);

	devname = dev_name(dev);

	/* Iterate over the pin control maps to locate the right ones */

	for_each_maps(maps_node, i, map) {

		if (strcmp(map->dev_name, devname))

			continue;

		/* State name must be the one we're looking for */

		if (strcmp(map->name, name))

			continue;

		/*

		 * Try to find the pctldev given in the map

		 */

		pctldev = get_pinctrl_dev_from_devname(map->ctrl_dev_name);

		if (!pctldev) {

			dev_err(dev, "unknown pinctrl device %s in map entry",

				map->ctrl_dev_name);

			/* Eventually, this should trigger deferred probe */

			ret = -ENODEV;

			goto error;

		ret = add_setting(p, map);

		if (ret < 0) {

			pinctrl_put_locked(p, false);

			return ERR_PTR(ret);

		}

		dev_dbg(dev, "in map, found pctldev %s to handle function %s",

			dev_name(pctldev->dev), map->function);

		setting = kzalloc(sizeof(*setting), GFP_KERNEL);

		if (setting == NULL) {

			dev_err(dev,

				"failed to alloc struct pinctrl_setting\n");

			ret = -ENOMEM;

			goto error;

	}

		setting->pctldev = pctldev;

		ret = pinmux_map_to_setting(map, setting);

		if (ret < 0)

			goto error;

		list_add_tail(&setting->node, &p->settings);

	/* Add the pinmux to the global list */

	list_add_tail(&p->node, &pinctrl_list);

		num_maps++;

	return p;

}

	/*

	 * This may be perfectly legitimate. An IP block may get re-used

	 * across SoCs. Not all of those SoCs may need pinmux settings for the

	 * IP block, e.g. if one SoC dedicates pins to that function but

	 * another doesn't. The driver won't know this, and will always

	 * attempt to set up the pinmux. The mapping table defines whether any

	 * HW programming is actually needed.

	 */

	if (!num_maps)

		dev_info(dev, "zero maps found for mapping %s\n", name);

static struct pinctrl *pinctrl_get_locked(struct device *dev)

{

	struct pinctrl *p;

	dev_dbg(dev, "found %u maps for device %s state %s\n",

		num_maps, devname, name ? name : "(undefined)");

	if (WARN_ON(!dev))

		return ERR_PTR(-EINVAL);

	/* Add the pinmux to the global list */

	list_add_tail(&p->node, &pinctrl_list);

	p = find_pinctrl(dev);

	if (p != NULL)

		return ERR_PTR(-EBUSY);

	p = create_pinctrl(dev);

	if (IS_ERR(p))

		return p;

error:

	list_for_each_entry(setting, &p->settings, node)

		pinmux_free_setting(setting);

	kfree(p);

	return ERR_PTR(ret);

	return p;

}

/**

 * pinctrl_get() - retrieves the pin controller handle for a certain device

 * @dev: the device to get the pin controller handle for

 * @name: an optional specific control mapping name or NULL, the name is only

 *	needed if you want to have more than one mapping per device, or if you

 *	need an anonymous pin control (not tied to any specific device)

 * pinctrl_get() - retrieves the pinctrl handle for a device

 * @dev: the device to obtain the handle for

 */

struct pinctrl *pinctrl_get(struct device *dev, const char *name)

struct pinctrl *pinctrl_get(struct device *dev)

{

	struct pinctrl *p;

	mutex_lock(&pinctrl_mutex);

	p = pinctrl_get_locked(dev, name);

	p = pinctrl_get_locked(dev);

	mutex_unlock(&pinctrl_mutex);

	return p;

}

EXPORT_SYMBOL_GPL(pinctrl_get);

static void pinctrl_put_locked(struct pinctrl *p)

static void pinctrl_put_locked(struct pinctrl *p, bool inlist)

{

	struct pinctrl_setting *setting, *n;

	struct pinctrl_state *state, *n1;

	struct pinctrl_setting *setting, *n2;

	if (p == NULL)

		return;

	if (p->usecount)

		pr_warn("releasing pin control handle with active users!\n");

	list_for_each_entry_safe(setting, n, &p->settings, node) {

	list_for_each_entry_safe(state, n1, &p->states, node) {

		list_for_each_entry_safe(setting, n2, &state->settings, node) {

			if (state == p->state)

				pinmux_disable_setting(setting);

			pinmux_free_setting(setting);

			list_del(&setting->node);

			kfree(setting);

		}

		list_del(&state->node);

		kfree(state);

	}

	/* Remove from list */

	if (inlist)

		list_del(&p->node);

	kfree(p);

}

/**

 * pinctrl_put() - release a previously claimed pin control handle

 * @p: a pin control handle previously claimed by pinctrl_get()

 * pinctrl_put() - release a previously claimed pinctrl handle

 * @p: the pinctrl handle to release

 */

void pinctrl_put(struct pinctrl *p)

{

	mutex_lock(&pinctrl_mutex);

	pinctrl_put(p);

	pinctrl_put_locked(p, true);

	mutex_unlock(&pinctrl_mutex);

}

EXPORT_SYMBOL_GPL(pinctrl_put);

static int pinctrl_enable_locked(struct pinctrl *p)

static struct pinctrl_state *pinctrl_lookup_state_locked(struct pinctrl *p,

							 const char *name)

{

	struct pinctrl_setting *setting;

	int ret;

	if (p == NULL)

		return -EINVAL;

	struct pinctrl_state *state;

	if (p->usecount++ == 0) {

		list_for_each_entry(setting, &p->settings, node) {

			ret = pinmux_enable_setting(setting);

			if (ret < 0) {

				/* FIXME: Difficult to return to prev state */

				p->usecount--;

				return ret;

			}

		}

	}

	state = find_state(p, name);

	if (!state)

		return ERR_PTR(-ENODEV);

	return 0;

	return state;

}

/**

 * pinctrl_enable() - enable a certain pin controller setting

 * @p: the pin control handle to enable, previously claimed by pinctrl_get()

 * pinctrl_lookup_state() - retrieves a state handle from a pinctrl handle

 * @p: the pinctrl handle to retrieve the state from

 * @name: the state name to retrieve

 */

int pinctrl_enable(struct pinctrl *p)

struct pinctrl_state *pinctrl_lookup_state(struct pinctrl *p, const char *name)

{

	int ret;

	struct pinctrl_state *s;

	mutex_lock(&pinctrl_mutex);

	ret = pinctrl_enable_locked(p);

	s = pinctrl_lookup_state_locked(p, name);

	mutex_unlock(&pinctrl_mutex);

	return ret;

	return s;

}

EXPORT_SYMBOL_GPL(pinctrl_enable);

EXPORT_SYMBOL_GPL(pinctrl_lookup_state);

static void pinctrl_disable_locked(struct pinctrl *p)

static int pinctrl_select_state_locked(struct pinctrl *p,

				       struct pinctrl_state *state)

{

	struct pinctrl_setting *setting;

	struct pinctrl_setting *setting, *setting2;

	int ret;

	if (p == NULL)

		return;

	if (p->state == state)

		return 0;

	if (--p->usecount == 0) {

		list_for_each_entry(setting, &p->settings, node)

	if (p->state) {

		/*

		 * The set of groups with a mux configuration in the old state

		 * may not be identical to the set of groups with a mux setting

		 * in the new state. While this might be unusual, it's entirely

		 * possible for the "user"-supplied mapping table to be written

		 * that way. For each group that was configured in the old state

		 * but not in the new state, this code puts that group into a

		 * safe/disabled state.

		 */

		list_for_each_entry(setting, &p->state->settings, node) {

			bool found = false;

			list_for_each_entry(setting2, &state->settings, node) {

				if (setting2->group_selector ==

						setting->group_selector) {

					found = true;

					break;

				}

			}

			if (!found)

				pinmux_disable_setting(setting);

		}

	}

	p->state = state;

	/* Apply all the settings for the new state */

	list_for_each_entry(setting, &state->settings, node) {

		ret = pinmux_enable_setting(setting);

		if (ret < 0) {

			/* FIXME: Difficult to return to prev state */

			return ret;

		}

	}

	return 0;

}

/**

 * pinctrl_disable() - disable a certain pin control setting

 * @p: the pin control handle to disable, previously claimed by pinctrl_get()

 * pinctrl_select() - select/activate/program a pinctrl state to HW

 * @p: the pinctrl handle for the device that requests configuratio

 * @state: the state handle to select/activate/program

 */

void pinctrl_disable(struct pinctrl *p)

int pinctrl_select_state(struct pinctrl *p, struct pinctrl_state *state)

{

	int ret;

	mutex_lock(&pinctrl_mutex);

	pinctrl_disable_locked(p);

	ret = pinctrl_select_state_locked(p, state);

	mutex_unlock(&pinctrl_mutex);

	return ret;

}

EXPORT_SYMBOL_GPL(pinctrl_disable);

EXPORT_SYMBOL_GPL(pinctrl_select_state);

/**

 * pinctrl_register_mappings() - register a set of pin controller mappings

static int pinctrl_show(struct seq_file *s, void *what)

{

	struct pinctrl *p;

	struct pinctrl_state *state;

	struct pinctrl_setting *setting;

	seq_puts(s, "Requested pin control handlers their pinmux maps:\n");

	mutex_lock(&pinctrl_mutex);

	list_for_each_entry(p, &pinctrl_list, node) {

		seq_printf(s, "device: %s state: %s users: %u\n",

			   dev_name(p->dev), p->state, p->usecount);

		seq_printf(s, "device: %s current state: %s\n",

			   dev_name(p->dev),

			   p->state ? p->state->name : "none");

		list_for_each_entry(state, &p->states, node) {

			seq_printf(s, "  state: %s\n", state->name);

		list_for_each_entry(setting, &p->settings, node) {

			list_for_each_entry(setting, &state->settings, node) {

				seq_printf(s, "    ");

				pinmux_dbg_show(s, setting);

			}

		}

	}

	mutex_unlock(&pinctrl_mutex);

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

	pctldev->p = pinctrl_get_locked(pctldev->dev, PINCTRL_STATE_DEFAULT);

	if (!IS_ERR(pctldev->p))

		pinctrl_enable_locked(pctldev->p);

	pctldev->p = pinctrl_get_locked(pctldev->dev);

	if (!IS_ERR(pctldev->p)) {

		struct pinctrl_state *s =

			pinctrl_lookup_state_locked(pctldev->p,

						    PINCTRL_STATE_DEFAULT);

		if (!IS_ERR(s))

			pinctrl_select_state_locked(pctldev->p, s);

	}

	mutex_unlock(&pinctrl_mutex);

	mutex_lock(&pinctrl_mutex);

	if (!IS_ERR(pctldev->p)) {

		pinctrl_disable_locked(pctldev->p);

		pinctrl_put_locked(pctldev->p);

	}

	if (!IS_ERR(pctldev->p))

		pinctrl_put_locked(pctldev->p, true);

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

	list_del(&pctldev->node);

 * struct pinctrl - per-device pin control state holder

 * @node: global list node

 * @dev: the device using this pin control handle

 * @state: the state name passed to pinctrl_get()

 * @usecount: the number of active users of this pin controller setting, used

 *	to keep track of nested use cases

 * @settings: a list of settings for this device/state

 * @states: a list of states for this device

 * @state: the current state

 */