Re: [patches] Re: [PATCH v4 04/17] Add documentation for __riscv_flush_icache

[Palmer Dabbelt <palmer at dabbelt dot com>]

On Mon, 15 Jan 2018 08:49:05 PST (-0800), joseph@codesourcery.com wrote:
> 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.

Sorry about that, that documentation was terrible.  Hopefully this is a bit 
better.

diff --git a/manual/platform.texi b/manual/platform.texi
index f6ca97ebf9d8..6caa988a02c2 100644
--- a/manual/platform.texi
+++ b/manual/platform.texi
@@ -121,11 +121,15 @@ when it is not allowed, the priority is set to medium.
@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}.
+ABI are declared in @file{sys/cachectl.h}.

-@deftypefun {void} __riscv_flush_icache(void *start, void *end, unsigned long int flags)
+@deftypefun {void} __riscv_flush_icache(void *@var{__start}, void *@var{__end},
+					unsigned long int @var{__flags})
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-Enforce ordering between stores and instruction cache fetches.  The flags
-variable is used to determine if this applies just to the local thread or to
-all threads in the system.
+Enforce ordering between stores and instruction cache fetches.  The range of
+addresses over which ordering is enforced is specified by @var{__start} and
+@var{__end}.  The @var{__flags} variable controls how the ordering is enforced,
+with @code{SYS_RISCV_FLUSH_ICACHE_LOCAL} specifying that the ordering is
+enforced only with respect to the local instruction stream (as opposed to all
+instruction streams).
@end deftypefun