Re: [PATCHv4 7/7] man2: Add uretprobe syscall page

[Jiri Olsa <olsajiri@gmail.com>]

On Mon, Sep 09, 2024 at 10:26:37PM +0200, Günther Noack wrote:
> Hello Jiri!
> 
> Sorry to revive this old thread with a meta-question...
> 
> We were discussing the workflow of using a single patch set for
> sending man pages together with kernel changes, and Alejandro pointed
> out on https://lwn.net/Articles/989398/ that you have been doing this
> in the past on this and other threads.
> 
> I have been trying to reconstruct how you have done this, and so far,
> my best guess is that the process is to:
> 
> 1. `git fetch` the man pages project into the same local repo where
>    you keep the kernel tree;
>    
> 2. prepare man page patches and kernel patches in that same repo
>    (probably using the git worktree feature);
>    
> 3. git format-patch with --subject-prefix="PATCH bpf-next" and a
>    revision range that gives both "dotted ranges" at the same time, e.g.
> 
>    git format-patch -v23 --cover-letter \
>        linux-master..mylinuxbranch man-master..mymanbranch
> 
> 4. In the resulting mail files, hand-edit the subject prefix in the
>    man page commit, in addition to the cover letter.
> 
> Is that an accurate description of your process?  Or am I overlooking
> another trick or tool that I could use here?  Is this a practice that
> other people are using as well?

hi,
bit simpler than that ;-) I kept kernel and man git repos separated

I have some extra tooling in place, but for this patchset I basically did:

 - git format-patch --prefix=... for kernel changes
 - git format-patch --prefix=... for man changes
 - changed the man patch to have proper patch index in subject and file
   name, so it's sorted behind kernel patches
 - git send-email on all above files/patches

jirka

> 
> Thanks,
> –-Günther
> 
> On Thu, May 02, 2024 at 02:23:13PM +0200, Jiri Olsa wrote:
> > Adding man page for new uretprobe syscall.
> > 
> > Signed-off-by: Jiri Olsa <jolsa@kernel.org>
> > ---
> >  man2/uretprobe.2 | 45 +++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 45 insertions(+)
> >  create mode 100644 man2/uretprobe.2
> > 
> > diff --git a/man2/uretprobe.2 b/man2/uretprobe.2
> > new file mode 100644
> > index 000000000000..08fe6a670430
> > --- /dev/null
> > +++ b/man2/uretprobe.2
> > @@ -0,0 +1,45 @@
> > +.\" Copyright (C) 2024, Jiri Olsa <jolsa@kernel.org>
> > +.\"
> > +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> > +.\"
> > +.TH uretprobe 2 (date) "Linux man-pages (unreleased)"
> > +.SH NAME
> > +uretprobe \- execute pending return uprobes
> > +.SH SYNOPSIS
> > +.nf
> > +.B int uretprobe(void)
> > +.fi
> > +.SH DESCRIPTION
> > +Kernel is using
> > +.BR uretprobe()
> > +syscall to trigger uprobe return probe consumers instead of using
> > +standard breakpoint instruction.
> > +
> > +The uretprobe syscall is not supposed to be called directly by user, it's allowed
> > +to be invoked only through user space trampoline provided by kernel.
> > +When called from outside of this trampoline, the calling process will receive
> > +.BR SIGILL .
> > +
> > +.SH RETURN VALUE
> > +.BR uretprobe()
> > +return value is specific for given architecture.
> > +
> > +.SH VERSIONS
> > +This syscall is not specified in POSIX,
> > +and details of its behavior vary across systems.
> > +.SH STANDARDS
> > +None.
> > +.SH NOTES
> > +.BR uretprobe()
> > +syscall is initially introduced on x86-64 architecture, because doing syscall
> > +is faster than doing breakpoint trap on it. It might be extended to other
> > +architectures.
> > +
> > +.BR uretprobe()
> > +syscall exists only to allow the invocation of return uprobe consumers.
> > +It should
> > +.B never
> > +be called directly.
> > +Details of the arguments (if any) passed to
> > +.BR uretprobe ()
> > +and the return value are specific for given architecture.
> > -- 
> > 2.44.0
> >