linux-toradex.git/Documentation/pinctrl.txt, branch v3.4.76

pinctrl: enhance mapping table to support pin config operations

2012-03-05T10:25:11+00:00

The pinctrl mapping table can now contain entries to:
* Set the mux function of a pin group
* Apply a set of pin config options to a pin or a group

This allows pinctrl_select_state() to apply pin configs settings as well
as mux settings.

v3: Fix find_pinctrl() to iterate over the correct list.
   s/_MUX_CONFIGS_/_CONFIGS_/ in mapping table macros.
   Fix documentation to use correct mapping table macro.
v2: Added numerous extra PIN_MAP_*() special-case macros.
   Fixed kerneldoc typo. Delete pinctrl_get_pin_id() and
   replace it with pin_get_from_name(). Various minor fixes.
   Updates due to rebase.

Signed-off-by: Stephen Warren 
Acked-by: Dong Aisheng 
Signed-off-by: Linus Walleij

pinctrl: API changes to support multiple states per device

2012-03-05T10:22:59+00:00

The API model is changed from:

p = pinctrl_get(dev, "state1");
pinctrl_enable(p);
...
pinctrl_disable(p);
pinctrl_put(p);
p = pinctrl_get(dev, "state2");
pinctrl_enable(p);
...
pinctrl_disable(p);
pinctrl_put(p);

to this:

p = pinctrl_get(dev);
s1 = pinctrl_lookup_state(p, "state1");
s2 = pinctrl_lookup_state(p, "state2");
pinctrl_select_state(p, s1);
...
pinctrl_select_state(p, s2);
...
pinctrl_put(p);

This allows devices to directly transition between states without
disabling the pin controller programming and put()/get()ing the
configuration data each time. This model will also better suit pinconf
programming, which doesn't have a concept of "disable".

The special-case hogging feature of pin controllers is re-written to use
the regular APIs instead of special-case code. Hence, the pinmux-hogs
debugfs file is removed; see the top-level pinctrl-handles files for
equivalent data.

Signed-off-by: Stephen Warren 
Acked-by: Dong Aisheng 
Signed-off-by: Linus Walleij

pinctrl: assume map table entries can't have a NULL name field

2012-03-02T15:20:54+00:00

pinctrl_register_mappings() already requires that every mapping table
entry have a non-NULL name field.

Logically, this makes sense too; drivers should always request a specific
named state so they know what they're getting. Relying on getting the
first mentioned state in the mapping table is error-prone, and a nasty
special case to implement, given that a given the mapping table may define
multiple states for a device.

Remove a small part of the documentation that talked about optionally
requesting a specific state; it's mandatory now.

Signed-off-by: Stephen Warren 
Acked-by: Dong Aisheng 
Signed-off-by: Linus Walleij

pinctrl: introduce PINCTRL_STATE_DEFAULT, define hogs as that state

2012-03-02T15:18:24+00:00

This provides a single centralized name for the default state.

Update PIN_MAP_* macros to use this state name, instead of requiring the
user to pass a state name in.

With this change, hog entries in the mapping table are defined as those
with state name PINCTRL_STATE_DEFAULT, i.e. all entries have the same
name. This interacts badly with the nested iteration over mapping table
entries in pinctrl_hog_maps() and pinctrl_hog_map() which would now
attempt to claim each hog mapping table entry multiple times. Replacing
the custom hog code with a simple pinctrl_get()/pinctrl_enable().

Update documentation and mapping tables to use this.

Signed-off-by: Stephen Warren 
Acked-by: Dong Aisheng 
Signed-off-by: Linus Walleij

pinctrl: re-order struct pinctrl_map

2012-02-29T18:10:55+00:00

The lookup key in struct pinctrl_map is (.dev_name, .name). Re-order the
struct definition to put the lookup key fields first, and the result
values afterwards. To me at least, this slightly better reflects the
lookup process.

Update the documentation in a similar fashion.

Note: PIN_MAP*() macros aren't updated; I plan to update this once later
when enhancing the mapping table format to support pin config to reduce
churn.

Signed-off-by: Stephen Warren 
Acked-by: Dong Aisheng 
[Rebased for cherry-picking]
Signed-off-by: Linus Walleij

pinctrl: disallow map table entries with NULL dev_name field

2012-02-24T05:24:52+00:00

Hog entries are mapping table entries with .ctrl_dev_name == .dev_name.
All other mapping table entries need .dev_name set so that they will
match some pinctrl_get() call. All extant PIN_MAP*() macros set
.dev_name.

So, there is no reason to allow mapping table entries without .dev_name
set. Update the code and documentation to disallow this.

Signed-off-by: Stephen Warren 
Acked-by: Dong Aisheng 
Signed-off-by: Linus Walleij

pinctrl: changes hog mechanism to be self-referential

2012-02-10T20:33:10+00:00

Instead of a specific boolean field to indicate if a map entry shall
be hogged, treat self-reference as an indication of desired hogging.
This drops one field off the map struct and has a nice Douglas R.
Hofstadter-feel to it.

Acked-by: Dong Aisheng 
Acked-by: Stephen Warren 
Signed-off-by: Linus Walleij

pinctrl: move generic functions to the pinctrl_ namespace

2012-02-10T20:33:02+00:00

Since we want to use the former pinmux handles and mapping tables for
generic control involving both muxing and configuration we begin
refactoring by renaming them from pinmux_* to pinctrl_*.

ChangeLog v1->v2:
- Also rename the PINMUX_* macros in machine.h to PIN_ as indicated
  in the documentation so as to reflect the generic nature of these
  mapping entries from now on.

Acked-by: Stephen Warren 
Signed-off-by: Linus Walleij

pinctrl: break out a pinctrl consumer header

2012-02-10T20:32:57+00:00

This breaks out a  header to be used by
all pinmux and pinconfig alike, so drivers needing services from
pinctrl does not need to include different headers. This is similar
to the approach taken by the regulator API.

Acked-by: Stephen Warren 
Signed-off-by: Linus Walleij

pinctrl: delete raw device pointers in pinmux maps

2012-02-01T18:42:35+00:00

After discussion with Mark Brown in an unrelated thread about
ADC lookups, it came to my knowledge that the ability to pass
a struct device * in the regulator consumers is just a
historical artifact, and not really recommended. Since there
are no in-kernel users of these pointers, we just kill them
right now, before someone starts to use them.

Reviewed-by: Mark Brown 
Signed-off-by: Linus Walleij