linux-kernel - Re: [PATCH v9 06/10] math.h: Add macros for rounding to closest value

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <86f9ed66-c58e-0b2d-dd2b-4372ff26a3c3@ti.com>
Date: Tue, 28 May 2024 16:02:30 +0530
From: Devarsh Thakkar <devarsht@...com>
To: Andy Shevchenko <andriy.shevchenko@...ux.intel.com>
CC: <mchehab@...nel.org>, <hverkuil-cisco@...all.nl>,
        <linux-media@...r.kernel.org>, <linux-kernel@...r.kernel.org>,
        <benjamin.gaignard@...labora.com>, <sebastian.fricke@...labora.com>,
        <akpm@...ux-foundation.org>, <gregkh@...uxfoundation.org>,
        <adobriyan@...il.com>, <jani.nikula@...el.com>,
        <p.zabel@...gutronix.de>, <airlied@...il.com>, <daniel@...ll.ch>,
        <dri-devel@...ts.freedesktop.org>, <laurent.pinchart@...asonboard.com>,
        <praneeth@...com>, <nm@...com>, <vigneshr@...com>, <a-bhatia1@...com>,
        <j-luthra@...com>, <b-brnich@...com>, <detheridge@...com>,
        <p-mantena@...com>, <vijayp@...com>, <andrzej.p@...labora.com>,
        <nicolas@...fresne.ca>, <davidgow@...gle.com>, <dlatypov@...gle.com>
Subject: Re: [PATCH v9 06/10] math.h: Add macros for rounding to closest value

Hi Andy,

Thanks for the review.

On 28/05/24 02:02, Andy Shevchenko wrote:
> On Sun, May 26, 2024 at 11:38:56PM +0530, Devarsh Thakkar wrote:
..

>> +/**
>> + * round_closest_up - round closest to be multiple of specified value (which is
>> + *                    power of 2) with preference to rounding up
>> +
> 
> Not that big deal, but missing '*' here. Personally I would not even put
> a blank line between Summary and Field Descriptions.
> 

My bad. Yes I would remove the blank line here. This is picked up as warning
from kernel-doc too.

>> + * @x: the value to round
>> + * @y: multiple to round closest to (must be a power of 2)
>> + *
>> + * Rounds @x to closest multiple of @y (which must be a power of 2).
>> + * The value can be either rounded up or rounded down depending upon rounded
>> + * value's closeness to the specified value. If there are two closest possible
>> + * values, i.e. the difference between the specified value and it's rounded up
>> + * and rounded down values is same then preference is given to rounded up
>> + * value.
>> + *
>> + * To perform arbitrary rounding to closest value (not multiple of 2), use
>> + * roundclosest().
>> + *
>> + * Examples :
> 
> What is this suppose to be rendered to?
> 

The file math.h is not rendered as part of kernel-doc right now. I can put
this under Documentation/core-api/kernel-api.rst perhaps I can create a new
section as below:

Rounding, absolute diff and 32bit division macros
-------------------------------------------------

under the section:
CRC and Math Functions in Linux

===============================

is that okay ?

>> + * round_closest_up(17, 4) = 16
>> + * round_closest_up(15, 4) = 16
>> + * round_closest_up(14, 4) = 16
> 
> Btw, is kernel-doc validator happy about all kernel docs you added?
> 

Yes, except the aforementioned blank line.

Regards
Devarsh