]>
Commit | Line | Data |
---|---|---|
70816e2c GB |
1 | This document provides an overview of the msm_gpiomux interface, which |
2 | is used to provide gpio pin multiplexing and configuration on mach-msm | |
3 | targets. | |
4 | ||
5 | History | |
6 | ======= | |
7 | ||
8 | The first-generation API for gpio configuration & multiplexing on msm | |
9 | is the function gpio_tlmm_config(). This function has a few notable | |
10 | shortcomings, which led to its deprecation and replacement by gpiomux: | |
11 | ||
12 | The 'disable' parameter: Setting the second parameter to | |
13 | gpio_tlmm_config to GPIO_CFG_DISABLE tells the peripheral | |
14 | processor in charge of the subsystem to perform a look-up into a | |
15 | low-power table and apply the low-power/sleep setting for the pin. | |
16 | As the msm family evolved this became problematic. Not all pins | |
17 | have sleep settings, not all peripheral processors will accept requests | |
18 | to apply said sleep settings, and not all msm targets have their gpio | |
19 | subsystems managed by a peripheral processor. In order to get consistent | |
20 | behavior on all targets, drivers are forced to ignore this parameter, | |
21 | rendering it useless. | |
22 | ||
23 | The 'direction' flag: for all mux-settings other than raw-gpio (0), | |
24 | the output-enable bit of a gpio is hard-wired to a known | |
25 | input (usually VDD or ground). For those settings, the direction flag | |
26 | is meaningless at best, and deceptive at worst. In addition, using the | |
27 | direction flag to change output-enable (OE) directly can cause trouble in | |
28 | gpiolib, which has no visibility into gpio direction changes made | |
29 | in this way. Direction control in gpio mode should be made through gpiolib. | |
30 | ||
31 | Key Features of gpiomux | |
32 | ======================= | |
33 | ||
34 | - A consistent interface across all generations of msm. Drivers can expect | |
35 | the same results on every target. | |
36 | - gpiomux plays nicely with gpiolib. Functions that should belong to gpiolib | |
37 | are left to gpiolib and not duplicated here. gpiomux is written with the | |
38 | intent that gpio_chips will call gpiomux reference-counting methods | |
39 | from their request() and free() hooks, providing full integration. | |
40 | - Tabular configuration. Instead of having to call gpio_tlmm_config | |
41 | hundreds of times, gpio configuration is placed in a single table. | |
42 | - Per-gpio sleep. Each gpio is individually reference counted, allowing only | |
43 | those lines which are in use to be put in high-power states. | |
44 | - 0 means 'do nothing': all flags are designed so that the default memset-zero | |
45 | equates to a sensible default of 'no configuration', preventing users | |
46 | from having to provide hundreds of 'no-op' configs for unused or | |
47 | unwanted lines. | |
48 | ||
49 | Usage | |
50 | ===== | |
51 | ||
52 | To use gpiomux, provide configuration information for relevant gpio lines | |
53 | in the msm_gpiomux_configs table. Since a 0 equates to "unconfigured", | |
54 | only those lines to be managed by gpiomux need to be specified. Here | |
55 | is a completely fictional example: | |
56 | ||
57 | struct msm_gpiomux_config msm_gpiomux_configs[GPIOMUX_NGPIOS] = { | |
58 | [12] = { | |
59 | .active = GPIOMUX_VALID | GPIOMUX_DRV_8MA | GPIOMUX_FUNC_1, | |
60 | .suspended = GPIOMUX_VALID | GPIOMUX_PULL_DOWN, | |
61 | }, | |
62 | [34] = { | |
63 | .suspended = GPIOMUX_VALID | GPIOMUX_PULL_DOWN, | |
64 | }, | |
65 | }; | |
66 | ||
67 | To indicate that a gpio is in use, call msm_gpiomux_get() to increase | |
68 | its reference count. To decrease the reference count, call msm_gpiomux_put(). | |
69 | ||
70 | The effect of this configuration is as follows: | |
71 | ||
72 | When the system boots, gpios 12 and 34 will be initialized with their | |
73 | 'suspended' configurations. All other gpios, which were left unconfigured, | |
74 | will not be touched. | |
75 | ||
76 | When msm_gpiomux_get() is called on gpio 12 to raise its reference count | |
77 | above 0, its active configuration will be applied. Since no other gpio | |
78 | line has a valid active configuration, msm_gpiomux_get() will have no | |
79 | effect on any other line. | |
80 | ||
81 | When msm_gpiomux_put() is called on gpio 12 or 34 to drop their reference | |
82 | count to 0, their suspended configurations will be applied. | |
83 | Since no other gpio line has a valid suspended configuration, no other | |
84 | gpio line will be effected by msm_gpiomux_put(). Since gpio 34 has no valid | |
85 | active configuration, this is effectively a no-op for gpio 34 as well, | |
86 | with one small caveat, see the section "About Output-Enable Settings". | |
87 | ||
88 | All of the GPIOMUX_VALID flags may seem like unnecessary overhead, but | |
89 | they address some important issues. As unused entries (all those | |
90 | except 12 and 34) are zero-filled, gpiomux needs a way to distinguish | |
91 | the used fields from the unused. In addition, the all-zero pattern | |
92 | is a valid configuration! Therefore, gpiomux defines an additional bit | |
93 | which is used to indicate when a field is used. This has the pleasant | |
94 | side-effect of allowing calls to msm_gpiomux_write to use '0' to indicate | |
95 | that a value should not be changed: | |
96 | ||
97 | msm_gpiomux_write(0, GPIOMUX_VALID, 0); | |
98 | ||
99 | replaces the active configuration of gpio 0 with an all-zero configuration, | |
100 | but leaves the suspended configuration as it was. | |
101 | ||
102 | Static Configurations | |
103 | ===================== | |
104 | ||
105 | To install a static configuration, which is applied at boot and does | |
106 | not change after that, install a configuration with a suspended component | |
107 | but no active component, as in the previous example: | |
108 | ||
109 | [34] = { | |
110 | .suspended = GPIOMUX_VALID | GPIOMUX_PULL_DOWN, | |
111 | }, | |
112 | ||
113 | The suspended setting is applied during boot, and the lack of any valid | |
114 | active setting prevents any other setting from being applied at runtime. | |
115 | If other subsystems attempting to access the line is a concern, one could | |
116 | *really* anchor the configuration down by calling msm_gpiomux_get on the | |
117 | line at initialization to move the line into active mode. With the line | |
118 | held, it will never be re-suspended, and with no valid active configuration, | |
119 | no new configurations will be applied. | |
120 | ||
121 | But then, if having other subsystems grabbing for the line is truly a concern, | |
122 | it should be reserved with gpio_request instead, which carries an implicit | |
123 | msm_gpiomux_get. | |
124 | ||
125 | gpiomux and gpiolib | |
126 | =================== | |
127 | ||
128 | It is expected that msm gpio_chips will call msm_gpiomux_get() and | |
129 | msm_gpiomux_put() from their request and free hooks, like this fictional | |
130 | example: | |
131 | ||
132 | static int request(struct gpio_chip *chip, unsigned offset) | |
133 | { | |
134 | return msm_gpiomux_get(chip->base + offset); | |
135 | } | |
136 | ||
137 | static void free(struct gpio_chip *chip, unsigned offset) | |
138 | { | |
139 | msm_gpiomux_put(chip->base + offset); | |
140 | } | |
141 | ||
142 | ...somewhere in a gpio_chip declaration... | |
143 | .request = request, | |
144 | .free = free, | |
145 | ||
146 | This provides important functionality: | |
147 | - It guarantees that a gpio line will have its 'active' config applied | |
148 | when the line is requested, and will not be suspended while the line | |
149 | remains requested; and | |
150 | - It guarantees that gpio-direction settings from gpiolib behave sensibly. | |
151 | See "About Output-Enable Settings." | |
152 | ||
153 | This mechanism allows for "auto-request" of gpiomux lines via gpiolib | |
154 | when it is suitable. Drivers wishing more exact control are, of course, | |
155 | free to also use msm_gpiomux_set and msm_gpiomux_get. | |
156 | ||
157 | About Output-Enable Settings | |
158 | ============================ | |
159 | ||
160 | Some msm targets do not have the ability to query the current gpio | |
161 | configuration setting. This means that changes made to the output-enable | |
162 | (OE) bit by gpiolib cannot be consistently detected and preserved by gpiomux. | |
163 | Therefore, when gpiomux applies a configuration setting, any direction | |
164 | settings which may have been applied by gpiolib are lost and the default | |
165 | input settings are re-applied. | |
166 | ||
167 | For this reason, drivers should not assume that gpio direction settings | |
168 | continue to hold if they free and then re-request a gpio. This seems like | |
169 | common sense - after all, anybody could have obtained the line in the | |
170 | meantime - but it needs saying. | |
171 | ||
172 | This also means that calls to msm_gpiomux_write will reset the OE bit, | |
173 | which means that if the gpio line is held by a client of gpiolib and | |
174 | msm_gpiomux_write is called, the direction setting has been lost and | |
175 | gpiolib's internal state has been broken. | |
176 | Release gpio lines before reconfiguring them. |