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 9D56D41B91;
	Tue, 31 Jan 2023 19:26:15 +0100 (CET)
Received: from mails.dpdk.org (localhost [127.0.0.1])
	by mails.dpdk.org (Postfix) with ESMTP id 77BA740684;
	Tue, 31 Jan 2023 19:26:15 +0100 (CET)
Received: from linux.microsoft.com (linux.microsoft.com [13.77.154.182])
 by mails.dpdk.org (Postfix) with ESMTP id D8E154067B
 for <dev@dpdk.org>; Tue, 31 Jan 2023 19:26:13 +0100 (CET)
Received: by linux.microsoft.com (Postfix, from userid 1086)
 id 2E0CF20B3712; Tue, 31 Jan 2023 10:26:13 -0800 (PST)
DKIM-Filter: OpenDKIM Filter v2.11.0 linux.microsoft.com 2E0CF20B3712
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linux.microsoft.com;
 s=default; t=1675189573;
 bh=G3hVPJDDeHH4cNsnRdZo1AMko8+UpZaAXrSGNzakI80=;
 h=Date:From:To:Cc:Subject:References:In-Reply-To:From;
 b=QlWkaZhMbiw3Nj38Ar8rq0wTHeAxQnchp2qBc/9Kn64c/e1Duq7IVekRwGK7wPKZm
 JSBHcP2x6i6qRUBvvzTjXDTDrlR1bPdUZ70wMC3WOqPqXccIFV4xTCL80iuO8NqSdP
 pB8IdD765s0YHzI3/DpxXEVVfJuFAuYW4F6wcYa0=
Date: Tue, 31 Jan 2023 10:26:13 -0800
From: Tyler Retzlaff <roretzla@linux.microsoft.com>
To: Morten =?iso-8859-1?Q?Br=F8rup?= <mb@smartsharesystems.com>
Cc: David Marchand <david.marchand@redhat.com>, thomas@monjalon.net,
 bruce.richardson@intel.com, Ferruh Yigit <ferruh.yigit@amd.com>,
 dev@dpdk.org, rmody@marvell.com, timothy.mcdaniel@intel.com,
 matan@nvidia.com, viacheslavo@nvidia.com, ruifeng.wang@arm.com,
 zhoumin@loongson.cn, drc@linux.vnet.ibm.com, kda@semihalf.com,
 konstantin.v.ananyev@yandex.ru, stephen@networkplumber.org
Subject: Re: [PATCH v7 4/4] eal: add nonnull and access function attributes
Message-ID: <20230131182613.GB11223@linuxonhyperv3.guj3yctzbm1etfxqx2vob5hsef.xx.internal.cloudapp.net>
References: <20221202153432.131023-1-mb@smartsharesystems.com>
 <20230116130724.50277-1-mb@smartsharesystems.com>
 <20230116130724.50277-4-mb@smartsharesystems.com>
 <b1930d00-4e9c-00d9-5f49-d8fe2c559e8f@amd.com>
 <98CBD80474FA8B44BF855DF32C47DC35D8767B@smartserver.smartshare.dk>
 <20230117211656.GA30892@linuxonhyperv3.guj3yctzbm1etfxqx2vob5hsef.xx.internal.cloudapp.net>
 <98CBD80474FA8B44BF855DF32C47DC35D87683@smartserver.smartshare.dk>
 <CAJFAV8yduWRWYN_6Qg2RGKw9geYu1SopH5cxAmCKX2r1w2LqEw@mail.gmail.com>
 <98CBD80474FA8B44BF855DF32C47DC35D876DA@smartserver.smartshare.dk>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <98CBD80474FA8B44BF855DF32C47DC35D876DA@smartserver.smartshare.dk>
User-Agent: Mutt/1.5.21 (2010-09-15)
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

On Tue, Jan 31, 2023 at 01:23:34PM +0100, Morten Brørup wrote:
> > From: David Marchand [mailto:david.marchand@redhat.com]
> > Sent: Tuesday, 31 January 2023 12.15
> > 
> > On Wed, Jan 18, 2023 at 9:31 AM Morten Brørup
> > <mb@smartsharesystems.com> wrote:
> > >
> > > +To: Thomas & David, you probably have some opinions on this too!
> > >
> > > > From: Tyler Retzlaff [mailto:roretzla@linux.microsoft.com]
> > > > Sent: Tuesday, 17 January 2023 22.17
> > > >
> > > > On Tue, Jan 17, 2023 at 09:19:22AM +0100, Morten Brørup wrote:
> > > > > > From: Ferruh Yigit [mailto:ferruh.yigit@amd.com]
> > > > > > Sent: Monday, 16 January 2023 18.02
> > > > > >
> > > > > > On 1/16/2023 1:07 PM, Morten Brørup wrote:
> > > > > > > Add nonnull function attribute to help the compiler detect a
> > NULL
> > > > > > > pointer being passed to a function not accepting NULL
> > pointers as
> > > > an
> > > > > > > argument at build time.
> > > > > > >
> > > > > > > Add access function attributes to tell the compiler how a
> > > > function
> > > > > > > accesses memory pointed to by its pointer arguments.
> > > > > > >
> > > > > > > Add these attributes to the rte_memcpy() function, as the
> > first
> > > > in
> > > > > > > hopefully many to come.
> > > > > > >
> > > > > > > Signed-off-by: Morten Brørup <mb@smartsharesystems.com>
> > > > > > > Acked-by: Tyler Retzlaff <roretzla@linux.microsoft.com>
> > > > > > > Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com>
> > > > > > > ---
> > > > >
> > > > > [...]
> > > > >
> > > > > > > +/**
> > > > > > > + * Tells compiler that the pointer arguments must be non-
> > null.
> > > > > > > + *
> > > > > > > + * @param ...
> > > > > > > + *    Comma separated list of parameter indexes of pointer
> > > > > > arguments.
> > > > > > > + */
> > > > > > > +#if defined(RTE_CC_GCC) || defined(RTE_CC_CLANG)
> > > > > > > +#define __rte_nonnull_params(...) \
> > > > > > > +       __attribute__((nonnull(__VA_ARGS__)))
> > > > > > > +#else
> > > > > > > +#define __rte_nonnull_params(...)
> > > > > > > +#endif
> > > > > > > +
> > > > > >
> > > > > > What do you think to have a namespace for macros like
> > > > > > '__rte_param_xxx',
> > > > > > so name macros as:
> > > > > > __rte_param_nonull
> > > > > > __rte_param_read_only
> > > > > > __rte_param_write_only
> > > > > >
> > > > > > No strong opinion, it just feels tidier this way
> > > > >
> > > > > Being a proponent of the world_country_city naming scheme myself,
> > I
> > > > would usually agree with this proposal.
> > > > >
> > > > > However, in the future, we might add macros without _param for
> > use
> > > > along with the function parameters, e.g.:
> > > > >
> > > > > int foo(int bar __rte_nonnull __rte_read_only);
> > > > >
> > > > > So I decided for this order in the names (treating
> > > > nonnull/access_mode as "country" and param/params as "city"), also
> > > > somewhat looking at the __rte_deprecated and
> > __rte_deprecated_msg(msg)
> > > > macros.
> > > > >
> > > > > I have no strong preference either, so if anyone does, please
> > speak
> > > > up.
> > > > >
> > > > > Slightly related, also note this:
> > > > >
> > > > > The nonnull macro is plural (_params), because it can take
> > multiple
> > > > pointer parameter indexes.
> > > > > The access mode macros are singular (_param), because they only
> > take
> > > > one pointer parameter index, and the optional size parameter index.
> > > > >
> > > > > I considered splitting up the access mode macros even more,
> > making
> > > > two variants of each, e.g. __rte_read_only_param(ptr_index) and
> > > > __rte_read_only_param_size(ptr_index, size_index), but concluded
> > that
> > > > it would be excruciatingly verbose. The only purpose would be to
> > reduce
> > > > the risk of using them incorrectly. I decided against it, thinking
> > that
> > > > any developer clever enough to use these macros is also clever
> > enough
> > > > to understand how to use them (or at least read their parameter
> > > > descriptions to learn how).
> > > > >
> > > >
> > > > microsoft also has a tool & annotation vehicle for this type of
> > stuff.
> > > > this discussion has caused me to wonder what happens if we would
> > like
> > > > to
> > > > add additional annotations for other tools. just load on the
> > > > annotations
> > > > and expand them empty conditionally?
> > > >
> > > > https://learn.microsoft.com/en-us/cpp/code-quality/using-sal-
> > > > annotations-to-reduce-c-cpp-code-defects?view=msvc-170
> > > >
> > > > anyway, just a thought. no serious response required here.
> > >
> > > Excellent input, Tyler!
> > >
> > > If we want DPDK to be considered truly cross-platform, and not treat
> > non-Linux/non-GCC as second class citizens, we need to discuss this.
> > >
> > > Microsoft's Source Code Annotation Language (SAL) seems very good,
> > based on its finer granularity than GCC's attributes (which in
> > comparison seem added as an afterthought, not cleanly structured like
> > SAL). I have only skimmed the documentation, but that is my immediate
> > impression of it.
> > >
> > > SAL uses a completely different syntax than GCC attributes, and
> > Microsoft happens to also use memcpy() as an example in the
> > documentation referred to:
> > >
> > > void * memcpy(
> > >    _Out_writes_bytes_all_(count) void *dest,
> > >    _In_reads_bytes_(count) const void *src,
> > >    size_t count
> > > );
> 
> Stephen had bad experiences with SAL, so let's just consider the SAL memcpy() example a reference only, showing how the syntax of annotations can differ very much between build systems.

yes, if we are in a position to use annotations today that work with
clang/gcc then let's do that even if they aren't compatible with SAL.
so long as they expand empty when not using clang/gcc we can defer discussion
about other tools like SAL.

> 
> > >
> > > Going back to how we can handle this in DPDK, we can either:
> > >
> > > 1. Not annotate the functions at all, and miss out on finding the
> > errors for us.
> > 
> > Seeing how clang safety checks helped me catch bugs, that would be a
> > pity.
> > 
> > >
> > > 2. Invent our own language (or find something existing) for function
> > headers, and use a parser to convert them to compiler specific C/C++
> > headers when building the code.
> > 
> > Argh, no.
> > 
> > >
> > > 3a. Keep loading on attributes, with empty macros for unsupported
> > compilers.
> > >
> > > 3b. Keep loading on attributes, with empty macros for unsupported
> > compilers. But limit ourselves to GCC/Clang style attributes.
> > >
> > > 3c. Keep loading on attributes, with empty macros for unsupported
> > compilers. But limit ourselves to Microsoft SAL style attributes.
> > >
> > > 3d. Keep loading on attributes, with empty macros for unsupported
> > compilers. But limit ourselves to the most relevant attributes, using
> > performance and/or bug detection as criteria when considering
> > relevance.
> > >
> > > I am strongly against both 1 and 2.
> > >
> > > If bug detection is the primary driver, we could stick with either 3b
> > or 3c (i.e. only target one specific build environment) and rely on the
> > DPDK CI for detecting bugs. But then application developers would not
> > benefit, because they don't run their code through the DPDK CI. So I am
> > also against this.
> > >
> > > I think 3d (keep loading on attributes, but only the most relevant
> > ones) is the best choice.
> > >
> > > GCC/Clang style attributes are already supported as macros prefixed
> > by __rte, so let's not change the way we do that.
> > >
> > > Regarding the Microsoft SAL, I suppose Microsoft already chose
> > annotation names to avoid collisions, so we could consider using those
> > exact names (i.e. without __rte prefix), and define empty macros for
> > non-Microsoft compilers. This would allow using Microsoft SAL
> > annotations directly in the DPDK code.
> > >
> > 
> > I have a bit of trouble understanding the difference between 3a and
> > 3d.. 3a would be about accepting any annotation?
> 
> Correct.
> 
> > 
> > 3d is the best option as it is not changing anything to what we were
> > doing so far: we evaluate the pros and cons of each annotations/tools,
> > case per case.
> 
> Agree!
>