doc: announce API changes for Windows compatibility
authorDmitry Kozlyuk <dmitry.kozliuk@gmail.com>
Wed, 21 Jul 2021 19:55:57 +0000 (22:55 +0300)
committerThomas Monjalon <thomas@monjalon.net>
Mon, 2 Aug 2021 17:29:47 +0000 (19:29 +0200)
commitc4379ee599ef2f6feea914566bd494f66f7e8ad0
treeb91972a42228c1ac1398bc15294c548d4d9047d2
parent9a5c09211b3a6de69efa88429409fa5a1be5e9e3
doc: announce API changes for Windows compatibility

Windows headers define `s_addr`, `min`, and `max` as macros.
If DPDK headers are included after Windows ones, DPDK structure
definitions containing fields with these names get broken (example 1),
as well as any usage of such fields (example 2). If DPDK headers
undefined these macros, it could break consumer code (example 3).
It is proposed to rename structure fields in DPDK, because Win32 headers
are used more widely than DPDK, as a general-purpose platform compared
to domain-specific kit, and are harder to fix because of that.
Exact new names are left for further discussion.

Example 1:

    /* in DPDK public header included after windows.h */
    struct rte_type {
        int min;    /* ERROR: `min` is a macro */
    };

Example 2:

    #include <rte_ether.h>
    #include <winsock2.h>
    struct rte_ether_hdr eh;
    eh.s_addr.addr_bytes[0] = 0;    /* ERROR: `addr_s` is a macro */

Example 3:

    #include <winsock2.h>
    #include <rte_ether.h>
    struct in_addr addr;
    addr.s_addr = 0;      /* ERROR: there is no `s_addr` field,
                             and `s_addr` macro is undefined by DPDK. */

Commit 6c068dbd9fea ("net: work around s_addr macro on Windows")
modified definition of `struct rte_ether_hdr` to avoid the issue.
However, the workaround assumes `#define s_addr S_addr.S_un`
in Windows headers, which is not a part of official API.
It also complicates the definition of `struct rte_ether_hdr`.

Signed-off-by: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
Acked-by: Khoa To <khot@microsoft.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Akhil Goyal <gakhil@marvell.com>
doc/guides/rel_notes/deprecation.rst