Documentation/userspace-api/media/drivers/dw100.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 DW100 dewarp driver
   4 ===================
   5
   6 The Vivante DW100 Dewarp Processor IP core found on i.MX8MP SoC applies a
   7 programmable geometrical transformation on the input image to correct distortion
   8 introduced by lenses.
   9
  10 The transformation function is exposed by the hardware as a grid map with 16x16
  11 pixel macroblocks indexed using X, Y vertex coordinates.
  12 ::
  13
  14                           Image width
  15            <--------------------------------------->
  16
  17       ^    .-------.-------.-------.-------.-------.
  18       |    | 16x16 |       |       |       |       |
  19    I  |    | pixel |       |       |       |       |
  20    m  |    | block |       |       |       |       |
  21    a  |    .-------.-------.-------.-------.-------.
  22    g  |    |       |       |       |       |       |
  23    e  |    |       |       |       |       |       |
  24       |    |       |       |       |       |       |
  25    h  |    .-------.-------.-------.-------.-------.
  26    e  |    |       |       |       |       |       |
  27    i  |    |       |       |       |       |       |
  28    g  |    |       |       |       |       |       |
  29    h  |    .-------.-------.-------.-------.-------.
  30    t  |    |       |       |       |       |       |
  31       |    |       |       |       |       |       |
  32       |    |       |       |       |       |       |
  33       v    '-------'-------'-------'-------'-------'
  34
  35             Grid of Image Blocks for Dewarping Map
  36
  37
  38 Each x, y coordinate register uses 16 bits to record the coordinate address in
  39 an unsigned 12.4 fixed point format (UQ12.4).
  40 ::
  41
  42     .----------------------.--------..----------------------.--------.
  43     |         31~20        | 19~16  ||         15~4         |  3~0   |
  44     |       (integer)      | (frac) ||       (integer)      | (frac) |
  45     '----------------------'--------''----------------------'--------'
  46     <-------------------------------><------------------------------->
  47                 Y coordinate                     X coordinate
  48
  49                            Remap Register Layout
  50
  51 The dewarping map is set from applications using the
  52 V4L2_CID_DW100_DEWARPING_16x16_VERTEX_MAP control. The control contains
  53 an array of u32 values storing (x, y) destination coordinates for each
  54 vertex of the grid. The x coordinate is stored in the 16 LSBs and the y
  55 coordinate in the 16 MSBs.
  56
  57 The number of elements in the array must match the image size:
  58
  59 .. code-block:: C
  60
  61     elems = (DIV_ROUND_UP(width, 16) + 1) * (DIV_ROUND_UP(height, 16) + 1);
  62
  63 If the control has not been set by the application, the driver uses an identity
  64 map.
  65
  66 More details on the DW100 hardware operations can be found in
  67 *chapter 13.15 DeWarp* of IMX8MP_ reference manual.
  68
  69 The Vivante DW100 m2m driver implements the following driver-specific control:
  70
  71 ``V4L2_CID_DW100_DEWARPING_16x16_VERTEX_MAP (__u32 array)``
  72     Specifies to DW100 driver its dewarping map (aka LUT) blob as described in
  73     *chapter 13.15.2.3 Dewarping Remap* of IMX8MP_ reference manual as an U32
  74     dynamic array. The image is divided into many small 16x16 blocks. If the
  75     width/height of the image is not divisible by 16, the size of the
  76     rightmost/bottommost block is the remainder. The dewarping map only saves
  77     the vertex coordinates of the block. The dewarping grid map is comprised of
  78     vertex coordinates for x and y. Each x, y coordinate register uses 16 bits
  79     (UQ12.4) to record the coordinate address, with the Y coordinate in the
  80     upper bits and X in the lower bits. The driver modifies the dimensions of
  81     this control when the sink format is changed, to reflect the new input
  82     resolution.
  83
  84 .. _IMX8MP: https://www.nxp.com/webapp/Download?colCode=IMX8MPRM