Re: [PATCH v11 15/66] media: uapi: Add generic CSI-2 raw pixelformats

[Sakari Ailus <sakari.ailus@linux.intel.com>]

Hi Jacopo,

On Mon, Sep 01, 2025 at 03:25:01PM +0200, Jacopo Mondi wrote:
> Hi Sakari
> 
> On Mon, Aug 25, 2025 at 12:50:16PM +0300, Sakari Ailus wrote:
> > Add generic raw pixelformats for bit depths 8, 10, 12 and 14. These
> > formats are CSI-2 packed, apart from the 8-bit format.
> >
> > Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> > ---
> >  .../media/v4l/pixfmt-raw-generic.rst          | 175 ++++++++++++++++++
> >  .../userspace-api/media/v4l/pixfmt.rst        |   1 +
> >  drivers/media/v4l2-core/v4l2-ioctl.c          |   4 +
> >  include/uapi/linux/videodev2.h                |   6 +
> >  4 files changed, 186 insertions(+)
> >  create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-raw-generic.rst
> >
> > diff --git a/Documentation/userspace-api/media/v4l/pixfmt-raw-generic.rst b/Documentation/userspace-api/media/v4l/pixfmt-raw-generic.rst
> > new file mode 100644
> > index 000000000000..9fda7a36cd3a
> > --- /dev/null
> > +++ b/Documentation/userspace-api/media/v4l/pixfmt-raw-generic.rst
> > @@ -0,0 +1,175 @@
> > +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
> > +
> > +************************************************************************************************************************************************************************************************************************************************************************************
> > +V4L2_PIX_FMT_RAW_8 ('RAW8'), V4L2_PIX_FMT_RAW_CSI2_10 ('RACA'), V4L2_PIX_FMT_RAW_CSI2_12 ('RACC'), V4L2_PIX_FMT_RAW_CSI2_14 ('RACE'), V4L2_PIX_FMT_RAW_16 ('RAWG'), V4L2_PIX_FMT_RAW_CSI2_20 ('RACK'), V4L2_PIX_FMT_RAW_24 ('RAWO'), V4L2_PIX_FMT_RAW_CSI2_28 ('RACS')
> > +************************************************************************************************************************************************************************************************************************************************************************************
> 
> I see in your branch
> "media: uapi: Add generic CSI-2 raw pixelformats for 16, 20, 24 and 28 bpp"
> 
> Which adds pixel formats for the additional formats not documented in
> this patch but mentioned here above in the header.
> 
> Should you squash it with this patch ?

The reason these are being postponed is that we haven't yet seen devices
using them. The systems these are used in tend to be little endian while
the format documentation suggests big endian byte order. That'd be
inconvenient. So we'd like to see what do they actually use.

I'll move the extra ones to the other patch.

> 
> > +
> > +
> > +Generic line-based image data formats
> 
> Does "line-based" applies to image formats as well or to metadata only ?

These, too.

> 
> > +
> > +
> > +Description
> > +===========
> > +
> > +These generic raw image data formats define the memory layout of the data
> > +without defining the order of the pixels in the format or even the CFA (Colour
> 
> What about s/in the format// ?

Yes.

> 
> > +Filter Array) itself. See also :ref:`source routes <subdev-routing>`.
> 
> I might have missed why the reference to the routing documentation.

I think this bit can be removed now.

> 
> > +
> > +.. _v4l2-pix-fmt-raw-8:
> > +
> > +V4L2_PIX_FMT_RAW_8
> > +------------------
> > +
> > +The V4L2_PIX_FMT_GENERIC_8 format is a plain 8-bit raw pixel data format. This
> > +format is used on CSI-2 for 8 bits per :term:`Data Unit`.
> > +
> > +**Byte Order Of V4L2_PIX_FMT_RAW_8.**
> > +Each cell is one byte. "P" denotes a pixel.
> > +
> > +.. tabularcolumns:: |p{2.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|
> > +
> > +.. flat-table:: Sample 4x2 Image Frame
> > +    :header-rows:  0
> > +    :stub-columns: 0
> > +    :widths: 12 8 8 8 8
> > +
> > +    * - start + 0:
> > +      - P\ :sub:`00`
> > +      - P\ :sub:`10`
> > +      - P\ :sub:`20`
> > +      - P\ :sub:`30`
> > +    * - start + 4:
> > +      - P\ :sub:`01`
> > +      - P\ :sub:`11`
> > +      - P\ :sub:`21`
> > +      - P\ :sub:`31`
> > +
> > +.. _v4l2-pix-fmt-raw-csi2-10:
> > +
> > +V4L2_PIX_FMT_RAW_CSI2_10
> > +------------------------
> > +
> > +V4L2_PIX_FMT_RAW_CSI2_10 contains 10-bit packed image data, with four bytes
> > +containing the top 8 bits of the pixels followed by lowest 2 bits of the pixels
> > +packed into one byte. This format is typically used by CSI-2 receivers with
> > +a source that transmits MEDIA_BUS_FMT_RAW_10 and the CSI-2 receiver writes the
> > +received data to memory as-is.
> > +
> > +The packing of the data follows the MIPI CSI-2 specification.
> > +
> > +**Byte Order Of V4L2_PIX_FMT_RAW_CSI2_10.**
> > +Each cell is one byte. "P" denotes a pixel.
> > +
> > +.. tabularcolumns:: |p{2.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{1.8cm}|
> > +
> > +.. flat-table:: Sample 4x2 Image Frame
> > +    :header-rows:  0
> > +    :stub-columns: 0
> > +    :widths: 12 8 8 8 8 8
> > +
> > +    * - start + 0:
> > +      - P\ :sub:`00 bits 9--2`
> > +      - P\ :sub:`10 bits 9--2`
> > +      - P\ :sub:`20 bits 9--2`
> > +      - P\ :sub:`30 bits 9--2`
> > +      - P\ :sub:`00 bits 1--0` (bits 1--0)
> > +        P\ :sub:`10 bits 1--0` (bits 3--2)
> > +        P\ :sub:`20 bits 1--0` (bits 5--4)
> > +        P\ :sub:`30 bits 1--0` (bits 7--6)
> > +    * - start + 5:
> > +      - P\ :sub:`01 bits 9--2`
> > +      - P\ :sub:`11 bits 9--2`
> > +      - P\ :sub:`21 bits 9--2`
> > +      - P\ :sub:`31 bits 9--2`
> > +      - P\ :sub:`01 bits 1--0` (bits 1--0)
> > +        P\ :sub:`11 bits 1--0` (bits 3--2)
> > +        P\ :sub:`21 bits 1--0` (bits 5--4)
> > +        P\ :sub:`31 bits 1--0` (bits 7--6)
> > +
> > +.. _v4l2-pix-fmt-raw-csi2-12:
> > +
> > +V4L2_PIX_FMT_RAW_CSI2_12
> > +------------------------
> > +
> > +V4L2_PIX_FMT_RAW_CSI2_12 contains 12-bit packed image data, with two bytes
> > +containing the top 8 bits of the pixels followed by lowest 4 bits of the pixels
> > +packed into 1 byte. This format is typically used by CSI-2 receivers with
> > +a source that transmits MEDIA_BUS_FMT_RAW_12 and the CSI-2 receiver writes the
> > +received data to memory as-is.
> > +
> > +The packing of the data follows the MIPI CSI-2 specification.
> > +
> > +**Byte Order Of V4L2_PIX_FMT_RAW_CSI2_12.**
> > +Each cell is one byte. "P" denotes a pixel.
> > +
> > +.. tabularcolumns:: |p{2.4cm}|p{1.2cm}|p{1.2cm}|p{1.8cm}|p{1.2cm}|p{1.2cm}|p{1.8cm}|
> > +
> > +.. flat-table:: Sample 4x2 Image Frame
> > +    :header-rows:  0
> > +    :stub-columns: 0
> > +    :widths: 12 8 8 8 8 8 8
> > +
> > +    * - start + 0:
> > +      - P\ :sub:`00 bits 11--4`
> > +      - P\ :sub:`10 bits 11--4`
> > +      - P\ :sub:`00 bits 3--0` (bits 3--0)
> > +        P\ :sub:`10 bits 3--0` (bits 7--4)
> > +      - P\ :sub:`20 bits 11--4`
> > +      - P\ :sub:`30 bits 11--4`
> > +      - P\ :sub:`20 bits 3--0` (bits 3--0)
> > +        P\ :sub:`30 bits 3--0` (bits 7--4)
> > +    * - start + 6:
> > +      - P\ :sub:`01 bits 11--4`
> > +      - P\ :sub:`11 bits 11--4`
> > +      - P\ :sub:`01 bits 3--0` (bits 3--0)
> > +        P\ :sub:`11 bits 3--0` (bits 7--4)
> > +      - P\ :sub:`21 bits 11--4`
> > +      - P\ :sub:`31 bits 11--4`
> > +      - P\ :sub:`21 bits 3--0` (bits 3--0)
> > +        P\ :sub:`31 bits 3--0` (bits 7--4)
> > +
> > +.. _v4l2-pix-fmt-raw-csi2-14:
> > +
> > +V4L2_PIX_FMT_RAW_CSI2_14
> > +------------------------
> > +
> > +V4L2_PIX_FMT_RAW_CSI2_14 contains 14-bit packed image data, with four bytes
> > +containing the top 8 bits of the pixels followed by lowest 6 bits of the pixels
> > +packed into three bytes. This format is typically used by CSI-2 receivers with a
> > +source that transmits MEDIA_BUS_FMT_RAW_14 and the CSI-2 receiver writes the
> > +received data to memory as-is.
> > +
> > +The packing of the data follows the MIPI CSI-2 specification.
> > +
> > +**Byte Order Of V4L2_PIX_FMT_RAW_CSI2_14.**
> > +Each cell is one byte. "P" denotes a pixel.
> > +
> > +.. tabularcolumns:: |p{2.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{1.8cm}|p{1.8cm}|p{1.8cm}|
> > +
> > +.. flat-table:: Sample 4x2 Image Frame
> > +    :header-rows:  0
> > +    :stub-columns: 0
> > +    :widths: 12 8 8 8 8 8 8 8
> > +
> > +    * - start + 0:
> > +      - P\ :sub:`00 bits 13--6`
> > +      - P\ :sub:`10 bits 13--6`
> > +      - P\ :sub:`20 bits 13--6`
> > +      - P\ :sub:`30 bits 13--6`
> > +      - P\ :sub:`10 bits 1--0` (bits 7--6)
> > +        P\ :sub:`00 bits 5--0` (bits 5--0)
> > +      - P\ :sub:`20 bits 3--0` (bits 7--4)
> > +        P\ :sub:`10 bits 5--2` (bits 3--0)
> > +      - P\ :sub:`30 bits 5--0` (bits 7--2)
> > +        P\ :sub:`20 bits 5--4` (bits 1--0)
> > +    * - start + 7:
> > +      - P\ :sub:`01 bits 13--6`
> > +      - P\ :sub:`11 bits 13--6`
> > +      - P\ :sub:`21 bits 13--6`
> > +      - P\ :sub:`31 bits 13--6`
> > +      - P\ :sub:`11 bits 1--0` (bits 7--6)
> > +        P\ :sub:`01 bits 5--0` (bits 5--0)
> > +      - P\ :sub:`21 bits 3--0` (bits 7--4)
> > +        P\ :sub:`11 bits 5--2` (bits 3--0)
> > +      - P\ :sub:`31 bits 5--0` (bits 7--2)
> > +        P\ :sub:`21 bits 5--4` (bits 1--0)
> > diff --git a/Documentation/userspace-api/media/v4l/pixfmt.rst b/Documentation/userspace-api/media/v4l/pixfmt.rst
> > index 11dab4a90630..d917190c717d 100644
> > --- a/Documentation/userspace-api/media/v4l/pixfmt.rst
> > +++ b/Documentation/userspace-api/media/v4l/pixfmt.rst
> > @@ -25,6 +25,7 @@ see also :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`.)
> >      pixfmt-indexed
> >      pixfmt-rgb
> >      pixfmt-bayer
> > +    pixfmt-raw-generic
> >      yuv-formats
> >      hsv-formats
> >      depth-formats
> > diff --git a/drivers/media/v4l2-core/v4l2-ioctl.c b/drivers/media/v4l2-core/v4l2-ioctl.c
> > index 01cf52c3ea33..e538c1230631 100644
> > --- a/drivers/media/v4l2-core/v4l2-ioctl.c
> > +++ b/drivers/media/v4l2-core/v4l2-ioctl.c
> > @@ -1434,6 +1434,10 @@ static void v4l_fill_fmtdesc(struct v4l2_fmtdesc *fmt)
> >  	case V4L2_PIX_FMT_SGBRG16:	descr = "16-bit Bayer GBGB/RGRG"; break;
> >  	case V4L2_PIX_FMT_SGRBG16:	descr = "16-bit Bayer GRGR/BGBG"; break;
> >  	case V4L2_PIX_FMT_SRGGB16:	descr = "16-bit Bayer RGRG/GBGB"; break;
> > +	case V4L2_PIX_FMT_RAW_8:	descr = "8-bit Raw"; break;
> > +	case V4L2_PIX_FMT_RAW_CSI2_10:	descr = "10-bit Raw, CSI-2 Packed"; break;
> > +	case V4L2_PIX_FMT_RAW_CSI2_12:	descr = "12-bit Raw, CSI-2 Packed"; break;
> > +	case V4L2_PIX_FMT_RAW_CSI2_14:	descr = "14-bit Raw, CSI-2 Packed"; break;
> >  	case V4L2_PIX_FMT_RAW_CRU20:	descr = "14-bit Raw CRU Packed"; break;
> >  	case V4L2_PIX_FMT_SN9C20X_I420:	descr = "GSPCA SN9C20X I420"; break;
> >  	case V4L2_PIX_FMT_SPCA501:	descr = "GSPCA SPCA501"; break;
> > diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> > index 3dd9fa45dde1..c4c4f3eb67e1 100644
> > --- a/include/uapi/linux/videodev2.h
> > +++ b/include/uapi/linux/videodev2.h
> > @@ -745,6 +745,12 @@ struct v4l2_pix_format {
> >  #define V4L2_PIX_FMT_SGRBG16 v4l2_fourcc('G', 'R', '1', '6') /* 16  GRGR.. BGBG.. */
> >  #define V4L2_PIX_FMT_SRGGB16 v4l2_fourcc('R', 'G', '1', '6') /* 16  RGRG.. GBGB.. */
> >
> > +/* Generic CSI-2 packed raw pixel formats */
> > +#define V4L2_PIX_FMT_RAW_8 v4l2_fourcc('R', 'A', 'W', '8')
> > +#define V4L2_PIX_FMT_RAW_CSI2_10 v4l2_fourcc('R', 'A', 'C', 'A')
> > +#define V4L2_PIX_FMT_RAW_CSI2_12 v4l2_fourcc('R', 'A', 'C', 'C')
> > +#define V4L2_PIX_FMT_RAW_CSI2_14 v4l2_fourcc('R', 'A', 'C', 'E')
> > +
> With
> "media: uapi: Add generic CSI-2 raw pixelformats for 16, 20, 24 and 28 bpp"
> 
> and the above minors clarified
> Reviewed-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>

Thank you!

> 
> >  /* HSV formats */
> >  #define V4L2_PIX_FMT_HSV24 v4l2_fourcc('H', 'S', 'V', '3')
> >  #define V4L2_PIX_FMT_HSV32 v4l2_fourcc('H', 'S', 'V', '4')
> > --
> > 2.47.2
> >
> >

-- 
Sakari Ailus