Documentation/arm/pxa/mfp.rst

   1 ==============================================
   2 MFP Configuration for PXA2xx/PXA3xx Processors
   3 ==============================================
   4
   5                         Eric Miao <eric.miao@marvell.com>
   6
   7 MFP stands for Multi-Function Pin, which is the pin-mux logic on PXA3xx and
   8 later PXA series processors.  This document describes the existing MFP API,
   9 and how board/platform driver authors could make use of it.
  10
  11 Basic Concept
  12 =============
  13
  14 Unlike the GPIO alternate function settings on PXA25x and PXA27x, a new MFP
  15 mechanism is introduced from PXA3xx to completely move the pin-mux functions
  16 out of the GPIO controller. In addition to pin-mux configurations, the MFP
  17 also controls the low power state, driving strength, pull-up/down and event
  18 detection of each pin.  Below is a diagram of internal connections between
  19 the 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
  43 NOTE: the external pad is named as MFP_PIN_GPIO19, it doesn't necessarily
  44 mean it's dedicated for GPIO19, only as a hint that internally this pin
  45 can be routed from GPIO19 of the GPIO controller.
  46
  47 To better understand the change from PXA25x/PXA27x GPIO alternate function
  48 to 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
  70 NOTE: with such a clear separation of MFP and GPIO, by GPIO<xx> we normally
  71 mean it is a GPIO signal, and by MFP<xxx> or pin xxx, we mean a physical
  72 pad (or ball).
  73
  74 MFP API Usage
  75 =============
  76
  77 For board code writers, here are some guidelines:
  78
  79 1. 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
  99 2. 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
 152 MFP on PXA3xx
 153 =============
 154
 155 Every external I/O pad on PXA3xx (excluding those for special purpose) has
 156 one MFP logic associated, and is controlled by one MFP register (MFPR).
 157
 158 The 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
 188 MFP Design for PXA2xx/PXA3xx
 189 ============================
 190
 191 Due to the difference of pin-mux handling between PXA2xx and PXA3xx, a unified
 192 MFP API is introduced to cover both series of processors.
 193
 194 The basic idea of this design is to introduce definitions for all possible pin
 195 configurations, these definitions are processor and platform independent, and
 196 the actual API invoked to convert these definitions into register settings and
 197 make them effective there-after.
 198
 199 Files 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
 231 Pin 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
 277 Register 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.