1/* SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note */
  2#ifndef _LINUX_RSEQ_H
  3#define _LINUX_RSEQ_H
  4
  5/*
  6 * linux/rseq.h
  7 *
  8 * Restartable sequences system call API
  9 *
 10 * Copyright (c) 2015-2018 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
 11 */
 12
 13#include <linux/types.h>
 14#include <asm/byteorder.h>
 15
 16enum rseq_cpu_id_state {
 17	RSEQ_CPU_ID_UNINITIALIZED		= -1,
 18	RSEQ_CPU_ID_REGISTRATION_FAILED		= -2,
 19};
 20
 21enum rseq_flags {
 22	RSEQ_FLAG_UNREGISTER = (1 << 0),
 23};
 24
 25enum rseq_cs_flags_bit {
 26	RSEQ_CS_FLAG_NO_RESTART_ON_PREEMPT_BIT	= 0,
 27	RSEQ_CS_FLAG_NO_RESTART_ON_SIGNAL_BIT	= 1,
 28	RSEQ_CS_FLAG_NO_RESTART_ON_MIGRATE_BIT	= 2,
 29};
 30
 31enum rseq_cs_flags {
 32	RSEQ_CS_FLAG_NO_RESTART_ON_PREEMPT	=
 33		(1U << RSEQ_CS_FLAG_NO_RESTART_ON_PREEMPT_BIT),
 34	RSEQ_CS_FLAG_NO_RESTART_ON_SIGNAL	=
 35		(1U << RSEQ_CS_FLAG_NO_RESTART_ON_SIGNAL_BIT),
 36	RSEQ_CS_FLAG_NO_RESTART_ON_MIGRATE	=
 37		(1U << RSEQ_CS_FLAG_NO_RESTART_ON_MIGRATE_BIT),
 38};
 39
 40/*
 41 * struct rseq_cs is aligned on 4 * 8 bytes to ensure it is always
 42 * contained within a single cache-line. It is usually declared as
 43 * link-time constant data.
 44 */
 45struct rseq_cs {
 46	/* Version of this structure. */
 47	__u32 version;
 48	/* enum rseq_cs_flags */
 49	__u32 flags;
 50	__u64 start_ip;
 51	/* Offset from start_ip. */
 52	__u64 post_commit_offset;
 53	__u64 abort_ip;
 54} __attribute__((aligned(4 * sizeof(__u64))));
 55
 56/*
 57 * struct rseq is aligned on 4 * 8 bytes to ensure it is always
 58 * contained within a single cache-line.
 59 *
 60 * A single struct rseq per thread is allowed.
 61 */
 62struct rseq {
 63	/*
 64	 * Restartable sequences cpu_id_start field. Updated by the
 65	 * kernel. Read by user-space with single-copy atomicity
 66	 * semantics. This field should only be read by the thread which
 67	 * registered this data structure. Aligned on 32-bit. Always
 68	 * contains a value in the range of possible CPUs, although the
 69	 * value may not be the actual current CPU (e.g. if rseq is not
 70	 * initialized). This CPU number value should always be compared
 71	 * against the value of the cpu_id field before performing a rseq
 72	 * commit or returning a value read from a data structure indexed
 73	 * using the cpu_id_start value.
 74	 */
 75	__u32 cpu_id_start;
 76	/*
 77	 * Restartable sequences cpu_id field. Updated by the kernel.
 78	 * Read by user-space with single-copy atomicity semantics. This
 79	 * field should only be read by the thread which registered this
 80	 * data structure. Aligned on 32-bit. Values
 81	 * RSEQ_CPU_ID_UNINITIALIZED and RSEQ_CPU_ID_REGISTRATION_FAILED
 82	 * have a special semantic: the former means "rseq uninitialized",
 83	 * and latter means "rseq initialization failed". This value is
 84	 * meant to be read within rseq critical sections and compared
 85	 * with the cpu_id_start value previously read, before performing
 86	 * the commit instruction, or read and compared with the
 87	 * cpu_id_start value before returning a value loaded from a data
 88	 * structure indexed using the cpu_id_start value.
 89	 */
 90	__u32 cpu_id;
 91	/*
 92	 * Restartable sequences rseq_cs field.
 93	 *
 94	 * Contains NULL when no critical section is active for the current
 95	 * thread, or holds a pointer to the currently active struct rseq_cs.
 96	 *
 97	 * Updated by user-space, which sets the address of the currently
 98	 * active rseq_cs at the beginning of assembly instruction sequence
 99	 * block, and set to NULL by the kernel when it restarts an assembly
100	 * instruction sequence block, as well as when the kernel detects that
101	 * it is preempting or delivering a signal outside of the range
102	 * targeted by the rseq_cs. Also needs to be set to NULL by user-space
103	 * before reclaiming memory that contains the targeted struct rseq_cs.
104	 *
105	 * Read and set by the kernel. Set by user-space with single-copy
106	 * atomicity semantics. This field should only be updated by the
107	 * thread which registered this data structure. Aligned on 64-bit.
108	 *
109	 * 32-bit architectures should update the low order bits of the
110	 * rseq_cs field, leaving the high order bits initialized to 0.
111	 */
112	__u64 rseq_cs;
113
114	/*
115	 * Restartable sequences flags field.
116	 *
117	 * This field should only be updated by the thread which
118	 * registered this data structure. Read by the kernel.
119	 * Mainly used for single-stepping through rseq critical sections
120	 * with debuggers.
121	 *
122	 * - RSEQ_CS_FLAG_NO_RESTART_ON_PREEMPT
123	 *     Inhibit instruction sequence block restart on preemption
124	 *     for this thread.
125	 * - RSEQ_CS_FLAG_NO_RESTART_ON_SIGNAL
126	 *     Inhibit instruction sequence block restart on signal
127	 *     delivery for this thread.
128	 * - RSEQ_CS_FLAG_NO_RESTART_ON_MIGRATE
129	 *     Inhibit instruction sequence block restart on migration for
130	 *     this thread.
131	 */
132	__u32 flags;
133
134	/*
135	 * Restartable sequences node_id field. Updated by the kernel. Read by
136	 * user-space with single-copy atomicity semantics. This field should
137	 * only be read by the thread which registered this data structure.
138	 * Aligned on 32-bit. Contains the current NUMA node ID.
139	 */
140	__u32 node_id;
141
142	/*
143	 * Restartable sequences mm_cid field. Updated by the kernel. Read by
144	 * user-space with single-copy atomicity semantics. This field should
145	 * only be read by the thread which registered this data structure.
146	 * Aligned on 32-bit. Contains the current thread's concurrency ID
147	 * (allocated uniquely within a memory map).
148	 */
149	__u32 mm_cid;
150
151	/*
152	 * Flexible array member at end of structure, after last feature field.
153	 */
154	char end[];
155} __attribute__((aligned(4 * sizeof(__u64))));
156
157#endif /* _LINUX_RSEQ_H */