Re: [dpdk-dev] [PATCHv3] include: fix sys/queue.h.

[Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>]

2021-08-12 20:05 (UTC+0000), William Tu:
> Currently there are a couple of public header files include

Suggested subject: "eal: remove sys/queue.h from public headers".

1. The state before the patch should be described in the past tense.
2. Really ten times more than "a couple", suggesting "some" (nit).
2. "files _that_ include"?

> 'sys/queue.h', which is a POSIX functionality.

It's not POSIX, it's found on many Unix systems.

> When compiling DPDK with OVS on Windows, we encountered issues such as, found the missing
> header.

This sentence is a little hard to parse. Instead, suggesting:

	This file is missing on Windows. During the build, DPDK uses a
	bundled copy, but it cannot be installed because macros it exports
	may conflict with the ones from application code or environment.

> In file included from ../lib/dpdk.c:27:
> C:\temp\dpdk\include\rte_log.h:24:10: fatal error: 'sys/queue.h' file
> not found

An explanation is missing why <sys/queue.h> embedded in DPDK shouldn't be
installed (see above, maybe you can come up with something better).

> 
> The patch fixes it by removing the #include <sys/queue.h> from
> DPDK public headers, so programs including DPDK headers don't depend
> on POSIX sys/queue.h. For Linux/FreeBSD, DPDK public headers only need a
> handful of macros for list/tailq heads and links. Those macros should be
> provided by DPDK, with RTE_ prefix.

It is worth noting that RTE_ macros must be compatible with <sys/queue.h>
at the level of API (to use with <sys/queue.h> macros in C files) and ABI
(to avoid breaking it).

Nit: "Should" is not the right word for things done in the patch. Same below.

> For Linux and FreeBSD it will just be:
>     #include <sys/queue.h>
>     #define RTE_TAILQ_ENTRY(type) TAILQ_ENTRY(type)
>     /* ... */
> For Windows, we copy these definitions from <sys/queue.h> to rte_os.h.

No need to describe what's inside the patch, diff already does it :)

> With this patch, all the public headers should not have
> "#include <sys/queue.h>" or "TAILQ_xxx" macros.
> 
> Suggested-by: Nick Connolly <nick.connolly@mayadata.io>
> Suggested-by: Dmitry Kozliuk <Dmitry.Kozliuk@gmail.com>
> Signed-off-by: William Tu <u9012063@gmail.com>
> ---
> v2->v3:
>   * follow the suggestion by Dmitry
>   * run checkpatches, there are some errors but I think either
>     the original file has over 80-char line due to comments,
>     or some false positive about macro.
> v1->v2:
>   - follow the suggestion by Nick and Dmitry
>   - http://mails.dpdk.org/archives/dev/2021-August/216304.html
> 
> Signed-off-by: William Tu <u9012063@gmail.com>
> ---
[...]
> diff --git a/lib/eal/freebsd/include/rte_os.h b/lib/eal/freebsd/include/rte_os.h
> index 627f0483ab..dc889e5826 100644
> --- a/lib/eal/freebsd/include/rte_os.h
> +++ b/lib/eal/freebsd/include/rte_os.h
> @@ -11,6 +11,39 @@
>   */
>  
>  #include <pthread_np.h>
> +#include <sys/queue.h>
> +
> +/* These macros are compatible with system's sys/queue.h. */
> +#define RTE_TAILQ_INIT(head) TAILQ_INIT(head)
> +#define RTE_TAILQ_HEAD(name, type) TAILQ_HEAD(name, type)
> +#define RTE_TAILQ_LAST(head, headname) TAILQ_LAST(head, headname)
> +#define RTE_TAILQ_ENTRY(type) TAILQ_ENTRY(type)
> +#define RTE_TAILQ_FIRST(head) TAILQ_FIRST(head)
> +#define RTE_TAILQ_EMPTY(head) TAILQ_EMPTY(head)
> +#define RTE_TAILQ_NEXT(elem, field) TAILQ_NEXT(elem, field)
> +#define RTE_TAILQ_HEAD_INITIALIZER(head) TAILQ_HEAD_INITIALIZER(head)
> +#define RTE_TAILQ_FOREACH(var, head, field) TAILQ_FOREACH(var, head, field)
> +#define RTE_TAILQ_INSERT_TAIL(head, elm, field) \
> +	TAILQ_INSERT_TAIL(head, elm, field)
> +#define RTE_TAILQ_REMOVE(head, elm, field) TAILQ_REMOVE(head, elm, field)
> +#define RTE_TAILQ_INSERT_BEFORE(listelm, elm, field) \
> +	TAILQ_INSERT_BEFORE(listelm, elm, field)
> +#define RTE_TAILQ_INSERT_AFTER(head, listelm, elm, field) \
> +	TAILQ_INSERT_AFTER(head, listelm, elm, field)
> +#define RTE_TAILQ_INSERT_HEAD(head, elm, field) \
> +	TAILQ_INSERT_HEAD(head, elm, field)
> +
> +#define RTE_STAILQ_HEAD(name, type) STAILQ_HEAD(name, type)
> +#define RTE_STAILQ_HEAD_INITIALIZER(head) STAILQ_HEAD_INITIALIZER(head)
> +#define RTE_STAILQ_ENTRY(type) STAILQ_ENTRY(type)

Most of these macros are not used in public headers and are not needed.
The idea is that TAILQ_* macros from sys/queue.h can be used in C files
with variables declared with RTE_TAILQ_HEAD/ENTRY in public headers.
Needed macros:
	RTE_TAILQ_HEAD
	RTE_TAILQ_ENTRY
	RTE_TAILQ_FOREACH
	RTE_TAILQ_FIRST (for RTE_TAILQ_FOREACH_SAFE only)
	RTE_TAILQ_NEXT (ditto)
	RTE_STAILQ_HEAD
	RTE_STAILQ_ENTRY

> +
> +/* This is not defined in sys/queue.h */
> +#ifndef TAILQ_FOREACH_SAFE
> +#define TAILQ_FOREACH_SAFE(var, head, field, tvar)		\
> +	for ((var) = RTE_TAILQ_FIRST((head));			\
> +	    (var) && ((tvar) = RTE_TAILQ_NEXT((var), field), 1);	\
> +	    (var) = (tvar))
> +#endif

Please simply change the three usages of TAILQ_FOREACH_SAFE to
RTE_TAILQ_FOREACH_SAFE and remove this one. It cannot be placed in rte_os.h,
because rte_os.h is public and it must not export non-RTE symbols.

All comments to this file obviously apply to Linux version as well.

>  
>  typedef cpuset_t rte_cpuset_t;
>  #define RTE_HAS_CPUSET
[...]
> diff --git a/lib/eal/windows/include/rte_os.h b/lib/eal/windows/include/rte_os.h
> index 66c711d458..d0935c5003 100644
> --- a/lib/eal/windows/include/rte_os.h
> +++ b/lib/eal/windows/include/rte_os.h
> @@ -18,6 +18,144 @@
>  extern "C" {
>  #endif
>  
> +#ifdef QUEUE_MACRO_DEBUG_TRACE

IMO we all these debugging macros should be removed from this header,
including their use in user-facing macros.
They are implementation detail for <sys/queue.h> developers.

> +/* Store the last 2 places the queue element or head was altered */
> +struct qm_trace {
> +	unsigned long	 lastline;
> +	unsigned long	 prevline;
> +	const char	*lastfile;
> +	const char	*prevfile;
> +};
> +
> +/**
> + * These macros are compatible with the sys/queue.h provided
> + * at DPDK source code.
> + */
[...]
> +
> +#define	QMD_TAILQ_CHECK_HEAD(head, field)
> +#define	QMD_TAILQ_CHECK_TAIL(head, headname)
> +#define	QMD_TAILQ_CHECK_NEXT(elm, field)
> +#define	QMD_TAILQ_CHECK_PREV(elm, field)

Redundant empty lines below.

> +
> +
> +#define	RTE_TAILQ_EMPTY(head)	((head)->tqh_first == NULL)
> +
> +#define	RTE_TAILQ_FIRST(head)	((head)->tqh_first)
> +
> +#define	RTE_TAILQ_INIT(head) do {					\

I suggest removing all spaces but one before the backslash
so that you don't need to manually align.
At least please keep the lines within 80 characters.

> +	RTE_TAILQ_FIRST((head)) = NULL;					\
> +	(head)->tqh_last = &RTE_TAILQ_FIRST((head));			\
> +	QMD_TRACE_HEAD(head);						\
> +} while (0)
[...]