Re: [Qemu-devel] [PATCH v3] bitops.h: Add functions to extract and deposit bitfields

Re: [Qemu-devel] [PATCH v3] bitops.h: Add functions to extract and deposit bitfields

[Peter Maydell]

On 28 June 2012 13:55, Peter Maydell <peter.maydell@linaro.org> wrote:
> Add functions deposit32(), deposit64(), extract32() and extract64()
> to extract and deposit bitfields in 32 and 64 bit words. Based on
> ideas by Jia Liu and Avi Kivity.

NB: I'm planning to put this v3 into a target-arm pullreq at the end
of next week, since the LPAE patches depend on it, unless somebody
wishes to (a) object (b) commit it before then.

thanks
-- PMM

Re: [Qemu-devel] [PATCH v3] bitops.h: Add functions to extract and deposit bitfields

[Andreas Färber]

Am 28.06.2012 14:55, schrieb Peter Maydell:
> Add functions deposit32(), deposit64(), extract32() and extract64()
> to extract and deposit bitfields in 32 and 64 bit words. Based on
> ideas by Jia Liu and Avi Kivity.
> 
> Suggested-by: Jia Liu <proljc@gmail.com>
> Suggested-by: Avi Kivity <avi@redhat.com>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> Changes:
>  v1->v2: added missing brackets
>  v2->v3: renamed field32,field64 to extract32,extract64
>          added deposit32,deposit64 at Avi's suggestion
>          fixed assertion as per Jay Foad's suggestion
>          bikeshed roof is now a slightly darker shade of grey

Reviewed-by: Andreas Färber <afaerber@suse.de>

Small improvement would be to replace "Returns the" with "Returns: The"
in line with how you annotated the arguments, and the function summary
should go into its own paragraph between @foo: and Returns:.

http://developer.gnome.org/gtk-doc-manual/unstable/documenting_symbols.html.en

Andreas

-- 
SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer; HRB 16746 AG Nürnberg

Re: [Qemu-devel] [PATCH v3] bitops.h: Add functions to extract and deposit bitfields

[Peter Maydell]

On 6 July 2012 14:41, Andreas Färber <afaerber@suse.de> wrote:
> Small improvement would be to replace "Returns the" with "Returns: The"
> in line with how you annotated the arguments, and the function summary
> should go into its own paragraph between @foo: and Returns:.
>
> http://developer.gnome.org/gtk-doc-manual/unstable/documenting_symbols.html.en

Hmm. I was just following the existing practice in this file,
which consistently uses "Returns $whatever" without a colon.
memory.h uses "Returns $whatever" rather than "Returns: $whatever"
too. But I guess the doc you link to is the official statement
of the required syntax. How are these comments?

/**
 * extract32:
 * @value: the value to extract the bit field from
 * @start: the lowest bit in the bit field (numbered from 0)
 * @length: the length of the bit field
 *
 * Extract from the 32 bit input @value the bit field specified by the
 * @start and @length parameters, and return it. The bit field must
 * lie entirely within the 32 bit word. It is valid to request that
 * all 32 bits are returned (ie @length 32 and @start 0).
 *
 * Returns: the value of the bit field extracted from the input value.
 */

/**
 * extract64:
 * @value: the value to extract the bit field from
 * @start: the lowest bit in the bit field (numbered from 0)
 * @length: the length of the bit field
 *
 * Extract from the 64 bit input @value the bit field specified by the
 * @start and @length parameters, and return it. The bit field must
 * lie entirely within the 64 bit word. It is valid to request that
 * all 64 bits are returned (ie @length 64 and @start 0).
 *
 * Returns: the value of the bit field extracted from the input value.
 */

/**
 * deposit32:
 * @value: initial value to insert bit field into
 * @start: the lowest bit in the bit field (numbered from 0)
 * @length: the length of the bit field
 * @fieldval: the value to insert into the bit field
 *
 * Deposit @fieldval into the 32 bit @value at the bit field specified
 * by the @start and @length parameters, and return the modified
 * @value. Bits of @value outside the bit field are not modified.
 * Bits of @fieldval above the least significant @length bits are
 * ignored. The bit field must lie entirely within the 32 bit word.
 * It is valid to request that all 64 bits are modified (ie @length
 * 64 and @start 0).
 *
 * Returns: the modified @value.
 */

/**
 * deposit32:
 * @value: initial value to insert bit field into
 * @start: the lowest bit in the bit field (numbered from 0)
 * @length: the length of the bit field
 * @fieldval: the value to insert into the bit field
 *
 * Deposit @fieldval into the 64 bit @value at the bit field specified
 * by the @start and @length parameters, and return the modified
 * @value. Bits of @value outside the bit field are not modified.
 * Bits of @fieldval above the least significant @length bits are
 * ignored. The bit field must lie entirely within the 32 bit word.
 * It is valid to request that all 64 bits are modified (ie @length
 * 64 and @start 0).
 *
 * Returns: the modified @value.
 */

-- PMM

Re: [Qemu-devel] [PATCH v3] bitops.h: Add functions to extract and deposit bitfields

[Andreas Färber]

Am 06.07.2012 16:01, schrieb Peter Maydell:
> On 6 July 2012 14:41, Andreas Färber <afaerber@suse.de> wrote:
>> Small improvement would be to replace "Returns the" with "Returns: The"
>> in line with how you annotated the arguments, and the function summary
>> should go into its own paragraph between @foo: and Returns:.
>>
>> http://developer.gnome.org/gtk-doc-manual/unstable/documenting_symbols.html.en
> 
> Hmm. I was just following the existing practice in this file,
> which consistently uses "Returns $whatever" without a colon.
> memory.h uses "Returns $whatever" rather than "Returns: $whatever"
> too. But I guess the doc you link to is the official statement
> of the required syntax. How are these comments?

Looking fine. Didn't know about the "existing practice", I picked up
Anthony's object.h style and remembered adjusting that in qom-next.

Andreas

-- 
SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer; HRB 16746 AG Nürnberg