Received-SPF: pass (google.com: domain of linux-kernel+bounces-184883-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) client-ip=2604:1380:4601:e00::3;
Date: Tue, 21 May 2024 13:36:25 +0200
From: Alejandro Colomar <alx@kernel.org>
To: Jiri Olsa <jolsa@kernel.org>
Cc: Steven Rostedt <rostedt@goodmis.org>, 
	Masami Hiramatsu <mhiramat@kernel.org>, Oleg Nesterov <oleg@redhat.com>, 
	Alexei Starovoitov <ast@kernel.org>, Daniel Borkmann <daniel@iogearbox.net>, 
	Andrii Nakryiko <andrii@kernel.org>, linux-kernel@vger.kernel.org, linux-trace-kernel@vger.kernel.org, 
	linux-api@vger.kernel.org, linux-man@vger.kernel.org, x86@kernel.org, bpf@vger.kernel.org, 
	Song Liu <songliubraving@fb.com>, Yonghong Song <yhs@fb.com>, 
	John Fastabend <john.fastabend@gmail.com>, Peter Zijlstra <peterz@infradead.org>, 
	Thomas Gleixner <tglx@linutronix.de>, "Borislav Petkov (AMD)" <bp@alien8.de>, 
	Ingo Molnar <mingo@redhat.com>, Andy Lutomirski <luto@kernel.org>, 
	"Edgecombe, Rick P" <rick.p.edgecombe@intel.com>, Deepak Gupta <debug@rivosinc.com>
Subject: Re: [PATCHv6 9/9] man2: Add uretprobe syscall page
Message-ID: <j6qxudmvwccpqnle4evabxbswdygmx35bgqwhemuzsjs5iuydv@fk2iumwucifx>
References: <20240521104825.1060966-1-jolsa@kernel.org>
 <20240521104825.1060966-10-jolsa@kernel.org>
Precedence: bulk
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha512;
	protocol="application/pgp-signature"; boundary="sord6gh2s3weogw7"
Content-Disposition: inline
In-Reply-To: <20240521104825.1060966-10-jolsa@kernel.org>


--sord6gh2s3weogw7
Content-Type: text/plain; protected-headers=v1; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
From: Alejandro Colomar <alx@kernel.org>
To: Jiri Olsa <jolsa@kernel.org>
Cc: Steven Rostedt <rostedt@goodmis.org>, 
	Masami Hiramatsu <mhiramat@kernel.org>, Oleg Nesterov <oleg@redhat.com>, 
	Alexei Starovoitov <ast@kernel.org>, Daniel Borkmann <daniel@iogearbox.net>, 
	Andrii Nakryiko <andrii@kernel.org>, linux-kernel@vger.kernel.org, linux-trace-kernel@vger.kernel.org, 
	linux-api@vger.kernel.org, linux-man@vger.kernel.org, x86@kernel.org, bpf@vger.kernel.org, 
	Song Liu <songliubraving@fb.com>, Yonghong Song <yhs@fb.com>, 
	John Fastabend <john.fastabend@gmail.com>, Peter Zijlstra <peterz@infradead.org>, 
	Thomas Gleixner <tglx@linutronix.de>, "Borislav Petkov (AMD)" <bp@alien8.de>, 
	Ingo Molnar <mingo@redhat.com>, Andy Lutomirski <luto@kernel.org>, 
	"Edgecombe, Rick P" <rick.p.edgecombe@intel.com>, Deepak Gupta <debug@rivosinc.com>
Subject: Re: [PATCHv6 9/9] man2: Add uretprobe syscall page
References: <20240521104825.1060966-1-jolsa@kernel.org>
 <20240521104825.1060966-10-jolsa@kernel.org>
MIME-Version: 1.0
In-Reply-To: <20240521104825.1060966-10-jolsa@kernel.org>

Hi Jiri,

On Tue, May 21, 2024 at 12:48:25PM GMT, Jiri Olsa wrote:
> Adding man page for new uretprobe syscall.
>=20
> Signed-off-by: Jiri Olsa <jolsa@kernel.org>
> ---
>  man2/uretprobe.2 | 50 ++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 50 insertions(+)
>  create mode 100644 man2/uretprobe.2
>=20
> diff --git a/man2/uretprobe.2 b/man2/uretprobe.2
> new file mode 100644
> index 000000000000..690fe3b1a44f
> --- /dev/null
> +++ b/man2/uretprobe.2
> @@ -0,0 +1,50 @@
> +.\" 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

What header file provides this system call?

> +.SH DESCRIPTION
> +The
> +.BR uretprobe ()
> +syscall is an alternative to breakpoint instructions for
> +triggering return uprobe consumers.
> +.P
> +Calls to
> +.BR uretprobe ()
> +suscall are only made from the user-space trampoline provided by the ker=
nel.

s/suscall/system call/

> +Calls from any other place result in a
> +.BR SIGILL .

Maybe add an ERRORS section?

> +

We don't use blank lines; it causes a groff(1) warning, and other
problems.  Instead, use '.P'.

> +.SH RETURN VALUE
> +The
> +.BR uretprobe ()
> +syscall return value is architecture-specific.
> +

=2EP

> +.SH VERSIONS
> +This syscall is not specified in POSIX,

Redundant with "STANDARDS: None.".

> +and details of its behavior vary across systems.

Keep this.

> +.SH STANDARDS
> +None.
> +.SH HISTORY
> +TBD
> +.SH NOTES
> +The
> +.BR uretprobe ()
> +syscall was initially introduced for the x86_64 architecture where it wa=
s shown
> +to be faster than breakpoint traps. It might be extended to other archit=
ectures.

Please use semantic newlines.

$ MANWIDTH=3D72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
   Use semantic newlines
     In the source of a manual page, new sentences should be started on
     new lines, long sentences should be split  into  lines  at  clause
     breaks  (commas,  semicolons, colons, and so on), and long clauses
     should be split at phrase boundaries.  This convention,  sometimes
     known as "semantic newlines", makes it easier to see the effect of
     patches, which often operate at the level of individual sentences,
     clauses, or phrases.

> +.P
> +The
> +.BR uretprobe ()
> +syscall exists only to allow the invocation of return uprobe consumers.

s/syscall/system call/

> +It should
> +.B never
> +be called directly.
> +Details of the arguments (if any) passed to
> +.BR uretprobe ()
> +and the return value are architecture-specific.
> --=20
> 2.44.0

Have a lovely day!
Alex

--=20
<https://www.alejandro-colomar.es/>

--sord6gh2s3weogw7
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAABCgAdFiEE6jqH8KTroDDkXfJAnowa+77/2zIFAmZMhzkACgkQnowa+77/
2zLxzw/+Nr7TcDedetItg4H5lLs1D0c6PkeDczXCv/HgvC3U929LIyVMR3YxbcRY
DZEvb2xL2lZuP5tBisHE+uA4f9mnPztAv6siRWgf3BhpBokLZ06TIek17DHo2kwL
ZL7a1xdI6XxduGBQv3U348TLH7y6ya3KXlAlt3tYaLh2vbmcsyo5WFUZNqfGDO4R
k05CXBvDmG5aotK5h/KWZSdvYn5auZh7le7Rg2qW1yP6hkK7eDz4Sx7bP0+IVIy7
lJVOMj0MhuVr8ZyX/CtP9cQBJWUw/9ZVByudEF8SFvkJTgBBK7oxypTGcN1I47Yd
JKQIMH64nKxvrP6k1Ba3PMwmrEDGdZnS1OB9X8rEdjoHYhOqcQszSo1tM3cyQqzA
5v8LHWZ1tr+AxMUw0igiK0TCAeqZYS2c0sKRavzEx2nZ/BCOGDwMBSQ1Ax4vjiWl
/J6H74GM+gz1oRGMwVpAAFHXDQjCarblNEpNSYah+jd83f2TtmkF84unPRAnNDbp
Pe/z3k1mC5veFjCvKFF13SbhS/vm59wSsxi61Kz0rVAsgZSNdk2q+VJIaablNv8w
M7fa44YS37NQ29zhZRmKtTHGXOAuMyKYx+3ZdPUh+bvH6Ovip677+OUkDD8BwY9t
2dU6YQNKk+I3dmmIgnCkfUb+cOrOMTAkRA1Tl6zIR1nDGiJa5Bk=
=SNMs
-----END PGP SIGNATURE-----

--sord6gh2s3weogw7--