host-utils: Fix coding style and add comments

Add function comments to the routines, documenting the corner
cases upon which we are standardizing.  Fix the few instances
of non-standard coding style.

Signed-off-by: Richard Henderson <rth@twiddle.net>
Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Blue Swirl <blauwirbel@gmail.com>

include/qemu/host-utils.h

@@ -50,16 +50,19 @@ void muls64(uint64_t *phigh, uint64_t *plow, int64_t a, int64_t b);
 void mulu64(uint64_t *phigh, uint64_t *plow, uint64_t a, uint64_t b);
 #endif
 
-/* Binary search for leading zeros.  */
+/**
-
+ * clz32 - count leading zeros in a 32-bit value.
+ * @val: The value to search
+ *
+ * Returns 32 if the value is zero.  Note that the GCC builtin is
+ * undefined if the value is zero.
+ */
 static inline int clz32(uint32_t val)
 {
 #if QEMU_GNUC_PREREQ(3, 4)
-    if (val)
+    return val ? __builtin_clz(val) : 32;
-        return __builtin_clz(val);
-    else
-        return 32;
 #else
+    /* Binary search for the leading one bit.  */
     int cnt = 0;
 
     if (!(val & 0xFFFF0000U)) {
@@ -89,18 +92,28 @@ static inline int clz32(uint32_t val)
 #endif
 }
 
+/**
+ * clo32 - count leading ones in a 32-bit value.
+ * @val: The value to search
+ *
+ * Returns 32 if the value is -1.
+ */
 static inline int clo32(uint32_t val)
 {
     return clz32(~val);
 }
 
+/**
+ * clz64 - count leading zeros in a 64-bit value.
+ * @val: The value to search
+ *
+ * Returns 64 if the value is zero.  Note that the GCC builtin is
+ * undefined if the value is zero.
+ */
 static inline int clz64(uint64_t val)
 {
 #if QEMU_GNUC_PREREQ(3, 4)
-    if (val)
+    return val ? __builtin_clzll(val) : 64;
-        return __builtin_clzll(val);
-    else
-        return 64;
 #else
     int cnt = 0;
 
@@ -114,19 +127,30 @@ static inline int clz64(uint64_t val)
 #endif
 }
 
+/**
+ * clo64 - count leading ones in a 64-bit value.
+ * @val: The value to search
+ *
+ * Returns 64 if the value is -1.
+ */
 static inline int clo64(uint64_t val)
 {
     return clz64(~val);
 }
 
+/**
+ * ctz32 - count trailing zeros in a 32-bit value.
+ * @val: The value to search
+ *
+ * Returns 32 if the value is zero.  Note that the GCC builtin is
+ * undefined if the value is zero.
+ */
 static inline int ctz32(uint32_t val)
 {
 #if QEMU_GNUC_PREREQ(3, 4)
-    if (val)
+    return val ? __builtin_ctz(val) : 32;
-        return __builtin_ctz(val);
-    else
-        return 32;
 #else
+    /* Binary search for the trailing one bit.  */
     int cnt;
 
     cnt = 0;
@@ -158,18 +182,28 @@ static inline int ctz32(uint32_t val)
 #endif
 }
 
+/**
+ * cto32 - count trailing ones in a 32-bit value.
+ * @val: The value to search
+ *
+ * Returns 32 if the value is -1.
+ */
 static inline int cto32(uint32_t val)
 {
     return ctz32(~val);
 }
 
+/**
+ * ctz64 - count trailing zeros in a 64-bit value.
+ * @val: The value to search
+ *
+ * Returns 64 if the value is zero.  Note that the GCC builtin is
+ * undefined if the value is zero.
+ */
 static inline int ctz64(uint64_t val)
 {
 #if QEMU_GNUC_PREREQ(3, 4)
-    if (val)
+    return val ? __builtin_ctzll(val) : 64;
-        return __builtin_ctzll(val);
-    else
-        return 64;
 #else
     int cnt;
 
@@ -183,30 +217,56 @@ static inline int ctz64(uint64_t val)
 #endif
 }
 
+/**
+ * ctz64 - count trailing ones in a 64-bit value.
+ * @val: The value to search
+ *
+ * Returns 64 if the value is -1.
+ */
 static inline int cto64(uint64_t val)
 {
     return ctz64(~val);
 }
 
+/**
+ * ctpop8 - count the population of one bits in an 8-bit value.
+ * @val: The value to search
+ */
 static inline int ctpop8(uint8_t val)
 {
+#if QEMU_GNUC_PREREQ(3, 4)
+    return __builtin_popcount(val);
+#else
     val = (val & 0x55) + ((val >> 1) & 0x55);
     val = (val & 0x33) + ((val >> 2) & 0x33);
     val = (val & 0x0f) + ((val >> 4) & 0x0f);
 
     return val;
+#endif
 }
 
+/**
+ * ctpop16 - count the population of one bits in a 16-bit value.
+ * @val: The value to search
+ */
 static inline int ctpop16(uint16_t val)
 {
+#if QEMU_GNUC_PREREQ(3, 4)
+    return __builtin_popcount(val);
+#else
     val = (val & 0x5555) + ((val >> 1) & 0x5555);
     val = (val & 0x3333) + ((val >> 2) & 0x3333);
     val = (val & 0x0f0f) + ((val >> 4) & 0x0f0f);
     val = (val & 0x00ff) + ((val >> 8) & 0x00ff);
 
     return val;
+#endif
 }
 
+/**
+ * ctpop32 - count the population of one bits in a 32-bit value.
+ * @val: The value to search
+ */
 static inline int ctpop32(uint32_t val)
 {
 #if QEMU_GNUC_PREREQ(3, 4)
@@ -222,6 +282,10 @@ static inline int ctpop32(uint32_t val)
 #endif
 }
 
+/**
+ * ctpop64 - count the population of one bits in a 64-bit value.
+ * @val: The value to search
+ */
 static inline int ctpop64(uint64_t val)
 {
 #if QEMU_GNUC_PREREQ(3, 4)