|
| 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. |
0 commit comments