| Message ID | 20220207152109.197566-7-broonie@kernel.org (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | arm64/sme: Initial support for the Scalable Matrix Extension | expand |
Hi Mark, On 2/7/22 8:20 AM, Mark Brown wrote: > Provide ABI documentation for SME similar to that for SVE. Due to the very > large overlap around streaming SVE mode in both implementation and > interfaces documentation for streaming mode SVE is added to the SVE > document rather than the SME one. > > Signed-off-by: Mark Brown <broonie@kernel.org> A few typos and missing SPDX comments below. > --- > Documentation/arm64/index.rst | 1 + > Documentation/arm64/sme.rst | 432 ++++++++++++++++++++++++++++++++++ > Documentation/arm64/sve.rst | 70 +++++- > 3 files changed, 493 insertions(+), 10 deletions(-) > create mode 100644 Documentation/arm64/sme.rst > > diff --git a/Documentation/arm64/index.rst b/Documentation/arm64/index.rst > index 4f840bac083e..ae21f8118830 100644 > --- a/Documentation/arm64/index.rst > +++ b/Documentation/arm64/index.rst > @@ -21,6 +21,7 @@ ARM64 Architecture > perf > pointer-authentication > silicon-errata > + sme > sve > tagged-address-abi > tagged-pointers > diff --git a/Documentation/arm64/sme.rst b/Documentation/arm64/sme.rst > new file mode 100644 > index 000000000000..15df3157c592 > --- /dev/null > +++ b/Documentation/arm64/sme.rst > @@ -0,0 +1,432 @@ Missing SPDX here? > +=================================================== > +Scalable Matrix Extension support for AArch64 Linux > +=================================================== > + > + > +When returning from a signal handler: > + > +* If there is no za_context record in the signal frame, or if the record is > + present but contains no register data as desribed in the previous section, described > + then ZA is disabled. > + > + PR_SME_SET_VL_ONEXEC > + > + Defer the requested vector length change until the next execve() > + performed by this thread. > + > + The effect is equivalent to implicit exceution of the following execution > + call immediately after the next execve() (if any) by the thread: > + > + > +[3] Documentation/arm64/cpu-feature-registers.rst > + > +[4] ARM IHI0055C > + http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055c/IHI0055C_beta_aapcs64.pdf > + http://infocenter.arm.com/help/topic/com.arm.doc.subset.swdev.abi/index.html > + Procedure Call Standard for the ARM 64-bit Architecture (AArch64) > diff --git a/Documentation/arm64/sve.rst b/Documentation/arm64/sve.rst > index 9d9a4de5bc34..93c2c2990584 100644 > --- a/Documentation/arm64/sve.rst > +++ b/Documentation/arm64/sve.rst > @@ -7,7 +7,9 @@ Author: Dave Martin <Dave.Martin@arm.com> > Date: 4 August 2017 > Missing SPDX perhaps? > This document outlines briefly the interface provided to userspace by Linux in > -order to support use of the ARM Scalable Vector Extension (SVE). > +order to support use of the ARM Scalable Vector Extension (SVE), including > +interactions with Streaming SVE mode added by the Scalable Matrix Extension > +(SME). > Looks good otherwise. Reviewed-by: Shuah Khan <skhan@linuxfoundation.org> thanks, -- Shuah
On Mon, Feb 07, 2022 at 05:10:35PM -0700, Shuah Khan wrote: > > +++ b/Documentation/arm64/sme.rst > > @@ -0,0 +1,432 @@ > > Missing SPDX here? Only a couple of rst files have SPDX documentation here, I guess the SPDX people aren't worrying about documentation?
On Tue, Feb 08, 2022 at 03:46:27PM +0000, Mark Brown wrote: > On Mon, Feb 07, 2022 at 05:10:35PM -0700, Shuah Khan wrote: > > > > +++ b/Documentation/arm64/sme.rst > > > @@ -0,0 +1,432 @@ > > > > Missing SPDX here? > Only a couple of rst files have SPDX documentation here, I guess the > SPDX people aren't worrying about documentation? I can't find any free format plain text files with SPDX in them, even really prominent stuff like README. The process documentation is silent on what's supposed to be done here too, it says you should use the comment style for whatever format you're writing in but that's not a thing for free format text. Dealing with this feels out of scope for this series, probably something for whenever someone gets round to doing a conversion to .rst or some other format.
On 2/8/22 11:38 AM, Mark Brown wrote: > On Tue, Feb 08, 2022 at 03:46:27PM +0000, Mark Brown wrote: >> On Mon, Feb 07, 2022 at 05:10:35PM -0700, Shuah Khan wrote: >> >>>> +++ b/Documentation/arm64/sme.rst >>>> @@ -0,0 +1,432 @@ >>> >>> Missing SPDX here? > >> Only a couple of rst files have SPDX documentation here, I guess the >> SPDX people aren't worrying about documentation? > > I can't find any free format plain text files with SPDX in them, even > really prominent stuff like README. The process documentation is silent > on what's supposed to be done here too, it says you should use the > comment style for whatever format you're writing in but that's not a > thing for free format text. Dealing with this feels out of scope for > this series, probably something for whenever someone gets round to doing > a conversion to .rst or some other format. > There are about 570+ files under Documentation directory that have SPDX including Documentation/index.rst Based on a recent doc patch I did, I have seen warns during doc build about the missing SPDX. Let's add it now so it doesn't need fixing later. thanks, -- Shuah
On Tue, Feb 08, 2022 at 11:48:39AM -0700, Shuah Khan wrote: > On 2/8/22 11:38 AM, Mark Brown wrote: > > I can't find any free format plain text files with SPDX in them, even > > really prominent stuff like README. The process documentation is silent > There are about 570+ files under Documentation directory that have SPDX > including Documentation/index.rst > Based on a recent doc patch I did, I have seen warns during doc build > about the missing SPDX. > Let's add it now so it doesn't need fixing later. Sure, there are lots of structured files in there like .rst ones which have SPDX headers but this is just a free format text file so it's not clear what if any format to use.
On 2/8/22 12:00 PM, Mark Brown wrote: > On Tue, Feb 08, 2022 at 11:48:39AM -0700, Shuah Khan wrote: >> On 2/8/22 11:38 AM, Mark Brown wrote: > >>> I can't find any free format plain text files with SPDX in them, even >>> really prominent stuff like README. The process documentation is silent > >> There are about 570+ files under Documentation directory that have SPDX >> including Documentation/index.rst > >> Based on a recent doc patch I did, I have seen warns during doc build >> about the missing SPDX. > >> Let's add it now so it doesn't need fixing later. > > Sure, there are lots of structured files in there like .rst ones which > have SPDX headers but this is just a free format text file so it's not > clear what if any format to use. > I think SPDX is applicable to all files free format or not. Are you seeing any build warns during doc build on this? thanks, -- Shuah
On Thu, Feb 10, 2022 at 08:12:44AM -0700, Shuah Khan wrote: > On 2/8/22 12:00 PM, Mark Brown wrote: > > Sure, there are lots of structured files in there like .rst ones which > > have SPDX headers but this is just a free format text file so it's not > > clear what if any format to use. > I think SPDX is applicable to all files free format or not. Are you seeing > any build warns during doc build on this? No, but I'm not exactly going out of my way to do anything with them. As far as I know these files don't get touched during builds, they just exist in the kernel tree. If there is some way of generating warnings from them there are quite a lot of other such files already there and doing so. Like I say I can't find any evidence that anyone has looked at adding SPDX to these files, as far as I know the long term plan such as it is is to convert to other formats and I can't immediately think how one would do it otherwise in a way that works well. I'm sure the license compliance people would find adding annotations useful but working out how to do that sensibly for these files seems beyond the scope of this series.
On 2/10/22 9:18 AM, Mark Brown wrote: > On Thu, Feb 10, 2022 at 08:12:44AM -0700, Shuah Khan wrote: >> On 2/8/22 12:00 PM, Mark Brown wrote: > >>> Sure, there are lots of structured files in there like .rst ones which >>> have SPDX headers but this is just a free format text file so it's not >>> clear what if any format to use. > >> I think SPDX is applicable to all files free format or not. Are you seeing >> any build warns during doc build on this? > > No, but I'm not exactly going out of my way to do anything with them. > As far as I know these files don't get touched during builds, they just > exist in the kernel tree. If there is some way of generating warnings > from them there are quite a lot of other such files already there and > doing so. Like I say I can't find any evidence that anyone has looked > at adding SPDX to these files, as far as I know the long term plan such > as it is is to convert to other formats and I can't immediately think > how one would do it otherwise in a way that works well. > If build isn't saying anything, we can move on from SPDX comment. :) thanks, -- Shuah
On Mon, Feb 07, 2022 at 03:20:35PM +0000, Mark Brown wrote: > diff --git a/Documentation/arm64/sme.rst b/Documentation/arm64/sme.rst > new file mode 100644 > index 000000000000..15df3157c592 > --- /dev/null > +++ b/Documentation/arm64/sme.rst [...] > +3. Sharing of streaming and non-streaming mode SVE state > +--------------------------------------------------------- > + > +It is implementation defined which if any parts of the SVE state are shared > +between streaming and non-streaming modes. When switching between modes > +via software interfaces such as ptrace if no register content is provided as > +part of switching no state will be assumed to be shared and everything will > +be zeroed. Is there anything other than ptrace() here? I read the sigreturn() case below but did not say anything about changing PSTATE.SM via the sigcontext. I guess it's similar to ptrace(). > +4. System call behaviour > +------------------------- > + > +* On syscall PSTATE.ZA is preserved, if PSTATE.ZA==1 then the contents of the > + ZA matrix are preserved. Sorry if this was discussed. What is the rationale for preserving the ZA registers on syscall? We don't do this for the top part of the Z registers. > +* On syscall PSTATE.SM will be cleared and the SVE registers will be handled > + as normal. What does that mean? Is this as per the sve.rst doc (unspecified but zeroed in practice)? > +* Neither the SVE registers nor ZA are used to pass arguments to or receive > + results from any syscall. > + > +* On creation fork() or clone() the newly created process will have PSTATE.SM > + and PSTATE.ZA cleared. This looks slightly inconsistent with the first bullet point on ZA being preserved on syscalls. Why do these differ? [...] > +References > +========== > + > +[1] arch/arm64/include/uapi/asm/sigcontext.h > + AArch64 Linux signal ABI definitions > + > +[2] arch/arm64/include/uapi/asm/ptrace.h > + AArch64 Linux ptrace ABI definitions > + > +[3] Documentation/arm64/cpu-feature-registers.rst > + > +[4] ARM IHI0055C > + http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055c/IHI0055C_beta_aapcs64.pdf > + http://infocenter.arm.com/help/topic/com.arm.doc.subset.swdev.abi/index.html > + Procedure Call Standard for the ARM 64-bit Architecture (AArch64) The second link no longer works. I also couldn't find any reference to [4] but there's a lot of text to scan, so I may have missed it.
On Thu, Feb 10, 2022 at 06:32:46PM +0000, Catalin Marinas wrote: > On Mon, Feb 07, 2022 at 03:20:35PM +0000, Mark Brown wrote: > > +It is implementation defined which if any parts of the SVE state are shared > > +between streaming and non-streaming modes. When switching between modes > > +via software interfaces such as ptrace if no register content is provided as > > +part of switching no state will be assumed to be shared and everything will > > +be zeroed. > Is there anything other than ptrace() here? I read the sigreturn() case > below but did not say anything about changing PSTATE.SM via the > sigcontext. I guess it's similar to ptrace(). The signal handling code requires that register data be provided to restore with either form of SVE data, this falls out of the existing requirement that register data be provided for SVE. > > +4. System call behaviour > > +------------------------- > > +* On syscall PSTATE.ZA is preserved, if PSTATE.ZA==1 then the contents of the > > + ZA matrix are preserved. > Sorry if this was discussed. What is the rationale for preserving the ZA > registers on syscall? We don't do this for the top part of the Z > registers. In both cases it's mirroring the expected PCS which is that for normal functions they must be called with streaming mode disabled, the high bits of Z may be changed and there is a lazy saving scheme for ZA. The handling of the Z registers falls out of a combination of the fact that the low bits are shared with the V registers and a desire to interoperate with binaries that are only aware of FPSIMD. See: https://github.com/rsandifo-arm/abi-aa/blob/sme-aapcs64/aapcs64/aapcs64.rst for the PCS (it's an open pull request on the AAPCS), if we disable ZA we should really cooperate with the lazy save scheme for ZA in section 6.5 which would involve writing to userspace buffers. Given that we need to support preserving ZA for cases where userspace is preempted it's not really much effort to do that, if userspace doesn't want the cost it can disable ZA before doing a syscall and it means that syscalls don't push userspace code that would otherwise not do anything with ZA to have problems interoperating with the lazy saving scheme. If we don't preserve ZA then userspace will be forced to save it when enabled which increases overall costs, if we do preserve ZA then it's no more expensive for the kernel to save it than userspace, we avoid the cost of restoring in the case where return directly to userspace without context switching and if we do future work to save more lazily then we may be able to avoid some of the saves. > > + as normal. > What does that mean? Is this as per the sve.rst doc (unspecified but > zeroed in practice)? Yes, we will exit streaming mode and proceed as per sve.rst and the rest of the ABI. > > +* Neither the SVE registers nor ZA are used to pass arguments to or receive > > + results from any syscall. > > + > > +* On creation fork() or clone() the newly created process will have PSTATE.SM > > + and PSTATE.ZA cleared. > This looks slightly inconsistent with the first bullet point on ZA being > preserved on syscalls. Why do these differ? Largely just because it's more complicated to implement copying the ZA backing store for this and it seemed more likely that someone would be surprised by a new process getting stuck carrying a potentially large copy of ZA around that it was unaware of than that someone would actually want that to happen. It's not a particularly strongly held opinon. > > +[4] ARM IHI0055C > > + http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055c/IHI0055C_beta_aapcs64.pdf > > + http://infocenter.arm.com/help/topic/com.arm.doc.subset.swdev.abi/index.html > > + Procedure Call Standard for the ARM 64-bit Architecture (AArch64) > The second link no longer works. I also couldn't find any reference to > [4] but there's a lot of text to scan, so I may have missed it. We don't referenced it, it's just carried over from SVE.
On Thu, Feb 10, 2022 at 07:45:49PM +0000, Mark Brown wrote: > On Thu, Feb 10, 2022 at 06:32:46PM +0000, Catalin Marinas wrote: > > On Mon, Feb 07, 2022 at 03:20:35PM +0000, Mark Brown wrote: > > > +4. System call behaviour > > > +------------------------- > > > > +* On syscall PSTATE.ZA is preserved, if PSTATE.ZA==1 then the contents of the > > > + ZA matrix are preserved. > > > Sorry if this was discussed. What is the rationale for preserving the ZA > > registers on syscall? We don't do this for the top part of the Z > > registers. > > In both cases it's mirroring the expected PCS which is that for normal > functions they must be called with streaming mode disabled, the high > bits of Z may be changed and there is a lazy saving scheme for ZA. The > handling of the Z registers falls out of a combination of the fact that > the low bits are shared with the V registers and a desire to > interoperate with binaries that are only aware of FPSIMD. > > See: > > https://github.com/rsandifo-arm/abi-aa/blob/sme-aapcs64/aapcs64/aapcs64.rst > > for the PCS (it's an open pull request on the AAPCS), if we disable ZA > we should really cooperate with the lazy save scheme for ZA in section > 6.5 which would involve writing to userspace buffers. Given that we > need to support preserving ZA for cases where userspace is preempted > it's not really much effort to do that, if userspace doesn't want the > cost it can disable ZA before doing a syscall and it means that syscalls > don't push userspace code that would otherwise not do anything with ZA > to have problems interoperating with the lazy saving scheme. > > If we don't preserve ZA then userspace will be forced to save it when > enabled which increases overall costs, if we do preserve ZA then it's no > more expensive for the kernel to save it than userspace, we avoid the > cost of restoring in the case where return directly to userspace without > context switching and if we do future work to save more lazily then we > may be able to avoid some of the saves. Thanks for the explanation and the PCS pointer. I guess doing the lazy saving scheme in the syscall handler is a lot more painful (faults etc.) and it's a user-only ABI/PCS, so we shouldn't tie the kernel into it. Given that Linux doesn't plan to use the ZA registers itself, in most cases it won't need to restore anything. But we still need to save the ZA registers on context switch in case the thread wakes up on a different CPU. How often do you reckon would the user do a syscall with active ZA? Anyway, I'll go through the other patches and get back to the ABI doc later, once I understand the kernel implementation better. > > > + as normal. > > > What does that mean? Is this as per the sve.rst doc (unspecified but > > zeroed in practice)? > > Yes, we will exit streaming mode and proceed as per sve.rst and the rest > of the ABI. So in this case we consider the syscall interface as non-streaming (as per the PCS terminology). Should we require that the PSTATE.SM is cleared by the user as well? Alternatively, we could make it streaming-compatible and just preserve it. Are there any drawbacks? kernel_neon_begin() could clear SM if needed. > > > +* Neither the SVE registers nor ZA are used to pass arguments to or receive > > > + results from any syscall. > > > + > > > +* On creation fork() or clone() the newly created process will have PSTATE.SM > > > + and PSTATE.ZA cleared. > > > This looks slightly inconsistent with the first bullet point on ZA being > > preserved on syscalls. Why do these differ? > > Largely just because it's more complicated to implement copying the ZA > backing store for this and it seemed more likely that someone would be > surprised by a new process getting stuck carrying a potentially large > copy of ZA around that it was unaware of than that someone would > actually want that to happen. It's not a particularly strongly held > opinon. If PSTATE.ZA is valid and the user does a fork() (well, implemented as clone()), normally it expects a nearly identical state in the child. With clone() if a new thread is created, we likely don't need the additional ZA state. We got away with having to think about this for SVE as the state is lost on syscall. Here we risk having a vaguely defined ABI - fork() is disabled on arm64 for example but we do have clone() and clone3(). Still thinking about this but maybe we could do something like always copy the ZA state unless CLONE_VM is passed for example. It is marginally more precise. > > > +[4] ARM IHI0055C > > > + http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055c/IHI0055C_beta_aapcs64.pdf > > > + http://infocenter.arm.com/help/topic/com.arm.doc.subset.swdev.abi/index.html > > > + Procedure Call Standard for the ARM 64-bit Architecture (AArch64) > > > The second link no longer works. I also couldn't find any reference to > > [4] but there's a lot of text to scan, so I may have missed it. > > We don't referenced it, it's just carried over from SVE. So I guess we can drop them from this doc.
On Fri, Feb 11, 2022 at 05:02:16PM +0000, Catalin Marinas wrote: > On Thu, Feb 10, 2022 at 07:45:49PM +0000, Mark Brown wrote: > > If we don't preserve ZA then userspace will be forced to save it when > > enabled which increases overall costs, if we do preserve ZA then it's no > > more expensive for the kernel to save it than userspace, we avoid the > > cost of restoring in the case where return directly to userspace without > > context switching and if we do future work to save more lazily then we > > may be able to avoid some of the saves. > Thanks for the explanation and the PCS pointer. I guess doing the lazy > saving scheme in the syscall handler is a lot more painful (faults etc.) > and it's a user-only ABI/PCS, so we shouldn't tie the kernel into it. Yes, other than the considerations around clone() it's clearly more complicated to engage with. > Given that Linux doesn't plan to use the ZA registers itself, in most > cases it won't need to restore anything. But we still need to save the > ZA registers on context switch in case the thread wakes up on a > different CPU. How often do you reckon would the user do a syscall with > active ZA? I would expect it to be very rare that userspace would want to do a syscall with ZA enabled, though obviously there's not a huge body of real world SME code to validate that against yet. The expected usage pattern is that both ZA and SM are only enabled for fairly brief bursts of intense computation and disabled when not actively used. It's possible that you will see things like logging during computation, or perhaps streaming data to/from a running algorithm incrementally during operation, generating syscalls so I wouldn't be surprised to see it happen but it for most systems it should be a very small percentage of system calls. > > > What does that mean? Is this as per the sve.rst doc (unspecified but > > > zeroed in practice)? > > Yes, we will exit streaming mode and proceed as per sve.rst and the rest > > of the ABI. > So in this case we consider the syscall interface as non-streaming (as > per the PCS terminology). Should we require that the PSTATE.SM is > cleared by the user as well? Alternatively, we could make it > streaming-compatible and just preserve it. Are there any drawbacks? > kernel_neon_begin() could clear SM if needed. In fact kernel_neon_begin() already disables PSTATE.SM since we need to account for the case where userspace was preempted rather than issued a syscall. We could require that PSTATE.SM is disabled by the user, though it's questionable what we could usefully and helpfully do about it if they forget other than disable it anyway or generate a signal. We could preserve PSTATE.SM, though since all the other register state for streaming mode is shared with SVE I would expect that we should be applying the SVE discard rules to it and there is therefore no other state that should be retained. As things stand this would either result in more overhead or complicate the register save and restore a bit since if we're in streaming mode we currently assume that we should save and restore the full SVE register contents but normally in a syscall we only need to save and restore the FPSIMD subset. The overhead might go away anyway as a result of general work on syscall optimisation for SVE, though that work isn't done yet and may not end up working out that way. Having said that as with ZA userspace can just exit streaming mode to avoid any overhead having it enabled introduces and the common case is expected to be that it will have done so due to the PCS, it should be an extremely rare case - unlike keeping ZA active there doesn't seem to be any case where it would be sensible to want to do this and the PCS means you'd have to actively try to do so. > > Largely just because it's more complicated to implement copying the ZA > > backing store for this and it seemed more likely that someone would be > > surprised by a new process getting stuck carrying a potentially large > > copy of ZA around that it was unaware of than that someone would > > actually want that to happen. It's not a particularly strongly held > > opinon. > If PSTATE.ZA is valid and the user does a fork() (well, implemented as > clone()), normally it expects a nearly identical state in the child. > With clone() if a new thread is created, we likely don't need the > additional ZA state. We got away with having to think about this for > SVE as the state is lost on syscall. Here we risk having a vaguely > defined ABI - fork() is disabled on arm64 for example but we do have > clone() and clone3(). > Still thinking about this but maybe we could do something like always > copy the ZA state unless CLONE_VM is passed for example. It is > marginally more precise. We should definitely write this up a bit more explictly whatever we do, like I say I don't really have strong opinions here. There's also the interaction with the lazy save state to consider - TPIDR2 is cleared if CLONE_SETTLS is specified which would interfere with any lazy state saving that had already happened, though hopefully userspace is taking care of that as part of setting up the new thread so I think it's fine.
On Fri, Feb 11, 2022 at 06:13:58PM +0000, Mark Brown wrote: > On Fri, Feb 11, 2022 at 05:02:16PM +0000, Catalin Marinas wrote: > > So in this case we consider the syscall interface as non-streaming (as > > per the PCS terminology). Should we require that the PSTATE.SM is > > cleared by the user as well? Alternatively, we could make it > > streaming-compatible and just preserve it. Are there any drawbacks? > > kernel_neon_begin() could clear SM if needed. > > In fact kernel_neon_begin() already disables PSTATE.SM since we need to > account for the case where userspace was preempted rather than issued a > syscall. We could require that PSTATE.SM is disabled by the user, > though it's questionable what we could usefully and helpfully do about > it if they forget other than disable it anyway or generate a signal. > > We could preserve PSTATE.SM, though since all the other register state > for streaming mode is shared with SVE I would expect that we should be > applying the SVE discard rules to it and there is therefore no other > state that should be retained. So when clearing PSTATE.SM, the streaming SVE regs become unknown (well, the wording is a bit more verbose). I think this fits well with the proposal to drop the streaming SVE state entirely on syscalls. The ZA state I think is not affected by the PSTATE.SM change (early internal SME specs were listing this as unknown after SM clearing but I can't find it in the latest spec). However, after the syscall, the user won't be able to execute SME instruction until turning on PSTATE.SM again. Would the libc wrappers preserve PSTATE.SM? What I find a bit confusing is that we only partially preserve some state while in streaming mode - the ZA registers but not the SVE ones. Is the user more likely to turn PSTATE.SM on for ZA processing or for SVE? If the former, we don't want to unnecessarily save/restore some SVE state that the user doesn't care about (can we even trap SVE instructions independently of SME while in streaming mode?). I'd find it clearer if we preserved PSTATE.SM and, w.r.t. the streaming SVE state, we somewhat follow the PCS and not restore the regs (input from the libc people welcomed). > As things stand this would either result > in more overhead or complicate the register save and restore a bit since > if we're in streaming mode we currently assume that we should save and > restore the full SVE register contents but normally in a syscall we only > need to save and restore the FPSIMD subset. The overhead might go away > anyway as a result of general work on syscall optimisation for SVE, > though that work isn't done yet and may not end up working out that way. > > Having said that as with ZA userspace can just exit streaming mode to > avoid any overhead having it enabled introduces and the common case is > expected to be that it will have done so due to the PCS, it should be an > extremely rare case - unlike keeping ZA active there doesn't seem to be > any case where it would be sensible to want to do this and the PCS means > you'd have to actively try to do so. IIUC, the PCS introduced the notion of streaming-compatible functions that preserve the SM bit. If they are non-streaming, SM should be 0 on entry. It would be nice if we put the syscalls in one of these categories, so either mandate SM == 0 on entry or preserve (the latter being easier, I think, I haven't looked at what it takes to save/restore the streaming SVE state; I may change my mind after reviewing at the other patches). > > If PSTATE.ZA is valid and the user does a fork() (well, implemented as > > clone()), normally it expects a nearly identical state in the child. > > With clone() if a new thread is created, we likely don't need the > > additional ZA state. We got away with having to think about this for > > SVE as the state is lost on syscall. Here we risk having a vaguely > > defined ABI - fork() is disabled on arm64 for example but we do have > > clone() and clone3(). > > > Still thinking about this but maybe we could do something like always > > copy the ZA state unless CLONE_VM is passed for example. It is > > marginally more precise. > > We should definitely write this up a bit more explictly whatever we do, > like I say I don't really have strong opinions here. > > There's also the interaction with the lazy save state to consider - > TPIDR2 is cleared if CLONE_SETTLS is specified which would interfere > with any lazy state saving that had already happened, though hopefully > userspace is taking care of that as part of setting up the new thread so > I think it's fine. TPIDR2_EL0 should indeed be cleared in the child, it doesn't make sense to start a thread with this reg pointing to a buffer in another thread (not sure whether it needs to be tied to SETTLS but that works as well). In fork()+execve() cases, it doesn't make sense to preserve ZA in the child but we can't tell at fork/clone3() time. OTOH, it probably doesn't make much sense to call clone3() with PSTATE.ZA set either, so such copy would rarely/never happen in the kernel. We'd just carry some code for the classic fork() case. (few hours later) I think instead of singling out fork() (clone3() actually), we can just say that new tasks (process/thread) always start with PSTATE.ZA == 0, PSTATE.SM == 0 (tbd for this) and TPIDR2_EL0 == 0 irrespective of any clone3() flags (even CLONE_SETTLS). The C library will have to implement the lazy ZA saving in the parent before the syscall and the child will automatically recover the state if it follows the PCS.
On Mon, Feb 14, 2022 at 06:19:58PM +0000, Catalin Marinas wrote: > On Fri, Feb 11, 2022 at 06:13:58PM +0000, Mark Brown wrote: > > We could preserve PSTATE.SM, though since all the other register state > > for streaming mode is shared with SVE I would expect that we should be > > applying the SVE discard rules to it and there is therefore no other > > state that should be retained. > So when clearing PSTATE.SM, the streaming SVE regs become unknown (well, > the wording is a bit more verbose). I think this fits well with the > proposal to drop the streaming SVE state entirely on syscalls. They're preserved or zeroed, yes. > The ZA state I think is not affected by the PSTATE.SM change (early > internal SME specs were listing this as unknown after SM clearing but I > can't find it in the latest spec). However, after the syscall, the user > won't be able to execute SME instruction until turning on PSTATE.SM > again. Yes, ZA is preserved unless PSTATE.ZA is disabled. There are some instructions that can be used to interact with it outside of streaming mode, a subset of the instructions for loading and storing values in ZA. > Would the libc wrappers preserve PSTATE.SM? What I find a bit confusing > is that we only partially preserve some state while in streaming mode - > the ZA registers but not the SVE ones. I would expect that libc wrappers would expect to be called with streaming mode already disabled - that's what default functions in the PCS expect, and since without FA64 enabled a huge proportion of FPSIMD instructions and some SVE instructions become undefined standard code could easily generate traps if it uses those instructions for anything. I wouldn't expect that libc would explicitly disable SME itself in standard configurations. > Is the user more likely to turn > PSTATE.SM on for ZA processing or for SVE? If the former, we don't want > to unnecessarily save/restore some SVE state that the user doesn't care It's expected that any active work with ZA will require enabling streaming mode, you can't do any actual computation with it without doing so and most of the work with ZA will involve using the streaming mode SVE registers as part of the computation (eg, collecting results in a Z register, or doing an operation to a ZA tile using the contents of a Z register as an operand). It is also expected that some applications may prefer to execute what is mainly a SVE workload in streaming mode, as well as any performance relevant differences in the implementation choices the hardware makes it is likely that some systems will have vector lengths available in streaming mode that are otherwise unavailable (eg, you might have PEs with 128 bit FPSIMD/SVE units and a 512 bit SMCU). I don't have a good handle on which sort of usage is going to be more common, and I expect that the answer is going to be very system dependent varying based on both the mix of applications running on the system at any given moment and the capabilities of the standard and streaming mode floating point implementations that the system has. However the existing syscall ABI for the Z and P registers (which is all the SVE register state, FFR is a magic P register) means that unless we treat streaming mode differently to non-streaming mode we'll be discarding whatever state is there anyway so userspace by definition shouldn't have anything in there it expects to be preserved when it does a syscall. I'd rather not introduce an ABI that guarantees that we preserve the streaming mode SVE register state in cases where we discard (or can discard) the non-streaming SVE register state, that's both going to be more complicated to implement and more likely to cause unexpected differences that trip userspace up. > about (can we even trap SVE instructions independently of SME while in > streaming mode?). I'd need to check through but I don't believe so. > I'd find it clearer if we preserved PSTATE.SM and, w.r.t. the streaming > SVE state, we somewhat follow the PCS and not restore the regs (input > from the libc people welcomed). Like I say we can do that easily enough, it's not something I expect to ever come up in practical usage though. > > Having said that as with ZA userspace can just exit streaming mode to > > avoid any overhead having it enabled introduces and the common case is > > expected to be that it will have done so due to the PCS, it should be an > > extremely rare case - unlike keeping ZA active there doesn't seem to be > > any case where it would be sensible to want to do this and the PCS means > > you'd have to actively try to do so. > IIUC, the PCS introduced the notion of streaming-compatible functions > that preserve the SM bit. If they are non-streaming, SM should be 0 on Yes, it isn't the default though. > entry. It would be nice if we put the syscalls in one of these > categories, so either mandate SM == 0 on entry or preserve (the latter > being easier, I think, I haven't looked at what it takes to save/restore > the streaming SVE state; I may change my mind after reviewing at the > other patches). The streaming SVE state is identical to the SVE state with the exception of the FFR predicate register which is not present unless FA64 is available in the system and enabled and the separatly configured vector length. It's sounding like we may as well just preserve SM, it shouldn't come up that often anyway and if it causes performance problems we can probably optimise it, and/or userspace can simply just not do that. Like I say I don't have particularly strong feelings, the current behaviour was just the easiest thing to implement and it doesn't seem like there is a use case. This is fine by me, I can do that for the next version. [fork()/clone() behaviour] > (few hours later) I think instead of singling out fork() (clone3() > actually), we can just say that new tasks (process/thread) always start > with PSTATE.ZA == 0, PSTATE.SM == 0 (tbd for this) and TPIDR2_EL0 == 0 > irrespective of any clone3() flags (even CLONE_SETTLS). The C library > will have to implement the lazy ZA saving in the parent before the > syscall and the child will automatically recover the state if it follows > the PCS. Works for me, I think forcing the userspace to consider this is going to work out more robust.
diff --git a/Documentation/arm64/index.rst b/Documentation/arm64/index.rst index 4f840bac083e..ae21f8118830 100644 --- a/Documentation/arm64/index.rst +++ b/Documentation/arm64/index.rst @@ -21,6 +21,7 @@ ARM64 Architecture perf pointer-authentication silicon-errata + sme sve tagged-address-abi tagged-pointers diff --git a/Documentation/arm64/sme.rst b/Documentation/arm64/sme.rst new file mode 100644 index 000000000000..15df3157c592 --- /dev/null +++ b/Documentation/arm64/sme.rst @@ -0,0 +1,432 @@ +=================================================== +Scalable Matrix Extension support for AArch64 Linux +=================================================== + +This document outlines briefly the interface provided to userspace by Linux in +order to support use of the ARM Scalable Matrix Extension (SME). + +This is an outline of the most important features and issues only and not +intended to be exhaustive. It should be read in conjunction with the SVE +documentation in sve.rst which provides details on the Streaming SVE mode +included in SME. + +This document does not aim to describe the SME architecture or programmer's +model. To aid understanding, a minimal description of relevant programmer's +model features for SME is included in Appendix A. + + +1. General +----------- + +* PSTATE.SM, PSTATE.ZA, the streaming mode vector length, the ZA + register state and TPIDR2_EL0 are tracked per thread. + +* The presence of SME is reported to userspace via HWCAP2_SME in the aux vector + AT_HWCAP2 entry. Presence of this flag implies the presence of the SME + instructions and registers, and the Linux-specific system interfaces + described in this document. SME is reported in /proc/cpuinfo as "sme". + +* Support for the execution of SME instructions in userspace can also be + detected by reading the CPU ID register ID_AA64PFR1_EL1 using an MRS + instruction, and checking that the value of the SME field is nonzero. [3] + + It does not guarantee the presence of the system interfaces described in the + following sections: software that needs to verify that those interfaces are + present must check for HWCAP2_SME instead. + +* There are a number of optional SME features, presence of these is reported + through AT_HWCAP2 through: + + HWCAP2_SME_I16I64 + HWCAP2_SME_F64F64 + HWCAP2_SME_I8I32 + HWCAP2_SME_F16F32 + HWCAP2_SME_B16F32 + HWCAP2_SME_F32F32 + HWCAP2_SME_FA64 + + This list may be extended over time as the SME architecture evolves. + + These extensions are also reported via the CPU ID register ID_AA64SMFR0_EL1, + which userspace can read using an MRS instruction. See elf_hwcaps.txt and + cpu-feature-registers.txt for details. + +* Debuggers should restrict themselves to interacting with the target via the + NT_ARM_SVE, NT_ARM_SSVE and NT_ARM_ZA regsets. The recommended way + of detecting support for these regsets is to connect to a target process + first and then attempt a + + ptrace(PTRACE_GETREGSET, pid, NT_ARM_<regset>, &iov). + +* Whenever ZA register values are exchanged in memory between userspace and + the kernel, the register value is encoded in memory as a series of horizontal + vectors from 0 to VL/8-1 stored in the same endianness invariant format as is + used for SVE vectors. + +* On thread creation TPIDR2_EL0 is preserved unless CLONE_SETTLS is specified, + in which case it is set to 0. + +2. Vector lengths +------------------ + +SME defines a second vector length similar to the SVE vector length which is +controls the size of the streaming mode SVE vectors and the ZA matrix array. +The ZA matrix is square with each side having as many bytes as a SVE vector. + + +3. Sharing of streaming and non-streaming mode SVE state +--------------------------------------------------------- + +It is implementation defined which if any parts of the SVE state are shared +between streaming and non-streaming modes. When switching between modes +via software interfaces such as ptrace if no register content is provided as +part of switching no state will be assumed to be shared and everything will +be zeroed. + + +4. System call behaviour +------------------------- + +* On syscall PSTATE.ZA is preserved, if PSTATE.ZA==1 then the contents of the + ZA matrix are preserved. + +* On syscall PSTATE.SM will be cleared and the SVE registers will be handled + as normal. + +* Neither the SVE registers nor ZA are used to pass arguments to or receive + results from any syscall. + +* On creation fork() or clone() the newly created process will have PSTATE.SM + and PSTATE.ZA cleared. + +* All other SME state of a thread, including the currently configured vector + length, the state of the PR_SME_VL_INHERIT flag, and the deferred vector + length (if any), is preserved across all syscalls, subject to the specific + exceptions for execve() described in section 6. + + +5. Signal handling +------------------- + +* Signal handlers are invoked with streaming mode and ZA disabled. + +* A new signal frame record za_context encodes the ZA register contents on + signal delivery. [1] + +* The signal frame record for ZA always contains basic metadata, in particular + the thread's vector length (in za_context.vl). + +* The ZA matrix may or may not be included in the record, depending on + the value of PSTATE.ZA. The registers are present if and only if: + za_context.head.size >= ZA_SIG_CONTEXT_SIZE(sve_vq_from_vl(za_context.vl)) + in which case PSTATE.ZA == 1. + +* If matrix data is present, the remainder of the record has a vl-dependent + size and layout. Macros ZA_SIG_* are defined [1] to facilitate access to + them. + +* The matrix is stored as a series of horizontal vectors in the same format as + is used for SVE vectors. + +* If the ZA context is too big to fit in sigcontext.__reserved[], then extra + space is allocated on the stack, an extra_context record is written in + __reserved[] referencing this space. za_context is then written in the + extra space. Refer to [1] for further details about this mechanism. + + +5. Signal return +----------------- + +When returning from a signal handler: + +* If there is no za_context record in the signal frame, or if the record is + present but contains no register data as desribed in the previous section, + then ZA is disabled. + +* If za_context is present in the signal frame and contains matrix data then + PSTATE.ZA is set to 1 and ZA is populated with the specified data. + +* The vector length cannot be changed via signal return. If za_context.vl in + the signal frame does not match the current vector length, the signal return + attempt is treated as illegal, resulting in a forced SIGSEGV. + + +6. prctl extensions +-------------------- + +Some new prctl() calls are added to allow programs to manage the SME vector +length: + +prctl(PR_SME_SET_VL, unsigned long arg) + + Sets the vector length of the calling thread and related flags, where + arg == vl | flags. Other threads of the calling process are unaffected. + + vl is the desired vector length, where sve_vl_valid(vl) must be true. + + flags: + + PR_SME_VL_INHERIT + + Inherit the current vector length across execve(). Otherwise, the + vector length is reset to the system default at execve(). (See + Section 9.) + + PR_SME_SET_VL_ONEXEC + + Defer the requested vector length change until the next execve() + performed by this thread. + + The effect is equivalent to implicit exceution of the following + call immediately after the next execve() (if any) by the thread: + + prctl(PR_SME_SET_VL, arg & ~PR_SME_SET_VL_ONEXEC) + + This allows launching of a new program with a different vector + length, while avoiding runtime side effects in the caller. + + Without PR_SME_SET_VL_ONEXEC, the requested change takes effect + immediately. + + + Return value: a nonnegative on success, or a negative value on error: + EINVAL: SME not supported, invalid vector length requested, or + invalid flags. + + + On success: + + * Either the calling thread's vector length or the deferred vector length + to be applied at the next execve() by the thread (dependent on whether + PR_SME_SET_VL_ONEXEC is present in arg), is set to the largest value + supported by the system that is less than or equal to vl. If vl == + SVE_VL_MAX, the value set will be the largest value supported by the + system. + + * Any previously outstanding deferred vector length change in the calling + thread is cancelled. + + * The returned value describes the resulting configuration, encoded as for + PR_SME_GET_VL. The vector length reported in this value is the new + current vector length for this thread if PR_SME_SET_VL_ONEXEC was not + present in arg; otherwise, the reported vector length is the deferred + vector length that will be applied at the next execve() by the calling + thread. + + * Changing the vector length causes all of ZA, P0..P15, FFR and all bits of + Z0..Z31 except for Z0 bits [127:0] .. Z31 bits [127:0] to become + unspecified, including both streaming and non-streaming SVE state. + Calling PR_SME_SET_VL with vl equal to the thread's current vector + length, or calling PR_SME_SET_VL with the PR_SVE_SET_VL_ONEXEC flag, + does not constitute a change to the vector length for this purpose. + + * Changing the vector length causes PSTATE.ZA and PSTATE.SM to be cleared. + Calling PR_SME_SET_VL with vl equal to the thread's current vector + length, or calling PR_SME_SET_VL with the PR_SVE_SET_VL_ONEXEC flag, + does not constitute a change to the vector length for this purpose. + + +prctl(PR_SME_GET_VL) + + Gets the vector length of the calling thread. + + The following flag may be OR-ed into the result: + + PR_SME_VL_INHERIT + + Vector length will be inherited across execve(). + + There is no way to determine whether there is an outstanding deferred + vector length change (which would only normally be the case between a + fork() or vfork() and the corresponding execve() in typical use). + + To extract the vector length from the result, bitwise and it with + PR_SME_VL_LEN_MASK. + + Return value: a nonnegative value on success, or a negative value on error: + EINVAL: SME not supported. + + +7. ptrace extensions +--------------------- + +* A new regset NT_ARM_SSVE is defined for access to streaming mode SVE + state via PTRACE_GETREGSET and PTRACE_SETREGSET, this is documented in + sve.rst. + +* A new regset NT_ARM_ZA is defined for ZA state for access to ZA state via + PTRACE_GETREGSET and PTRACE_SETREGSET. + + Refer to [2] for definitions. + +The regset data starts with struct user_za_header, containing: + + size + + Size of the complete regset, in bytes. + This depends on vl and possibly on other things in the future. + + If a call to PTRACE_GETREGSET requests less data than the value of + size, the caller can allocate a larger buffer and retry in order to + read the complete regset. + + max_size + + Maximum size in bytes that the regset can grow to for the target + thread. The regset won't grow bigger than this even if the target + thread changes its vector length etc. + + vl + + Target thread's current streaming vector length, in bytes. + + max_vl + + Maximum possible streaming vector length for the target thread. + + flags + + Zero or more of the following flags, which have the same + meaning and behaviour as the corresponding PR_SET_VL_* flags: + + SME_PT_VL_INHERIT + + SME_PT_VL_ONEXEC (SETREGSET only). + +* The effects of changing the vector length and/or flags are equivalent to + those documented for PR_SME_SET_VL. + + The caller must make a further GETREGSET call if it needs to know what VL is + actually set by SETREGSET, unless is it known in advance that the requested + VL is supported. + +* The size and layout of the payload depends on the header fields. The + SME_PT_ZA_*() macros are provided to facilitate access to the data. + +* In either case, for SETREGSET it is permissible to omit the payload, in which + case the vector length and flags are changed and PSTATE.ZA is set to 0 + (along with any consequences of those changes). If a payload is provided + then PSTATE.ZA will be set to 1. + +* For SETREGSET, if the requested VL is not supported, the effect will be the + same as if the payload were omitted, except that an EIO error is reported. + No attempt is made to translate the payload data to the correct layout + for the vector length actually set. It is up to the caller to translate the + payload layout for the actual VL and retry. + +* The effect of writing a partial, incomplete payload is unspecified. + + +8. ELF coredump extensions +--------------------------- + +* NT_ARM_SSVE notes will be added to each coredump for + each thread of the dumped process. The contents will be equivalent to the + data that would have been read if a PTRACE_GETREGSET of the corresponding + type were executed for each thread when the coredump was generated. + +* A NT_ARM_ZA note will be added to each coredump for each thread of the + dumped process. The contents will be equivalent to the data that would have + been read if a PTRACE_GETREGSET of NT_ARM_ZA were executed for each thread + when the coredump was generated. + + +9. System runtime configuration +-------------------------------- + +* To mitigate the ABI impact of expansion of the signal frame, a policy + mechanism is provided for administrators, distro maintainers and developers + to set the default vector length for userspace processes: + +/proc/sys/abi/sme_default_vector_length + + Writing the text representation of an integer to this file sets the system + default vector length to the specified value, unless the value is greater + than the maximum vector length supported by the system in which case the + default vector length is set to that maximum. + + The result can be determined by reopening the file and reading its + contents. + + At boot, the default vector length is initially set to 32 or the maximum + supported vector length, whichever is smaller and supported. This + determines the initial vector length of the init process (PID 1). + + Reading this file returns the current system default vector length. + +* At every execve() call, the new vector length of the new process is set to + the system default vector length, unless + + * PR_SME_VL_INHERIT (or equivalently SME_PT_VL_INHERIT) is set for the + calling thread, or + + * a deferred vector length change is pending, established via the + PR_SME_SET_VL_ONEXEC flag (or SME_PT_VL_ONEXEC). + +* Modifying the system default vector length does not affect the vector length + of any existing process or thread that does not make an execve() call. + + +Appendix A. SME programmer's model (informative) +================================================= + +This section provides a minimal description of the additions made by SVE to the +ARMv8-A programmer's model that are relevant to this document. + +Note: This section is for information only and not intended to be complete or +to replace any architectural specification. + +A.1. Registers +--------------- + +In A64 state, SME adds the following: + +* A new mode, streaming mode, in which a subset of the normal FPSIMD and SVE + features are available. When supported EL0 software may enter and leave + streaming mode at any time. + + For best system performance it is strongly encouraged for software to enable + streaming mode only when it is actively being used. + +* A new vector length controlling the size of ZA and the Z registers when in + streaming mode, separately to the vector length used for SVE when not in + streaming mode. There is no requirement that either the currently selected + vector length or the set of vector lengths supported for the two modes in + a given system have any relationship. The streaming mode vector length + is referred to as SVL. + +* A new ZA matrix register. This is a square matrix of SVLxSVL bits. Most + operations on ZA require that streaming mode be enabled but ZA can be + enabled without streaming mode in order to load, save and retain data. + + For best system performance it is strongly encouraged for software to enable + ZA only when it is actively being used. + +* Two new 1 bit fields in PSTATE which may be controlled via the SMSTART and + SMSTOP instructions or by access to the SVCR system register: + + * PSTATE.ZA, if this is 1 then the ZA matrix is accessible and has valid + data while if it is 0 then ZA can not be accessed. When PSTATE.ZA is + changed from 0 to 1 all bits in ZA are cleared. + + * PSTATE.SM, if this is 1 then the PE is in streaming mode. When the value + of PSTATE.SM is changed then it is implementation defined if the subset + of the floating point register bits valid in both modes may be retained. + Any other bits will be cleared. + + +References +========== + +[1] arch/arm64/include/uapi/asm/sigcontext.h + AArch64 Linux signal ABI definitions + +[2] arch/arm64/include/uapi/asm/ptrace.h + AArch64 Linux ptrace ABI definitions + +[3] Documentation/arm64/cpu-feature-registers.rst + +[4] ARM IHI0055C + http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055c/IHI0055C_beta_aapcs64.pdf + http://infocenter.arm.com/help/topic/com.arm.doc.subset.swdev.abi/index.html + Procedure Call Standard for the ARM 64-bit Architecture (AArch64) diff --git a/Documentation/arm64/sve.rst b/Documentation/arm64/sve.rst index 9d9a4de5bc34..93c2c2990584 100644 --- a/Documentation/arm64/sve.rst +++ b/Documentation/arm64/sve.rst @@ -7,7 +7,9 @@ Author: Dave Martin <Dave.Martin@arm.com> Date: 4 August 2017 This document outlines briefly the interface provided to userspace by Linux in -order to support use of the ARM Scalable Vector Extension (SVE). +order to support use of the ARM Scalable Vector Extension (SVE), including +interactions with Streaming SVE mode added by the Scalable Matrix Extension +(SME). This is an outline of the most important features and issues only and not intended to be exhaustive. @@ -23,6 +25,10 @@ model features for SVE is included in Appendix A. * SVE registers Z0..Z31, P0..P15 and FFR and the current vector length VL, are tracked per-thread. +* In streaming mode FFR is not accessible unless HWCAP2_SME_FA64 is present + in the system, when it is not supported and these interfaces are used to + access streaming mode FFR is read and written as zero. + * The presence of SVE is reported to userspace via HWCAP_SVE in the aux vector AT_HWCAP entry. Presence of this flag implies the presence of the SVE instructions and registers, and the Linux-specific system interfaces @@ -53,10 +59,19 @@ model features for SVE is included in Appendix A. which userspace can read using an MRS instruction. See elf_hwcaps.txt and cpu-feature-registers.txt for details. +* On hardware that supports the SME extensions, HWCAP2_SME will also be + reported in the AT_HWCAP2 aux vector entry. Among other things SME adds + streaming mode which provides a subset of the SVE feature set using a + separate SME vector length and the same Z/V registers. See sme.rst + for more details. + * Debuggers should restrict themselves to interacting with the target via the NT_ARM_SVE regset. The recommended way of detecting support for this regset is to connect to a target process first and then attempt a - ptrace(PTRACE_GETREGSET, pid, NT_ARM_SVE, &iov). + ptrace(PTRACE_GETREGSET, pid, NT_ARM_SVE, &iov). Note that when SME is + present and streaming SVE mode is in use the FPSIMD subset of registers + will be read via NT_ARM_SVE and NT_ARM_SVE writes will exit streaming mode + in the target. * Whenever SVE scalable register values (Zn, Pn, FFR) are exchanged in memory between userspace and the kernel, the register value is encoded in memory in @@ -126,6 +141,11 @@ the SVE instruction set architecture. are only present in fpsimd_context. For convenience, the content of V0..V31 is duplicated between sve_context and fpsimd_context. +* The record contains a flag field which includes a flag SVE_SIG_FLAG_SM which + if set indicates that the thread is in streaming mode and the vector length + and register data (if present) describe the streaming SVE data and vector + length. + * The signal frame record for SVE always contains basic metadata, in particular the thread's vector length (in sve_context.vl). @@ -170,6 +190,11 @@ When returning from a signal handler: the signal frame does not match the current vector length, the signal return attempt is treated as illegal, resulting in a forced SIGSEGV. +* It is permitted to enter or leave streaming mode by setting or clearing + the SVE_SIG_FLAG_SM flag but applications should take care to ensure that + when doing so sve_context.vl and any register data are appropriate for the + vector length in the new mode. + 6. prctl extensions -------------------- @@ -265,8 +290,14 @@ prctl(PR_SVE_GET_VL) 7. ptrace extensions --------------------- -* A new regset NT_ARM_SVE is defined for use with PTRACE_GETREGSET and - PTRACE_SETREGSET. +* New regsets NT_ARM_SVE and NT_ARM_SSVE are defined for use with + PTRACE_GETREGSET and PTRACE_SETREGSET. NT_ARM_SSVE describes the + streaming mode SVE registers and NT_ARM_SVE describes the + non-streaming mode SVE registers. + + In this description a register set is referred to as being "live" when + the target is in the appropriate streaming or non-streaming mode and is + using data beyond the subset shared with the FPSIMD Vn registers. Refer to [2] for definitions. @@ -297,7 +328,7 @@ The regset data starts with struct user_sve_header, containing: flags - either + at most one of SVE_PT_REGS_FPSIMD @@ -331,6 +362,10 @@ The regset data starts with struct user_sve_header, containing: SVE_PT_VL_ONEXEC (SETREGSET only). + If neither FPSIMD nor SVE flags are provided then no register + payload is available, this is only possible when SME is implemented. + + * The effects of changing the vector length and/or flags are equivalent to those documented for PR_SVE_SET_VL. @@ -346,6 +381,13 @@ The regset data starts with struct user_sve_header, containing: case only the vector length and flags are changed (along with any consequences of those changes). +* In systems supporting SME when in streaming mode a GETREGSET for + NT_REG_SVE will return only the user_sve_header with no register data, + similarly a GETREGSET for NT_REG_SSVE will not return any register data + when not in streaming mode. + +* A GETREGSET for NT_ARM_SSVE will never return SVE_PT_REGS_FPSIMD. + * For SETREGSET, if an SVE_PT_REGS_SVE payload is present and the requested VL is not supported, the effect will be the same as if the payload were omitted, except that an EIO error is reported. No @@ -355,17 +397,25 @@ The regset data starts with struct user_sve_header, containing: unspecified. It is up to the caller to translate the payload layout for the actual VL and retry. +* Where SME is implemented it is not possible to GETREGSET the register + state for normal SVE when in streaming mode, nor the streaming mode + register state when in normal mode, regardless of the implementation defined + behaviour of the hardware for sharing data between the two modes. + +* Any SETREGSET of NT_ARM_SVE will exit streaming mode if the target was in + streaming mode and any SETREGSET of NT_ARM_SSVE will enter streaming mode + if the target was not in streaming mode. + * The effect of writing a partial, incomplete payload is unspecified. 8. ELF coredump extensions --------------------------- -* A NT_ARM_SVE note will be added to each coredump for each thread of the - dumped process. The contents will be equivalent to the data that would have - been read if a PTRACE_GETREGSET of NT_ARM_SVE were executed for each thread - when the coredump was generated. - +* NT_ARM_SVE and NT_ARM_SSVE notes will be added to each coredump for + each thread of the dumped process. The contents will be equivalent to the + data that would have been read if a PTRACE_GETREGSET of the corresponding + type were executed for each thread when the coredump was generated. 9. System runtime configuration --------------------------------
Provide ABI documentation for SME similar to that for SVE. Due to the very large overlap around streaming SVE mode in both implementation and interfaces documentation for streaming mode SVE is added to the SVE document rather than the SME one. Signed-off-by: Mark Brown <broonie@kernel.org> --- Documentation/arm64/index.rst | 1 + Documentation/arm64/sme.rst | 432 ++++++++++++++++++++++++++++++++++ Documentation/arm64/sve.rst | 70 +++++- 3 files changed, 493 insertions(+), 10 deletions(-) create mode 100644 Documentation/arm64/sme.rst