Re: [PATCH] Documentation: syscalls: add a note about ABI-agnostic types
On Wed, Apr 14, 2021 at 03:38:47PM +0200, Christian Brauner wrote:
> On Wed, Apr 14, 2021 at 12:46:01PM +0300, Mike Rapoport wrote:
> > On Wed, Apr 14, 2021 at 10:46:05AM +0200, Christian Brauner wrote:
> > > On Wed, Apr 14, 2021 at 08:14:22AM +0200, Mauro Carvalho Chehab wrote:
> > > > Em Tue, 13 Apr 2021 21:40:20 -0700
> > > > Yury Norov escreveu:
> > > >
> > > > > Ping?
> > > > >
> > > > > On Fri, Apr 09, 2021 at 01:43:04PM -0700, Yury Norov wrote:
> > > > > > Recently added memfd_secret() syscall had a flags parameter passed
> > > > > > as unsigned long, which requires creation of compat entry for it.
> > > > > > It was possible to change the type of flags to unsigned int and so
> > > > > > avoid bothering with compat layer.
> > > > > >
> > > > > > https://www.spinics.net/lists/linux-mm/msg251550.html
> > > > > >
> > > > > > Documentation/process/adding-syscalls.rst doesn't point clearly
> > > > > > about
> > > > > > preference of ABI-agnostic types. This patch adds such notification.
> > > > > >
> > > > > > Signed-off-by: Yury Norov
> > > > > > ---
> > > > > > Documentation/process/adding-syscalls.rst | 7 +++
> > > > > > 1 file changed, 7 insertions(+)
> > > > > >
> > > > > > diff --git a/Documentation/process/adding-syscalls.rst
> > > > > > b/Documentation/process/adding-syscalls.rst
> > > > > > index 9af35f4ec728..46add16edf14 100644
> > > > > > --- a/Documentation/process/adding-syscalls.rst
> > > > > > +++ b/Documentation/process/adding-syscalls.rst
> > > > > > @@ -172,6 +172,13 @@ arguments (i.e. parameter 1, 3, 5), to allow
> > > > > > use of contiguous pairs of 32-bit
> > > > > > registers. (This concern does not apply if the arguments are part
> > > > > > of a
> > > > > > structure that's passed in by pointer.)
> > > > > >
> > > > > > +Whenever possible, try to use ABI-agnostic types for passing
> > > > > > parameters to
> > > > > > +a syscall in order to avoid creating compat entry for it. Linux
> > > > > > supports two
> > > > > > +ABI models - ILP32 and LP64.
> > > >
> > > > > > + The types like ``void *``, ``long``, ``size_t``,
> > > > > > +``off_t`` have different size in those ABIs;
> > > >
> > > > In the case of pointers, the best is to use __u64. The pointer can then
> > > > be read on Kernelspace with something like this:
> > > >
> > > > static inline void __user *media_get_uptr(__u64 arg)
> > > > {
> > > > return (void __user *)(uintptr_t)arg;
> > > > }
> > > >
> > > >
> > > > > > types like ``char`` and ``int``
> > > > > > +have the same size and don't require a compat layer support. For
> > > > > > flags, it's
> > > > > > +always better to use ``unsigned int``.
> > > > > > +
> > > >
> > > > I don't think this is true for all compilers on userspace, as the C
> > > > standard doesn't define how many bits an int/unsigned int has.
> > > > So, even if this is today's reality, things may change in the future.
> > > >
> > > > For instance, I remember we had to replace "int" and "enum" by "__u32"
> > > > and "long" by "__u64" at the media uAPI in the past, when we start
> > > > seeing x86_64 Kernels with 32-bits userspace and when cameras started
> > > > being supported on arm32.
> > > >
> > > > We did have some real bugs with "enum", as, on that time, some
> > > > compilers (gcc, I guess) were optimizing them to have less than
> > > > 32 bits on certain architectures, when it fits.
> > >
> > > Fwiw, Aleksa and I have written extended syscall documentation
> > > documenting the agreement that we came to in a dedicated session with a
> > > wide range of kernel folks during Linux Plumbers last year. We simply
> > > never had time to actually send this series but fwiw here it is. It also
> > > mentions the use of correct types. If people feel it's worth it I can
> > > send as a proper series:
> >
> > Yes, please.
>
> Ok, I'll try to fix the commit messages and send it out.
>
> Christian
Could you pelease keep me in CC in your submission?
Re: [PATCH] Documentation: syscalls: add a note about ABI-agnostic types
On Wed, Apr 14, 2021 at 08:14:22AM +0200, Mauro Carvalho Chehab wrote:
> Em Tue, 13 Apr 2021 21:40:20 -0700
> Yury Norov escreveu:
>
> > Ping?
> >
> > On Fri, Apr 09, 2021 at 01:43:04PM -0700, Yury Norov wrote:
> > > Recently added memfd_secret() syscall had a flags parameter passed
> > > as unsigned long, which requires creation of compat entry for it.
> > > It was possible to change the type of flags to unsigned int and so
> > > avoid bothering with compat layer.
> > >
> > > https://www.spinics.net/lists/linux-mm/msg251550.html
> > >
> > > Documentation/process/adding-syscalls.rst doesn't point clearly about
> > > preference of ABI-agnostic types. This patch adds such notification.
> > >
> > > Signed-off-by: Yury Norov
> > > ---
> > > Documentation/process/adding-syscalls.rst | 7 +++
> > > 1 file changed, 7 insertions(+)
> > >
> > > diff --git a/Documentation/process/adding-syscalls.rst
> > > b/Documentation/process/adding-syscalls.rst
> > > index 9af35f4ec728..46add16edf14 100644
> > > --- a/Documentation/process/adding-syscalls.rst
> > > +++ b/Documentation/process/adding-syscalls.rst
> > > @@ -172,6 +172,13 @@ arguments (i.e. parameter 1, 3, 5), to allow use of
> > > contiguous pairs of 32-bit
> > > registers. (This concern does not apply if the arguments are part of a
> > > structure that's passed in by pointer.)
> > >
> > > +Whenever possible, try to use ABI-agnostic types for passing parameters
> > > to
> > > +a syscall in order to avoid creating compat entry for it. Linux supports
> > > two
> > > +ABI models - ILP32 and LP64.
>
> > > + The types like ``void *``, ``long``, ``size_t``,
> > > +``off_t`` have different size in those ABIs;
>
> In the case of pointers, the best is to use __u64. The pointer can then
> be read on Kernelspace with something like this:
>
> static inline void __user *media_get_uptr(__u64 arg)
> {
> return (void __user *)(uintptr_t)arg;
> }
For 32-bit userspace reserving 64-bit type for pointers looks
excessive, isn't? And anyways, how could this help to prevent
malicious/broken compat userspace from passing pointers with
dirty top 32 bits?
>From what I can see, in case of compat ABI, the 'void *' args
are cast to compat_uptr_t in the compat layer, and then passed
to native handlers. Bypassing compat layer in the example above
would break consistency for a syscall.
> > > types like ``char`` and ``int``
> > > +have the same size and don't require a compat layer support. For flags,
> > > it's
> > > +always better to use ``unsigned int``.
> > > +
>
> I don't think this is true for all compilers on userspace, as the C
> standard doesn't define how many bits an int/unsigned int has.
> So, even if this is today's reality, things may change in the future.
Agree, it's not a standard in C, but this is pretty much a standard in
Linux. Introducing a new ABI nor ILP32, neither LP64 would require huge
amount of work, especially on a maintenance level, and I bet it will be
blocked by Arnd. :) In practice it's correct to recommend using unsigned
int for flags now, and if in future someone will introduce new ABI, it
will be his responsibility to explain us how to design syscalls in a
compatible and unified way.
> For instance, I remember we had to replace "int" and "enum" by "__u32"
> and "long" by "__u64" at the media uAPI in the past, when we start
> seeing x86_64 Kernels with 32-bits userspace and when cameras started
> being supported on arm32.
>
> We did have some real bugs with "enum", as, on that time, some
> compilers (gcc, I guess) were optimizing them to have less than
> 32 bits on certain architectures, when it fits.
I think this example agrees with what I said - if userspace has
nonstandard ABI, it has to use kernel types to communicate with
kernel, which are exposed as __u32-style typedefs. For me, it's
a compatibility layer implemented in userspace.
This patch is about good practices for standard 32, 64 and compat
ABIs supported by kernel.
(Or if I missed you point, can you please explain in more details?)
Thanks,
Yury
Re: [PATCH] Documentation: syscalls: add a note about ABI-agnostic types
On Wed, Apr 14, 2021 at 12:46:01PM +0300, Mike Rapoport wrote:
> On Wed, Apr 14, 2021 at 10:46:05AM +0200, Christian Brauner wrote:
> > On Wed, Apr 14, 2021 at 08:14:22AM +0200, Mauro Carvalho Chehab wrote:
> > > Em Tue, 13 Apr 2021 21:40:20 -0700
> > > Yury Norov escreveu:
> > >
> > > > Ping?
> > > >
> > > > On Fri, Apr 09, 2021 at 01:43:04PM -0700, Yury Norov wrote:
> > > > > Recently added memfd_secret() syscall had a flags parameter passed
> > > > > as unsigned long, which requires creation of compat entry for it.
> > > > > It was possible to change the type of flags to unsigned int and so
> > > > > avoid bothering with compat layer.
> > > > >
> > > > > https://www.spinics.net/lists/linux-mm/msg251550.html
> > > > >
> > > > > Documentation/process/adding-syscalls.rst doesn't point clearly about
> > > > > preference of ABI-agnostic types. This patch adds such notification.
> > > > >
> > > > > Signed-off-by: Yury Norov
> > > > > ---
> > > > > Documentation/process/adding-syscalls.rst | 7 +++
> > > > > 1 file changed, 7 insertions(+)
> > > > >
> > > > > diff --git a/Documentation/process/adding-syscalls.rst
> > > > > b/Documentation/process/adding-syscalls.rst
> > > > > index 9af35f4ec728..46add16edf14 100644
> > > > > --- a/Documentation/process/adding-syscalls.rst
> > > > > +++ b/Documentation/process/adding-syscalls.rst
> > > > > @@ -172,6 +172,13 @@ arguments (i.e. parameter 1, 3, 5), to allow use
> > > > > of contiguous pairs of 32-bit
> > > > > registers. (This concern does not apply if the arguments are part
> > > > > of a
> > > > > structure that's passed in by pointer.)
> > > > >
> > > > > +Whenever possible, try to use ABI-agnostic types for passing
> > > > > parameters to
> > > > > +a syscall in order to avoid creating compat entry for it. Linux
> > > > > supports two
> > > > > +ABI models - ILP32 and LP64.
> > >
> > > > > + The types like ``void *``, ``long``, ``size_t``,
> > > > > +``off_t`` have different size in those ABIs;
> > >
> > > In the case of pointers, the best is to use __u64. The pointer can then
> > > be read on Kernelspace with something like this:
> > >
> > > static inline void __user *media_get_uptr(__u64 arg)
> > > {
> > > return (void __user *)(uintptr_t)arg;
> > > }
> > >
> > >
> > > > > types like ``char`` and ``int``
> > > > > +have the same size and don't require a compat layer support. For
> > > > > flags, it's
> > > > > +always better to use ``unsigned int``.
> > > > > +
> > >
> > > I don't think this is true for all compilers on userspace, as the C
> > > standard doesn't define how many bits an int/unsigned int has.
> > > So, even if this is today's reality, things may change in the future.
> > >
> > > For instance, I remember we had to replace "int" and "enum" by "__u32"
> > > and "long" by "__u64" at the media uAPI in the past, when we start
> > > seeing x86_64 Kernels with 32-bits userspace and when cameras started
> > > being supported on arm32.
> > >
> > > We did have some real bugs with "enum", as, on that time, some
> > > compilers (gcc, I guess) were optimizing them to have less than
> > > 32 bits on certain architectures, when it fits.
> >
> > Fwiw, Aleksa and I have written extended syscall documentation
> > documenting the agreement that we came to in a dedicated session with a
> > wide range of kernel folks during Linux Plumbers last year. We simply
> > never had time to actually send this series but fwiw here it is. It also
> > mentions the use of correct types. If people feel it's worth it I can
> > send as a proper series:
>
> Yes, please.
Ok, I'll try to fix the commit messages and send it out.
Christian
Re: [PATCH] Documentation: syscalls: add a note about ABI-agnostic types
On Wed, Apr 14, 2021 at 10:46:05AM +0200, Christian Brauner wrote:
> On Wed, Apr 14, 2021 at 08:14:22AM +0200, Mauro Carvalho Chehab wrote:
> > Em Tue, 13 Apr 2021 21:40:20 -0700
> > Yury Norov escreveu:
> >
> > > Ping?
> > >
> > > On Fri, Apr 09, 2021 at 01:43:04PM -0700, Yury Norov wrote:
> > > > Recently added memfd_secret() syscall had a flags parameter passed
> > > > as unsigned long, which requires creation of compat entry for it.
> > > > It was possible to change the type of flags to unsigned int and so
> > > > avoid bothering with compat layer.
> > > >
> > > > https://www.spinics.net/lists/linux-mm/msg251550.html
> > > >
> > > > Documentation/process/adding-syscalls.rst doesn't point clearly about
> > > > preference of ABI-agnostic types. This patch adds such notification.
> > > >
> > > > Signed-off-by: Yury Norov
> > > > ---
> > > > Documentation/process/adding-syscalls.rst | 7 +++
> > > > 1 file changed, 7 insertions(+)
> > > >
> > > > diff --git a/Documentation/process/adding-syscalls.rst
> > > > b/Documentation/process/adding-syscalls.rst
> > > > index 9af35f4ec728..46add16edf14 100644
> > > > --- a/Documentation/process/adding-syscalls.rst
> > > > +++ b/Documentation/process/adding-syscalls.rst
> > > > @@ -172,6 +172,13 @@ arguments (i.e. parameter 1, 3, 5), to allow use
> > > > of contiguous pairs of 32-bit
> > > > registers. (This concern does not apply if the arguments are part of a
> > > > structure that's passed in by pointer.)
> > > >
> > > > +Whenever possible, try to use ABI-agnostic types for passing
> > > > parameters to
> > > > +a syscall in order to avoid creating compat entry for it. Linux
> > > > supports two
> > > > +ABI models - ILP32 and LP64.
> >
> > > > + The types like ``void *``, ``long``, ``size_t``,
> > > > +``off_t`` have different size in those ABIs;
> >
> > In the case of pointers, the best is to use __u64. The pointer can then
> > be read on Kernelspace with something like this:
> >
> > static inline void __user *media_get_uptr(__u64 arg)
> > {
> > return (void __user *)(uintptr_t)arg;
> > }
> >
> >
> > > > types like ``char`` and ``int``
> > > > +have the same size and don't require a compat layer support. For
> > > > flags, it's
> > > > +always better to use ``unsigned int``.
> > > > +
> >
> > I don't think this is true for all compilers on userspace, as the C
> > standard doesn't define how many bits an int/unsigned int has.
> > So, even if this is today's reality, things may change in the future.
> >
> > For instance, I remember we had to replace "int" and "enum" by "__u32"
> > and "long" by "__u64" at the media uAPI in the past, when we start
> > seeing x86_64 Kernels with 32-bits userspace and when cameras started
> > being supported on arm32.
> >
> > We did have some real bugs with "enum", as, on that time, some
> > compilers (gcc, I guess) were optimizing them to have less than
> > 32 bits on certain architectures, when it fits.
>
> Fwiw, Aleksa and I have written extended syscall documentation
> documenting the agreement that we came to in a dedicated session with a
> wide range of kernel folks during Linux Plumbers last year. We simply
> never had time to actually send this series but fwiw here it is. It also
> mentions the use of correct types. If people feel it's worth it I can
> send as a proper series:
Yes, please.
> From 9035258aaa23c5e1bb5bc2242f97221a3e5b9a87 Mon Sep 17 00:00:00 2001
> From: Christian Brauner
> Date: Fri, 4 Sep 2020 14:27:47 +0200
> Subject: [PATCH 1/6] docs: split extensibility section into two subsections
...
--
Sincerely yours,
Mike.
Re: [PATCH] Documentation: syscalls: add a note about ABI-agnostic types
On Wed, Apr 14, 2021 at 08:14:22AM +0200, Mauro Carvalho Chehab wrote:
> Em Tue, 13 Apr 2021 21:40:20 -0700
> Yury Norov escreveu:
>
> > Ping?
> >
> > On Fri, Apr 09, 2021 at 01:43:04PM -0700, Yury Norov wrote:
> > > Recently added memfd_secret() syscall had a flags parameter passed
> > > as unsigned long, which requires creation of compat entry for it.
> > > It was possible to change the type of flags to unsigned int and so
> > > avoid bothering with compat layer.
> > >
> > > https://www.spinics.net/lists/linux-mm/msg251550.html
> > >
> > > Documentation/process/adding-syscalls.rst doesn't point clearly about
> > > preference of ABI-agnostic types. This patch adds such notification.
> > >
> > > Signed-off-by: Yury Norov
> > > ---
> > > Documentation/process/adding-syscalls.rst | 7 +++
> > > 1 file changed, 7 insertions(+)
> > >
> > > diff --git a/Documentation/process/adding-syscalls.rst
> > > b/Documentation/process/adding-syscalls.rst
> > > index 9af35f4ec728..46add16edf14 100644
> > > --- a/Documentation/process/adding-syscalls.rst
> > > +++ b/Documentation/process/adding-syscalls.rst
> > > @@ -172,6 +172,13 @@ arguments (i.e. parameter 1, 3, 5), to allow use of
> > > contiguous pairs of 32-bit
> > > registers. (This concern does not apply if the arguments are part of a
> > > structure that's passed in by pointer.)
> > >
> > > +Whenever possible, try to use ABI-agnostic types for passing parameters
> > > to
> > > +a syscall in order to avoid creating compat entry for it. Linux supports
> > > two
> > > +ABI models - ILP32 and LP64.
>
> > > + The types like ``void *``, ``long``, ``size_t``,
> > > +``off_t`` have different size in those ABIs;
>
> In the case of pointers, the best is to use __u64. The pointer can then
> be read on Kernelspace with something like this:
>
> static inline void __user *media_get_uptr(__u64 arg)
> {
> return (void __user *)(uintptr_t)arg;
> }
>
>
> > > types like ``char`` and ``int``
> > > +have the same size and don't require a compat layer support. For flags,
> > > it's
> > > +always better to use ``unsigned int``.
> > > +
>
> I don't think this is true for all compilers on userspace, as the C
> standard doesn't define how many bits an int/unsigned int has.
> So, even if this is today's reality, things may change in the future.
>
> For instance, I remember we had to replace "int" and "enum" by "__u32"
> and "long" by "__u64" at the media uAPI in the past, when we start
> seeing x86_64 Kernels with 32-bits userspace and when cameras started
> being supported on arm32.
>
> We did have some real bugs with "enum", as, on that time, some
> compilers (gcc, I guess) were optimizing them to have less than
> 32 bits on certain architectures, when it fits.
Fwiw, Aleksa and I have written extended syscall documentation
documenting the agreement that we came to in a dedicated session with a
wide range of kernel folks during Linux Plumbers last year. We simply
never had time to actually send this series but fwiw here it is. It also
mentions the use of correct types. If people feel it's worth it I can
send as a proper series:
>From 9035258aaa23c5e1bb5bc2242f97221a3e5b9a87 Mon Sep 17 00:00:00 2001
From: Christian Brauner
Date: Fri, 4 Sep 2020 14:27:47 +0200
Subject: [PATCH 1/6] docs: split extensibility section into two subsections
The section already explains two different formats that are available to
extend a syscall. Move each into its own subsection. This clarifies the
structure and will be useful when we extend each section in follow-up
patches.
Signed-off-by: Christian Brauner
Signed-off-by: Aleksa Sarai
Co-developed-by: Aleksa Sarai
Signed-off-by: Christian Brauner
---
Documentation/process/adding-syscalls.rst | 6 ++
1 file changed, 6 insertions(+)
diff --git a/Documentation/process/adding-syscalls.rst
b/Documentation/process/adding-syscalls.rst
index 906c47f1a9e5..3853ce57e757 100644
--- a/Documentation/process/adding-syscalls.rst
+++ b/Documentation/process/adding-syscalls.rst
@@ -65,6 +65,9 @@ together with the corresponding follow-up system calls --
``pipe``/``pipe2``, ``renameat``/``renameat2`` -- so
learn from the history of the kernel and plan for extensions from the start.)
+Baseline extensibility: adding a flag argument
+~~
+
For simpler system calls that only take a couple of arguments, the preferred
way to allow for future extensibility is to include a flags argument to the
system call. To make sure that userspace programs can safely use flags
@@ -76,6 +79,9 @@ flags, and reject the system call (with ``EINVAL``) if it
does::
(If no flags values are used yet, check that the flags argument is zero.)
+Advanced extensibility: extensible structs
+~~
+
For more sophisticated system calls that involve a larger number of arguments,
it's preferred to encapsulate the majority of the arguments into
Re: [PATCH] Documentation: syscalls: add a note about ABI-agnostic types
Em Tue, 13 Apr 2021 21:40:20 -0700
Yury Norov escreveu:
> Ping?
>
> On Fri, Apr 09, 2021 at 01:43:04PM -0700, Yury Norov wrote:
> > Recently added memfd_secret() syscall had a flags parameter passed
> > as unsigned long, which requires creation of compat entry for it.
> > It was possible to change the type of flags to unsigned int and so
> > avoid bothering with compat layer.
> >
> > https://www.spinics.net/lists/linux-mm/msg251550.html
> >
> > Documentation/process/adding-syscalls.rst doesn't point clearly about
> > preference of ABI-agnostic types. This patch adds such notification.
> >
> > Signed-off-by: Yury Norov
> > ---
> > Documentation/process/adding-syscalls.rst | 7 +++
> > 1 file changed, 7 insertions(+)
> >
> > diff --git a/Documentation/process/adding-syscalls.rst
> > b/Documentation/process/adding-syscalls.rst
> > index 9af35f4ec728..46add16edf14 100644
> > --- a/Documentation/process/adding-syscalls.rst
> > +++ b/Documentation/process/adding-syscalls.rst
> > @@ -172,6 +172,13 @@ arguments (i.e. parameter 1, 3, 5), to allow use of
> > contiguous pairs of 32-bit
> > registers. (This concern does not apply if the arguments are part of a
> > structure that's passed in by pointer.)
> >
> > +Whenever possible, try to use ABI-agnostic types for passing parameters to
> > +a syscall in order to avoid creating compat entry for it. Linux supports
> > two
> > +ABI models - ILP32 and LP64.
> > + The types like ``void *``, ``long``, ``size_t``,
> > +``off_t`` have different size in those ABIs;
In the case of pointers, the best is to use __u64. The pointer can then
be read on Kernelspace with something like this:
static inline void __user *media_get_uptr(__u64 arg)
{
return (void __user *)(uintptr_t)arg;
}
> > types like ``char`` and ``int``
> > +have the same size and don't require a compat layer support. For flags,
> > it's
> > +always better to use ``unsigned int``.
> > +
I don't think this is true for all compilers on userspace, as the C
standard doesn't define how many bits an int/unsigned int has.
So, even if this is today's reality, things may change in the future.
For instance, I remember we had to replace "int" and "enum" by "__u32"
and "long" by "__u64" at the media uAPI in the past, when we start
seeing x86_64 Kernels with 32-bits userspace and when cameras started
being supported on arm32.
We did have some real bugs with "enum", as, on that time, some
compilers (gcc, I guess) were optimizing them to have less than
32 bits on certain architectures, when it fits.
Thanks,
Mauro
Re: [PATCH] Documentation: syscalls: add a note about ABI-agnostic types
Ping? On Fri, Apr 09, 2021 at 01:43:04PM -0700, Yury Norov wrote: > Recently added memfd_secret() syscall had a flags parameter passed > as unsigned long, which requires creation of compat entry for it. > It was possible to change the type of flags to unsigned int and so > avoid bothering with compat layer. > > https://www.spinics.net/lists/linux-mm/msg251550.html > > Documentation/process/adding-syscalls.rst doesn't point clearly about > preference of ABI-agnostic types. This patch adds such notification. > > Signed-off-by: Yury Norov > --- > Documentation/process/adding-syscalls.rst | 7 +++ > 1 file changed, 7 insertions(+) > > diff --git a/Documentation/process/adding-syscalls.rst > b/Documentation/process/adding-syscalls.rst > index 9af35f4ec728..46add16edf14 100644 > --- a/Documentation/process/adding-syscalls.rst > +++ b/Documentation/process/adding-syscalls.rst > @@ -172,6 +172,13 @@ arguments (i.e. parameter 1, 3, 5), to allow use of > contiguous pairs of 32-bit > registers. (This concern does not apply if the arguments are part of a > structure that's passed in by pointer.) > > +Whenever possible, try to use ABI-agnostic types for passing parameters to > +a syscall in order to avoid creating compat entry for it. Linux supports two > +ABI models - ILP32 and LP64. The types like ``void *``, ``long``, ``size_t``, > +``off_t`` have different size in those ABIs; types like ``char`` and ``int`` > +have the same size and don't require a compat layer support. For flags, it's > +always better to use ``unsigned int``. > + > > Proposing the API > - > -- > 2.25.1
[PATCH] Documentation: syscalls: add a note about ABI-agnostic types
Recently added memfd_secret() syscall had a flags parameter passed as unsigned long, which requires creation of compat entry for it. It was possible to change the type of flags to unsigned int and so avoid bothering with compat layer. https://www.spinics.net/lists/linux-mm/msg251550.html Documentation/process/adding-syscalls.rst doesn't point clearly about preference of ABI-agnostic types. This patch adds such notification. Signed-off-by: Yury Norov --- Documentation/process/adding-syscalls.rst | 7 +++ 1 file changed, 7 insertions(+) diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst index 9af35f4ec728..46add16edf14 100644 --- a/Documentation/process/adding-syscalls.rst +++ b/Documentation/process/adding-syscalls.rst @@ -172,6 +172,13 @@ arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit registers. (This concern does not apply if the arguments are part of a structure that's passed in by pointer.) +Whenever possible, try to use ABI-agnostic types for passing parameters to +a syscall in order to avoid creating compat entry for it. Linux supports two +ABI models - ILP32 and LP64. The types like ``void *``, ``long``, ``size_t``, +``off_t`` have different size in those ABIs; types like ``char`` and ``int`` +have the same size and don't require a compat layer support. For flags, it's +always better to use ``unsigned int``. + Proposing the API - -- 2.25.1
