Re: [PATCH 2/8] media: v4l2-ioctl.h: convert debug into an enum of bits

[Laurent Pinchart <laurent.pinchart@ideasonboard.com>]

On Tuesday, 19 December 2017 16:02:02 EET Laurent Pinchart wrote:
> On Tuesday, 19 December 2017 13:39:27 EET Sakari Ailus wrote:
> > Hi Mauro,
> > 
> > On Mon, Dec 18, 2017 at 05:53:56PM -0200, Mauro Carvalho Chehab wrote:
> > > The V4L2_DEV_DEBUG_IOCTL macros actually define a bitmask,
> > > but without using Kernel's modern standards. Also,
> > > documentation looks akward.
> > > 
> > > So, convert them into an enum with valid bits, adding
> > > the correspoinding kernel-doc documentation for it.
> > 
> > The pattern of using bits for flags is a well established one and I
> > wouldn't deviate from that by requiring the use of the BIT() macro. There
> > are no benefits that I can see from here but the approach brings
> > additional
> > risks: misuse of the flags and mimicing the same risky pattern.
> > 
> > I'd also like to echo Laurent's concern that code is being changed in odd
> > ways and not for itself, but due to deficiencies in documentation tools.
> > 
> > I believe the tooling has to be improved to address this properly. That
> > only needs to done once, compared to changing all flag definitions to
> > enums.
> 
> That's my main concern too. We really must not sacrifice code readability or
> writing ease in order to work around limitations of the documentation
> system. For this reason I'm strongly opposed to patches 2 and 5 in this
> series.

And I forgot to mention patch 8/8. Let's drop those three and improve the 
documentation system instead.

> > Another point I want to make is that the uAPI definitions cannot be
> > changed: enums are thus an option in kAPI only.
> 
> And furthermore using enum types in the uAPI is a bad idea as the enum size
> is architecture-dependent. That's why we use integer types in structures
> used as ioctl arguments.
> 
> > Improved KernelDoc tools would thus also allow improving uAPI macro
> > documentation --- which is more important anyway.

-- 
Regards,

Laurent Pinchart