1/* SPDX-License-Identifier: BSD-3-Clause */
2/*
3 * Copyright (C) 2019 - 2023 Intel Corporation
4 */
5#ifndef _LINUX_UM_TIMETRAVEL_H
6#define _LINUX_UM_TIMETRAVEL_H
7#include <linux/types.h>
8
9/**
10 * struct um_timetravel_msg - UM time travel message
11 *
12 * This is the basic message type, going in both directions.
13 *
14 * This is the message passed between the host (user-mode Linux instance)
15 * and the calendar (the application on the other side of the socket) in
16 * order to implement common scheduling.
17 *
18 * Whenever UML has an event it will request runtime for it from the
19 * calendar, and then wait for its turn until it can run, etc. Note
20 * that it will only ever request the single next runtime, i.e. multiple
21 * REQUEST messages override each other.
22 */
23struct um_timetravel_msg {
24 /**
25 * @op: operation value from &enum um_timetravel_ops
26 */
27 __u32 op;
28
29 /**
30 * @seq: sequence number for the message - shall be reflected in
31 * the ACK response, and should be checked while processing
32 * the response to see if it matches
33 */
34 __u32 seq;
35
36 /**
37 * @time: time in nanoseconds
38 */
39 __u64 time;
40};
41
42/* max number of file descriptors that can be sent/received in a message */
43#define UM_TIMETRAVEL_MAX_FDS 2
44
45/**
46 * enum um_timetravel_shared_mem_fds - fds sent in ACK message for START message
47 */
48enum um_timetravel_shared_mem_fds {
49 /**
50 * @UM_TIMETRAVEL_SHARED_MEMFD: Index of the shared memory file
51 * descriptor in the control message
52 */
53 UM_TIMETRAVEL_SHARED_MEMFD,
54 /**
55 * @UM_TIMETRAVEL_SHARED_LOGFD: Index of the logging file descriptor
56 * in the control message
57 */
58 UM_TIMETRAVEL_SHARED_LOGFD,
59 /**
60 * @UM_TIMETRAVEL_SHARED_MAX_FDS: number of fds listed here
61 */
62 UM_TIMETRAVEL_SHARED_MAX_FDS,
63};
64
65/**
66 * enum um_timetravel_start_ack - ack-time mask for start message
67 */
68enum um_timetravel_start_ack {
69 /**
70 * @UM_TIMETRAVEL_START_ACK_ID: client ID that controller allocated.
71 */
72 UM_TIMETRAVEL_START_ACK_ID = 0xffff,
73};
74
75/**
76 * enum um_timetravel_ops - Operation codes
77 */
78enum um_timetravel_ops {
79 /**
80 * @UM_TIMETRAVEL_ACK: response (ACK) to any previous message,
81 * this usually doesn't carry any data in the 'time' field
82 * unless otherwise specified below, note: while using shared
83 * memory no ACK for WAIT and RUN messages, for more info see
84 * &struct um_timetravel_schedshm.
85 */
86 UM_TIMETRAVEL_ACK = 0,
87
88 /**
89 * @UM_TIMETRAVEL_START: initialize the connection, the time
90 * field contains an (arbitrary) ID to possibly be able
91 * to distinguish the connections.
92 */
93 UM_TIMETRAVEL_START = 1,
94
95 /**
96 * @UM_TIMETRAVEL_REQUEST: request to run at the given time
97 * (host -> calendar)
98 */
99 UM_TIMETRAVEL_REQUEST = 2,
100
101 /**
102 * @UM_TIMETRAVEL_WAIT: Indicate waiting for the previously requested
103 * runtime, new requests may be made while waiting (e.g. due to
104 * interrupts); the time field is ignored. The calendar must process
105 * this message and later send a %UM_TIMETRAVEL_RUN message when
106 * the host can run again.
107 * (host -> calendar)
108 */
109 UM_TIMETRAVEL_WAIT = 3,
110
111 /**
112 * @UM_TIMETRAVEL_GET: return the current time from the calendar in the
113 * ACK message, the time in the request message is ignored
114 * (host -> calendar)
115 */
116 UM_TIMETRAVEL_GET = 4,
117
118 /**
119 * @UM_TIMETRAVEL_UPDATE: time update to the calendar, must be sent e.g.
120 * before kicking an interrupt to another calendar
121 * (host -> calendar)
122 */
123 UM_TIMETRAVEL_UPDATE = 5,
124
125 /**
126 * @UM_TIMETRAVEL_RUN: run time request granted, current time is in
127 * the time field
128 * (calendar -> host)
129 */
130 UM_TIMETRAVEL_RUN = 6,
131
132 /**
133 * @UM_TIMETRAVEL_FREE_UNTIL: Enable free-running until the given time,
134 * this is a message from the calendar telling the host that it can
135 * freely do its own scheduling for anything before the indicated
136 * time.
137 * Note that if a calendar sends this message once, the host may
138 * assume that it will also do so in the future, if it implements
139 * wraparound semantics for the time field.
140 * (calendar -> host)
141 */
142 UM_TIMETRAVEL_FREE_UNTIL = 7,
143
144 /**
145 * @UM_TIMETRAVEL_GET_TOD: Return time of day, typically used once at
146 * boot by the virtual machines to get a synchronized time from
147 * the simulation.
148 */
149 UM_TIMETRAVEL_GET_TOD = 8,
150
151 /**
152 * @UM_TIMETRAVEL_BROADCAST: Send/Receive a broadcast message.
153 * This message can be used to sync all components in the system
154 * with a single message, if the calender gets the message, the
155 * calender broadcast the message to all components, and if a
156 * component receives it it should act based on it e.g print a
157 * message to it's log system.
158 * (calendar <-> host)
159 */
160 UM_TIMETRAVEL_BROADCAST = 9,
161};
162
163/* version of struct um_timetravel_schedshm */
164#define UM_TIMETRAVEL_SCHEDSHM_VERSION 2
165
166/**
167 * enum um_timetravel_schedshm_cap - time travel capabilities of every client
168 *
169 * These flags must be set immediately after processing the ACK to
170 * the START message, before sending any message to the controller.
171 */
172enum um_timetravel_schedshm_cap {
173 /**
174 * @UM_TIMETRAVEL_SCHEDSHM_CAP_TIME_SHARE: client can read current time
175 * update internal time request to shared memory and read
176 * free until and send no Ack on RUN and doesn't expect ACK on
177 * WAIT.
178 */
179 UM_TIMETRAVEL_SCHEDSHM_CAP_TIME_SHARE = 0x1,
180};
181
182/**
183 * enum um_timetravel_schedshm_flags - time travel flags of every client
184 */
185enum um_timetravel_schedshm_flags {
186 /**
187 * @UM_TIMETRAVEL_SCHEDSHM_FLAGS_REQ_RUN: client has a request to run.
188 * It's set by client when it has a request to run, if (and only
189 * if) the @running_id points to a client that is able to use
190 * shared memory, i.e. has %UM_TIMETRAVEL_SCHEDSHM_CAP_TIME_SHARE
191 * (this includes the client itself). Otherwise, a message must
192 * be used.
193 */
194 UM_TIMETRAVEL_SCHEDSHM_FLAGS_REQ_RUN = 0x1,
195};
196
197/**
198 * DOC: Time travel shared memory overview
199 *
200 * The main purpose of the shared memory is to avoid all time travel message
201 * that don't need any action, for example current time can be held in shared
202 * memory without the need of any client to send a message UM_TIMETRAVEL_GET
203 * in order to know what's the time.
204 *
205 * Since this is shared memory with all clients and controller and controller
206 * creates the shared memory space, all time values are absolute to controller
207 * time. So first time client connects to shared memory mode it should take the
208 * current_time value in shared memory and keep it internally as a diff to
209 * shared memory times, and once shared memory is initialized, any interaction
210 * with the controller must happen in the controller time domain, including any
211 * messages (for clients that are not using shared memory, the controller will
212 * handle an offset and make the clients think they start at time zero.)
213 *
214 * Along with the shared memory file descriptor is sent to the client a logging
215 * file descriptor, to have all logs related to shared memory,
216 * logged into one place. note: to have all logs synced into log file at write,
217 * file should be flushed (fflush) after writing to it.
218 *
219 * To avoid memory corruption, we define below for each field who can write to
220 * it at what time, defined in the structure fields.
221 *
222 * To avoid having to pack this struct, all fields in it must be naturally aligned
223 * (i.e. aligned to their size).
224 */
225
226/**
227 * union um_timetravel_schedshm_client - UM time travel client struct
228 *
229 * Every entity using the shared memory including the controller has a place in
230 * the um_timetravel_schedshm clients array, that holds info related to the client
231 * using the shared memory, and can be set only by the client after it gets the
232 * fd memory.
233 *
234 * @capa: bit fields with client capabilities see
235 * &enum um_timetravel_schedshm_cap, set by client once after getting the
236 * shared memory file descriptor.
237 * @flags: bit fields for flags see &enum um_timetravel_schedshm_flags for doc.
238 * @req_time: request time to run, set by client on every request it needs.
239 * @name: unique id sent to the controller by client with START message.
240 */
241union um_timetravel_schedshm_client {
242 struct {
243 __u32 capa;
244 __u32 flags;
245 __u64 req_time;
246 __u64 name;
247 };
248 /* private: */
249 char reserve[128]; /* reserved for future usage */
250};
251
252/**
253 * struct um_timetravel_schedshm - UM time travel shared memory struct
254 *
255 * @hdr: header fields:
256 * @version: Current version struct UM_TIMETRAVEL_SCHEDSHM_VERSION,
257 * set by controller once at init, clients must check this after mapping
258 * and work without shared memory if they cannot handle the indicated
259 * version.
260 * @len: Length of all the memory including header (@hdr), clients should once
261 * per connection first mmap the header and take the length (@len) to remap the entire size.
262 * This is done in order to support dynamic struct size letting number of
263 * clients be dynamic based on controller support.
264 * @free_until: Stores the next request to run by any client, in order for the
265 * current client to know how long it can still run. A client needs to (at
266 * least) reload this value immediately after communicating with any other
267 * client, since the controller will update this field when a new request
268 * is made by any client. Clients also must update this value when they
269 * insert/update an own request into the shared memory while not running
270 * themselves, and the new request is before than the current value.
271 * @current_time: Current time, can only be set by the client in running state
272 * (indicated by @running_id), though that client may only run until @free_until,
273 * so it must remain smaller than @free_until.
274 * @running_id: The current client in state running, set before a client is
275 * notified that it's now running.
276 * @max_clients: size of @clients array, set once at init by the controller.
277 * @clients: clients array see &union um_timetravel_schedshm_client for doc,
278 * set only by client.
279 */
280struct um_timetravel_schedshm {
281 union {
282 struct {
283 __u32 version;
284 __u32 len;
285 __u64 free_until;
286 __u64 current_time;
287 __u16 running_id;
288 __u16 max_clients;
289 };
290 char hdr[4096]; /* align to 4K page size */
291 };
292 union um_timetravel_schedshm_client clients[];
293};
294#endif /* _LINUX_UM_TIMETRAVEL_H */