5. DW100 dewarp driver

The Vivante DW100 Dewarp Processor IP core found on i.MX8MP SoC applies a programmable geometrical transformation on the input image to correct distortion introduced by lenses.

The transformation function is exposed by the hardware as a grid map with 16x16 pixel macroblocks indexed using X, Y vertex coordinates.

                       Image width
        <--------------------------------------->

   ^    .-------.-------.-------.-------.-------.
   |    | 16x16 |       |       |       |       |
I  |    | pixel |       |       |       |       |
m  |    | block |       |       |       |       |
a  |    .-------.-------.-------.-------.-------.
g  |    |       |       |       |       |       |
e  |    |       |       |       |       |       |
   |    |       |       |       |       |       |
h  |    .-------.-------.-------.-------.-------.
e  |    |       |       |       |       |       |
i  |    |       |       |       |       |       |
g  |    |       |       |       |       |       |
h  |    .-------.-------.-------.-------.-------.
t  |    |       |       |       |       |       |
   |    |       |       |       |       |       |
   |    |       |       |       |       |       |
   v    '-------'-------'-------'-------'-------'

         Grid of Image Blocks for Dewarping Map

Each x, y coordinate register uses 16 bits to record the coordinate address in an unsigned 12.4 fixed point format (UQ12.4).

.----------------------.--------..----------------------.--------.
|         31~20        | 19~16  ||         15~4         |  3~0   |
|       (integer)      | (frac) ||       (integer)      | (frac) |
'----------------------'--------''----------------------'--------'
<-------------------------------><------------------------------->
            Y coordinate                     X coordinate

                       Remap Register Layout

The dewarping map is set from applications using the V4L2_CID_DW100_DEWARPING_16x16_VERTEX_MAP control. The control contains an array of u32 values storing (x, y) destination coordinates for each vertex of the grid. The x coordinate is stored in the 16 LSBs and the y coordinate in the 16 MSBs.

The number of elements in the array must match the image size:

elems = (DIV_ROUND_UP(width, 16) + 1) * (DIV_ROUND_UP(height, 16) + 1);

If the control has not been set by the application, the driver uses an identity map.

More details on the DW100 hardware operations can be found in chapter 13.15 DeWarp of IMX8MP reference manual.

The Vivante DW100 m2m driver implements the following driver-specific control:

V4L2_CID_DW100_DEWARPING_16x16_VERTEX_MAP (__u32 array)

Specifies to DW100 driver its dewarping map (aka LUT) blob as described in chapter 13.15.2.3 Dewarping Remap of IMX8MP reference manual as an U32 dynamic array. The image is divided into many small 16x16 blocks. If the width/height of the image is not divisible by 16, the size of the rightmost/bottommost block is the remainder. The dewarping map only saves the vertex coordinates of the block. The dewarping grid map is comprised of vertex coordinates for x and y. Each x, y coordinate register uses 16 bits (UQ12.4) to record the coordinate address, with the Y coordinate in the upper bits and X in the lower bits. The driver modifies the dimensions of this control when the sink format is changed, to reflect the new input resolution.