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

[Joseph Myers <joseph at codesourcery dot com>]

On Mon, 22 Jan 2018, Palmer Dabbelt wrote:

> -@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})

No __ on parameter names in the manual, only in the installed header.  And 
you can't split the @deftypefun line like that.  (Texinfo supports a 
syntax with @ at end of line when such an @def* line is split, but I don't 
think glibc's own scripts processing .texi files handle that.)

> @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,

As I said before I think this should be called an argument not a variable.

> +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).

And what other values are valid and what do they mean?  Is 0 the only 
other alternative value, meaning ordering over all cores?  Are other 
values reserved for future use?  You seem to describe only one value, 
SYS_RISCV_FLUSH_ICACHE_LOCAL, without saying anything about any other 
values such as 0.

-- 
Joseph S. Myers
joseph@codesourcery.com