Hi Charlie,
On Fri, Jun 28, 2024 at 08:32:47PM GMT, Charlie Jenkins wrote:
> riscv_flush_icache has been present in syscall.2, but had no page for
> itself. Add the page for this syscall.
>
> The syscall is named riscv_flush_icache, but the glibc function is
> named __riscv_flush_icache. To handle this, name the syscall page
> riscv_flush_icache.2 and point to the libc page __riscv_flush_icache.3.
>
> Signed-off-by: Charlie Jenkins <charlie@xxxxxxxxxxxx>
> ---
> man/man2/riscv_flush_icache.2 | 2 ++
> man/man3/__riscv_flush_icache.3 | 42 +++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 44 insertions(+)
>
> diff --git a/man/man2/riscv_flush_icache.2 b/man/man2/riscv_flush_icache.2
> new file mode 100644
> index 000000000..3bafb5aca
> --- /dev/null
> +++ b/man/man2/riscv_flush_icache.2
> @@ -0,0 +1,2 @@
> +.so man3/__riscv_flush_icache.3
> +.\" Because __riscv_flush_icache(3) is layered on a system call of the same name
No need for that comment. That's usually the reason. :)
> diff --git a/man/man3/__riscv_flush_icache.3 b/man/man3/__riscv_flush_icache.3
> new file mode 100644
> index 000000000..db59f4672
> --- /dev/null
> +++ b/man/man3/__riscv_flush_icache.3
> @@ -0,0 +1,42 @@
> +.\" Copyright (C) Rivos Inc., 2024
> +.\"
> +.\" SPDX-License-Identifier: GPL-2.0-or-later
> +.\"
> +.TH riscv_flush_icache 3 (date) "Linux man-pages (unreleased)"
The TH arg1 should match the file name.
> +.SH NAME
> +riscv_flush_icache \- Flush icaches on RISC-V
Same here. BTW, please put the \- on a line of its own.
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ", " \-lc )
> +.SH SYNOPSIS
> +.nf
> +.B #include <sys/cachectl.h>
> +.P
> +.B int __riscv_flush_icache(void *start, void *end, \
> +unsigned long int flags);
We say 'unsigned long'. We only use 'int' for 'int' and 'unsigned int'.
> +.fi
> +.SH DESCRIPTION
> +.BR __riscv_flush_icache ()
> +enforces ordering between stores and instruction cache fetches. The range of
Please use semantic newlines. See man-pages:
$ MANWIDTH=72 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.
See also:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man7/man-pages.7?id=6ff6f43d68164f99a8c3fb66f4525d145571310c>
Cheers,
Alex
> +addresses over which ordering is enforced is specified by
> +.I start
> +and
> +.I end .
> +The
> +.I flags
> +argument controls the extent of this ordering, with
> +the default behavior (a
> +.I flags
> +value of 0) being to enforce the fence on
> +all threads in the current process. Setting the
> +.B SYS_RISCV_FLUSH_ICACHE_LOCAL
> +bit allows users to indicate that enforcing
> +ordering on only the current thread is necessary. All other flag bits are
> +reserved.
> +.SH STANDARDS
> +Linux on RISC-V.
> +.SH HISTORY
> +Linux 4.15.
> +glibc 2.27.
> +.SH SEE ALSO
> +.BR syscall (2)
>
> ---
> base-commit: d0621648b4b5a356e86cea23e842f2591461f0cf
> change-id: 20240628-flush_icache-bf5a1f88032e
>
> Best regards,
> --
> Charlie Jenkins <charlie@xxxxxxxxxxxx>
>
>
--
<https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
