Skip to contentSkip to conversation

public: add RING_NR_UNCONSUMED_*() macros to ring.h

PATCH Superseded Juergen Gross 3 participants 5 messages Dec 9, 2021

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 public: add RING_NR_UNCONSUMED_*() macros to ring.h

Today RING_HAS_UNCONSUMED_*() macros are returning the number of unconsumed requests or responses instead of a boolean as the name of the macros would imply.

As this "feature" is already being used, rename the macros to RING_NR_UNCONSUMED_*() and define the RING_HAS_UNCONSUMED_*() macros by using the new RING_NR_UNCONSUMED_*() macros. In order to avoid future misuse let RING_HAS_UNCONSUMED_*() optionally really return a boolean (can be activated by defining RING_HAS_UNCONSUMED_IS_BOOL).

Note that the known misuses need to be switched to the new RING_NR_UNCONSUMED_*() macros when using this version of ring.h.

Cc Roger Pau Monne <[email protected]>
Cc Manuel Bouyer <[email protected]>
Cc Simon Kuenzer <[email protected]>
Cc Paul Durrant <[email protected]>

---
I have checked Xen, Mini-OS, qemu, grub2, OVMF and Linux kernel for misuses of the RING_HAS_UNCONSUMED_*() macros. There is currently only one instance in the Linux kernel netback driver. The BSDs, UNIKRAFT and Windows PV drivers should be checked for misuse, too.
V2: make RING_HAS_UNCONSUMED_*() returning a bool optional (Jan Beulich)

---
 xen/include/public/io/ring.h | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)
xen/include/public/io/ring.h +15 -3
index c486c457e0..a7f492db39 100644
@@ -208,11 +208,11 @@ typedef struct __name##_back_ring __name##_back_ring_t
     (RING_FREE_REQUESTS(_r) == 0)
 
 /* Test if there are outstanding messages to be processed on a ring. */
-#define RING_HAS_UNCONSUMED_RESPONSES(_r)                               \
+#define RING_NR_UNCONSUMED_RESPONSES(_r)                                \
     ((_r)->sring->rsp_prod - (_r)->rsp_cons)
 
 #ifdef __GNUC__
-#define RING_HAS_UNCONSUMED_REQUESTS(_r) ({                             \
+#define RING_NR_UNCONSUMED_REQUESTS(_r) ({                              \
     unsigned int req = (_r)->sring->req_prod - (_r)->req_cons;          \
     unsigned int rsp = RING_SIZE(_r) -                                  \
         ((_r)->req_cons - (_r)->rsp_prod_pvt);                          \
@@ -220,13 +220,25 @@ typedef struct __name##_back_ring __name##_back_ring_t
 })
 #else
 /* Same as above, but without the nice GCC ({ ... }) syntax. */
-#define RING_HAS_UNCONSUMED_REQUESTS(_r)                                \
+#define RING_NR_UNCONSUMED_REQUESTS(_r)                                 \
     ((((_r)->sring->req_prod - (_r)->req_cons) <                        \
       (RING_SIZE(_r) - ((_r)->req_cons - (_r)->rsp_prod_pvt))) ?        \
      ((_r)->sring->req_prod - (_r)->req_cons) :                         \
      (RING_SIZE(_r) - ((_r)->req_cons - (_r)->rsp_prod_pvt)))
 #endif
 
+#ifdef RING_HAS_UNCONSUMED_IS_BOOL
+/*
+ * These variants should only be used in case no caller is abusing them for
+ * obtaining the number of unconsumed responses/requests.
+ */
+#define RING_HAS_UNCONSUMED_RESPONSES(_r) (!!RING_NR_UNCONSUMED_RESPONSES(_r))
+#define RING_HAS_UNCONSUMED_REQUESTS(_r)  (!!RING_NR_UNCONSUMED_REQUESTS(_r))
+#else
+#define RING_HAS_UNCONSUMED_RESPONSES(_r) RING_NR_UNCONSUMED_RESPONSES(_r)
+#define RING_HAS_UNCONSUMED_REQUESTS(_r)  RING_NR_UNCONSUMED_REQUESTS(_r)
+#endif
+
 /* Direct access to individual ring elements, by index. */
 #define RING_GET_REQUEST(_r, _idx)                                      \
     (&((_r)->sring->ring[((_idx) & (RING_SIZE(_r) - 1))].req))
Signature · 1 line
2.26.2
Reviewed-by Paul Durrant on v2 1/1
#1 lore raw
Quoted 18 lines · Juergen Gross

Today RING_HAS_UNCONSUMED_*() macros are returning the number of unconsumed requests or responses instead of a boolean as the name of the macros would imply.

As this "feature" is already being used, rename the macros to RING_NR_UNCONSUMED_*() and define the RING_HAS_UNCONSUMED_*() macros by using the new RING_NR_UNCONSUMED_*() macros. In order to avoid future misuse let RING_HAS_UNCONSUMED_*() optionally really return a boolean (can be activated by defining RING_HAS_UNCONSUMED_IS_BOOL).

Note that the known misuses need to be switched to the new RING_NR_UNCONSUMED_*() macros when using this version of ring.h.

Cc Roger Pau Monne <[email protected]>
Cc Manuel Bouyer <[email protected]>
Cc Simon Kuenzer <[email protected]>
Cc Paul Durrant <[email protected]>
Quoted 7 lines

---
I have checked Xen, Mini-OS, qemu, grub2, OVMF and Linux kernel for misuses of the RING_HAS_UNCONSUMED_*() macros. There is currently only one instance in the Linux kernel netback driver. The BSDs, UNIKRAFT and Windows PV drivers should be checked for misuse, too.
V2: make RING_HAS_UNCONSUMED_*() returning a bool optional (Jan Beulich)
---

#2 lore raw
In reply to Juergen Gross
Quoted 4 lines · Juergen Gross

Today RING_HAS_UNCONSUMED_*() macros are returning the number of unconsumed requests or responses instead of a boolean as the name of the macros would imply.

Quoted 8 lines

As this "feature" is already being used, rename the macros to RING_NR_UNCONSUMED_*() and define the RING_HAS_UNCONSUMED_*() macros by using the new RING_NR_UNCONSUMED_*() macros. In order to avoid future misuse let RING_HAS_UNCONSUMED_*() optionally really return a boolean (can be activated by defining RING_HAS_UNCONSUMED_IS_BOOL).

Note that the known misuses need to be switched to the new RING_NR_UNCONSUMED_*() macros when using this version of ring.h.

Is this last statement stale with the introduction of RING_HAS_UNCONSUMED_IS_BOOL?

Quoted 6 lines
xen/include/public/io/ring.h +0 -0
@@ -208,11 +208,11 @@ typedef struct __name##_back_ring __name##_back_ring_t
     (RING_FREE_REQUESTS(_r) == 0)
 
 /* Test if there are outstanding messages to be processed on a ring. */

xen/include/public/io/ring.h typedef struct __name##_back_ring __name##_back_ring_t · line 218

Quoted 10 lines
xen/include/public/io/ring.h +2 -2
-#define RING_HAS_UNCONSUMED_RESPONSES(_r)                               \
+#define RING_NR_UNCONSUMED_RESPONSES(_r)                                \
     ((_r)->sring->rsp_prod - (_r)->rsp_cons)
 
 #ifdef __GNUC__
-#define RING_HAS_UNCONSUMED_REQUESTS(_r) ({                             \
+#define RING_NR_UNCONSUMED_REQUESTS(_r) ({                              \
     unsigned int req = (_r)->sring->req_prod - (_r)->req_cons;          \
     unsigned int rsp = RING_SIZE(_r) -                                  \
         ((_r)->req_cons - (_r)->rsp_prod_pvt);                          \

To answer the "whether" question this was likely good enough. I wonder though whether the use of (_r)->sring->{rsp,req}_prod doesn't require further sanitizing of the result as it's now intended to be used as a count - afaict the returned values could easily be beyond the number of ring elements when the other end is misbehaving. Or if not bounding the values here, I would say the comment in context would need updating / extending, to tell consumers that they may not blindly use the returned values.

Also imo all new identifiers would better have a XEN_ prefix to avoid further growing the risk of name space clashes. But I can see how this would result in inconsistencies with existing names.

Jan

#3 lore raw
Quoted 11 lines · Jan Beulich
Quoted 10 lines · Juergen Gross

Today RING_HAS_UNCONSUMED_*() macros are returning the number of unconsumed requests or responses instead of a boolean as the name of the macros would imply.

As this "feature" is already being used, rename the macros to RING_NR_UNCONSUMED_*() and define the RING_HAS_UNCONSUMED_*() macros by using the new RING_NR_UNCONSUMED_*() macros. In order to avoid future misuse let RING_HAS_UNCONSUMED_*() optionally really return a boolean (can be activated by defining RING_HAS_UNCONSUMED_IS_BOOL).

Quoted 5 lines
Quoted 2 lines

Note that the known misuses need to be switched to the new RING_NR_UNCONSUMED_*() macros when using this version of ring.h.

Is this last statement stale with the introduction of RING_HAS_UNCONSUMED_IS_BOOL?

It should rather be modified like:

Note that the known misuses need to be switched to the new RING_NR_UNCONSUMED_*() macros when using the RING_HAS_UNCONSUMED_*() variants returning a boolean value.

Quoted 11 lines
Quoted 11 lines
xen/include/public/io/ring.h +1 -1
@@ -208,11 +208,11 @@ typedef struct __name##_back_ring __name##_back_ring_t
      (RING_FREE_REQUESTS(_r) == 0)
 
  /* Test if there are outstanding messages to be processed on a ring. */
-#define RING_HAS_UNCONSUMED_RESPONSES(_r)                               \
+#define RING_NR_UNCONSUMED_RESPONSES(_r)                                \
      ((_r)->sring->rsp_prod - (_r)->rsp_cons)
 
Quoted 15 lines

xen/include/public/io/ring.h typedef struct __name##_back_ring __name##_back_ring_t · line 218

Quoted 6 lines
xen/include/public/io/ring.h +1 -1
  #ifdef __GNUC__
-#define RING_HAS_UNCONSUMED_REQUESTS(_r) ({                             \
+#define RING_NR_UNCONSUMED_REQUESTS(_r) ({                              \
      unsigned int req = (_r)->sring->req_prod - (_r)->req_cons;          \
      unsigned int rsp = RING_SIZE(_r) -                                  \
          ((_r)->req_cons - (_r)->rsp_prod_pvt);                          \

To answer the "whether" question this was likely good enough. I wonder though whether the use of (_r)->sring->{rsp,req}_prod doesn't require further sanitizing of the result as it's now intended to be used as a count - afaict the returned values could easily be beyond the number of ring elements when the other end is misbehaving. Or if not bounding the values here, I would say the comment in context would need updating / extending, to tell consumers that they may not blindly use the returned values.

I'll modify the comment:

/*
* Test if there are outstanding messages to be processed on a ring.
* The answer is based on values writable by the other side, so further
* processing should fail gracefully in case the return value was wrong. */

Quoted 3 lines

Also imo all new identifiers would better have a XEN_ prefix to avoid further growing the risk of name space clashes. But I can see how this would result in inconsistencies with existing names.

Yes, I do see the problem.

Would you support switching all the names to the XEN name space and adding a section like:

#ifndef XEN_RING_NAMESPACE
/* Following for all macros etc. not in the XEN name space today */ #define x XEN_x
#endif

Juergen

#4 lore raw
Quoted 51 lines · Juergen Gross
Quoted 11 lines · Jan Beulich
Quoted 10 lines · Juergen Gross

Today RING_HAS_UNCONSUMED_*() macros are returning the number of unconsumed requests or responses instead of a boolean as the name of the macros would imply.

As this "feature" is already being used, rename the macros to RING_NR_UNCONSUMED_*() and define the RING_HAS_UNCONSUMED_*() macros by using the new RING_NR_UNCONSUMED_*() macros. In order to avoid future misuse let RING_HAS_UNCONSUMED_*() optionally really return a boolean (can be activated by defining RING_HAS_UNCONSUMED_IS_BOOL).

Quoted 5 lines
Quoted 2 lines

Note that the known misuses need to be switched to the new RING_NR_UNCONSUMED_*() macros when using this version of ring.h.

Is this last statement stale with the introduction of RING_HAS_UNCONSUMED_IS_BOOL?

It should rather be modified like:

Note that the known misuses need to be switched to the new RING_NR_UNCONSUMED_*() macros when using the RING_HAS_UNCONSUMED_*() variants returning a boolean value.

Quoted 11 lines
Quoted 11 lines
xen/include/public/io/ring.h +1 -1
@@ -208,11 +208,11 @@ typedef struct __name##_back_ring __name##_back_ring_t
      (RING_FREE_REQUESTS(_r) == 0)
 
  /* Test if there are outstanding messages to be processed on a ring. */
-#define RING_HAS_UNCONSUMED_RESPONSES(_r)                               \
+#define RING_NR_UNCONSUMED_RESPONSES(_r)                                \
      ((_r)->sring->rsp_prod - (_r)->rsp_cons)
 
Quoted 15 lines

xen/include/public/io/ring.h typedef struct __name##_back_ring __name##_back_ring_t · line 218

Quoted 6 lines
xen/include/public/io/ring.h +1 -1
  #ifdef __GNUC__
-#define RING_HAS_UNCONSUMED_REQUESTS(_r) ({                             \
+#define RING_NR_UNCONSUMED_REQUESTS(_r) ({                              \
      unsigned int req = (_r)->sring->req_prod - (_r)->req_cons;          \
      unsigned int rsp = RING_SIZE(_r) -                                  \
          ((_r)->req_cons - (_r)->rsp_prod_pvt);                          \

To answer the "whether" question this was likely good enough. I wonder though whether the use of (_r)->sring->{rsp,req}_prod doesn't require further sanitizing of the result as it's now intended to be used as a count - afaict the returned values could easily be beyond the number of ring elements when the other end is misbehaving. Or if not bounding the values here, I would say the comment in context would need updating / extending, to tell consumers that they may not blindly use the returned values.

Quoted 7 lines

I'll modify the comment:

/*
* Test if there are outstanding messages to be processed on a ring.
* The answer is based on values writable by the other side, so further
* processing should fail gracefully in case the return value was wrong. */

I'd recommend to avoid the word "fail" here. Maybe "... should deal gracefully with the case ..."?

Quoted 6 lines
Quoted 3 lines

Also imo all new identifiers would better have a XEN_ prefix to avoid further growing the risk of name space clashes. But I can see how this would result in inconsistencies with existing names.

Yes, I do see the problem.

Quoted 7 lines

Would you support switching all the names to the XEN name space and adding a section like:

#ifndef XEN_RING_NAMESPACE
/* Following for all macros etc. not in the XEN name space today */ #define x XEN_x
#endif

Well, as that's not very neat either, I wouldn't go as far as saying "support", but I certainly wouldn't object, and I also wouldn't mind ack-ing such a change.

Jan