util-linux/schedutils/coresched.1

'\" t
.\"     Title: coresched
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.20
.\"      Date: 2025-02-26
.\"    Manual: User Commands
.\"    Source: util-linux 2.41
.\"  Language: English
.\"
.TH "CORESCHED" "1" "2025-02-26" "util\-linux 2.41" "User Commands"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
coresched \- manage core scheduling cookies for tasks
.SH "SYNOPSIS"
.sp
\fBcoresched\fP [\fBget\fP] [\fB\-s\fP \fIpid\fP]
.sp
\fBcoresched\fP \fBnew\fP [\fB\-t\fP \fItype\fP] \fB\-d\fP \fIpid\fP
.sp
\fBcoresched\fP \fBnew\fP [\fB\-t\fP \fItype\fP] \-\- \fIcommand\fP [\fIargument\fP...]
.sp
\fBcoresched\fP \fBcopy\fP [\fB\-s\fP \fIpid\fP] [\fB\-t\fP \fItype\fP] \fB\-d\fP \fIpid\fP
.sp
\fBcoresched\fP \fBcopy\fP [\fB\-s\fP \fIpid\fP] [\fB\-t\fP \fItype\fP] \-\- \fIcommand\fP [\fIargument\fP...]
.SH "DESCRIPTION"
.sp
The \fBcoresched\fP command is used to retrieve or modify the core scheduling cookies of a running process given its \fIpid\fP, or to spawn a new \fIcommand\fP with core scheduling cookies.
.sp
Core scheduling permits the definition of groups of tasks that are allowed to share a physical core.
This is done by assigning a cookie to each task.
Only tasks have the same cookie are allowed to be scheduled on the same physical core.
.sp
It is possible to either assign a new random cookie to a task, or copy a cookie from another task. It is not possible to choose the value of the cookie.
.SH "FUNCTIONS"
.sp
\fBget\fP
.RS 4
Retrieve the core scheduling cookie of the PID specified in \fB\-s\fP.
If \fB\-s\fP is omitted, it will get the cookie of the current \fBcoresched\fP process.
.RE
.sp
\fBnew\fP
.RS 4
Assign a new cookie to an existing PID specified in \fB\-d\fP, or execute \fIcommand\fP with a new cookie.
.RE
.sp
\fBcopy\fP
.RS 4
Copy the cookie from an existing PID (\fB\-s\fP) to another PID (\fB\-d\fP), or execute \fIcommand\fP with that cookie.
If \fB\-s\fP is omitted, it will get the cookie of the current \fBcoresched\fP process.
.RE
.sp
If no function is specified, it will run the \fBget\fP function.
.SH "OPTIONS"
.sp
\fB\-s\fP, \fB\-\-source\fP \fIPID\fP
.RS 4
Which \fIPID\fP to get the cookie from.
If this option is omitted, it will get the cookie from the current \fBcoresched\fP process.
.RE
.sp
\fB\-d\fP, \fB\-\-dest\fP \fIPID\fP
.RS 4
Which \fIPID\fP to modify the cookie of.
.RE
.sp
\fB\-t\fP, \fB\-\-dest\-type\fP \fITYPE\fP
.RS 4
The type of the PID whose cookie will be modified. This can be one of three values:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBpid\fP, or process ID
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBtgid\fP, or thread group ID (default value)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBpgid\fP, or process group ID
.RE
.RE
.sp
\fB\-v\fP, \fB\-\-verbose\fP
.RS 4
Show extra information when modifying cookies of tasks.
.RE
.sp
\fB\-h\fP, \fB\-\-help\fP
.RS 4
Display help text and exit.
.RE
.sp
\fB\-V\fP, \fB\-\-version\fP
.RS 4
Display version and exit.
.RE
.SH "EXAMPLES"
.sp
Get the core scheduling cookie of the coresched task itself, usually inherited from its parent:
.RS 4
\fBcoresched get\fP
.RE
.sp
Get the core scheduling cookie of a task with PID \fI123\fP:
.RS 4
\fBcoresched get \-s\fP \fI123\fP
.RE
.sp
Give a task with PID \fI123\fP a new core scheduling cookie:
.RS 4
\fBcoresched new \-d\fP \fI123\fP
.RE
.sp
Spawn a new task with a new core scheduling cookie:
.RS 4
\fBcoresched new\fP \-\- \fIcommand\fP [\fIargument\fP...]
.RE
.sp
Copy the cookie from the current coresched process another task with pid \fI456\fP:
.RS 4
\fBcoresched copy \-d\fP \fI456\fP
.RE
.sp
Copy the cookie from a task with pid \fI123\fP to another task with pid \fI456\fP:
.RS 4
\fBcoresched copy \-s\fP \fI123\fP \fB\-d\fP \fI456\fP
.RE
.sp
Copy the cookie from a task with pid \fI123\fP to a new task \fIcommand\fP:
.RS 4
\fBcoresched copy \-s\fP \fI123\fP \-\- \fIcommand\fP [\fIargument\fP...]
.RE
.sp
Copy the cookie from a task with pid \fI123\fP to the process group ID \fI456\fP:
.RS 4
\fBcoresched copy \-s\fP \fI123\fP \fB\-t\fP \fIpgid\fP \fB\-d\fP \fI456\fP
.RE
.SH "PERMISSIONS"
.sp
Retrieving or modifying the core scheduling cookie of a process requires \fBPTRACE_MODE_READ_REALCREDS\fP ptrace access to that process.
See the section "Ptrace access mode checking" in \fBptrace\fP(2) for more information.
.SH "RETURN VALUE"
.sp
On success, \fBcoresched\fP returns 0.
If \fBcoresched\fP fails, it will print an error and return 1.
.sp
If a \fIcommand\fP is being executed, the return value of \fBcoresched\fP will be the return value of \fIcommand\fP.
.SH "NOTES"
.sp
\fBcoresched\fP requires core scheduling support in the kernel.
This can be enabled via the \fBCONFIG_SCHED_CORE\fP kernel config option.
.SH "AUTHORS"
.sp
.MTO "thijs\(atraymakers.nl" "Thijs Raymakers" ","
.MTO "pauld\(atredhat.com" "Phil Auld" ""
.SH "COPYRIGHT"
.sp
Copyright © 2024 Thijs Raymakers and Phil Auld. This is free software licensed under the EUPL.
.SH "SEE ALSO"
.sp
\fBchrt\fP(1),
\fBnice\fP(1),
\fBrenice\fP(1),
\fBtaskset\fP(1),
\fBptrace\fP(2),
\fBsched\fP(7)
.sp
The Linux kernel source files \fIDocumentation/admin\-guide/hw\-vuln/core\-scheduling.rst\fP
.SH "REPORTING BUGS"
.sp
For bug reports, use the \c
.URL "https://github.com/util\-linux/util\-linux/issues" "issue tracker" "."
.SH "AVAILABILITY"
.sp
The \fBcoresched\fP command is part of the util\-linux package which can be downloaded from \c
.URL "https://www.kernel.org/pub/linux/utils/util\-linux/" "Linux Kernel Archive" "."