Re: [PATCH 22/22] man2: Add uprobe syscall page

[Jiri Olsa <olsajiri@gmail.com>]

On Tue, Apr 22, 2025 at 09:00:17AM +0200, Alejandro Colomar wrote:
> Hi Jiri,
> 
> On Mon, Apr 21, 2025 at 11:44:22PM +0200, Jiri Olsa wrote:
> > Adding man page for new uprobe syscall.
> > 
> > Cc: Alejandro Colomar <alx@kernel.org>
> > Signed-off-by: Jiri Olsa <jolsa@kernel.org>
> > ---
> >  man/man2/uprobe.2    | 49 ++++++++++++++++++++++++++++++++++++++++++++
> >  man/man2/uretprobe.2 |  2 ++
> >  2 files changed, 51 insertions(+)
> >  create mode 100644 man/man2/uprobe.2
> > 
> > diff --git a/man/man2/uprobe.2 b/man/man2/uprobe.2
> > new file mode 100644
> > index 000000000000..2b01a5ab5f3e
> > --- /dev/null
> > +++ b/man/man2/uprobe.2
> > @@ -0,0 +1,49 @@
> > +.\" Copyright (C) 2024, Jiri Olsa <jolsa@kernel.org>
> > +.\"
> > +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> > +.\"
> > +.TH uprobe 2 (date) "Linux man-pages (unreleased)"
> > +.SH NAME
> > +uprobe
> > +\-
> > +execute pending entry uprobes
> > +.SH SYNOPSIS
> > +.nf
> > +.B int uprobe(void);
> > +.fi
> > +.SH DESCRIPTION
> > +.BR uprobe ()
> > +is an alternative to breakpoint instructions
> > +for triggering entry uprobe consumers.
> 
> What are breakpoint instructions?

it's int3 instruction to trigger breakpoint (on x86_64)

> 
> > +.P
> > +Calls to
> > +.BR uprobe ()
> > +are only made from the user-space trampoline provided by the kernel.
> > +Calls from any other place result in a
> > +.BR SIGILL .
> > +.SH RETURN VALUE
> > +The return value is architecture-specific.
> > +.SH ERRORS
> > +.TP
> > +.B SIGILL
> > +.BR uprobe ()
> > +was called by a user-space program.
> > +.SH VERSIONS
> > +The behavior varies across systems.
> > +.SH STANDARDS
> > +None.
> > +.SH HISTORY
> > +TBD
> > +.P
> > +.BR uprobe ()
> > +was initially introduced for the x86_64 architecture
> > +where it was shown to be faster than breakpoint traps.
> > +It might be extended to other architectures.
> > +.SH CAVEATS
> > +.BR uprobe ()
> > +exists only to allow the invocation of entry uprobe consumers.
> > +It should
> > +.B never
> > +be called directly.
> > +.SH SEE ALSO
> > +.BR uretprobe (2)
> 
> The pages are almost identical.  Should we document both pages in the
> same page?

great, I was wondering this was an option, looks much better
should we also add uprobe link, like below?

thanks,
jirka


---
diff --git a/man/man2/uprobe.2 b/man/man2/uprobe.2
new file mode 100644
index 000000000000..ea5ccf901591
--- /dev/null
+++ b/man/man2/uprobe.2
@@ -0,0 +1 @@
+.so man2/uretprobe.2