From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
by inbox.dpdk.org (Postfix) with ESMTP id C6102A0C46;
Wed, 21 Jul 2021 21:56:12 +0200 (CEST)
Received: from [217.70.189.124] (localhost [127.0.0.1])
by mails.dpdk.org (Postfix) with ESMTP id BAEE940DF7;
Wed, 21 Jul 2021 21:56:08 +0200 (CEST)
Received: from mail-lj1-f181.google.com (mail-lj1-f181.google.com
[209.85.208.181])
by mails.dpdk.org (Postfix) with ESMTP id B1CF84014D
for <dev@dpdk.org>; Wed, 21 Jul 2021 21:56:06 +0200 (CEST)
Received: by mail-lj1-f181.google.com with SMTP id c23so4480583ljr.8
for <dev@dpdk.org>; Wed, 21 Jul 2021 12:56:06 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025;
h=from:to:cc:subject:date:message-id:in-reply-to:references
:mime-version:content-transfer-encoding;
bh=8yPILbLpNSk8gguMacoVWXmVyjRd3Qoi+gSZH0LQ9ak=;
b=n+u7NL6viNX/LJSJkb4sBxZdlHrank4Mm5Lx+VwXCYtReII85Ks01kN5IMqqdhurFN
Rdy6NN++ptXu/roCDTAsTQ8t06Jyz4jtYJIGTNXJoXzJpP13ZsZuUsuFcrDFJqG6AikG
DVFRmI5G6dyhqfKf6le/ODoeeUsQAd6ONbKsfQqpx4+/dfEXyjjYFlF2dNucm6lCG0Yv
LeGr41k4zAG7eoE6ytkyvRQsKeijA5AF+z4AifORsawN8NJMUw3+Qn0se4guXuNEtTxX
gxcDwnTKEuxhZsbD+I+9bp/IV6AGOian38/PPb3lNfRnVKuu9+j+IyHVouF4tWSPZt9V
XySQ==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20161025;
h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to
:references:mime-version:content-transfer-encoding;
bh=8yPILbLpNSk8gguMacoVWXmVyjRd3Qoi+gSZH0LQ9ak=;
b=kSPYlTHVKbRKwhN1BOw3HEFiL/+jbrkeRyDYN8XFzX7NcoIHI4Nz7DaJ4SzGSBmx7Y
awVzGKQ5FuL4QeqN8h5FrtoZnNxhbI+PQUTIdFNwTfsYp6JAZdO4od5kUoW2EHKBEeyh
HC4XAyEI/vbL9EgYAFb1L8+x0XU8oEuJAbP8SwqG7oCsmPVA02yA4Y3tX3NVAhy+llkZ
epcuWDn+CFI1Yh1tA5t79fauWR6sheXOA0o65IgaFUAgzwZ/DNoyJfyrBiDa93NWVvcG
+KS8zW8x2clBaJSW5gA1ovMkoIYRiy8c++DumYzRPSW+zRUsrLqDLdYdxCGfEtz8/Kic
fNuQ==
X-Gm-Message-State: AOAM533nrcPxAIbyBhHamZhArHvO/ZD9K+fGY4SuYdRdCsMVtoICQwcy
6/hvkKY5NZ4GRE0plZlrvct8z+R9+Zh18A==
X-Google-Smtp-Source: ABdhPJztoxikNgEufVU6rG137Y/res85gNslJ/f2StbkD+crsluzXHHtza/0E9qaGiDc7DQoXbsk7Q==
X-Received: by 2002:a2e:a885:: with SMTP id m5mr26086803ljq.288.1626897366006;
Wed, 21 Jul 2021 12:56:06 -0700 (PDT)
Received: from sovereign.. (broadband-37-110-65-23.ip.moscow.rt.ru.
[37.110.65.23])
by smtp.gmail.com with ESMTPSA id x17sm2895163ljx.75.2021.07.21.12.56.05
(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
Wed, 21 Jul 2021 12:56:05 -0700 (PDT)
From: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
To: dev@dpdk.org
Cc: Ferruh Yigit <ferruh.yigit@intel.com>, Akhil Goyal <gakhil@marvell.com>,
Fiona Trahe <fiona.trahe@intel.com>, Neil Horman <nhorman@tuxdriver.com>,
Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>, Khoa To <khot@microsoft.com>,
Ray Kinsella <mdr@ashroe.eu>
Date: Wed, 21 Jul 2021 22:55:57 +0300
Message-Id: <20210721195557.762726-2-dmitry.kozliuk@gmail.com>
X-Mailer: git-send-email 2.29.3
In-Reply-To: <20210721195557.762726-1-dmitry.kozliuk@gmail.com>
References: <20210520184254.16790-1-dmitry.kozliuk@gmail.com>
<20210721195557.762726-1-dmitry.kozliuk@gmail.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Subject: [dpdk-dev] [PATCH v4] doc: announce API changes for Windows
compatibility
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Sender: "dev" <dev-bounces@dpdk.org>
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>
---
v4: improve wording (Akhil).
v3: fix typos (Ferruh), remove naming speculation,
replace workaround snippet with commit reference.
doc/guides/rel_notes/deprecation.rst | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
index 9584d6bfd7..cc6e8db92c 100644
--- a/doc/guides/rel_notes/deprecation.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -147,3 +147,12 @@ Deprecation Notices
* cmdline: ``cmdline`` structure will be made opaque to hide platform-specific
content. On Linux and FreeBSD, supported prior to DPDK 20.11,
original structure will be kept until DPDK 21.11.
+
+* net: ``s_addr`` and ``d_addr`` fields of ``rte_ether_hdr`` structure
+ will be renamed in DPDK 21.11 to avoid conflict with Windows Sockets headers.
+
+* compressdev: ``min`` and ``max`` fields of ``rte_param_log2_range`` structure
+ will be renamed in DPDK 21.11 to avoid conflict with Windows Sockets headers.
+
+* cryptodev: ``min`` and ``max`` fields of ``rte_crypto_param_range`` structure
+ will be renamed in DPDK 21.11 to avoid conflict with Windows Sockets headers.
--
2.29.3