diff mbox

[v4,04/17] Add documentation for __riscv_flush_icache

Message ID 20180113103816.4861-5-palmer@dabbelt.com
State New, archived
Headers

Commit Message

Palmer Dabbelt Jan. 13, 2018, 10:38 a.m. UTC 
  I don't know if this is actually the right place to put this: it's a
Linux-specific function, and while users can call it we'd really prefer
they use rely on GCC to emit it when necessary from via its cache
flushing intrinsics.

2018-01-13  Palmer Dabbelt  <palmer@sifive.com>

        * manual/platform.texi: Add RISC-V documenation for
        __riscv_flush_icache.
---
 manual/platform.texi | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

Comments

Joseph Myers Jan. 15, 2018, 4:49 p.m. UTC | #1 
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.
diff mbox

Patch

diff --git a/manual/platform.texi b/manual/platform.texi
index cb166641fb71..f6ca97ebf9d8 100644
--- a/manual/platform.texi
+++ b/manual/platform.texi
@@ -6,6 +6,7 @@ 
 
 @menu
 * PowerPC::           Facilities Specific to the PowerPC Architecture
+* RISC-V::            Facilities Specific to the RISC-V Architecture
 @end menu
 
 @node PowerPC
@@ -115,3 +116,16 @@  problem-state programs.  If the program priority is medium high when the time
 interval expires or if an attempt is made to set the priority to medium high
 when it is not allowed, the priority is set to medium.
 @end deftypefun
+
+@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}.
+
+@deftypefun {void} __riscv_flush_icache(void *start, void *end, unsigned long int 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.
+@end deftypefun