dt-bindings: display: xlnx: mixer: Inconsistent pixel format terminology in dt docs

dt-bindings: display: xlnx: mixer: Inconsistent pixel format terminology in dt docs

[Kenneth Sloat]

Hello,

The Xilinx Video mixer IP uses the DRM fourcc string as a device tree binding in order to describe the format for a specific DRM layer/plane. Currently, in the device tree doc in "Documentation/devicetree/bindings/dma/xilinx/xilinx_frmbuf.txt" there is a list called "VIDEO FORMATS" with a table containing "Mixer IP Format" and associated "Driver supported Format String" (fourcc). In general, this table is not helpful, because "Mixer IP Format" does not match the Xilinx IP datasheet terminology for formats but rather some other commonly used nomenclature. This is also inconsistent from other Xilinx dts binding docs which specify the actual correct IP name and at times list other format nomenclature where helpful (i.e. xilinx_frmbuf.txt)

My suggestion is to remove the current "Mixer IP Format" strings in the doc and replace them with the actual IP names in the datasheet (which also match those used in Xilinx's Vivado FPGA tool). Otherwise, the programmer must cross reference other dts documentation or the code in order to figure these out. I am happy to provide a patch for this but wanted to throw out the suggestion first.

Thanks

Sincerely,
Ken Sloat

RE: dt-bindings: display: xlnx: mixer: Inconsistent pixel format terminology in dt docs

[Hyun Kwon]

Hi Kenneth,

> -----Original Message-----
> From: Kenneth Sloat <ksloat@designlinxhs.com>
> Sent: Thursday, August 20, 2020 2:18 PM
> To: Hyun Kwon <hyunk@xilinx.com>; linux-arm-kernel@lists.infradead.org
> Cc: Michal Simek <michals@xilinx.com>; dri-devel@lists.freedesktop.org; linux-
> kernel@vger.kernel.org; laurent.pinchart@ideasonboard.com;
> devicetree@vger.kernel.org; linux-kernel@vger.kernel.org;
> mark.rutland@arm.com
> Subject: dt-bindings: display: xlnx: mixer: Inconsistent pixel format terminology
> in dt docs
> 
> Hello,
> 
> The Xilinx Video mixer IP uses the DRM fourcc string as a device tree binding in
> order to describe the format for a specific DRM layer/plane. Currently, in the
> device tree doc in
> "Documentation/devicetree/bindings/dma/xilinx/xilinx_frmbuf.txt" there is a list
> called "VIDEO FORMATS" with a table containing "Mixer IP Format" and
> associated "Driver supported Format String" (fourcc). In general, this table is not
> helpful, because "Mixer IP Format" does not match the Xilinx IP datasheet
> terminology for formats but rather some other commonly used nomenclature.
> This is also inconsistent from other Xilinx dts binding docs which specify the
> actual correct IP name and at times list other format nomenclature where
> helpful (i.e. xilinx_frmbuf.txt)
> 
> My suggestion is to remove the current "Mixer IP Format" strings in the doc and
> replace them with the actual IP names in the datasheet (which also match those
> used in Xilinx's Vivado FPGA tool). Otherwise, the programmer must cross
> reference other dts documentation or the code in order to figure these out. I am
> happy to provide a patch for this but wanted to throw out the suggestion first.

I agree. The bindings should be in sync with datasheet and not rely on
software definitions. Since the driver is only in Xilinx vendor tree,
please send directly to git@xilinx.com.

Thanks!

-hyun

> 
> Thanks
> 
> Sincerely,
> Ken Sloat

Re: dt-bindings: display: xlnx: mixer: Inconsistent pixel format terminology in dt docs

[Laurent Pinchart]

Hello,

On Thu, Aug 20, 2020 at 04:38:18PM -0700, Hyun Kwon wrote:
> On Thursday, August 20, 2020 2:18 PM, Kenneth Sloat write:
> > Hello,
> > 
> > The Xilinx Video mixer IP uses the DRM fourcc string as a device tree binding in
> > order to describe the format for a specific DRM layer/plane. Currently, in the
> > device tree doc in
> > "Documentation/devicetree/bindings/dma/xilinx/xilinx_frmbuf.txt" there is a list
> > called "VIDEO FORMATS" with a table containing "Mixer IP Format" and
> > associated "Driver supported Format String" (fourcc). In general, this table is not
> > helpful, because "Mixer IP Format" does not match the Xilinx IP datasheet
> > terminology for formats but rather some other commonly used nomenclature.
> > This is also inconsistent from other Xilinx dts binding docs which specify the
> > actual correct IP name and at times list other format nomenclature where
> > helpful (i.e. xilinx_frmbuf.txt)
> > 
> > My suggestion is to remove the current "Mixer IP Format" strings in the doc and
> > replace them with the actual IP names in the datasheet (which also match those
> > used in Xilinx's Vivado FPGA tool). Otherwise, the programmer must cross
> > reference other dts documentation or the code in order to figure these out. I am
> > happy to provide a patch for this but wanted to throw out the suggestion first.

Are you talking about the "Video Format" column in table 2-8 of PG243 ?
Those values seem good to me.

Documentation/devicetree/bindings/media/xilinx/video.txt also defines a
xlnx,video-format property that uses the values from UG934 for the AXI
streaming interface.

> I agree. The bindings should be in sync with datasheet and not rely on
> software definitions. Since the driver is only in Xilinx vendor tree,
> please send directly to git@xilinx.com.

-- 
Regards,

Laurent Pinchart