2 files changed, 376 insertions, 2 deletions

diff --git a/Documentation/arm/pxa/mfp.txt b/Documentation/arm/pxa/mfp.txt
new file mode 100644
index 000000000000..a179e5bc02c9
--- /dev/null
+++ b/Documentation/arm/pxa/mfp.txt
@@ -0,0 +1,286 @@
+                 MFP Configuration for PXA2xx/PXA3xx Processors
+
+                        Eric Miao <eric.miao@marvell.com>
+
+MFP stands for Multi-Function Pin, which is the pin-mux logic on PXA3xx and
+later PXA series processors.  This document describes the existing MFP API,
+and how board/platform driver authors could make use of it.
+
+ Basic Concept
+===============
+
+Unlike the GPIO alternate function settings on PXA25x and PXA27x, a new MFP
+mechanism is introduced from PXA3xx to completely move the pin-mux functions
+out of the GPIO controller. In addition to pin-mux configurations, the MFP
+also controls the low power state, driving strength, pull-up/down and event
+detection of each pin.  Below is a diagram of internal connections between
+the MFP logic and the remaining SoC peripherals:
+
+ +--------+
+ |        |--(GPIO19)--+
+ |  GPIO  |            |
+ |        |--(GPIO...) |
+ +--------+            |
+                       |       +---------+
+ +--------+            +------>|         |
+ |  PWM2  |--(PWM_OUT)-------->|   MFP   |
+ +--------+            +------>|         |-------> to external PAD
+                       | +---->|         |
+ +--------+            | | +-->|         |
+ |  SSP2  |---(TXD)----+ | |   +---------+
+ +--------+              | |
+                         | |
+ +--------+              | |
+ | Keypad |--(MKOUT4)----+ |
+ +--------+                |
+                           |
+ +--------+                |
+ |  UART2 |---(TXD)--------+
+ +--------+
+
+NOTE: the external pad is named as MFP_PIN_GPIO19, it doesn't necessarily
+mean it's dedicated for GPIO19, only as a hint that internally this pin
+can be routed from GPIO19 of the GPIO controller.
+
+To better understand the change from PXA25x/PXA27x GPIO alternate function
+to this new MFP mechanism, here are several key points:
+
+  1. GPIO controller on PXA3xx is now a dedicated controller, same as other
+     internal controllers like PWM, SSP and UART, with 128 internal signals
+     which can be routed to external through one or more MFPs (e.g. GPIO<0>
+     can be routed through either MFP_PIN_GPIO0 as well as MFP_PIN_GPIO0_2,
+     see arch/arm/mach-pxa/mach/include/mfp-pxa300.h)
+
+  2. Alternate function configuration is removed from this GPIO controller,
+     the remaining functions are pure GPIO-specific, i.e.
+
+       - GPIO signal level control
+       - GPIO direction control
+       - GPIO level change detection
+
+  3. Low power state for each pin is now controlled by MFP, this means the
+     PGSRx registers on PXA2xx are now useless on PXA3xx
+
+  4. Wakeup detection is now controlled by MFP, PWER does not control the
+     wakeup from GPIO(s) any more, depending on the sleeping state, ADxER
+     (as defined in pxa3xx-regs.h) controls the wakeup from MFP
+
+NOTE: with such a clear separation of MFP and GPIO, by GPIO<xx> we normally
+mean it is a GPIO signal, and by MFP<xxx> or pin xxx, we mean a physical
+pad (or ball).
+
+ MFP API Usage
+===============
+
+For board code writers, here are some guidelines:
+
+1. include ONE of the following header files in your <board>.c:
+
+   - #include <mach/mfp-pxa25x.h>
+   - #include <mach/mfp-pxa27x.h>
+   - #include <mach/mfp-pxa300.h>
+   - #include <mach/mfp-pxa320.h>
+   - #include <mach/mfp-pxa930.h>
+
+   NOTE: only one file in your <board>.c, depending on the processors used,
+   because pin configuration definitions may conflict in these file (i.e.
+   same name, different meaning and settings on different processors). E.g.
+   for zylonite platform, which support both PXA300/PXA310 and PXA320, two
+   separate files are introduced: zylonite_pxa300.c and zylonite_pxa320.c
+   (in addition to handle MFP configuration differences, they also handle
+   the other differences between the two combinations).
+
+   NOTE: PXA300 and PXA310 are almost identical in pin configurations (with
+   PXA310 supporting some additional ones), thus the difference is actually
+   covered in a single mfp-pxa300.h.
+
+2. prepare an array for the initial pin configurations, e.g.:
+
+   static unsigned long mainstone_pin_config[] __initdata = {
+        /* Chip Select */
+        GPIO15_nCS_1,
+
+        /* LCD - 16bpp Active TFT */
+        GPIOxx_TFT_LCD_16BPP,
+        GPIO16_PWM0_OUT,        /* Backlight */
+
+        /* MMC */
+        GPIO32_MMC_CLK,
+        GPIO112_MMC_CMD,
+        GPIO92_MMC_DAT_0,
+        GPIO109_MMC_DAT_1,
+        GPIO110_MMC_DAT_2,
+        GPIO111_MMC_DAT_3,
+
+        ...
+
+        /* GPIO */
+        GPIO1_GPIO | WAKEUP_ON_EDGE_BOTH,
+   };
+
+   a) once the pin configurations are passed to pxa{2xx,3xx}_mfp_config(),
+   and written to the actual registers, they are useless and may discard,
+   adding '__initdata' will help save some additional bytes here.
+
+   b) when there is only one possible pin configurations for a component,
+   some simplified definitions can be used, e.g. GPIOxx_TFT_LCD_16BPP on
+   PXA25x and PXA27x processors
+
+   c) if by board design, a pin can be configured to wake up the system
+   from low power state, it can be 'OR'ed with any of:
+
+      WAKEUP_ON_EDGE_BOTH
+      WAKEUP_ON_EDGE_RISE
+      WAKEUP_ON_EDGE_FALL
+      WAKEUP_ON_LEVEL_HIGH - specifically for enabling of keypad GPIOs,
+
+   to indicate that this pin has the capability of wake-up the system,
+   and on which edge(s). This, however, doesn't necessarily mean the
+   pin _will_ wakeup the system, it will only when set_irq_wake() is
+   invoked with the corresponding GPIO IRQ (GPIO_IRQ(xx) or gpio_to_irq())
+   and eventually calls gpio_set_wake() for the actual register setting.
+
+   d) although PXA3xx MFP supports edge detection on each pin, the
+   internal logic will only wakeup the system when those specific bits
+   in ADxER registers are set, which can be well mapped to the
+   corresponding peripheral, thus set_irq_wake() can be called with 
+   the peripheral IRQ to enable the wakeup.
+
+
+ MFP on PXA3xx
+===============
+
+Every external I/O pad on PXA3xx (excluding those for special purpose) has
+one MFP logic associated, and is controlled by one MFP register (MFPR).
+
+The MFPR has the following bit definitions (for PXA300/PXA310/PXA320):
+
+ 31                        16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
+  +-------------------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+  |         RESERVED        |PS|PU|PD|  DRIVE |SS|SD|SO|EC|EF|ER|--| AF_SEL |
+  +-------------------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+
+  Bit 3:   RESERVED
+  Bit 4:   EDGE_RISE_EN - enable detection of rising edge on this pin
+  Bit 5:   EDGE_FALL_EN - enable detection of falling edge on this pin
+  Bit 6:   EDGE_CLEAR   - disable edge detection on this pin
+  Bit 7:   SLEEP_OE_N   - enable outputs during low power modes
+  Bit 8:   SLEEP_DATA   - output data on the pin during low power modes
+  Bit 9:   SLEEP_SEL    - selection control for low power modes signals
+  Bit 13:  PULLDOWN_EN  - enable the internal pull-down resistor on this pin
+  Bit 14:  PULLUP_EN    - enable the internal pull-up resistor on this pin
+  Bit 15:  PULL_SEL     - pull state controlled by selected alternate function
+                          (0) or by PULL{UP,DOWN}_EN bits (1)
+
+  Bit 0 - 2: AF_SEL - alternate function selection, 8 possibilities, from 0-7
+  Bit 10-12: DRIVE  - drive strength and slew rate
+                        0b000 - fast 1mA
+                        0b001 - fast 2mA
+                        0b002 - fast 3mA
+                        0b003 - fast 4mA
+                        0b004 - slow 6mA
+                        0b005 - fast 6mA
+                        0b006 - slow 10mA
+                        0b007 - fast 10mA
+
+ MFP Design for PXA2xx/PXA3xx
+==============================
+
+Due to the difference of pin-mux handling between PXA2xx and PXA3xx, a unified
+MFP API is introduced to cover both series of processors.
+
+The basic idea of this design is to introduce definitions for all possible pin
+configurations, these definitions are processor and platform independent, and
+the actual API invoked to convert these definitions into register settings and
+make them effective there-after.
+
+  Files Involved
+  --------------
+
+  - arch/arm/mach-pxa/include/mach/mfp.h
+  
+  for
+    1. Unified pin definitions - enum constants for all configurable pins
+    2. processor-neutral bit definitions for a possible MFP configuration
+
+  - arch/arm/mach-pxa/include/mach/mfp-pxa3xx.h
+
+  for PXA3xx specific MFPR register bit definitions and PXA3xx common pin
+  configurations
+
+  - arch/arm/mach-pxa/include/mach/mfp-pxa2xx.h
+
+  for PXA2xx specific definitions and PXA25x/PXA27x common pin configurations
+
+  - arch/arm/mach-pxa/include/mach/mfp-pxa25x.h
+    arch/arm/mach-pxa/include/mach/mfp-pxa27x.h
+    arch/arm/mach-pxa/include/mach/mfp-pxa300.h
+    arch/arm/mach-pxa/include/mach/mfp-pxa320.h
+    arch/arm/mach-pxa/include/mach/mfp-pxa930.h
+
+  for processor specific definitions
+
+  - arch/arm/mach-pxa/mfp-pxa3xx.c
+  - arch/arm/mach-pxa/mfp-pxa2xx.c
+
+  for implementation of the pin configuration to take effect for the actual
+  processor.
+
+  Pin Configuration
+  -----------------
+
+  The following comments are copied from mfp.h (see the actual source code
+  for most updated info)
+  
+  /*
+   * a possible MFP configuration is represented by a 32-bit integer
+   *
+   * bit  0.. 9 - MFP Pin Number (1024 Pins Maximum)
+   * bit 10..12 - Alternate Function Selection
+   * bit 13..15 - Drive Strength
+   * bit 16..18 - Low Power Mode State
+   * bit 19..20 - Low Power Mode Edge Detection
+   * bit 21..22 - Run Mode Pull State
+   *
+   * to facilitate the definition, the following macros are provided
+   *
+   * MFP_CFG_DEFAULT - default MFP configuration value, with
+   *              alternate function = 0,
+   *              drive strength = fast 3mA (MFP_DS03X)
+   *              low power mode = default
+   *              edge detection = none
+   *
+   * MFP_CFG    - default MFPR value with alternate function
+   * MFP_CFG_DRV        - default MFPR value with alternate function and
+   *              pin drive strength
+   * MFP_CFG_LPM        - default MFPR value with alternate function and
+   *              low power mode
+   * MFP_CFG_X  - default MFPR value with alternate function,
+   *              pin drive strength and low power mode
+   */
+
+   Examples of pin configurations are:
+
+   #define GPIO94_SSP3_RXD              MFP_CFG_X(GPIO94, AF1, DS08X, FLOAT)
+
+   which reads GPIO94 can be configured as SSP3_RXD, with alternate function
+   selection of 1, driving strength of 0b101, and a float state in low power
+   modes.
+
+   NOTE: this is the default setting of this pin being configured as SSP3_RXD
+   which can be modified a bit in board code, though it is not recommended to
+   do so, simply because this default setting is usually carefully encoded,
+   and is supposed to work in most cases.
+
+  Register Settings
+  -----------------
+
+   Register settings on PXA3xx for a pin configuration is actually very
+   straight-forward, most bits can be converted directly into MFPR value
+   in a easier way. Two sets of MFPR values are calculated: the run-time
+   ones and the low power mode ones, to allow different settings.
+
+   The conversion from a generic pin configuration to the actual register
+   settings on PXA2xx is a bit complicated: many registers are involved,
+   including GAFRx, GPDRx, PGSRx, PWER, PKWR, PFER and PRER. Please see
+   mfp-pxa2xx.c for how the conversion is made.
diff --git a/Documentation/fb/pxafb.txt b/Documentation/fb/pxafb.txt
index db9b8500b43b..d143a0a749f9 100644
--- a/Documentation/fb/pxafb.txt
+++ b/Documentation/fb/pxafb.txt
@@ -5,9 +5,13 @@ The driver supports the following options, either via
 options=<OPTIONS> when modular or video=pxafb:<OPTIONS> when built in.
 
 For example:
-        modprobe pxafb options=mode:640x480-8,passive
+        modprobe pxafb options=vmem:2M,mode:640x480-8,passive
 or on the kernel command line
-        video=pxafb:mode:640x480-8,passive
+        video=pxafb:vmem:2M,mode:640x480-8,passive
+
+vmem: VIDEO_MEM_SIZE
+        Amount of video memory to allocate (can be suffixed with K or M
+        for kilobytes or megabytes)
 
 mode:XRESxYRES[-BPP]
         XRES == LCCR1_PPL + 1
@@ -52,3 +56,87 @@ outputen:POLARITY
 pixclockpol:POLARITY
         pixel clock polarity
         0 => falling edge, 1 => rising edge
+
+
+Overlay Support for PXA27x and later LCD controllers
+====================================================
+
+  PXA27x and later processors support overlay1 and overlay2 on-top of the
+  base framebuffer (although under-neath the base is also possible). They
+  support palette and no-palette RGB formats, as well as YUV formats (only
+  available on overlay2). These overlays have dedicated DMA channels and
+  behave in a similar way as a framebuffer.
+
+  However, there are some differences between these overlay framebuffers
+  and normal framebuffers, as listed below:
+
+  1. overlay can start at a 32-bit word aligned position within the base
+     framebuffer, which means they have a start (x, y). This information
+     is encoded into var->nonstd (no, var->xoffset and var->yoffset are
+     not for such purpose).
+
+  2. overlay framebuffer is allocated dynamically according to specified
+     'struct fb_var_screeninfo', the amount is decided by:
+
+        var->xres_virtual * var->yres_virtual * bpp
+
+     bpp = 16 -- for RGB565 or RGBT555
+         = 24 -- for YUV444 packed
+         = 24 -- for YUV444 planar
+         = 16 -- for YUV422 planar (1 pixel = 1 Y + 1/2 Cb + 1/2 Cr)
+         = 12 -- for YUV420 planar (1 pixel = 1 Y + 1/4 Cb + 1/4 Cr)
+
+     NOTE:
+
+     a. overlay does not support panning in x-direction, thus
+        var->xres_virtual will always be equal to var->xres
+
+     b. line length of overlay(s) must be on a 32-bit word boundary,
+        for YUV planar modes, it is a requirement for the component
+        with minimum bits per pixel,  e.g. for YUV420, Cr component
+        for one pixel is actually 2-bits, it means the line length
+        should be a multiple of 16-pixels
+
+     c. starting horizontal position (XPOS) should start on a 32-bit
+        word boundary, otherwise the fb_check_var() will just fail.
+
+     d. the rectangle of the overlay should be within the base plane,
+        otherwise fail
+
+     Applications should follow the sequence below to operate an overlay
+     framebuffer:
+
+         a. open("/dev/fb[1-2]", ...)
+         b. ioctl(fd, FBIOGET_VSCREENINFO, ...)
+         c. modify 'var' with desired parameters:
+            1) var->xres and var->yres
+            2) larger var->yres_virtual if more memory is required,
+               usually for double-buffering
+            3) var->nonstd for starting (x, y) and color format
+            4) var->{red, green, blue, transp} if RGB mode is to be used
+         d. ioctl(fd, FBIOPUT_VSCREENINFO, ...)
+         e. ioctl(fd, FBIOGET_FSCREENINFO, ...)
+         f. mmap
+         g. ...
+
+  3. for YUV planar formats, these are actually not supported within the
+     framebuffer framework, application has to take care of the offsets
+     and lengths of each component within the framebuffer.
+
+  4. var->nonstd is used to pass starting (x, y) position and color format,
+     the detailed bit fields are shown below:
+
+    31                23  20         10          0
+     +-----------------+---+----------+----------+
+     |  ... unused ... |FOR|   XPOS   |   YPOS   |
+     +-----------------+---+----------+----------+
+
+     FOR  - color format, as defined by OVERLAY_FORMAT_* in pxafb.h
+            0 - RGB
+            1 - YUV444 PACKED
+            2 - YUV444 PLANAR
+            3 - YUV422 PLANAR
+            4 - YUR420 PLANAR
+
+     XPOS - starting horizontal position
+     YPOS - starting vertical position