From 7ba4d884eeb562c7c034b0809a829a534c20547b Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Thu, 10 Nov 2011 09:27:41 +0100 Subject: [PATCH] pinctrl: documentation update Update the docs removing an obsolete __refdata tag and document the mysterious return value of pin_free(). And fixes up some various confusions in the pinctrl documentation. Reported-by: Rajendra Nayak Reported-by: Randy Dunlap Reported-by: Thomas Abraham Acked-by: Stephen Warren Signed-off-by: Linus Walleij --- Documentation/pinctrl.txt | 40 +++++++++++++++++++-------------------- drivers/pinctrl/pinmux.c | 4 ++++ 2 files changed, 24 insertions(+), 20 deletions(-) diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index b04cb7d45a16..f78ebce09b9b 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -32,7 +32,7 @@ Definition of PIN: be sparse - i.e. there may be gaps in the space with numbers where no pin exists. -When a PIN CONTROLLER is instatiated, it will register a descriptor to the +When a PIN CONTROLLER is instantiated, it will register a descriptor to the pin control framework, and this descriptor contains an array of pin descriptors describing the pins handled by this specific pin controller. @@ -61,14 +61,14 @@ this in our driver: #include -const struct pinctrl_pin_desc __refdata foo_pins[] = { - PINCTRL_PIN(0, "A1"), - PINCTRL_PIN(1, "A2"), - PINCTRL_PIN(2, "A3"), +const struct pinctrl_pin_desc foo_pins[] = { + PINCTRL_PIN(0, "A8"), + PINCTRL_PIN(1, "B8"), + PINCTRL_PIN(2, "C8"), ... - PINCTRL_PIN(61, "H6"), - PINCTRL_PIN(62, "H7"), - PINCTRL_PIN(63, "H8"), + PINCTRL_PIN(61, "F1"), + PINCTRL_PIN(62, "G1"), + PINCTRL_PIN(63, "H1"), }; static struct pinctrl_desc foo_desc = { @@ -91,8 +91,8 @@ int __init foo_probe(void) Pins usually have fancier names than this. You can find these in the dataheet 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, -this enumeration was arbitrarily chosen, in practice you need to think +the pins from 0 in the upper left corner to 63 in the lower right corner. +This enumeration was arbitrarily chosen, in practice you need to think through your numbering system so that it matches the layout of registers and such things in your driver, or the code may become complicated. You must also consider matching of offsets to the GPIO ranges that may be handled by @@ -242,7 +242,7 @@ chip a: [32 .. 47] chip b: [48 .. 55] When GPIO-specific functions in the pin control subsystem are called, these -ranges will be used to look up the apropriate pin controller by inspecting +ranges will be used to look up the appropriate pin controller by inspecting and matching the pin to the pin ranges across all controllers. When a pin controller handling the matching range is found, GPIO-specific functions will be called on that specific pin controller. @@ -438,7 +438,7 @@ you. Define enumerators only for the pins you can control if that makes sense. Assumptions: -We assume that the number possible function maps to pin groups is limited by +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 a certain function will be limited to a few choices (say up to eight or so), @@ -585,7 +585,7 @@ int foo_list_funcs(struct pinctrl_dev *pctldev, unsigned selector) const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector) { - return myfuncs[selector].name; + return foo_functions[selector].name; } static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector, @@ -606,7 +606,7 @@ int foo_enable(struct pinctrl_dev *pctldev, unsigned selector, return 0; } -int foo_disable(struct pinctrl_dev *pctldev, unsigned selector, +void foo_disable(struct pinctrl_dev *pctldev, unsigned selector, unsigned group) { u8 regbit = (1 << group); @@ -762,42 +762,42 @@ case), we define a mapping like this: .name "2bit" .ctrl_dev_name = "pinctrl.0", .function = "mmc0", - .group = "mmc0_0_grp", + .group = "mmc0_1_grp", .dev_name = "foo-mmc.0", }, { .name "4bit" .ctrl_dev_name = "pinctrl.0", .function = "mmc0", - .group = "mmc0_0_grp", + .group = "mmc0_1_grp", .dev_name = "foo-mmc.0", }, { .name "4bit" .ctrl_dev_name = "pinctrl.0", .function = "mmc0", - .group = "mmc0_1_grp", + .group = "mmc0_2_grp", .dev_name = "foo-mmc.0", }, { .name "8bit" .ctrl_dev_name = "pinctrl.0", .function = "mmc0", - .group = "mmc0_0_grp", + .group = "mmc0_1_grp", .dev_name = "foo-mmc.0", }, { .name "8bit" .ctrl_dev_name = "pinctrl.0", .function = "mmc0", - .group = "mmc0_1_grp", + .group = "mmc0_2_grp", .dev_name = "foo-mmc.0", }, { .name "8bit" .ctrl_dev_name = "pinctrl.0", .function = "mmc0", - .group = "mmc0_2_grp", + .group = "mmc0_3_grp", .dev_name = "foo-mmc.0", }, ... diff --git a/drivers/pinctrl/pinmux.c b/drivers/pinctrl/pinmux.c index 06bee1b733bb..4b35661bdfe9 100644 --- a/drivers/pinctrl/pinmux.c +++ b/drivers/pinctrl/pinmux.c @@ -178,6 +178,10 @@ out: * @pin: the pin to free * @gpio_range: the range matching the GPIO pin if this is a request for a * single GPIO pin + * + * This function returns a pointer to the function name in use. This is used + * for callers that dynamically allocate a function name so it can be freed + * once the pin is free. This is done for GPIO request functions. */ static const char *pin_free(struct pinctrl_dev *pctldev, int pin, struct pinctrl_gpio_range *gpio_range) -- 2.39.5