From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-5.6 required=3.0 tests=DKIMWL_WL_HIGH,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE, SPF_PASS,USER_AGENT_SANE_1 autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id A1787C433DF for ; Tue, 9 Jun 2020 09:57:41 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 6F122207C3 for ; Tue, 9 Jun 2020 09:57:41 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1591696661; bh=J6vQAi2iv0OM7Za6E+Q+xtNZ6rRIhyw/6fjQcMa2QUU=; h=Date:From:To:Cc:Subject:References:In-Reply-To:List-ID:From; b=hb3AYefZPNAVCicRZugsGY+JqY05sAHmQzRkk/TGMkb4/vVb4gS2yTP4QQE5Z4Q6M J1KNlxPBnTtVl3G22SusKYxtbJUCUNie1D8QO4w2oWJ85I7KAdrZi8yUqmQUapP/ic 2sAGqsgbvMFCEjaT5EVVtKPnlec/fW8XXj8W9SG4= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727086AbgFIJ5l (ORCPT ); Tue, 9 Jun 2020 05:57:41 -0400 Received: from mail.kernel.org ([198.145.29.99]:59178 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726765AbgFIJ5k (ORCPT ); Tue, 9 Jun 2020 05:57:40 -0400 Received: from willie-the-truck (236.31.169.217.in-addr.arpa [217.169.31.236]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 95D552074B; Tue, 9 Jun 2020 09:57:38 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1591696659; bh=J6vQAi2iv0OM7Za6E+Q+xtNZ6rRIhyw/6fjQcMa2QUU=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=pdDSc9Mom8h7szHkQE/KdCcrxBsFve5O0Finu7/evTT8qq4AZLEHvyBy/R35627bh ZHOvmnECAWZp5m3xCsVH7kfVguN+EIz0YlqprdlQHM/Q7JIujX+cmUNqwcW3NgUjZh QE/+hED2A0sXnEMDaexfP2Mdzifj4cFGf5mrsLFY= Date: Tue, 9 Jun 2020 10:57:35 +0100 From: Will Deacon To: Dave Martin Cc: Michael Kerrisk , linux-man@vger.kernel.org, linux-arch@vger.kernel.org, linux-arm-kernel@lists.infradead.org, Catalin Marinas Subject: Re: [PATCH v2 4/6] prctl.2: Add SVE prctls (arm64) Message-ID: <20200609095734.GA25362@willie-the-truck> References: <1590614258-24728-1-git-send-email-Dave.Martin@arm.com> <1590614258-24728-5-git-send-email-Dave.Martin@arm.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <1590614258-24728-5-git-send-email-Dave.Martin@arm.com> User-Agent: Mutt/1.10.1 (2018-07-13) Sender: linux-man-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-man@vger.kernel.org Hi Dave, On Wed, May 27, 2020 at 10:17:36PM +0100, Dave Martin wrote: > Add documentation for the the PR_SVE_SET_VL and PR_SVE_GET_VL > prctls added in Linux 4.15 for arm64. Looks really good to me, thanks. Just a few comments inline. > diff --git a/man2/prctl.2 b/man2/prctl.2 > index cab9915..91df7c8 100644 > --- a/man2/prctl.2 > +++ b/man2/prctl.2 > @@ -1291,6 +1291,148 @@ call failing with the error > .BR ENXIO . > For further details, see the kernel source file > .IR Documentation/admin\-guide/kernel\-parameters.txt . > +.\" prctl PR_SVE_SET_VL > +.\" commit 2d2123bc7c7f843aa9db87720de159a049839862 > +.\" linux-5.6/Documentation/arm64/sve.rst > +.TP > +.BR PR_SVE_SET_VL " (since Linux 4.15, only on arm64)" > +Configure the thread's SVE vector length, > +as specified by > +.IR "(int) arg2" . > +Arguments > +.IR arg3 ", " arg4 " and " arg5 > +are ignored. > +.IP > +The bits of > +.I arg2 > +corresponding to > +.B PR_SVE_VL_LEN_MASK > +must be set to the desired vector length in bytes. > +This is interpreted as an upper bound: > +the kernel will select the greatest available vector length > +that does not exceed the value specified. > +In particular, specifying > +.B SVE_VL_MAX > +(defined in > +.I ) > +for the > +.B PR_SVE_VL_LEN_MASK > +bits requests the maximum supported vector length. > +.IP > +In addition, > +.I arg2 > +must be set to one of the following combinations of flags: How about saying: In addition, the other bits of arg2 must be set according to the following combinations of flags: Otherwise I find it a bit fiddly to read, because it's valid to have flags of 0 and a non-zero length. > +.RS > +.TP > +.B 0 > +Perform the change immediately. > +At the next > +.BR execve (2) > +in the thread, > +the vector length will be reset to the value configured in > +.IR /proc/sys/abi/sve_default_vector_length . (implementation note: does this mean that 'sve_default_vl' should be an atomic_t, as it can be accessed concurrently? We probably need {READ,WRITE}_ONCE() at the very least, as I'm not seeing any locks that help us here...) > +.TP > +.B PR_SVE_VL_INHERIT > +Perform the change immediately. > +Subsequent > +.BR execve (2) > +calls will preserve the new vector length. > +.TP > +.B PR_SVE_SET_VL_ONEXEC > +Defer the change, so that it is performed at the next > +.BR execve (2) > +in the thread. > +Further > +.BR execve (2) > +calls will reset the vector length to the value configured in > +.IR /proc/sys/abi/sve_default_vector_length . > +.TP > +.B "PR_SVE_SET_VL_ONEXEC | PR_SVE_VL_INHERIT" > +Defer the change, so that it is performed at the next > +.BR execve (2) > +in the thread. > +Further > +.BR execve (2) > +calls will preserve the new vector length. > +.RE > +.IP > +In all cases, > +any previously pending deferred change is canceled. > +.IP > +The call fails with error > +.B EINVAL > +if SVE is not supported on the platform, if > +.I arg2 > +is unrecognized or invalid, or the value in the bits of > +.I arg2 > +corresponding to > +.B PR_SVE_VL_LEN_MASK > +is outside the range > +.BR SVE_VL_MIN .. SVE_VL_MAX > +or is not a multiple of 16. > +.IP > +On success, > +a nonnegative value is returned that describes the > +.I selected > +configuration, If I'm reading the kernel code correctly, this is slightly weird, as the returned value may contain the PR_SVE_VL_INHERIT flag but it will never contain the PR_SVE_SET_VL_ONEXEC flag. Is that right? If so, maybe just say something like: On success, a nonnegative value is returned that describes the selected configuration in the same way as PR_SVE_GET_VL. > +which may differ from the current configuration if > +.B PR_SVE_SET_VL_ONEXEC > +was specified. > +The value is encoded in the same way as the return value of > +.BR PR_SVE_GET_VL . > +.IP > +The configuration (including any pending deferred change) > +is inherited across > +.BR fork (2) > +and > +.BR clone (2). > +.IP > +.B Warning: > +Because the compiler or run-time environment > +may be using SVE, using this call without the > +.B PR_SVE_SET_VL_ONEXEC > +flag may crash the calling process. > +The conditions for using it safely are complex and system-dependent. > +Don't use it unless you really know what you are doing. > +.IP > +For more information, see the kernel source file > +.I Documentation/arm64/sve.rst > +.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed > +(or > +.I Documentation/arm64/sve.txt > +before Linux 5.3). I think I'd drop the kernel reference here, as it feels like we're saying "only do this if you know what you're doing" on one hand, but then "if you don't know what you're doing, see this other documentation" on the other. Will