From patchwork Mon Jan 22 20:14:54 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Palmer Dabbelt X-Patchwork-Id: 25479 Received: (qmail 37620 invoked by alias); 22 Jan 2018 20:14:59 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 37478 invoked by uid 89); 22 Jan 2018 20:14:58 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-26.1 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_NONE, SPF_PASS, URIBL_RED autolearn=ham version=3.3.2 spammy=controls, 12111, Facilities, H*RU:209.85.192.195 X-HELO: mail-pf0-f195.google.com X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:subject:in-reply-to:cc:from:to:message-id :mime-version:content-transfer-encoding; bh=vvAehd1xIz6WB85v33E5wYNcXybP9339KvbGOyahlgo=; b=pyKNzhY3LrtE2P15idLu7N9FNwXaUFHkTgWssJSJV5YxdKTRKS/LzIuhKlAe7svSMh 3CoUczBX2+nz2TDE7IjF8/3XXkm489XYyOU4r+TJtkVYus1rDj3YbST/Q7k06mLEA63e z49vl+ff+KlRi+iFobFVed4j9T1mqb//aZqUUrFKAXi7eGyLcmr9iYxrUI7Cg3GEx5k0 ml7+PU0+MaXGCEWM8vx1upJwdFJSTt6BG1z8fKtbWP5Pus59tVt0pPV2bwcOJRSt7mRd AzyNo0PWWM01YAn1zTSPSgrQCFN/W12dHKijCJd5JIJZKOHDRCvUoUlI0LyOCmhdG1pt wzjw== X-Gm-Message-State: AKwxytfvjgUu8Y7yTNta2ykoPYS/i3ZT1lkktgWV7Bm08jxlQdGYxk2C epzKubQuOmLsHh1PmrvIRVIbaea6Ehc= X-Google-Smtp-Source: AH8x227OzniwQb6Hqg8hVAW9+2Sbn7BGjuMdPjNpJgyGl7N0vt8YTbI7O0vnatp9MQJkROU1b8De0Q== X-Received: by 2002:a17:902:b613:: with SMTP id b19-v6mr4271974pls.164.1516652095349; Mon, 22 Jan 2018 12:14:55 -0800 (PST) Date: Mon, 22 Jan 2018 12:14:54 -0800 (PST) X-Google-Original-Date: Mon, 22 Jan 2018 12:14:37 PST (-0800) Subject: Re: [patches] Re: [PATCH v4 04/17] Add documentation for __riscv_flush_icache In-Reply-To: CC: libc-alpha@sourceware.org, patches@groups.riscv.org From: Palmer Dabbelt To: joseph@codesourcery.com Message-ID: Mime-Version: 1.0 (MHng) 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