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=-9.0 required=3.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH,MAILING_LIST_MULTI,SIGNED_OFF_BY,SPF_PASS,USER_AGENT_GIT autolearn=unavailable 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 9B71CC4360F for ; Mon, 18 Mar 2019 16:36:10 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 6D4CA2133D for ; Mon, 18 Mar 2019 16:36:10 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727811AbfCRQgI (ORCPT ); Mon, 18 Mar 2019 12:36:08 -0400 Received: from usa-sjc-mx-foss1.foss.arm.com ([217.140.101.70]:37300 "EHLO foss.arm.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726806AbfCRQgG (ORCPT ); Mon, 18 Mar 2019 12:36:06 -0400 Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.72.51.249]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 87E5A1682; Mon, 18 Mar 2019 09:36:05 -0700 (PDT) Received: from e119884-lin.cambridge.arm.com (e119884-lin.cambridge.arm.com [10.1.196.72]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 63E6A3F614; Mon, 18 Mar 2019 09:35:59 -0700 (PDT) From: Vincenzo Frascino To: linux-arm-kernel@lists.infradead.org, linux-doc@vger.kernel.org, linux-mm@kvack.org, linux-arch@vger.kernel.org, linux-kselftest@vger.kernel.org, linux-kernel@vger.kernel.org Cc: Alexander Viro , Alexei Starovoitov , Andrew Morton , Andrey Konovalov , Arnaldo Carvalho de Melo , Branislav Rankov , Catalin Marinas , Chintan Pandya , Daniel Borkmann , Dave Martin , "David S. Miller" , Dmitry Vyukov , Eric Dumazet , Evgeniy Stepanov , Graeme Barnes , Greg Kroah-Hartman , Ingo Molnar , Jacob Bramley , Kate Stewart , Kees Cook , Kevin Brodsky , "Kirill A . Shutemov" , Kostya Serebryany , Lee Smith , Luc Van Oostenryck , Mark Rutland , Peter Zijlstra , Ramana Radhakrishnan , Robin Murphy , Ruben Ayrapetyan , Shuah Khan , Steven Rostedt , Szabolcs Nagy , Will Deacon Subject: [PATCH v2 2/4] arm64: Define Documentation/arm64/elf_at_flags.txt Date: Mon, 18 Mar 2019 16:35:31 +0000 Message-Id: <20190318163533.26838-3-vincenzo.frascino@arm.com> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190318163533.26838-1-vincenzo.frascino@arm.com> References: <20190318163533.26838-1-vincenzo.frascino@arm.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On arm64 the TCR_EL1.TBI0 bit has been always enabled hence the userspace (EL0) is allowed to set a non-zero value in the top byte but the resulting pointers are not allowed at the user-kernel syscall ABI boundary. With the relaxed ABI proposed through this document, it is now possible to pass tagged pointers to the syscalls, when these pointers are in memory ranges obtained by an anonymous (MAP_ANONYMOUS) mmap() or brk(). This change in the ABI requires a mechanism to inform the userspace that such an option is available. Specify and document the way in which AT_FLAGS can be used to advertise this feature to the userspace. Cc: Catalin Marinas Cc: Will Deacon CC: Andrey Konovalov Signed-off-by: Vincenzo Frascino Squash with "arm64: Define Documentation/arm64/elf_at_flags.txt" --- Documentation/arm64/elf_at_flags.txt | 133 +++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 Documentation/arm64/elf_at_flags.txt diff --git a/Documentation/arm64/elf_at_flags.txt b/Documentation/arm64/elf_at_flags.txt new file mode 100644 index 000000000000..9b3494207c14 --- /dev/null +++ b/Documentation/arm64/elf_at_flags.txt @@ -0,0 +1,133 @@ +ARM64 ELF AT_FLAGS +================== + +This document describes the usage and semantics of AT_FLAGS on arm64. + +1. Introduction +--------------- + +AT_FLAGS is part of the Auxiliary Vector, contains the flags and it +is set to zero by the kernel on arm64 unless one or more of the +features detailed in paragraph 2 are present. + +The auxiliary vector can be accessed by the userspace using the +getauxval() API provided by the C library. +getauxval() returns an unsigned long and when a flag is present in +the AT_FLAGS, the corresponding bit in the returned value is set to 1. + +The AT_FLAGS with a "defined semantics" on arm64 are exposed to the +userspace via user API (uapi/asm/atflags.h). +The AT_FLAGS bits with "undefined semantics" are set to zero by default. +This means that the AT_FLAGS bits to which this document does not assign +an explicit meaning are to be intended reserved for future use. +The kernel will populate all such bits with zero until meanings are +assigned to them. If and when meanings are assigned, it is guaranteed +that they will not impact the functional operation of existing userspace +software. Userspace software should ignore any AT_FLAGS bit whose meaning +is not defined when the software is written. + +The userspace software can test for features by acquiring the AT_FLAGS +entry of the auxiliary vector, and testing whether a relevant flag +is set. + +Example of a userspace test function: + +bool feature_x_is_present(void) +{ + unsigned long at_flags = getauxval(AT_FLAGS); + if (at_flags & FEATURE_X) + return true; + + return false; +} + +Where the software relies on a feature advertised by AT_FLAGS, it +must check that the feature is present before attempting to +use it. + +2. Features exposed via AT_FLAGS +-------------------------------- + +bit[0]: ARM64_AT_FLAGS_SYSCALL_TBI + + On arm64 the TCR_EL1.TBI0 bit has been always enabled on the arm64 + kernel, hence the userspace (EL0) is allowed to set a non-zero value + in the top byte but the resulting pointers are not allowed at the + user-kernel syscall ABI boundary. + When bit[0] is set to 1 the kernel is advertising to the userspace + that a relaxed ABI is supported hence this type of pointers are now + allowed to be passed to the syscalls, when these pointers are in + memory ranges privately owned by a process and obtained by the + process in accordance with the definition of "valid tagged pointer" + in paragraph 3. + In these cases the tag is preserved as the pointer goes through the + kernel. Only when the kernel needs to check if a pointer is coming + from userspace an untag operation is required. + +3. ARM64_AT_FLAGS_SYSCALL_TBI +----------------------------- + +From the kernel syscall interface prospective, we define, for the purposes +of this document, a "valid tagged pointer" as a pointer that either it has +a zero value set in the top byte or it has a non-zero value, it is in memory +ranges privately owned by a userspace process and it is obtained in one of +the following ways: + - mmap() done by the process itself, where either: + * flags = MAP_PRIVATE | MAP_ANONYMOUS + * flags = MAP_PRIVATE and the file descriptor refers to a regular + file or "/dev/zero" + - a mapping below sbrk(0) done by the process itself + - any memory mapped by the kernel in the process's address space during + creation and following the restrictions presented above (i.e. data, bss, + stack). + +When the ARM64_AT_FLAGS_SYSCALL_TBI flag is set by the kernel, the following +behaviours are guaranteed by the ABI: + + - Every current or newly introduced syscall can accept any valid tagged + pointers. + + - If a non valid tagged pointer is passed to a syscall then the behaviour + is undefined. + + - Every valid tagged pointer is expected to work as an untagged one. + + - The kernel preserves any valid tagged pointers and returns them to the + userspace unchanged in all the cases except the ones documented in the + "Preserving tags" paragraph of tagged-pointers.txt. + +A definition of the meaning of tagged pointers on arm64 can be found in: +Documentation/arm64/tagged-pointers.txt. + +Example of correct usage (pseudo-code) for a userspace application: + +bool arm64_syscall_tbi_is_present(void) +{ + unsigned long at_flags = getauxval(AT_FLAGS); + if (at_flags & ARM64_AT_FLAGS_SYSCALL_TBI) + return true; + + return false; +} + +void main(void) +{ + char *addr = mmap(NULL, PAGE_SIZE, PROT_READ | PROT_WRITE, + MAP_ANONYMOUS, -1, 0); + + int fd = open("test.txt", O_WRONLY); + + /* Check if the relaxed ABI is supported */ + if (arm64_syscall_tbi_is_present()) { + /* Add a tag to the pointer */ + addr = tag_pointer(addr); + } + + strcpy("Hello World\n", addr); + + /* Write to a file */ + write(fd, addr, sizeof(addr)); + + close(fd); +} + -- 2.21.0 From mboxrd@z Thu Jan 1 00:00:00 1970 From: vincenzo.frascino at arm.com (Vincenzo Frascino) Date: Mon, 18 Mar 2019 16:35:31 +0000 Subject: [PATCH v2 2/4] arm64: Define Documentation/arm64/elf_at_flags.txt In-Reply-To: <20190318163533.26838-1-vincenzo.frascino@arm.com> References: <20190318163533.26838-1-vincenzo.frascino@arm.com> Message-ID: <20190318163533.26838-3-vincenzo.frascino@arm.com> On arm64 the TCR_EL1.TBI0 bit has been always enabled hence the userspace (EL0) is allowed to set a non-zero value in the top byte but the resulting pointers are not allowed at the user-kernel syscall ABI boundary. With the relaxed ABI proposed through this document, it is now possible to pass tagged pointers to the syscalls, when these pointers are in memory ranges obtained by an anonymous (MAP_ANONYMOUS) mmap() or brk(). This change in the ABI requires a mechanism to inform the userspace that such an option is available. Specify and document the way in which AT_FLAGS can be used to advertise this feature to the userspace. Cc: Catalin Marinas Cc: Will Deacon CC: Andrey Konovalov Signed-off-by: Vincenzo Frascino Squash with "arm64: Define Documentation/arm64/elf_at_flags.txt" --- Documentation/arm64/elf_at_flags.txt | 133 +++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 Documentation/arm64/elf_at_flags.txt diff --git a/Documentation/arm64/elf_at_flags.txt b/Documentation/arm64/elf_at_flags.txt new file mode 100644 index 000000000000..9b3494207c14 --- /dev/null +++ b/Documentation/arm64/elf_at_flags.txt @@ -0,0 +1,133 @@ +ARM64 ELF AT_FLAGS +================== + +This document describes the usage and semantics of AT_FLAGS on arm64. + +1. Introduction +--------------- + +AT_FLAGS is part of the Auxiliary Vector, contains the flags and it +is set to zero by the kernel on arm64 unless one or more of the +features detailed in paragraph 2 are present. + +The auxiliary vector can be accessed by the userspace using the +getauxval() API provided by the C library. +getauxval() returns an unsigned long and when a flag is present in +the AT_FLAGS, the corresponding bit in the returned value is set to 1. + +The AT_FLAGS with a "defined semantics" on arm64 are exposed to the +userspace via user API (uapi/asm/atflags.h). +The AT_FLAGS bits with "undefined semantics" are set to zero by default. +This means that the AT_FLAGS bits to which this document does not assign +an explicit meaning are to be intended reserved for future use. +The kernel will populate all such bits with zero until meanings are +assigned to them. If and when meanings are assigned, it is guaranteed +that they will not impact the functional operation of existing userspace +software. Userspace software should ignore any AT_FLAGS bit whose meaning +is not defined when the software is written. + +The userspace software can test for features by acquiring the AT_FLAGS +entry of the auxiliary vector, and testing whether a relevant flag +is set. + +Example of a userspace test function: + +bool feature_x_is_present(void) +{ + unsigned long at_flags = getauxval(AT_FLAGS); + if (at_flags & FEATURE_X) + return true; + + return false; +} + +Where the software relies on a feature advertised by AT_FLAGS, it +must check that the feature is present before attempting to +use it. + +2. Features exposed via AT_FLAGS +-------------------------------- + +bit[0]: ARM64_AT_FLAGS_SYSCALL_TBI + + On arm64 the TCR_EL1.TBI0 bit has been always enabled on the arm64 + kernel, hence the userspace (EL0) is allowed to set a non-zero value + in the top byte but the resulting pointers are not allowed at the + user-kernel syscall ABI boundary. + When bit[0] is set to 1 the kernel is advertising to the userspace + that a relaxed ABI is supported hence this type of pointers are now + allowed to be passed to the syscalls, when these pointers are in + memory ranges privately owned by a process and obtained by the + process in accordance with the definition of "valid tagged pointer" + in paragraph 3. + In these cases the tag is preserved as the pointer goes through the + kernel. Only when the kernel needs to check if a pointer is coming + from userspace an untag operation is required. + +3. ARM64_AT_FLAGS_SYSCALL_TBI +----------------------------- + +From the kernel syscall interface prospective, we define, for the purposes +of this document, a "valid tagged pointer" as a pointer that either it has +a zero value set in the top byte or it has a non-zero value, it is in memory +ranges privately owned by a userspace process and it is obtained in one of +the following ways: + - mmap() done by the process itself, where either: + * flags = MAP_PRIVATE | MAP_ANONYMOUS + * flags = MAP_PRIVATE and the file descriptor refers to a regular + file or "/dev/zero" + - a mapping below sbrk(0) done by the process itself + - any memory mapped by the kernel in the process's address space during + creation and following the restrictions presented above (i.e. data, bss, + stack). + +When the ARM64_AT_FLAGS_SYSCALL_TBI flag is set by the kernel, the following +behaviours are guaranteed by the ABI: + + - Every current or newly introduced syscall can accept any valid tagged + pointers. + + - If a non valid tagged pointer is passed to a syscall then the behaviour + is undefined. + + - Every valid tagged pointer is expected to work as an untagged one. + + - The kernel preserves any valid tagged pointers and returns them to the + userspace unchanged in all the cases except the ones documented in the + "Preserving tags" paragraph of tagged-pointers.txt. + +A definition of the meaning of tagged pointers on arm64 can be found in: +Documentation/arm64/tagged-pointers.txt. + +Example of correct usage (pseudo-code) for a userspace application: + +bool arm64_syscall_tbi_is_present(void) +{ + unsigned long at_flags = getauxval(AT_FLAGS); + if (at_flags & ARM64_AT_FLAGS_SYSCALL_TBI) + return true; + + return false; +} + +void main(void) +{ + char *addr = mmap(NULL, PAGE_SIZE, PROT_READ | PROT_WRITE, + MAP_ANONYMOUS, -1, 0); + + int fd = open("test.txt", O_WRONLY); + + /* Check if the relaxed ABI is supported */ + if (arm64_syscall_tbi_is_present()) { + /* Add a tag to the pointer */ + addr = tag_pointer(addr); + } + + strcpy("Hello World\n", addr); + + /* Write to a file */ + write(fd, addr, sizeof(addr)); + + close(fd); +} + -- 2.21.0 From mboxrd@z Thu Jan 1 00:00:00 1970 From: vincenzo.frascino@arm.com (Vincenzo Frascino) Date: Mon, 18 Mar 2019 16:35:31 +0000 Subject: [PATCH v2 2/4] arm64: Define Documentation/arm64/elf_at_flags.txt In-Reply-To: <20190318163533.26838-1-vincenzo.frascino@arm.com> References: <20190318163533.26838-1-vincenzo.frascino@arm.com> Message-ID: <20190318163533.26838-3-vincenzo.frascino@arm.com> Content-Type: text/plain; charset="UTF-8" Message-ID: <20190318163531.D9oXsDqnBlEMpRcd8Od5nVzNO_yAMtufpqu_0a3epAI@z> On arm64 the TCR_EL1.TBI0 bit has been always enabled hence the userspace (EL0) is allowed to set a non-zero value in the top byte but the resulting pointers are not allowed at the user-kernel syscall ABI boundary. With the relaxed ABI proposed through this document, it is now possible to pass tagged pointers to the syscalls, when these pointers are in memory ranges obtained by an anonymous (MAP_ANONYMOUS) mmap() or brk(). This change in the ABI requires a mechanism to inform the userspace that such an option is available. Specify and document the way in which AT_FLAGS can be used to advertise this feature to the userspace. Cc: Catalin Marinas Cc: Will Deacon CC: Andrey Konovalov Signed-off-by: Vincenzo Frascino Squash with "arm64: Define Documentation/arm64/elf_at_flags.txt" --- Documentation/arm64/elf_at_flags.txt | 133 +++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 Documentation/arm64/elf_at_flags.txt diff --git a/Documentation/arm64/elf_at_flags.txt b/Documentation/arm64/elf_at_flags.txt new file mode 100644 index 000000000000..9b3494207c14 --- /dev/null +++ b/Documentation/arm64/elf_at_flags.txt @@ -0,0 +1,133 @@ +ARM64 ELF AT_FLAGS +================== + +This document describes the usage and semantics of AT_FLAGS on arm64. + +1. Introduction +--------------- + +AT_FLAGS is part of the Auxiliary Vector, contains the flags and it +is set to zero by the kernel on arm64 unless one or more of the +features detailed in paragraph 2 are present. + +The auxiliary vector can be accessed by the userspace using the +getauxval() API provided by the C library. +getauxval() returns an unsigned long and when a flag is present in +the AT_FLAGS, the corresponding bit in the returned value is set to 1. + +The AT_FLAGS with a "defined semantics" on arm64 are exposed to the +userspace via user API (uapi/asm/atflags.h). +The AT_FLAGS bits with "undefined semantics" are set to zero by default. +This means that the AT_FLAGS bits to which this document does not assign +an explicit meaning are to be intended reserved for future use. +The kernel will populate all such bits with zero until meanings are +assigned to them. If and when meanings are assigned, it is guaranteed +that they will not impact the functional operation of existing userspace +software. Userspace software should ignore any AT_FLAGS bit whose meaning +is not defined when the software is written. + +The userspace software can test for features by acquiring the AT_FLAGS +entry of the auxiliary vector, and testing whether a relevant flag +is set. + +Example of a userspace test function: + +bool feature_x_is_present(void) +{ + unsigned long at_flags = getauxval(AT_FLAGS); + if (at_flags & FEATURE_X) + return true; + + return false; +} + +Where the software relies on a feature advertised by AT_FLAGS, it +must check that the feature is present before attempting to +use it. + +2. Features exposed via AT_FLAGS +-------------------------------- + +bit[0]: ARM64_AT_FLAGS_SYSCALL_TBI + + On arm64 the TCR_EL1.TBI0 bit has been always enabled on the arm64 + kernel, hence the userspace (EL0) is allowed to set a non-zero value + in the top byte but the resulting pointers are not allowed at the + user-kernel syscall ABI boundary. + When bit[0] is set to 1 the kernel is advertising to the userspace + that a relaxed ABI is supported hence this type of pointers are now + allowed to be passed to the syscalls, when these pointers are in + memory ranges privately owned by a process and obtained by the + process in accordance with the definition of "valid tagged pointer" + in paragraph 3. + In these cases the tag is preserved as the pointer goes through the + kernel. Only when the kernel needs to check if a pointer is coming + from userspace an untag operation is required. + +3. ARM64_AT_FLAGS_SYSCALL_TBI +----------------------------- + +From the kernel syscall interface prospective, we define, for the purposes +of this document, a "valid tagged pointer" as a pointer that either it has +a zero value set in the top byte or it has a non-zero value, it is in memory +ranges privately owned by a userspace process and it is obtained in one of +the following ways: + - mmap() done by the process itself, where either: + * flags = MAP_PRIVATE | MAP_ANONYMOUS + * flags = MAP_PRIVATE and the file descriptor refers to a regular + file or "/dev/zero" + - a mapping below sbrk(0) done by the process itself + - any memory mapped by the kernel in the process's address space during + creation and following the restrictions presented above (i.e. data, bss, + stack). + +When the ARM64_AT_FLAGS_SYSCALL_TBI flag is set by the kernel, the following +behaviours are guaranteed by the ABI: + + - Every current or newly introduced syscall can accept any valid tagged + pointers. + + - If a non valid tagged pointer is passed to a syscall then the behaviour + is undefined. + + - Every valid tagged pointer is expected to work as an untagged one. + + - The kernel preserves any valid tagged pointers and returns them to the + userspace unchanged in all the cases except the ones documented in the + "Preserving tags" paragraph of tagged-pointers.txt. + +A definition of the meaning of tagged pointers on arm64 can be found in: +Documentation/arm64/tagged-pointers.txt. + +Example of correct usage (pseudo-code) for a userspace application: + +bool arm64_syscall_tbi_is_present(void) +{ + unsigned long at_flags = getauxval(AT_FLAGS); + if (at_flags & ARM64_AT_FLAGS_SYSCALL_TBI) + return true; + + return false; +} + +void main(void) +{ + char *addr = mmap(NULL, PAGE_SIZE, PROT_READ | PROT_WRITE, + MAP_ANONYMOUS, -1, 0); + + int fd = open("test.txt", O_WRONLY); + + /* Check if the relaxed ABI is supported */ + if (arm64_syscall_tbi_is_present()) { + /* Add a tag to the pointer */ + addr = tag_pointer(addr); + } + + strcpy("Hello World\n", addr); + + /* Write to a file */ + write(fd, addr, sizeof(addr)); + + close(fd); +} + -- 2.21.0 From mboxrd@z Thu Jan 1 00:00:00 1970 From: Vincenzo Frascino Subject: [PATCH v2 2/4] arm64: Define Documentation/arm64/elf_at_flags.txt Date: Mon, 18 Mar 2019 16:35:31 +0000 Message-ID: <20190318163533.26838-3-vincenzo.frascino@arm.com> References: <20190318163533.26838-1-vincenzo.frascino@arm.com> Mime-Version: 1.0 Content-Transfer-Encoding: 8bit Return-path: In-Reply-To: <20190318163533.26838-1-vincenzo.frascino@arm.com> Sender: linux-kernel-owner@vger.kernel.org To: linux-arm-kernel@lists.infradead.org, linux-doc@vger.kernel.org, linux-mm@kvack.org, linux-arch@vger.kernel.org, linux-kselftest@vger.kernel.org, linux-kernel@vger.kernel.org Cc: Alexander Viro , Alexei Starovoitov , Andrew Morton , Andrey Konovalov , Arnaldo Carvalho de Melo , Branislav Rankov , Catalin Marinas , Chintan Pandya , Daniel Borkmann , Dave Martin , "David S. Miller" , Dmitry Vyukov , Eric Dumazet , Evgeniy Stepanov , Graeme Barnes , Greg Kroah-Hartman , Ingo Molnar , Jacob Bramley , Kate Stewart List-Id: linux-arch.vger.kernel.org On arm64 the TCR_EL1.TBI0 bit has been always enabled hence the userspace (EL0) is allowed to set a non-zero value in the top byte but the resulting pointers are not allowed at the user-kernel syscall ABI boundary. With the relaxed ABI proposed through this document, it is now possible to pass tagged pointers to the syscalls, when these pointers are in memory ranges obtained by an anonymous (MAP_ANONYMOUS) mmap() or brk(). This change in the ABI requires a mechanism to inform the userspace that such an option is available. Specify and document the way in which AT_FLAGS can be used to advertise this feature to the userspace. Cc: Catalin Marinas Cc: Will Deacon CC: Andrey Konovalov Signed-off-by: Vincenzo Frascino Squash with "arm64: Define Documentation/arm64/elf_at_flags.txt" --- Documentation/arm64/elf_at_flags.txt | 133 +++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 Documentation/arm64/elf_at_flags.txt diff --git a/Documentation/arm64/elf_at_flags.txt b/Documentation/arm64/elf_at_flags.txt new file mode 100644 index 000000000000..9b3494207c14 --- /dev/null +++ b/Documentation/arm64/elf_at_flags.txt @@ -0,0 +1,133 @@ +ARM64 ELF AT_FLAGS +================== + +This document describes the usage and semantics of AT_FLAGS on arm64. + +1. Introduction +--------------- + +AT_FLAGS is part of the Auxiliary Vector, contains the flags and it +is set to zero by the kernel on arm64 unless one or more of the +features detailed in paragraph 2 are present. + +The auxiliary vector can be accessed by the userspace using the +getauxval() API provided by the C library. +getauxval() returns an unsigned long and when a flag is present in +the AT_FLAGS, the corresponding bit in the returned value is set to 1. + +The AT_FLAGS with a "defined semantics" on arm64 are exposed to the +userspace via user API (uapi/asm/atflags.h). +The AT_FLAGS bits with "undefined semantics" are set to zero by default. +This means that the AT_FLAGS bits to which this document does not assign +an explicit meaning are to be intended reserved for future use. +The kernel will populate all such bits with zero until meanings are +assigned to them. If and when meanings are assigned, it is guaranteed +that they will not impact the functional operation of existing userspace +software. Userspace software should ignore any AT_FLAGS bit whose meaning +is not defined when the software is written. + +The userspace software can test for features by acquiring the AT_FLAGS +entry of the auxiliary vector, and testing whether a relevant flag +is set. + +Example of a userspace test function: + +bool feature_x_is_present(void) +{ + unsigned long at_flags = getauxval(AT_FLAGS); + if (at_flags & FEATURE_X) + return true; + + return false; +} + +Where the software relies on a feature advertised by AT_FLAGS, it +must check that the feature is present before attempting to +use it. + +2. Features exposed via AT_FLAGS +-------------------------------- + +bit[0]: ARM64_AT_FLAGS_SYSCALL_TBI + + On arm64 the TCR_EL1.TBI0 bit has been always enabled on the arm64 + kernel, hence the userspace (EL0) is allowed to set a non-zero value + in the top byte but the resulting pointers are not allowed at the + user-kernel syscall ABI boundary. + When bit[0] is set to 1 the kernel is advertising to the userspace + that a relaxed ABI is supported hence this type of pointers are now + allowed to be passed to the syscalls, when these pointers are in + memory ranges privately owned by a process and obtained by the + process in accordance with the definition of "valid tagged pointer" + in paragraph 3. + In these cases the tag is preserved as the pointer goes through the + kernel. Only when the kernel needs to check if a pointer is coming + from userspace an untag operation is required. + +3. ARM64_AT_FLAGS_SYSCALL_TBI +----------------------------- + +From the kernel syscall interface prospective, we define, for the purposes +of this document, a "valid tagged pointer" as a pointer that either it has +a zero value set in the top byte or it has a non-zero value, it is in memory +ranges privately owned by a userspace process and it is obtained in one of +the following ways: + - mmap() done by the process itself, where either: + * flags = MAP_PRIVATE | MAP_ANONYMOUS + * flags = MAP_PRIVATE and the file descriptor refers to a regular + file or "/dev/zero" + - a mapping below sbrk(0) done by the process itself + - any memory mapped by the kernel in the process's address space during + creation and following the restrictions presented above (i.e. data, bss, + stack). + +When the ARM64_AT_FLAGS_SYSCALL_TBI flag is set by the kernel, the following +behaviours are guaranteed by the ABI: + + - Every current or newly introduced syscall can accept any valid tagged + pointers. + + - If a non valid tagged pointer is passed to a syscall then the behaviour + is undefined. + + - Every valid tagged pointer is expected to work as an untagged one. + + - The kernel preserves any valid tagged pointers and returns them to the + userspace unchanged in all the cases except the ones documented in the + "Preserving tags" paragraph of tagged-pointers.txt. + +A definition of the meaning of tagged pointers on arm64 can be found in: +Documentation/arm64/tagged-pointers.txt. + +Example of correct usage (pseudo-code) for a userspace application: + +bool arm64_syscall_tbi_is_present(void) +{ + unsigned long at_flags = getauxval(AT_FLAGS); + if (at_flags & ARM64_AT_FLAGS_SYSCALL_TBI) + return true; + + return false; +} + +void main(void) +{ + char *addr = mmap(NULL, PAGE_SIZE, PROT_READ | PROT_WRITE, + MAP_ANONYMOUS, -1, 0); + + int fd = open("test.txt", O_WRONLY); + + /* Check if the relaxed ABI is supported */ + if (arm64_syscall_tbi_is_present()) { + /* Add a tag to the pointer */ + addr = tag_pointer(addr); + } + + strcpy("Hello World\n", addr); + + /* Write to a file */ + write(fd, addr, sizeof(addr)); + + close(fd); +} + -- 2.21.0 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=-9.0 required=3.0 tests=DKIMWL_WL_HIGH,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=unavailable 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 CBD90C43381 for ; Mon, 18 Mar 2019 16:36:28 +0000 (UTC) Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 9CFF62133F for ; Mon, 18 Mar 2019 16:36:28 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=lists.infradead.org header.i=@lists.infradead.org header.b="JOm7BoXa" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 9CFF62133F Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=arm.com Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=linux-arm-kernel-bounces+infradead-linux-arm-kernel=archiver.kernel.org@lists.infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20170209; h=Sender: Content-Transfer-Encoding:Content-Type:Cc:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:MIME-Version:References:In-Reply-To: Message-Id:Date:Subject:To:From:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=+6CgVfYVUZ10dpEktAyZEJ2DHPKKLrpG4XMDA+UvzYQ=; b=JOm7BoXaPrVT6y qv4o3GrvDYpTLWOQWzQkEbkiM5UNpu3bLPLgKMo0lYG4r6+W1ofzZXmp4WcWi0kYGtV5mb1DIcf3v ySVbJDWIWVkmmmf2rXAGS1m0hH8uWEueIEMHI8kxKN04Ycd9xkvctNXIXGpOwAEmskE+XyXVOE25w IH0Jk6q//PG1AGJ1eOJT/E6GTM81okGvOqAZjOFVa3zGTWhMXnJAQerDPP7LAq8ykSck/JK2UC2Ot xIjHegx5HIZyVHHxoWYzqOtsmBRG2BSqUhDMILldh+eOj0cpWpCm5fUqZ8nbciFZzR697apjWu5WL lcaKcaGcZSAlrpPIqZYw==; Received: from localhost ([127.0.0.1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.90_1 #2 (Red Hat Linux)) id 1h5vFN-0000xv-NN; Mon, 18 Mar 2019 16:36:21 +0000 Received: from foss.arm.com ([217.140.101.70]) by bombadil.infradead.org with esmtp (Exim 4.90_1 #2 (Red Hat Linux)) id 1h5vF8-0000eh-NG for linux-arm-kernel@lists.infradead.org; Mon, 18 Mar 2019 16:36:09 +0000 Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.72.51.249]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 87E5A1682; Mon, 18 Mar 2019 09:36:05 -0700 (PDT) Received: from e119884-lin.cambridge.arm.com (e119884-lin.cambridge.arm.com [10.1.196.72]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 63E6A3F614; Mon, 18 Mar 2019 09:35:59 -0700 (PDT) From: Vincenzo Frascino To: linux-arm-kernel@lists.infradead.org, linux-doc@vger.kernel.org, linux-mm@kvack.org, linux-arch@vger.kernel.org, linux-kselftest@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v2 2/4] arm64: Define Documentation/arm64/elf_at_flags.txt Date: Mon, 18 Mar 2019 16:35:31 +0000 Message-Id: <20190318163533.26838-3-vincenzo.frascino@arm.com> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190318163533.26838-1-vincenzo.frascino@arm.com> References: <20190318163533.26838-1-vincenzo.frascino@arm.com> MIME-Version: 1.0 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20190318_093606_927562_87146392 X-CRM114-Status: GOOD ( 26.10 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Kate Stewart , Mark Rutland , Peter Zijlstra , Catalin Marinas , Will Deacon , Alexei Starovoitov , Kostya Serebryany , Eric Dumazet , Chintan Pandya , Shuah Khan , Ingo Molnar , Jacob Bramley , Daniel Borkmann , Szabolcs Nagy , Steven Rostedt , Dave Martin , Evgeniy Stepanov , Kees Cook , Ruben Ayrapetyan , Andrey Konovalov , Kevin Brodsky , Arnaldo Carvalho de Melo , Graeme Barnes , Alexander Viro , Dmitry Vyukov , Branislav Rankov , Ramana Radhakrishnan , Greg Kroah-Hartman , Luc Van Oostenryck , Lee Smith , Andrew Morton , Robin Murphy , "David S. Miller" , "Kirill A . Shutemov" Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+infradead-linux-arm-kernel=archiver.kernel.org@lists.infradead.org On arm64 the TCR_EL1.TBI0 bit has been always enabled hence the userspace (EL0) is allowed to set a non-zero value in the top byte but the resulting pointers are not allowed at the user-kernel syscall ABI boundary. With the relaxed ABI proposed through this document, it is now possible to pass tagged pointers to the syscalls, when these pointers are in memory ranges obtained by an anonymous (MAP_ANONYMOUS) mmap() or brk(). This change in the ABI requires a mechanism to inform the userspace that such an option is available. Specify and document the way in which AT_FLAGS can be used to advertise this feature to the userspace. Cc: Catalin Marinas Cc: Will Deacon CC: Andrey Konovalov Signed-off-by: Vincenzo Frascino Squash with "arm64: Define Documentation/arm64/elf_at_flags.txt" --- Documentation/arm64/elf_at_flags.txt | 133 +++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 Documentation/arm64/elf_at_flags.txt diff --git a/Documentation/arm64/elf_at_flags.txt b/Documentation/arm64/elf_at_flags.txt new file mode 100644 index 000000000000..9b3494207c14 --- /dev/null +++ b/Documentation/arm64/elf_at_flags.txt @@ -0,0 +1,133 @@ +ARM64 ELF AT_FLAGS +================== + +This document describes the usage and semantics of AT_FLAGS on arm64. + +1. Introduction +--------------- + +AT_FLAGS is part of the Auxiliary Vector, contains the flags and it +is set to zero by the kernel on arm64 unless one or more of the +features detailed in paragraph 2 are present. + +The auxiliary vector can be accessed by the userspace using the +getauxval() API provided by the C library. +getauxval() returns an unsigned long and when a flag is present in +the AT_FLAGS, the corresponding bit in the returned value is set to 1. + +The AT_FLAGS with a "defined semantics" on arm64 are exposed to the +userspace via user API (uapi/asm/atflags.h). +The AT_FLAGS bits with "undefined semantics" are set to zero by default. +This means that the AT_FLAGS bits to which this document does not assign +an explicit meaning are to be intended reserved for future use. +The kernel will populate all such bits with zero until meanings are +assigned to them. If and when meanings are assigned, it is guaranteed +that they will not impact the functional operation of existing userspace +software. Userspace software should ignore any AT_FLAGS bit whose meaning +is not defined when the software is written. + +The userspace software can test for features by acquiring the AT_FLAGS +entry of the auxiliary vector, and testing whether a relevant flag +is set. + +Example of a userspace test function: + +bool feature_x_is_present(void) +{ + unsigned long at_flags = getauxval(AT_FLAGS); + if (at_flags & FEATURE_X) + return true; + + return false; +} + +Where the software relies on a feature advertised by AT_FLAGS, it +must check that the feature is present before attempting to +use it. + +2. Features exposed via AT_FLAGS +-------------------------------- + +bit[0]: ARM64_AT_FLAGS_SYSCALL_TBI + + On arm64 the TCR_EL1.TBI0 bit has been always enabled on the arm64 + kernel, hence the userspace (EL0) is allowed to set a non-zero value + in the top byte but the resulting pointers are not allowed at the + user-kernel syscall ABI boundary. + When bit[0] is set to 1 the kernel is advertising to the userspace + that a relaxed ABI is supported hence this type of pointers are now + allowed to be passed to the syscalls, when these pointers are in + memory ranges privately owned by a process and obtained by the + process in accordance with the definition of "valid tagged pointer" + in paragraph 3. + In these cases the tag is preserved as the pointer goes through the + kernel. Only when the kernel needs to check if a pointer is coming + from userspace an untag operation is required. + +3. ARM64_AT_FLAGS_SYSCALL_TBI +----------------------------- + +From the kernel syscall interface prospective, we define, for the purposes +of this document, a "valid tagged pointer" as a pointer that either it has +a zero value set in the top byte or it has a non-zero value, it is in memory +ranges privately owned by a userspace process and it is obtained in one of +the following ways: + - mmap() done by the process itself, where either: + * flags = MAP_PRIVATE | MAP_ANONYMOUS + * flags = MAP_PRIVATE and the file descriptor refers to a regular + file or "/dev/zero" + - a mapping below sbrk(0) done by the process itself + - any memory mapped by the kernel in the process's address space during + creation and following the restrictions presented above (i.e. data, bss, + stack). + +When the ARM64_AT_FLAGS_SYSCALL_TBI flag is set by the kernel, the following +behaviours are guaranteed by the ABI: + + - Every current or newly introduced syscall can accept any valid tagged + pointers. + + - If a non valid tagged pointer is passed to a syscall then the behaviour + is undefined. + + - Every valid tagged pointer is expected to work as an untagged one. + + - The kernel preserves any valid tagged pointers and returns them to the + userspace unchanged in all the cases except the ones documented in the + "Preserving tags" paragraph of tagged-pointers.txt. + +A definition of the meaning of tagged pointers on arm64 can be found in: +Documentation/arm64/tagged-pointers.txt. + +Example of correct usage (pseudo-code) for a userspace application: + +bool arm64_syscall_tbi_is_present(void) +{ + unsigned long at_flags = getauxval(AT_FLAGS); + if (at_flags & ARM64_AT_FLAGS_SYSCALL_TBI) + return true; + + return false; +} + +void main(void) +{ + char *addr = mmap(NULL, PAGE_SIZE, PROT_READ | PROT_WRITE, + MAP_ANONYMOUS, -1, 0); + + int fd = open("test.txt", O_WRONLY); + + /* Check if the relaxed ABI is supported */ + if (arm64_syscall_tbi_is_present()) { + /* Add a tag to the pointer */ + addr = tag_pointer(addr); + } + + strcpy("Hello World\n", addr); + + /* Write to a file */ + write(fd, addr, sizeof(addr)); + + close(fd); +} + -- 2.21.0 _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel