Re: [PATCH] Documentation: Document user_events ioctl code

[Masami Hiramatsu (Google) <mhiramat@kernel.org>]

On Wed, 3 Jul 2024 16:13:43 -0700
Beau Belgrave <beaub@linux.microsoft.com> wrote:

> On Wed, Jul 03, 2024 at 06:58:03PM -0400, Mathieu Desnoyers wrote:
> > On 03-Jul-2024 10:25:01 PM, Beau Belgrave wrote:
> > > The user events trace subsystem uses the 0x2A/'*' code for ioctls. These
> > > are published via the uapi/linux/user_events.h header file.
> > > 
> > > Add a line indicating user events as the owner of the 0x2A/'*' code and the
> > > current sequence numbers that are in use (00-02).
> > > 
> > > Signed-off-by: Beau Belgrave <beaub@linux.microsoft.com>
> > > ---
> > >  Documentation/userspace-api/ioctl/ioctl-number.rst | 2 ++
> > >  1 file changed, 2 insertions(+)
> > > 
> > > diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst
> > > index a141e8e65c5d..191609fe4593 100644
> > > --- a/Documentation/userspace-api/ioctl/ioctl-number.rst
> > > +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst
> > > @@ -97,6 +97,8 @@ Code  Seq#    Include File                                           Comments
> > >  '%'   00-0F  include/uapi/linux/stm.h                                System Trace Module subsystem
> > >                                                                       <mailto:alexander.shishkin@linux.intel.com>
> > >  '&'   00-07  drivers/firewire/nosy-user.h
> > > +'*'   00-02  uapi/linux/user_events.h                                User Events Subsystem
> > 
> > You may want to consider reserving a wider sequence number range to plan
> > ahead for future extensions to user events. This way you won't end up
> > having to jump over sequence numbers eventually reserved by others
> > within the '*' code.
> > 
> > Thanks,
> > 
> > Mathieu
> 
> Yeah, I thought about that, but really didn't know how greedy we could
> be. At first I had all, but then thought we would never use all of that
> sequence. We'll likely want a few more for libside integration.
> 
> Maybe I'll grab the first 16, that should leave a lot for others and
> give us quite bit of growing room.

I think that sounds reasonable, there is a sentence in the same file:

----
If you are writing a driver for a new device and need a letter, pick an
unused block with enough room for expansion: 32 to 256 ioctl commands.
----

Maybe you can reserve a block for 32 ioctl.

Thank you,

> 
> How many do you think we'll need for libside? I think we'd only need 2-3
> personally.
> 
> Thanks,
> -Beau
> 
> > 
> > 
> > > +                                                                     <mailto:linux-trace-kernel@vger.kernel.org>
> > >  '1'   00-1F  linux/timepps.h                                         PPS kit from Ulrich Windl
> > >                                                                       <ftp://ftp.de.kernel.org/pub/linux/daemons/ntp/PPS/>
> > >  '2'   01-04  linux/i2o.h
> > > -- 
> > > 2.34.1
> > > 
> > 
> > -- 
> > Mathieu Desnoyers
> > EfficiOS Inc.
> > http://www.efficios.com


-- 
Masami Hiramatsu (Google) <mhiramat@kernel.org>