This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH v4 04/17] Add documentation for __riscv_flush_icache
- From: Joseph Myers <joseph at codesourcery dot com>
- To: Palmer Dabbelt <palmer at dabbelt dot com>
- Cc: <libc-alpha at sourceware dot org>, <patches at groups dot riscv dot org>
- Date: Mon, 15 Jan 2018 16:49:05 +0000
- Subject: Re: [PATCH v4 04/17] Add documentation for __riscv_flush_icache
- Authentication-results: sourceware.org; auth=none
- References: <20180113103816.4861-1-palmer@dabbelt.com> <20180113103816.4861-5-palmer@dabbelt.com>
On Sat, 13 Jan 2018, Palmer Dabbelt wrote:
> +@node RISC-V
> +@appendixsec RISC-V-specific Facilities
> +
> +Cache management facilities specific to RISC-V systems that implement the Linux
> +ABI are declared in @file{sysdeps/unix/sysv/linux/riscv/sys/cachectl.h}.
This manual is for *users*, which means it should reference the installed
header sys/cachectl.h, not the location within the glibc source tree.
> +
> +@deftypefun {void} __riscv_flush_icache(void *start, void *end, unsigned long int flags)
That's @var{start}, @var{end}, @var{flags} in the @deftypefun line.
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +Enforce ordering between stores and instruction cache fetches. The flags
And then again @var{flags} (an argument, not a variable) in the
description of the function's semantics.
> +variable is used to determine if this applies just to the local thread or to
> +all threads in the system.
> +@end deftypefun
"used to determine" how? You need to say explicitly what the semantics of
all defined values of that argument are. You also need to say what the
semantics of the other arguments are; generally I'd expect documentation
for a function to refer explicitly to each argument, @var{start},
@var{end} and @var{flags}, in defining the function semantics in terms of
those arguments.
--
Joseph S. Myers
joseph@codesourcery.com