From 9b276f9ea8a9c017b0e86b267049bc192f4980db Mon Sep 17 00:00:00 2001 From: Dave Martin Date: Wed, 24 Jun 2020 18:36:02 +0100 Subject: [PATCH] prctl.2: Add tagged address ABI control prctls (arm64) Add documentation for the the PR_SET_TAGGED_ADDR_CTRL and PR_GET_TAGGED_ADDR_CTRL prctls added in Linux 5.4 for arm64. Signed-off-by: Dave Martin Reviewed-by: Catalin Marinas Cc: Vincenzo Frascino Signed-off-by: Michael Kerrisk --- man2/prctl.2 | 165 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 163 insertions(+), 2 deletions(-) diff --git a/man2/prctl.2 b/man2/prctl.2 index 8e6952d08..313ff3746 100644 --- a/man2/prctl.2 +++ b/man2/prctl.2 @@ -1379,7 +1379,7 @@ Configure the thread's SVE vector length, as specified by .IR "(int) arg2" . Arguments -.IR arg3 ", " arg4 " and " arg5 , +.IR arg3 ", " arg4 ", and " arg5 are ignored. .IP The bits of @@ -1496,7 +1496,7 @@ Don't use it unless you really know what you are doing. Get the thread's current SVE vector length configuration. .IP Arguments -.IR arg2 ", " arg3 ", " arg4 " and " arg5 , +.IR arg2 ", " arg3 ", " arg4 ", and " arg5 are ignored. .IP Provided that the kernel and platform support SVE, @@ -1522,6 +1522,148 @@ For more information, see the kernel source file (or .I Documentation/arm64/sve.txt before Linux 5.3). +.\" prctl PR_SET_TAGGED_ADDR_CTRL +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d +.TP +.BR PR_SET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)" +Controls support for passing tagged userspace addresses to the kernel +(i.e., addresses where bits 56\(em63 are not all zero). +.IP +The level of support is selected by +.IR "arg2" , +which can be one of the following: +.RS +.TP +.B 0 +Addresses that are passed +for the purpose of being dereferenced by the kernel +must be untagged. +.TP +.B PR_TAGGED_ADDR_ENABLE +Addresses that are passed +for the purpose of being dereferenced by the kernel +may be tagged, with the exceptions summarized below. +.RE +.IP +The remaining arguments +.IR arg3 ", " arg4 " and " arg5 +must all be zero. +.\" Enforcement added in +.\" commit 3e91ec89f527b9870fe42dcbdb74fd389d123a95 +.IP +On success, the mode specified in +.I arg2 +is set for the calling thread and the the return value is 0. +If the arguments are invalid, +the mode specified in +.I arg2 +is unrecognized, +or if this feature is unsupported by the kernel +or disabled via +.IR /proc/sys/abi/tagged_addr_disabled , +the call fails with +.BR EINVAL . +.IP +In particular, if +.BR prctl ( PR_SET_TAGGED_ADDR_CTRL , +0, 0, 0, 0) +fails with +.B EINVAL +then all addresses passed to the kernel must be untagged. +.IP +Irrespective of which mode is set, +addresses passed to certain interfaces +must always be untagged: +.RS +.IP \(em +.BR brk (2), +.BR mmap (2), +.BR shmat (2), +.BR shmdt (2), +and the +.I new_address +argument of +.BR mremap (2). +.IP +(Prior to Linux 5.6 these accepted tagged addresses, +but the behaviour may not be what you expect. +Don't rely on it.) +.IP \(em +\(oqpolymorphic\(cq interfaces +that accept pointers to arbitrary types cast to a +.I void * +or other generic type, specifically +.BR prctl (2), +.BR ioctl (2), +and in general +.BR setsockopt (2) +(only certain specific +.BR setsockopt (2) +options allow tagged addresses). +.RE +.IP +This list of exclusions may shrink +when moving from one kernel version to a later kernel version. +While the kernel may make some guarantees +for backwards compatibility reasons, +for the purposes of new software +the effect of passing tagged addresses to these interfaces +is unspecified. +.IP +The mode set by this call is inherited across +.BR fork (2) +and +.BR clone (2). +The mode is reset by +.BR execve (2) +to 0 +(i.e., tagged addresses not permitted in the user/kernel ABI). +.IP +For more information, see the kernel source file +.IR Documentation/arm64/tagged\-address\-abi.rst . +.IP +.B Warning: +This call is primarily intended for use by the run-time environment. +A successful +.B PR_SET_TAGGED_ADDR_CTRL +call elsewhere may crash the calling process. +The conditions for using it safely are complex and system-dependent; +Don't use it unless you know what you are doing. +.\" prctl PR_GET_TAGGED_ADDR_CTRL +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d +.TP +.BR PR_GET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)" +Returns the current tagged address mode +for the calling thread. +.IP +Arguments +.IR arg2 ", " arg3 ", " arg4 " and " arg5 +must all be zero. +.IP +If the arguments are invalid +or this feature is disabled or unsupported by the kernel, +the call fails with +.BR EINVAL . +In particular, if +.BR prctl ( PR_GET_TAGGED_ADDR_CTRL , +0, 0, 0, 0) +fails with +.BR EINVAL , +then this feature is definitely either unsupported, +or disabled via +.IR /proc/sys/abi/tagged_addr_disabled . +In this case, +all addresses passed to the kernel must be untagged. +.IP +Otherwise, the call returns a nonnegative value +describing the current tagged address mode, +encoded in the same way as the +.I arg2 +argument of +.BR PR_SET_TAGGED_ADDR_CTRL . +.IP +For more information, see the kernel source file +.IR Documentation/arm64/tagged\-address\-abi.rst . .\" .\" prctl PR_TASK_PERF_EVENTS_DISABLE .TP @@ -1767,6 +1909,7 @@ On success, .BR PR_GET_SPECULATION_CTRL , .BR PR_SVE_GET_VL , .BR PR_SVE_SET_VL , +.BR PR_GET_TAGGED_ADDR_CTRL , .BR PR_GET_THP_DISABLE , .BR PR_GET_TIMING , .BR PR_GET_TIMERSLACK , @@ -2074,6 +2217,24 @@ is .B PR_SVE_GET_VL and SVE is not available on this platform. .TP +.B EINVAL +.I option +is +.BR PR_SET_TAGGED_ADDR_CTRL +and the arguments are invalid or unsupported. +See the description of +.B PR_SET_TAGGED_ADDR_CTRL +above for details. +.TP +.B EINVAL +.I option +is +.BR PR_GET_TAGGED_ADDR_CTRL +and the arguments are invalid or unsupported. +See the description of +.B PR_GET_TAGGED_ADDR_CTRL +above for details. +.TP .B ENODEV .I option was