queue.3: Document existing QMD_* macros

Feedback from:	bapt, bdrewery, emaste
Sponsored by:	Dell EMC Isilon
Differential Revision:	https://reviews.freebsd.org/D3983

diff --git a/newlib/libc/include/sys/queue.h b/newlib/libc/include/sys/queue.h
index 8a9d07e1182c751f928efbc2aa40cf97dd8db63e..6cae4c14c2812825d0131892ca17883037205fd4 100644 (file)
--- a/newlib/libc/include/sys/queue.h
+++ b/newlib/libc/include/sys/queue.h
@@ -477,6 +477,12 @@ struct {                                                           \
  */
 
 #if (defined(_KERNEL) && defined(INVARIANTS))
+/*
+ * QMD_LIST_CHECK_HEAD(LIST_HEAD *head, LIST_ENTRY NAME)
+ *
+ * If the list is non-empty, validates that the first element of the list
+ * points back at 'head.'
+ */
 #define        QMD_LIST_CHECK_HEAD(head, field) do {                           \
        if (LIST_FIRST((head)) != NULL &&                               \
            LIST_FIRST((head))->field.le_prev !=                        \
@@ -484,6 +490,12 @@ struct {                                                           \
                panic("Bad list head %p first->prev != head", (head));  \
 } while (0)
 
+/*
+ * QMD_LIST_CHECK_NEXT(TYPE *elm, LIST_ENTRY NAME)
+ *
+ * If an element follows 'elm' in the list, validates that the next element
+ * points back at 'elm.'
+ */
 #define        QMD_LIST_CHECK_NEXT(elm, field) do {                            \
        if (LIST_NEXT((elm), field) != NULL &&                          \
            LIST_NEXT((elm), field)->field.le_prev !=                   \
@@ -491,6 +503,11 @@ struct {                                                           \
                panic("Bad link elm %p next->prev != elm", (elm));      \
 } while (0)
 
+/*
+ * QMD_LIST_CHECK_PREV(TYPE *elm, LIST_ENTRY NAME)
+ *
+ * Validates that the previous element (or head of the list) points to 'elm.'
+ */
 #define        QMD_LIST_CHECK_PREV(elm, field) do {                            \
        if (*(elm)->field.le_prev != (elm))                             \
                panic("Bad link elm %p prev->next != elm", (elm));      \
@@ -639,6 +656,12 @@ struct {                                                           \
  * Tail queue functions.
  */
 #if (defined(_KERNEL) && defined(INVARIANTS))
+/*
+ * QMD_TAILQ_CHECK_HEAD(TAILQ_HEAD *head, TAILQ_ENTRY NAME)
+ *
+ * If the tailq is non-empty, validates that the first element of the tailq
+ * points back at 'head.'
+ */
 #define        QMD_TAILQ_CHECK_HEAD(head, field) do {                          \
        if (!TAILQ_EMPTY(head) &&                                       \
            TAILQ_FIRST((head))->field.tqe_prev !=                      \
@@ -646,11 +669,22 @@ struct {                                                          \
                panic("Bad tailq head %p first->prev != head", (head)); \
 } while (0)
 
+/*
+ * QMD_TAILQ_CHECK_TAIL(TAILQ_HEAD *head, TAILQ_ENTRY NAME)
+ *
+ * Validates that the tail of the tailq is a pointer to pointer to NULL.
+ */
 #define        QMD_TAILQ_CHECK_TAIL(head, field) do {                          \
        if (*(head)->tqh_last != NULL)                                  \
                panic("Bad tailq NEXT(%p->tqh_last) != NULL", (head));  \
 } while (0)
 
+/*
+ * QMD_TAILQ_CHECK_NEXT(TYPE *elm, TAILQ_ENTRY NAME)
+ *
+ * If an element follows 'elm' in the tailq, validates that the next element
+ * points back at 'elm.'
+ */
 #define        QMD_TAILQ_CHECK_NEXT(elm, field) do {                           \
        if (TAILQ_NEXT((elm), field) != NULL &&                         \
            TAILQ_NEXT((elm), field)->field.tqe_prev !=                 \
@@ -658,6 +692,11 @@ struct {                                                           \
                panic("Bad link elm %p next->prev != elm", (elm));      \
 } while (0)
 
+/*
+ * QMD_TAILQ_CHECK_PREV(TYPE *elm, TAILQ_ENTRY NAME)
+ *
+ * Validates that the previous element (or head of the tailq) points to 'elm.'
+ */
 #define        QMD_TAILQ_CHECK_PREV(elm, field) do {                           \
        if (*(elm)->field.tqe_prev != (elm))                            \
                panic("Bad link elm %p prev->next != elm", (elm));      \