[v2,1/6] lib/eal: implement the family of rte bit operation APIs
Checks
Commit Message
There are a lot functions of bit operations scattered and
duplicated in PMDs, consolidating them into a common API
family is necessary. Furthermore, the bit operation is
mostly applied to the IO devices, so use __ATOMIC_ACQ_REL
to ensure the ordering.
Signed-off-by: Joyce Kong <joyce.kong@arm.com>
Reviewed-by: Gavin Hu <gavin.hu@arm.com>
---
lib/librte_eal/common/Makefile | 1 +
lib/librte_eal/common/include/rte_io_bitops.h | 112 ++++++++++++++++++++++++++
lib/librte_eal/common/meson.build | 1 +
3 files changed, 114 insertions(+)
create mode 100644 lib/librte_eal/common/include/rte_io_bitops.h
Comments
Hi Joyce,
Thanks for the patch, few comments.
<snip>
>
> There are a lot functions of bit operations scattered and duplicated in PMDs,
> consolidating them into a common API family is necessary. Furthermore, the
> bit operation is mostly applied to the IO devices, so use __ATOMIC_ACQ_REL
> to ensure the ordering.
The APIs are not taking memory ordering as a parameter. This presents the same problem as the rte_atomic_xxx APIs. IMO, the APIs should take memory ordering as a parameter.
>
> Signed-off-by: Joyce Kong <joyce.kong@arm.com>
> Reviewed-by: Gavin Hu <gavin.hu@arm.com>
> ---
> lib/librte_eal/common/Makefile | 1 +
> lib/librte_eal/common/include/rte_io_bitops.h | 112
> ++++++++++++++++++++++++++
> lib/librte_eal/common/meson.build | 1 +
> 3 files changed, 114 insertions(+)
> create mode 100644 lib/librte_eal/common/include/rte_io_bitops.h
>
> diff --git a/lib/librte_eal/common/Makefile
> b/lib/librte_eal/common/Makefile index a00d4fc..3831313 100644
> --- a/lib/librte_eal/common/Makefile
> +++ b/lib/librte_eal/common/Makefile
> @@ -18,6 +18,7 @@ INC += rte_malloc.h rte_keepalive.h rte_time.h INC +=
> rte_service.h rte_service_component.h INC += rte_bitmap.h rte_vfio.h
> rte_hypervisor.h rte_test.h INC += rte_reciprocal.h rte_fbarray.h rte_uuid.h
> +INC += rte_io_bitops.h
>
> GENERIC_INC := rte_atomic.h rte_byteorder.h rte_cycles.h rte_prefetch.h
> GENERIC_INC += rte_memcpy.h rte_cpuflags.h diff --git
> a/lib/librte_eal/common/include/rte_io_bitops.h
> b/lib/librte_eal/common/include/rte_io_bitops.h
> new file mode 100644
> index 0000000..5f778b8
> --- /dev/null
> +++ b/lib/librte_eal/common/include/rte_io_bitops.h
> @@ -0,0 +1,112 @@
> +/* SPDX-License-Identifier: BSD-3-Clause
> + * Copyright(c) 2019 Arm Limited
> + */
> +
> +#ifndef _RTE_IO_BITOPS_H_
> +#define _RTE_IO_BITOPS_H_
> +
> +/**
> + * @file
> + * Bit Operations
> + *
> + * This file defines a generic API for bit operations.
> + */
> +
> +#include <rte_lcore.h>
> +
> +/**
> + * Get a bit.
> + *
> + * @param nr
> + * The bit to get.
> + * @param addr
> + * The address to count from.
> + * @return
> + * The value of the bit.
> + */
> +static inline int32_t
> +rte_io_get_bit(uint32_t nr, uint64_t *addr) {
> + return __atomic_load_n(addr, __ATOMIC_ACQUIRE) & (1UL << nr); }
Some use cases might need 'relaxed' memory order for this API. So, the user of this API should be able to provide the memory order.
> +
> +/**
> + * Set a bit to 1.
> + *
> + * @param nr
> + * The bit to set.
> + * @param addr
> + * The address to count from.
> + */
> +static inline void
> +rte_io_set_bit(uint32_t nr, uint64_t *addr) {
> + __atomic_fetch_or(addr, (1UL << nr), __ATOMIC_ACQ_REL); }
Some use cases might need 'release' or 'relaxed' memory order.
Similar requirements apply to other APIs too.
> +
> +/**
> + * Set a bit to 0.
> + *
> + * @param nr
> + * The bit to set.
> + * @param addr
> + * The address to count from.
> + */
> +static inline void
> +rte_io_clear_bit(int32_t nr, uint64_t *addr) {
> + __atomic_fetch_and(addr, ~(1UL << nr), __ATOMIC_ACQ_REL); }
> +
> +/**
> + * Test if a bit is 1.
> + *
> + * @param nr
> + * The bit to test.
> + * @param addr
> + * The address to count from.
> + * @return
> + * 1 if the bit is 1; else 0.
> + */
> +static inline int32_t
> +rte_io_test_bit(int32_t nr, uint64_t *addr) {
> + return (__atomic_load_n(addr, __ATOMIC_ACQUIRE) & (1UL <<
> nr)) != 0; }
> +
> +/**
> + * Set a bit to 1 and return its old value.
> + *
> + * @param nr
> + * The bit to set.
> + * @param addr
> + * The address to count from.
> + * @return
> + * The old value of the bit.
> + */
> +static inline int32_t
> +rte_io_test_and_set_bit(int32_t nr, uint64_t *addr) {
> + unsigned long mask = (1UL << nr);
> +
> + return __atomic_fetch_or(addr, mask, __ATOMIC_ACQ_REL) &
> mask; }
> +
> +/**
> + * Set a bit to 0 and return its old value.
> + *
> + * @param nr
> + * The bit to set.
> + * @param addr
> + * The address to count from.
> + * @return
> + * The old value of the bit.
> + */
> +static inline int32_t
> +rte_io_test_and_clear_bit(int32_t nr, uint64_t *addr) {
> + unsigned long mask = (1UL << nr);
> +
> + return __atomic_fetch_and(addr, ~mask, __ATOMIC_ACQ_REL) &
> mask; }
> +#endif /* _RTE_IO_BITOPS_H_ */
> diff --git a/lib/librte_eal/common/meson.build
> b/lib/librte_eal/common/meson.build
> index 386577c..0a65d04 100644
> --- a/lib/librte_eal/common/meson.build
> +++ b/lib/librte_eal/common/meson.build
> @@ -52,6 +52,7 @@ common_headers = files(
> 'include/rte_alarm.h',
> 'include/rte_branch_prediction.h',
> 'include/rte_bus.h',
> + 'include/rte_io_bitops.h',
> 'include/rte_bitmap.h',
> 'include/rte_class.h',
> 'include/rte_common.h',
> --
> 2.7.4
On Wed, Oct 23, 2019 at 8:25 AM Joyce Kong <joyce.kong@arm.com> wrote:
>
> There are a lot functions of bit operations scattered and
> duplicated in PMDs, consolidating them into a common API
> family is necessary. Furthermore, the bit operation is
> mostly applied to the IO devices, so use __ATOMIC_ACQ_REL
> to ensure the ordering.
>
> Signed-off-by: Joyce Kong <joyce.kong@arm.com>
> Reviewed-by: Gavin Hu <gavin.hu@arm.com>
> ---
> lib/librte_eal/common/Makefile | 1 +
> lib/librte_eal/common/include/rte_io_bitops.h | 112 ++++++++++++++++++++++++++
> lib/librte_eal/common/meson.build | 1 +
Missing doc/api/doxy-api-index.md update
> 3 files changed, 114 insertions(+)
> create mode 100644 lib/librte_eal/common/include/rte_io_bitops.h
>
> +
> +/**
> + * Get a bit.
> + *
> + * @param nr
> + * The bit to get.
> + * @param addr
> + * The address to count from.
> + * @return
> + * The value of the bit.
> + */
> +static inline int32_t
Missing __rte_experimental
> +rte_io_get_bit(uint32_t nr, uint64_t *addr)
> +{
> + return __atomic_load_n(addr, __ATOMIC_ACQUIRE) & (1UL << nr);
> +}
> +
> -----Original Message-----
> From: Joyce Kong [mailto:joyce.kong@arm.com]
> Sent: Wednesday, October 23, 2019 4:55 AM
>
> There are a lot functions of bit operations scattered and
> duplicated in PMDs, consolidating them into a common API
> family is necessary. Furthermore, the bit operation is
> mostly applied to the IO devices, so use __ATOMIC_ACQ_REL
> to ensure the ordering.
>
> Signed-off-by: Joyce Kong <joyce.kong@arm.com>
> Reviewed-by: Gavin Hu <gavin.hu@arm.com>
> ---
> lib/librte_eal/common/Makefile | 1 +
> lib/librte_eal/common/include/rte_io_bitops.h | 112
> ++++++++++++++++++++++++++
> lib/librte_eal/common/meson.build | 1 +
> 3 files changed, 114 insertions(+)
> create mode 100644 lib/librte_eal/common/include/rte_io_bitops.h
>
> diff --git a/lib/librte_eal/common/Makefile
> b/lib/librte_eal/common/Makefile
> index a00d4fc..3831313 100644
> --- a/lib/librte_eal/common/Makefile
> +++ b/lib/librte_eal/common/Makefile
> @@ -18,6 +18,7 @@ INC += rte_malloc.h rte_keepalive.h rte_time.h
> INC += rte_service.h rte_service_component.h
> INC += rte_bitmap.h rte_vfio.h rte_hypervisor.h rte_test.h
> INC += rte_reciprocal.h rte_fbarray.h rte_uuid.h
> +INC += rte_io_bitops.h
>
> GENERIC_INC := rte_atomic.h rte_byteorder.h rte_cycles.h
> rte_prefetch.h
> GENERIC_INC += rte_memcpy.h rte_cpuflags.h
> diff --git a/lib/librte_eal/common/include/rte_io_bitops.h
> b/lib/librte_eal/common/include/rte_io_bitops.h
> new file mode 100644
> index 0000000..5f778b8
> --- /dev/null
> +++ b/lib/librte_eal/common/include/rte_io_bitops.h
> @@ -0,0 +1,112 @@
> +/* SPDX-License-Identifier: BSD-3-Clause
> + * Copyright(c) 2019 Arm Limited
> + */
> +
> +#ifndef _RTE_IO_BITOPS_H_
> +#define _RTE_IO_BITOPS_H_
> +
> +/**
> + * @file
> + * Bit Operations
> + *
> + * This file defines a generic API for bit operations.
> + */
-> This file defines a generic API for I/O device bit operations.
> +
> +#include <rte_lcore.h>
This library doesn't do any lcore operations. Please use the appropriate headers.
> +
> +/**
> + * Get a bit.
> + *
> + * @param nr
> + * The bit to get.
> + * @param addr
> + * The address to count from.
The address to count from. -> The address holding the bit. (Applies to all functions.)
> + * @return
> + * The value of the bit.
The description of the return value can be misinterpreted. The return value is not the value of the bit, which is 0 or 1, but the value of the word holding the bit, masked with the bit position. (Applies to all functions returning a value.)
> + */
> +static inline int32_t
> +rte_io_get_bit(uint32_t nr, uint64_t *addr)
The return type should be an unsigned type. (Applies to all functions returning a value.)
The addr type for 32 bit operations should not be uint64_t *, but uint32_t *. The __atomic_xxx functions actually use this type for something, and I think it would access the wrong 32 bits on a big endian CPU.
In some of the functions below, nr is signed (int32_t); it should be unsigned (uint32_t).
And a suggestion: Consider changing the type of nr from uint32_t to unsigned int.
> +{
> + return __atomic_load_n(addr, __ATOMIC_ACQUIRE) & (1UL << nr);
> +}
> +
> +/**
> + * Set a bit to 1.
> + *
> + * @param nr
> + * The bit to set.
> + * @param addr
> + * The address to count from.
> + */
> +static inline void
> +rte_io_set_bit(uint32_t nr, uint64_t *addr)
> +{
> + __atomic_fetch_or(addr, (1UL << nr), __ATOMIC_ACQ_REL);
> +}
> +
> +/**
> + * Set a bit to 0.
> + *
> + * @param nr
> + * The bit to set.
> + * @param addr
> + * The address to count from.
> + */
> +static inline void
> +rte_io_clear_bit(int32_t nr, uint64_t *addr)
> +{
> + __atomic_fetch_and(addr, ~(1UL << nr), __ATOMIC_ACQ_REL);
> +}
> +
> +/**
> + * Test if a bit is 1.
> + *
> + * @param nr
> + * The bit to test.
> + * @param addr
> + * The address to count from.
> + * @return
> + * 1 if the bit is 1; else 0.
> + */
> +static inline int32_t
> +rte_io_test_bit(int32_t nr, uint64_t *addr)
> +{
> + return (__atomic_load_n(addr, __ATOMIC_ACQUIRE) & (1UL << nr)) !=
> 0;
> +}
All the other functions in this library return a word with the bit masked. This function returns 0 or 1. I think it should return a word value, similar to the other functions.
> +
> +/**
> + * Set a bit to 1 and return its old value.
> + *
> + * @param nr
> + * The bit to set.
> + * @param addr
> + * The address to count from.
> + * @return
> + * The old value of the bit.
> + */
> +static inline int32_t
> +rte_io_test_and_set_bit(int32_t nr, uint64_t *addr)
> +{
> + unsigned long mask = (1UL << nr);
unsigned long mask -> uint32_t mask. (Also applies to other functions.)
> +
> + return __atomic_fetch_or(addr, mask, __ATOMIC_ACQ_REL) & mask;
> +}
> +
> +/**
> + * Set a bit to 0 and return its old value.
> + *
> + * @param nr
> + * The bit to set.
> + * @param addr
> + * The address to count from.
> + * @return
> + * The old value of the bit.
> + */
> +static inline int32_t
> +rte_io_test_and_clear_bit(int32_t nr, uint64_t *addr)
> +{
> + unsigned long mask = (1UL << nr);
> +
> + return __atomic_fetch_and(addr, ~mask, __ATOMIC_ACQ_REL) & mask;
> +}
> +#endif /* _RTE_IO_BITOPS_H_ */
> diff --git a/lib/librte_eal/common/meson.build
> b/lib/librte_eal/common/meson.build
> index 386577c..0a65d04 100644
> --- a/lib/librte_eal/common/meson.build
> +++ b/lib/librte_eal/common/meson.build
> @@ -52,6 +52,7 @@ common_headers = files(
> 'include/rte_alarm.h',
> 'include/rte_branch_prediction.h',
> 'include/rte_bus.h',
> + 'include/rte_io_bitops.h',
> 'include/rte_bitmap.h',
> 'include/rte_class.h',
> 'include/rte_common.h',
> --
> 2.7.4
>
@@ -18,6 +18,7 @@ INC += rte_malloc.h rte_keepalive.h rte_time.h
INC += rte_service.h rte_service_component.h
INC += rte_bitmap.h rte_vfio.h rte_hypervisor.h rte_test.h
INC += rte_reciprocal.h rte_fbarray.h rte_uuid.h
+INC += rte_io_bitops.h
GENERIC_INC := rte_atomic.h rte_byteorder.h rte_cycles.h rte_prefetch.h
GENERIC_INC += rte_memcpy.h rte_cpuflags.h
new file mode 100644
@@ -0,0 +1,112 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright(c) 2019 Arm Limited
+ */
+
+#ifndef _RTE_IO_BITOPS_H_
+#define _RTE_IO_BITOPS_H_
+
+/**
+ * @file
+ * Bit Operations
+ *
+ * This file defines a generic API for bit operations.
+ */
+
+#include <rte_lcore.h>
+
+/**
+ * Get a bit.
+ *
+ * @param nr
+ * The bit to get.
+ * @param addr
+ * The address to count from.
+ * @return
+ * The value of the bit.
+ */
+static inline int32_t
+rte_io_get_bit(uint32_t nr, uint64_t *addr)
+{
+ return __atomic_load_n(addr, __ATOMIC_ACQUIRE) & (1UL << nr);
+}
+
+/**
+ * Set a bit to 1.
+ *
+ * @param nr
+ * The bit to set.
+ * @param addr
+ * The address to count from.
+ */
+static inline void
+rte_io_set_bit(uint32_t nr, uint64_t *addr)
+{
+ __atomic_fetch_or(addr, (1UL << nr), __ATOMIC_ACQ_REL);
+}
+
+/**
+ * Set a bit to 0.
+ *
+ * @param nr
+ * The bit to set.
+ * @param addr
+ * The address to count from.
+ */
+static inline void
+rte_io_clear_bit(int32_t nr, uint64_t *addr)
+{
+ __atomic_fetch_and(addr, ~(1UL << nr), __ATOMIC_ACQ_REL);
+}
+
+/**
+ * Test if a bit is 1.
+ *
+ * @param nr
+ * The bit to test.
+ * @param addr
+ * The address to count from.
+ * @return
+ * 1 if the bit is 1; else 0.
+ */
+static inline int32_t
+rte_io_test_bit(int32_t nr, uint64_t *addr)
+{
+ return (__atomic_load_n(addr, __ATOMIC_ACQUIRE) & (1UL << nr)) != 0;
+}
+
+/**
+ * Set a bit to 1 and return its old value.
+ *
+ * @param nr
+ * The bit to set.
+ * @param addr
+ * The address to count from.
+ * @return
+ * The old value of the bit.
+ */
+static inline int32_t
+rte_io_test_and_set_bit(int32_t nr, uint64_t *addr)
+{
+ unsigned long mask = (1UL << nr);
+
+ return __atomic_fetch_or(addr, mask, __ATOMIC_ACQ_REL) & mask;
+}
+
+/**
+ * Set a bit to 0 and return its old value.
+ *
+ * @param nr
+ * The bit to set.
+ * @param addr
+ * The address to count from.
+ * @return
+ * The old value of the bit.
+ */
+static inline int32_t
+rte_io_test_and_clear_bit(int32_t nr, uint64_t *addr)
+{
+ unsigned long mask = (1UL << nr);
+
+ return __atomic_fetch_and(addr, ~mask, __ATOMIC_ACQ_REL) & mask;
+}
+#endif /* _RTE_IO_BITOPS_H_ */
@@ -52,6 +52,7 @@ common_headers = files(
'include/rte_alarm.h',
'include/rte_branch_prediction.h',
'include/rte_bus.h',
+ 'include/rte_io_bitops.h',
'include/rte_bitmap.h',
'include/rte_class.h',
'include/rte_common.h',