Patchwork [v3] bitops.h: Add functions to extract and deposit bitfields

login
register
mail settings
Submitter Peter Maydell
Date June 28, 2012, 12:55 p.m.
Message ID <1340888154-31903-1-git-send-email-peter.maydell@linaro.org>
Download mbox | patch
Permalink /patch/167870/
State New
Headers show

Comments

Peter Maydell - June 28, 2012, 12:55 p.m.
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

NB: the deposit functions differ slightly from Avi's proposal:
 * instead of taking a pointer which we modify, we return the updated
   value. (This matches the semantics of the TCG deposit op and also
   seems to me generally nicer)
 * the implementation permits deposits of the entire word (ie length 32/64)

 bitops.h |   66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 66 insertions(+), 0 deletions(-)
Eric Blake - June 28, 2012, 1:32 p.m.
On 06/28/2012 06:55 AM, Peter Maydell 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.
> 
> Suggested-by: Jia Liu <proljc@gmail.com>
> Suggested-by: Avi Kivity <avi@redhat.com>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Eric Blake <eblake@redhat.com>
Peter Maydell - July 6, 2012, 9:01 a.m.
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
Andreas Färber - July 6, 2012, 1:41 p.m.
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
Peter Maydell - July 6, 2012, 2:01 p.m.
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
Andreas Färber - July 6, 2012, 2:17 p.m.
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

Patch

diff --git a/bitops.h b/bitops.h
index 07d1a06..5a44bb1 100644
--- a/bitops.h
+++ b/bitops.h
@@ -269,4 +269,70 @@  static inline unsigned long hweight_long(unsigned long w)
     return count;
 }
 
+/**
+ * extract32 - return a specified bit field from a uint32_t value
+ * @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
+ *
+ * Returns the value of the bit field extracted from the input value.
+ */
+static inline uint32_t extract32(uint32_t value, int start, int length)
+{
+    assert(start >= 0 && length > 0 && length <= 32 - start);
+    return (value >> start) & (~0U >> (32 - length));
+}
+
+/**
+ * extract64 - return a specified bit field from a uint64_t value
+ * @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
+ *
+ * Returns the value of the bit field extracted from the input value.
+ */
+static inline uint64_t extract64(uint64_t value, int start, int length)
+{
+    assert(start >= 0 && length > 0 && length <= 64 - start);
+    return (value >> start) & (~0ULL >> (64 - length));
+}
+
+/**
+ * deposit32 - Insert into a specified bit field in a uint32_t
+ * @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
+ *
+ * Returns the input value with the fieldval inserted
+ * into it at the specified location.
+ */
+static inline uint32_t deposit32(uint32_t value, int start, int length,
+                                 uint32_t fieldval)
+{
+    uint32_t mask;
+    assert(start >= 0 && length > 0 && length <= 32 - start);
+    mask = (~0U >> (32 - length)) << start;
+    return (value & ~mask) | ((fieldval << start) & mask);
+}
+
+/**
+ * deposit64 - Insert into a specified bit field in a uint64_t
+ * @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
+ *
+ * Returns the input value with the fieldval inserted
+ * into it at the specified location.
+ */
+static inline uint64_t deposit64(uint64_t value, int start, int length,
+                                 uint64_t fieldval)
+{
+    uint64_t mask;
+    assert(start >= 0 && length > 0 && length <= 64 - start);
+    mask = (~0ULL >> (64 - length)) << start;
+    return (value & ~mask) | ((fieldval << start) & mask);
+}
+
 #endif