xref: /openbmc/linux/Documentation/arch/arm/pxa/mfp.rst (revision 0c6dfa75) 
1==============================================
2MFP Configuration for PXA2xx/PXA3xx Processors
3==============================================
4
5			Eric Miao <eric.miao@marvell.com>
6
7MFP stands for Multi-Function Pin, which is the pin-mux logic on PXA3xx and
8later PXA series processors.  This document describes the existing MFP API,
9and how board/platform driver authors could make use of it.
10
11Basic Concept
12=============
13
14Unlike the GPIO alternate function settings on PXA25x and PXA27x, a new MFP
15mechanism is introduced from PXA3xx to completely move the pin-mux functions
16out of the GPIO controller. In addition to pin-mux configurations, the MFP
17also controls the low power state, driving strength, pull-up/down and event
18detection of each pin.  Below is a diagram of internal connections between
19the MFP logic and the remaining SoC peripherals::
20
21 +--------+
22 |        |--(GPIO19)--+
23 |  GPIO  |            |
24 |        |--(GPIO...) |
25 +--------+            |
26                       |       +---------+
27 +--------+            +------>|         |
28 |  PWM2  |--(PWM_OUT)-------->|   MFP   |
29 +--------+            +------>|         |-------> to external PAD
30                       | +---->|         |
31 +--------+            | | +-->|         |
32 |  SSP2  |---(TXD)----+ | |   +---------+
33 +--------+              | |
34                         | |
35 +--------+              | |
36 | Keypad |--(MKOUT4)----+ |
37 +--------+                |
38                           |
39 +--------+                |
40 |  UART2 |---(TXD)--------+
41 +--------+
42
43NOTE: the external pad is named as MFP_PIN_GPIO19, it doesn't necessarily
44mean it's dedicated for GPIO19, only as a hint that internally this pin
45can be routed from GPIO19 of the GPIO controller.
46
47To better understand the change from PXA25x/PXA27x GPIO alternate function
48to this new MFP mechanism, here are several key points:
49
50  1. GPIO controller on PXA3xx is now a dedicated controller, same as other
51     internal controllers like PWM, SSP and UART, with 128 internal signals
52     which can be routed to external through one or more MFPs (e.g. GPIO<0>
53     can be routed through either MFP_PIN_GPIO0 as well as MFP_PIN_GPIO0_2,
54     see arch/arm/mach-pxa/mfp-pxa300.h)
55
56  2. Alternate function configuration is removed from this GPIO controller,
57     the remaining functions are pure GPIO-specific, i.e.
58
59       - GPIO signal level control
60       - GPIO direction control
61       - GPIO level change detection
62
63  3. Low power state for each pin is now controlled by MFP, this means the
64     PGSRx registers on PXA2xx are now useless on PXA3xx
65
66  4. Wakeup detection is now controlled by MFP, PWER does not control the
67     wakeup from GPIO(s) any more, depending on the sleeping state, ADxER
68     (as defined in pxa3xx-regs.h) controls the wakeup from MFP
69
70NOTE: with such a clear separation of MFP and GPIO, by GPIO<xx> we normally
71mean it is a GPIO signal, and by MFP<xxx> or pin xxx, we mean a physical
72pad (or ball).
73
74MFP API Usage
75=============
76
77For board code writers, here are some guidelines:
78
791. include ONE of the following header files in your <board>.c:
80
81   - #include "mfp-pxa25x.h"
82   - #include "mfp-pxa27x.h"
83   - #include "mfp-pxa300.h"
84   - #include "mfp-pxa320.h"
85   - #include "mfp-pxa930.h"
86
87   NOTE: only one file in your <board>.c, depending on the processors used,
88   because pin configuration definitions may conflict in these file (i.e.
89   same name, different meaning and settings on different processors). E.g.
90   for zylonite platform, which support both PXA300/PXA310 and PXA320, two
91   separate files are introduced: zylonite_pxa300.c and zylonite_pxa320.c
92   (in addition to handle MFP configuration differences, they also handle
93   the other differences between the two combinations).
94
95   NOTE: PXA300 and PXA310 are almost identical in pin configurations (with
96   PXA310 supporting some additional ones), thus the difference is actually
97   covered in a single mfp-pxa300.h.
98
992. prepare an array for the initial pin configurations, e.g.::
100
101     static unsigned long mainstone_pin_config[] __initdata = {
102	/* Chip Select */
103	GPIO15_nCS_1,
104
105	/* LCD - 16bpp Active TFT */
106	GPIOxx_TFT_LCD_16BPP,
107	GPIO16_PWM0_OUT,	/* Backlight */
108
109	/* MMC */
110	GPIO32_MMC_CLK,
111	GPIO112_MMC_CMD,
112	GPIO92_MMC_DAT_0,
113	GPIO109_MMC_DAT_1,
114	GPIO110_MMC_DAT_2,
115	GPIO111_MMC_DAT_3,
116
117	...
118
119	/* GPIO */
120	GPIO1_GPIO | WAKEUP_ON_EDGE_BOTH,
121     };
122
123   a) once the pin configurations are passed to pxa{2xx,3xx}_mfp_config(),
124   and written to the actual registers, they are useless and may discard,
125   adding '__initdata' will help save some additional bytes here.
126
127   b) when there is only one possible pin configurations for a component,
128   some simplified definitions can be used, e.g. GPIOxx_TFT_LCD_16BPP on
129   PXA25x and PXA27x processors
130
131   c) if by board design, a pin can be configured to wake up the system
132   from low power state, it can be 'OR'ed with any of:
133
134      WAKEUP_ON_EDGE_BOTH
135      WAKEUP_ON_EDGE_RISE
136      WAKEUP_ON_EDGE_FALL
137      WAKEUP_ON_LEVEL_HIGH - specifically for enabling of keypad GPIOs,
138
139   to indicate that this pin has the capability of wake-up the system,
140   and on which edge(s). This, however, doesn't necessarily mean the
141   pin _will_ wakeup the system, it will only when set_irq_wake() is
142   invoked with the corresponding GPIO IRQ (GPIO_IRQ(xx) or gpio_to_irq())
143   and eventually calls gpio_set_wake() for the actual register setting.
144
145   d) although PXA3xx MFP supports edge detection on each pin, the
146   internal logic will only wakeup the system when those specific bits
147   in ADxER registers are set, which can be well mapped to the
148   corresponding peripheral, thus set_irq_wake() can be called with
149   the peripheral IRQ to enable the wakeup.
150
151
152MFP on PXA3xx
153=============
154
155Every external I/O pad on PXA3xx (excluding those for special purpose) has
156one MFP logic associated, and is controlled by one MFP register (MFPR).
157
158The MFPR has the following bit definitions (for PXA300/PXA310/PXA320)::
159
160 31                        16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
161  +-------------------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
162  |         RESERVED        |PS|PU|PD|  DRIVE |SS|SD|SO|EC|EF|ER|--| AF_SEL |
163  +-------------------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
164
165  Bit 3:   RESERVED
166  Bit 4:   EDGE_RISE_EN - enable detection of rising edge on this pin
167  Bit 5:   EDGE_FALL_EN - enable detection of falling edge on this pin
168  Bit 6:   EDGE_CLEAR   - disable edge detection on this pin
169  Bit 7:   SLEEP_OE_N   - enable outputs during low power modes
170  Bit 8:   SLEEP_DATA   - output data on the pin during low power modes
171  Bit 9:   SLEEP_SEL    - selection control for low power modes signals
172  Bit 13:  PULLDOWN_EN  - enable the internal pull-down resistor on this pin
173  Bit 14:  PULLUP_EN    - enable the internal pull-up resistor on this pin
174  Bit 15:  PULL_SEL     - pull state controlled by selected alternate function
175                          (0) or by PULL{UP,DOWN}_EN bits (1)
176
177  Bit 0 - 2: AF_SEL - alternate function selection, 8 possibilities, from 0-7
178  Bit 10-12: DRIVE  - drive strength and slew rate
179			0b000 - fast 1mA
180			0b001 - fast 2mA
181			0b002 - fast 3mA
182			0b003 - fast 4mA
183			0b004 - slow 6mA
184			0b005 - fast 6mA
185			0b006 - slow 10mA
186			0b007 - fast 10mA
187
188MFP Design for PXA2xx/PXA3xx
189============================
190
191Due to the difference of pin-mux handling between PXA2xx and PXA3xx, a unified
192MFP API is introduced to cover both series of processors.
193
194The basic idea of this design is to introduce definitions for all possible pin
195configurations, these definitions are processor and platform independent, and
196the actual API invoked to convert these definitions into register settings and
197make them effective there-after.
198
199Files Involved
200--------------
201
202  - arch/arm/mach-pxa/include/mach/mfp.h
203
204  for
205    1. Unified pin definitions - enum constants for all configurable pins
206    2. processor-neutral bit definitions for a possible MFP configuration
207
208  - arch/arm/mach-pxa/mfp-pxa3xx.h
209
210  for PXA3xx specific MFPR register bit definitions and PXA3xx common pin
211  configurations
212
213  - arch/arm/mach-pxa/mfp-pxa2xx.h
214
215  for PXA2xx specific definitions and PXA25x/PXA27x common pin configurations
216
217  - arch/arm/mach-pxa/mfp-pxa25x.h
218    arch/arm/mach-pxa/mfp-pxa27x.h
219    arch/arm/mach-pxa/mfp-pxa300.h
220    arch/arm/mach-pxa/mfp-pxa320.h
221    arch/arm/mach-pxa/mfp-pxa930.h
222
223  for processor specific definitions
224
225  - arch/arm/mach-pxa/mfp-pxa3xx.c
226  - arch/arm/mach-pxa/mfp-pxa2xx.c
227
228  for implementation of the pin configuration to take effect for the actual
229  processor.
230
231Pin Configuration
232-----------------
233
234  The following comments are copied from mfp.h (see the actual source code
235  for most updated info)::
236
237    /*
238     * a possible MFP configuration is represented by a 32-bit integer
239     *
240     * bit  0.. 9 - MFP Pin Number (1024 Pins Maximum)
241     * bit 10..12 - Alternate Function Selection
242     * bit 13..15 - Drive Strength
243     * bit 16..18 - Low Power Mode State
244     * bit 19..20 - Low Power Mode Edge Detection
245     * bit 21..22 - Run Mode Pull State
246     *
247     * to facilitate the definition, the following macros are provided
248     *
249     * MFP_CFG_DEFAULT - default MFP configuration value, with
250     * 		  alternate function = 0,
251     * 		  drive strength = fast 3mA (MFP_DS03X)
252     * 		  low power mode = default
253     * 		  edge detection = none
254     *
255     * MFP_CFG	- default MFPR value with alternate function
256     * MFP_CFG_DRV	- default MFPR value with alternate function and
257     * 		  pin drive strength
258     * MFP_CFG_LPM	- default MFPR value with alternate function and
259     * 		  low power mode
260     * MFP_CFG_X	- default MFPR value with alternate function,
261     * 		  pin drive strength and low power mode
262     */
263
264   Examples of pin configurations are::
265
266     #define GPIO94_SSP3_RXD		MFP_CFG_X(GPIO94, AF1, DS08X, FLOAT)
267
268   which reads GPIO94 can be configured as SSP3_RXD, with alternate function
269   selection of 1, driving strength of 0b101, and a float state in low power
270   modes.
271
272   NOTE: this is the default setting of this pin being configured as SSP3_RXD
273   which can be modified a bit in board code, though it is not recommended to
274   do so, simply because this default setting is usually carefully encoded,
275   and is supposed to work in most cases.
276
277Register Settings
278-----------------
279
280   Register settings on PXA3xx for a pin configuration is actually very
281   straight-forward, most bits can be converted directly into MFPR value
282   in a easier way. Two sets of MFPR values are calculated: the run-time
283   ones and the low power mode ones, to allow different settings.
284
285   The conversion from a generic pin configuration to the actual register
286   settings on PXA2xx is a bit complicated: many registers are involved,
287   including GAFRx, GPDRx, PGSRx, PWER, PKWR, PFER and PRER. Please see
288   mfp-pxa2xx.c for how the conversion is made.
289