From 9dfac4fd7f8cdcdf734dff2ccc7ca467f53f1cfd Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Wed, 1 Feb 2012 18:02:47 +0100 Subject: pinctrl: delete raw device pointers in pinmux maps 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 --- Documentation/pinctrl.txt | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index 150fd3833d0..14aecd2b2db 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -805,10 +805,7 @@ 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. The map can also use struct device * directly, so there is no -inherent need to use strings to specify .dev_name or .ctrl_dev_name, these -are for the situation where you do not have a handle to the struct device *, -for example if they are not yet instantiated or cumbersome to obtain. +to map. You register this pinmux mapping to the pinmux subsystem by simply: -- cgit v1.2.3 From 28a8d14cc74a0180323d9150c3d3dbf9dd60d55a Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Thu, 9 Feb 2012 01:52:22 +0100 Subject: pinctrl: break out a pinctrl consumer header 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 --- Documentation/pinctrl.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index 14aecd2b2db..b268832c49d 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -208,6 +208,8 @@ unconnected. For example, a platform may do this: +#include + ret = pin_config_set("foo-dev", "FOO_GPIO_PIN", PLATFORM_X_PULL_UP); To pull up a pin to VDD. The pin configuration driver implements callbacks for @@ -920,7 +922,7 @@ this is not possible. A driver may request a certain mux to be activated, usually just the default mux like this: -#include +#include struct foo_state { struct pinmux *pmx; @@ -1019,6 +1021,8 @@ function, but with different named in the mapping as described under 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: +#include + foo_switch() { struct pinmux *pmx; -- cgit v1.2.3 From e93bcee00c43e2bd4037291262111016f4c05793 Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Thu, 9 Feb 2012 07:23:28 +0100 Subject: pinctrl: move generic functions to the pinctrl_ namespace 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 --- Documentation/pinctrl.txt | 118 +++++++++++++++++++++++----------------------- 1 file changed, 59 insertions(+), 59 deletions(-) (limited to 'Documentation') diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index b268832c49d..2e7132355db 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -728,19 +728,19 @@ same time. 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 @@ -749,7 +749,7 @@ the approach to define every pin as a function. 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(). @@ -764,7 +764,7 @@ gpiolib driver and the affected GPIO range, pin offset and desired direction 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. @@ -783,7 +783,7 @@ spi on the second function mapping: #include -static const struct pinmux_map __initdata pmx_mapping[] = { +static const struct pinctrl_map __initdata mapping[] = { { .ctrl_dev_name = "pinctrl-foo", .function = "spi0", @@ -811,14 +811,14 @@ to map. 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"), }; @@ -901,7 +901,7 @@ case), we define a mapping like this: 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 @@ -913,44 +913,44 @@ pinmux core. 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 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 @@ -958,35 +958,35 @@ arrangement on your bus. 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, @@ -1003,7 +1003,7 @@ Since it may be common to request the core to hog a few always-applicable 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. @@ -1025,23 +1025,23 @@ it, disables and releases it, and muxes it in on the pins defined by group B: 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); ... } -- cgit v1.2.3 From 77a5988355f993840928d195f790a939200a4ff0 Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Fri, 10 Feb 2012 01:34:12 +0100 Subject: pinctrl: changes hog mechanism to be self-referential 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 --- Documentation/pinctrl.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index 2e7132355db..ee3266b948e 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -989,21 +989,21 @@ 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, -like this: +This is enabled by simply setting the .dev_name field in the map to the name +of the pin controller itself, like this: { .name = "POWERMAP" .ctrl_dev_name = "pinctrl-foo", .function = "power_func", - .hog_on_boot = true, + .dev_name = "pinctrl-foo", }, Since it may be common to request the core to hog a few always-applicable mux settings on the primary pin controller, there is a convenience macro for this: -PIN_MAP_PRIMARY_SYS_HOG("POWERMAP", "power_func") +PIN_MAP_PRIMARY_SYS_HOG("POWERMAP", "pinctrl-foo", "power_func") This gives the exact same result as the above construction. -- cgit v1.2.3 From 1681f5ae4ca25bddb6f7b6d4f463cc83e3d1ad01 Mon Sep 17 00:00:00 2001 From: Stephen Warren Date: Wed, 22 Feb 2012 14:25:58 -0700 Subject: pinctrl: disallow map table entries with NULL dev_name field 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 --- Documentation/pinctrl.txt | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) (limited to 'Documentation') diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index ee3266b948e..fa9163af34f 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -494,14 +494,10 @@ Definitions: {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0} } - Every map must be assigned a symbolic name, pin controller and function. - The group is not compulsory - if it is omitted the first group presented by - the driver as applicable for the function will be selected, which is - useful for simple cases. - - The device name is present in map entries tied to specific devices. Maps - without device names are referred to as SYSTEM pinmuxes, such as can be taken - by the machine implementation on boot and not tied to any specific device. + Every map must be assigned a state name, pin controller, device and + function. The group is not compulsory - if it is omitted the first group + presented by the driver as applicable for the function will be selected, + which is useful for simple cases. It is possible to map several groups to the same combination of device, pin controller and function. This is for cases where a certain function on @@ -983,8 +979,7 @@ after this you should be able to see this in the debugfs listing of all pins. System pin control hogging ========================== -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 +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. -- cgit v1.2.3 From 806d314325812fb8ffe7059bd84a23d334350c21 Mon Sep 17 00:00:00 2001 From: Stephen Warren Date: Thu, 23 Feb 2012 17:04:39 -0700 Subject: pinctrl: re-order struct pinctrl_map 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 --- Documentation/pinctrl.txt | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'Documentation') diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index fa9163af34f..5e314cecab7 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -781,19 +781,19 @@ spi on the second function mapping: static const struct pinctrl_map __initdata mapping[] = { { + .dev_name = "foo-spi.0", .ctrl_dev_name = "pinctrl-foo", .function = "spi0", - .dev_name = "foo-spi.0", }, { + .dev_name = "foo-i2c.0", .ctrl_dev_name = "pinctrl-foo", .function = "i2c0", - .dev_name = "foo-i2c.0", }, { + .dev_name = "foo-mmc.0", .ctrl_dev_name = "pinctrl-foo", .function = "mmc0", - .dev_name = "foo-mmc.0", }, }; @@ -826,18 +826,18 @@ As it is possible to map a function to different groups of pins an optional ... { + .dev_name = "foo-spi.0", .name = "spi0-pos-A", .ctrl_dev_name = "pinctrl-foo", .function = "spi0", .group = "spi0_0_grp", - .dev_name = "foo-spi.0", }, { + .dev_name = "foo-spi.0", .name = "spi0-pos-B", .ctrl_dev_name = "pinctrl-foo", .function = "spi0", .group = "spi0_1_grp", - .dev_name = "foo-spi.0", }, ... @@ -852,45 +852,45 @@ case), we define a mapping like this: ... { + .dev_name = "foo-mmc.0", .name = "2bit" .ctrl_dev_name = "pinctrl-foo", .function = "mmc0", .group = "mmc0_1_grp", - .dev_name = "foo-mmc.0", }, { + .dev_name = "foo-mmc.0", .name = "4bit" .ctrl_dev_name = "pinctrl-foo", .function = "mmc0", .group = "mmc0_1_grp", - .dev_name = "foo-mmc.0", }, { + .dev_name = "foo-mmc.0", .name = "4bit" .ctrl_dev_name = "pinctrl-foo", .function = "mmc0", .group = "mmc0_2_grp", - .dev_name = "foo-mmc.0", }, { + .dev_name = "foo-mmc.0", .name = "8bit" .ctrl_dev_name = "pinctrl-foo", .group = "mmc0_1_grp", - .dev_name = "foo-mmc.0", }, { + .dev_name = "foo-mmc.0", .name = "8bit" .ctrl_dev_name = "pinctrl-foo", .function = "mmc0", .group = "mmc0_2_grp", - .dev_name = "foo-mmc.0", }, { + .dev_name = "foo-mmc.0", .name = "8bit" .ctrl_dev_name = "pinctrl-foo", .function = "mmc0", .group = "mmc0_3_grp", - .dev_name = "foo-mmc.0", }, ... @@ -988,10 +988,10 @@ This is enabled by simply setting the .dev_name field in the map to the name of the pin controller itself, like this: { + .dev_name = "pinctrl-foo", .name = "POWERMAP" .ctrl_dev_name = "pinctrl-foo", .function = "power_func", - .dev_name = "pinctrl-foo", }, Since it may be common to request the core to hog a few always-applicable -- cgit v1.2.3 From 46919ae63d4820e76724beb655274ce143f0da0b Mon Sep 17 00:00:00 2001 From: Stephen Warren Date: Thu, 1 Mar 2012 18:48:32 -0700 Subject: pinctrl: introduce PINCTRL_STATE_DEFAULT, define hogs as that state 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 --- Documentation/pinctrl.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index 5e314cecab7..6fe3232e798 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -814,7 +814,7 @@ 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[] = { - PIN_MAP("I2CMAP", "pinctrl-foo", "i2c0", "foo-i2c.0"), + PIN_MAP(PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", "foo-i2c.0"), }; @@ -930,7 +930,7 @@ foo_probe() /* Allocate a state holder named "state" etc */ struct pinctrl p; - p = pinctrl_get(&device, NULL); + p = pinctrl_get(&device, PINCTRL_STATE_DEFAULT); if IS_ERR(p) return PTR_ERR(p); pinctrl_enable(p); @@ -989,7 +989,7 @@ of the pin controller itself, like this: { .dev_name = "pinctrl-foo", - .name = "POWERMAP" + .name = PINCTRL_STATE_DEFAULT, .ctrl_dev_name = "pinctrl-foo", .function = "power_func", }, @@ -998,7 +998,7 @@ Since it may be common to request the core to hog a few always-applicable mux settings on the primary pin controller, there is a convenience macro for this: -PIN_MAP_PRIMARY_SYS_HOG("POWERMAP", "pinctrl-foo", "power_func") +PIN_MAP_SYS_HOG("pinctrl-foo", "power_func") This gives the exact same result as the above construction. -- cgit v1.2.3 From 110e4ec5a1cfe20190e7f8c2b8b4eef369de3c99 Mon Sep 17 00:00:00 2001 From: Stephen Warren Date: Thu, 1 Mar 2012 18:48:33 -0700 Subject: pinctrl: assume map table entries can't have a NULL name field 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 --- Documentation/pinctrl.txt | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index 6fe3232e798..558aac554d0 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -782,16 +782,19 @@ spi on the second function mapping: static const struct pinctrl_map __initdata mapping[] = { { .dev_name = "foo-spi.0", + .name = PINCTRL_STATE_DEFAULT, .ctrl_dev_name = "pinctrl-foo", .function = "spi0", }, { .dev_name = "foo-i2c.0", + .name = PINCTRL_STATE_DEFAULT, .ctrl_dev_name = "pinctrl-foo", .function = "i2c0", }, { .dev_name = "foo-mmc.0", + .name = PINCTRL_STATE_DEFAULT, .ctrl_dev_name = "pinctrl-foo", .function = "mmc0", }, @@ -944,10 +947,6 @@ foo_remove() pinctrl_put(state->p); } -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 arrangement on your bus. -- cgit v1.2.3 From 6e5e959dde0d92d177f035652aeaa77f9330c9c6 Mon Sep 17 00:00:00 2001 From: Stephen Warren Date: Fri, 2 Mar 2012 13:05:47 -0700 Subject: pinctrl: API changes to support multiple states per device 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 --- Documentation/pinctrl.txt | 120 ++++++++++++++++++++++++++++++---------------- 1 file changed, 79 insertions(+), 41 deletions(-) (limited to 'Documentation') diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index 558aac554d0..23426c7bc8d 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -847,8 +847,8 @@ As it is possible to map a function to different groups of pins an optional 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: @@ -879,6 +879,7 @@ 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", }, { @@ -900,10 +901,16 @@ case), we define a mapping like this: 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. @@ -925,45 +932,63 @@ default state like this: 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 = ...; + + foo->p = pinctrl_get(&device); + if (IS_ERR(foo->p)) { + /* FIXME: clean up "foo" here */ + return PTR_ERR(foo->p); + } - p = pinctrl_get(&device, PINCTRL_STATE_DEFAULT); - if IS_ERR(p) - return PTR_ERR(p); - pinctrl_enable(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); + } - state->p = p; + 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 @@ -979,12 +1004,12 @@ System pin control hogging ========================== 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", @@ -1009,8 +1034,8 @@ It is possible to mux a certain function in and out at runtime, say to move 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: @@ -1020,23 +1045,36 @@ 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. -- cgit v1.2.3 From 1e2082b520721734c358f776d34a069867214c8e Mon Sep 17 00:00:00 2001 From: Stephen Warren Date: Fri, 2 Mar 2012 13:05:48 -0700 Subject: pinctrl: enhance mapping table to support pin config operations 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 --- Documentation/pinctrl.txt | 76 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 64 insertions(+), 12 deletions(-) (limited to 'Documentation') diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index 23426c7bc8d..d97bccf4614 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -206,14 +206,21 @@ using a certain resistor value - pull up and pull down - so that the pin has a stable value when nothing is driving the rail it is connected to, or when it's unconnected. -For example, a platform may do this: +Pin configuration can be programmed either using the explicit APIs described +immediately below, or by adding configuration entries into the mapping table; +see section "Board/machine configuration" below. + +For example, a platform may do the following to pull up a pin to VDD: #include ret = pin_config_set("foo-dev", "FOO_GPIO_PIN", PLATFORM_X_PULL_UP); -To pull up a pin to VDD. The pin configuration driver implements callbacks for -changing pin configuration in the pin controller ops like this: +The format and meaning of the configuration parameter, PLATFORM_X_PULL_UP +above, is entirely defined by the pin controller driver. + +The pin configuration driver implements callbacks for changing pin +configuration in the pin controller ops like this: #include #include @@ -765,7 +772,7 @@ obtain the function "gpioN" where "N" is the global GPIO pin number if no special GPIO-handler is registered. -Pinmux board/machine configuration +Board/machine configuration ================================== Boards and machines define how a certain complete running system is put @@ -773,9 +780,9 @@ together, including how GPIOs and devices are muxed, how regulators are constrained and how the clock tree looks. Of course pinmux settings are also part of this. -A pinmux config for a machine looks pretty much like a simple regulator -configuration, so for the example array above we want to enable i2c and -spi on the second function mapping: +A pin controller configuration for a machine looks pretty much like a simple +regulator configuration, so for the example array above we want to enable i2c +and spi on the second function mapping: #include @@ -783,20 +790,23 @@ static const struct pinctrl_map __initdata mapping[] = { { .dev_name = "foo-spi.0", .name = PINCTRL_STATE_DEFAULT, + .type = PIN_MAP_TYPE_MUX_GROUP, .ctrl_dev_name = "pinctrl-foo", - .function = "spi0", + .data.mux.function = "spi0", }, { .dev_name = "foo-i2c.0", .name = PINCTRL_STATE_DEFAULT, + .type = PIN_MAP_TYPE_MUX_GROUP, .ctrl_dev_name = "pinctrl-foo", - .function = "i2c0", + .data.mux.function = "i2c0", }, { .dev_name = "foo-mmc.0", .name = PINCTRL_STATE_DEFAULT, + .type = PIN_MAP_TYPE_MUX_GROUP, .ctrl_dev_name = "pinctrl-foo", - .function = "mmc0", + .data.mux.function = "mmc0", }, }; @@ -817,7 +827,40 @@ 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[] = { - PIN_MAP(PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", "foo-i2c.0"), + PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT, "pinctrl-foo", NULL, "i2c0"), +}; + +The mapping table may also contain pin configuration entries. It's common for +each pin/group to have a number of configuration entries that affect it, so +the table entries for configuration reference an array of config parameters +and values. An example using the convenience macros is shown below: + +static unsigned long i2c_grp_configs[] = { + FOO_PIN_DRIVEN, + FOO_PIN_PULLUP, +}; + +static unsigned long i2c_pin_configs[] = { + FOO_OPEN_COLLECTOR, + FOO_SLEW_RATE_SLOW, +}; + +static struct pinctrl_map __initdata mapping[] = { + PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", "i2c0"), + PIN_MAP_MUX_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", i2c_grp_configs), + PIN_MAP_MUX_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0scl", i2c_pin_configs), + PIN_MAP_MUX_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0sda", i2c_pin_configs), +}; + +Finally, some devices expect the mapping table to contain certain specific +named states. When running on hardware that doesn't need any pin controller +configuration, the mapping table must still contain those named states, in +order to explicitly indicate that the states were provided and intended to +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[] = { + PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT), }; @@ -831,6 +874,7 @@ As it is possible to map a function to different groups of pins an optional { .dev_name = "foo-spi.0", .name = "spi0-pos-A", + .type = PIN_MAP_TYPE_MUX_GROUP, .ctrl_dev_name = "pinctrl-foo", .function = "spi0", .group = "spi0_0_grp", @@ -838,6 +882,7 @@ As it is possible to map a function to different groups of pins an optional { .dev_name = "foo-spi.0", .name = "spi0-pos-B", + .type = PIN_MAP_TYPE_MUX_GROUP, .ctrl_dev_name = "pinctrl-foo", .function = "spi0", .group = "spi0_1_grp", @@ -857,6 +902,7 @@ case), we define a mapping like this: { .dev_name = "foo-mmc.0", .name = "2bit" + .type = PIN_MAP_TYPE_MUX_GROUP, .ctrl_dev_name = "pinctrl-foo", .function = "mmc0", .group = "mmc0_1_grp", @@ -864,6 +910,7 @@ case), we define a mapping like this: { .dev_name = "foo-mmc.0", .name = "4bit" + .type = PIN_MAP_TYPE_MUX_GROUP, .ctrl_dev_name = "pinctrl-foo", .function = "mmc0", .group = "mmc0_1_grp", @@ -871,6 +918,7 @@ case), we define a mapping like this: { .dev_name = "foo-mmc.0", .name = "4bit" + .type = PIN_MAP_TYPE_MUX_GROUP, .ctrl_dev_name = "pinctrl-foo", .function = "mmc0", .group = "mmc0_2_grp", @@ -878,6 +926,7 @@ case), we define a mapping like this: { .dev_name = "foo-mmc.0", .name = "8bit" + .type = PIN_MAP_TYPE_MUX_GROUP, .ctrl_dev_name = "pinctrl-foo", .function = "mmc0", .group = "mmc0_1_grp", @@ -885,6 +934,7 @@ case), we define a mapping like this: { .dev_name = "foo-mmc.0", .name = "8bit" + .type = PIN_MAP_TYPE_MUX_GROUP, .ctrl_dev_name = "pinctrl-foo", .function = "mmc0", .group = "mmc0_2_grp", @@ -892,6 +942,7 @@ case), we define a mapping like this: { .dev_name = "foo-mmc.0", .name = "8bit" + .type = PIN_MAP_TYPE_MUX_GROUP, .ctrl_dev_name = "pinctrl-foo", .function = "mmc0", .group = "mmc0_3_grp", @@ -1014,6 +1065,7 @@ to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT. { .dev_name = "pinctrl-foo", .name = PINCTRL_STATE_DEFAULT, + .type = PIN_MAP_TYPE_MUX_GROUP, .ctrl_dev_name = "pinctrl-foo", .function = "power_func", }, @@ -1022,7 +1074,7 @@ Since it may be common to request the core to hog a few always-applicable mux settings on the primary pin controller, there is a convenience macro for this: -PIN_MAP_SYS_HOG("pinctrl-foo", "power_func") +PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */, "power_func") This gives the exact same result as the above construction. -- cgit v1.2.3