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
