Skip to content

Commit

Permalink
pinctrl: documentation update
Browse files Browse the repository at this point in the history 
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 <[email protected]>
Reported-by: Randy Dunlap <[email protected]>
Reported-by: Thomas Abraham <[email protected]>
Reported-by: Uwe Kleine-König <[email protected]>
Acked-by: Stephen Warren <[email protected]>
Signed-off-by: Linus Walleij <[email protected]>
  • Loading branch information
@linusw
linusw committed Jan 3, 2012
1 parent 3712a3c commit 336cdba
Show file tree
Hide file tree
Showing 2 changed files with 31 additions and 27 deletions.
52 changes: 26 additions & 26 deletions Documentation/pinctrl.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -61,14 +61,14 @@ this in our driver:

#include <linux/pinctrl/pinctrl.h>

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 = {
Expand All @@ -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
Expand Down Expand Up @@ -133,8 +133,8 @@ struct foo_group {
const unsigned num_pins;
};

static unsigned int spi0_pins[] = { 0, 8, 16, 24 };
static unsigned int i2c0_pins[] = { 24, 25 };
static const unsigned int spi0_pins[] = { 0, 8, 16, 24 };
static const unsigned int i2c0_pins[] = { 24, 25 };

static const struct foo_group foo_groups[] = {
{
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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),
Expand Down Expand Up @@ -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,
Expand All @@ -600,16 +600,16 @@ static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector,
int foo_enable(struct pinctrl_dev *pctldev, unsigned selector,
unsigned group)
{
u8 regbit = (1 << group);
u8 regbit = (1 << selector + group);

writeb((readb(MUX)|regbit), MUX)
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);
u8 regbit = (1 << selector + group);

writeb((readb(MUX) & ~(regbit)), MUX)
return 0;
Expand Down Expand Up @@ -683,7 +683,7 @@ spi on the second function mapping:

#include <linux/pinctrl/machine.h>

static struct pinmux_map pmx_mapping[] = {
static const struct pinmux_map pmx_mapping[] = {
{
.ctrl_dev_name = "pinctrl.0",
.function = "spi0",
Expand Down Expand Up @@ -714,7 +714,7 @@ for example if they are not yet instantiated or cumbersome to obtain.

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

ret = pinmux_register_mappings(&pmx_mapping, ARRAY_SIZE(pmx_mapping));
ret = pinmux_register_mappings(pmx_mapping, ARRAY_SIZE(pmx_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.0 and position
Expand Down Expand Up @@ -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",
},
...
Expand Down
6 changes: 5 additions & 1 deletion drivers/pinctrl/pinmux.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,10 @@ static int pin_request(struct pinctrl_dev *pctldev,
* @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)
Expand Down Expand Up @@ -919,7 +923,7 @@ int pinmux_hog_maps(struct pinctrl_dev *pctldev)
}

/**
* pinmux_hog_maps() - unhog specific map entries on controller device
* pinmux_unhog_maps() - unhog specific map entries on controller device
* @pctldev: the pin control device to unhog entries on
*/
void pinmux_unhog_maps(struct pinctrl_dev *pctldev)
Expand Down

0 comments on commit 336cdba

Please sign in to comment.