291 lines · c
1/* SPDX-License-Identifier: BSD-3-Clause */2/*3 * Copyright (C) 2019 - 2023 Intel Corporation4 */5#ifndef _UAPI_LINUX_UM_TIMETRAVEL_H6#define _UAPI_LINUX_UM_TIMETRAVEL_H7#include <linux/types.h>8 9/**10 * struct um_timetravel_msg - UM time travel message11 *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) in16 * order to implement common scheduling.17 *18 * Whenever UML has an event it will request runtime for it from the19 * calendar, and then wait for its turn until it can run, etc. Note20 * that it will only ever request the single next runtime, i.e. multiple21 * REQUEST messages override each other.22 */23struct um_timetravel_msg {24 /**25 * @op: operation value from &enum um_timetravel_ops26 */27 __u32 op;28 29 /**30 * @seq: sequence number for the message - shall be reflected in31 * the ACK response, and should be checked while processing32 * the response to see if it matches33 */34 __u32 seq;35 36 /**37 * @time: time in nanoseconds38 */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 244 45/**46 * enum um_timetravel_shared_mem_fds - fds sent in ACK message for START message47 */48enum um_timetravel_shared_mem_fds {49 /**50 * @UM_TIMETRAVEL_SHARED_MEMFD: Index of the shared memory file51 * descriptor in the control message52 */53 UM_TIMETRAVEL_SHARED_MEMFD,54 /**55 * @UM_TIMETRAVEL_SHARED_LOGFD: Index of the logging file descriptor56 * in the control message57 */58 UM_TIMETRAVEL_SHARED_LOGFD,59 UM_TIMETRAVEL_SHARED_MAX_FDS,60};61 62/**63 * enum um_timetravel_start_ack - ack-time mask for start message64 */65enum um_timetravel_start_ack {66 /**67 * @UM_TIMETRAVEL_START_ACK_ID: client ID that controller allocated.68 */69 UM_TIMETRAVEL_START_ACK_ID = 0xffff,70};71 72/**73 * enum um_timetravel_ops - Operation codes74 */75enum um_timetravel_ops {76 /**77 * @UM_TIMETRAVEL_ACK: response (ACK) to any previous message,78 * this usually doesn't carry any data in the 'time' field79 * unless otherwise specified below, note: while using shared80 * memory no ACK for WAIT and RUN messages, for more info see81 * &struct um_timetravel_schedshm.82 */83 UM_TIMETRAVEL_ACK = 0,84 85 /**86 * @UM_TIMETRAVEL_START: initialize the connection, the time87 * field contains an (arbitrary) ID to possibly be able88 * to distinguish the connections.89 */90 UM_TIMETRAVEL_START = 1,91 92 /**93 * @UM_TIMETRAVEL_REQUEST: request to run at the given time94 * (host -> calendar)95 */96 UM_TIMETRAVEL_REQUEST = 2,97 98 /**99 * @UM_TIMETRAVEL_WAIT: Indicate waiting for the previously requested100 * runtime, new requests may be made while waiting (e.g. due to101 * interrupts); the time field is ignored. The calendar must process102 * this message and later send a %UM_TIMETRAVEL_RUN message when103 * the host can run again.104 * (host -> calendar)105 */106 UM_TIMETRAVEL_WAIT = 3,107 108 /**109 * @UM_TIMETRAVEL_GET: return the current time from the calendar in the110 * ACK message, the time in the request message is ignored111 * (host -> calendar)112 */113 UM_TIMETRAVEL_GET = 4,114 115 /**116 * @UM_TIMETRAVEL_UPDATE: time update to the calendar, must be sent e.g.117 * before kicking an interrupt to another calendar118 * (host -> calendar)119 */120 UM_TIMETRAVEL_UPDATE = 5,121 122 /**123 * @UM_TIMETRAVEL_RUN: run time request granted, current time is in124 * the time field125 * (calendar -> host)126 */127 UM_TIMETRAVEL_RUN = 6,128 129 /**130 * @UM_TIMETRAVEL_FREE_UNTIL: Enable free-running until the given time,131 * this is a message from the calendar telling the host that it can132 * freely do its own scheduling for anything before the indicated133 * time.134 * Note that if a calendar sends this message once, the host may135 * assume that it will also do so in the future, if it implements136 * wraparound semantics for the time field.137 * (calendar -> host)138 */139 UM_TIMETRAVEL_FREE_UNTIL = 7,140 141 /**142 * @UM_TIMETRAVEL_GET_TOD: Return time of day, typically used once at143 * boot by the virtual machines to get a synchronized time from144 * the simulation.145 */146 UM_TIMETRAVEL_GET_TOD = 8,147 148 /**149 * @UM_TIMETRAVEL_BROADCAST: Send/Receive a broadcast message.150 * This message can be used to sync all components in the system151 * with a single message, if the calender gets the message, the152 * calender broadcast the message to all components, and if a153 * component receives it it should act based on it e.g print a154 * message to it's log system.155 * (calendar <-> host)156 */157 UM_TIMETRAVEL_BROADCAST = 9,158};159 160/* version of struct um_timetravel_schedshm */161#define UM_TIMETRAVEL_SCHEDSHM_VERSION 2162 163/**164 * enum um_timetravel_schedshm_cap - time travel capabilities of every client165 *166 * These flags must be set immediately after processing the ACK to167 * the START message, before sending any message to the controller.168 */169enum um_timetravel_schedshm_cap {170 /**171 * @UM_TIMETRAVEL_SCHEDSHM_CAP_TIME_SHARE: client can read current time172 * update internal time request to shared memory and read173 * free until and send no Ack on RUN and doesn't expect ACK on174 * WAIT.175 */176 UM_TIMETRAVEL_SCHEDSHM_CAP_TIME_SHARE = 0x1,177};178 179/**180 * enum um_timetravel_schedshm_flags - time travel flags of every client181 */182enum um_timetravel_schedshm_flags {183 /**184 * @UM_TIMETRAVEL_SCHEDSHM_FLAGS_REQ_RUN: client has a request to run.185 * It's set by client when it has a request to run, if (and only186 * if) the @running_id points to a client that is able to use187 * shared memory, i.e. has %UM_TIMETRAVEL_SCHEDSHM_CAP_TIME_SHARE188 * (this includes the client itself). Otherwise, a message must189 * be used.190 */191 UM_TIMETRAVEL_SCHEDSHM_FLAGS_REQ_RUN = 0x1,192};193 194/**195 * DOC: Time travel shared memory overview196 *197 * The main purpose of the shared memory is to avoid all time travel message198 * that don't need any action, for example current time can be held in shared199 * memory without the need of any client to send a message UM_TIMETRAVEL_GET200 * in order to know what's the time.201 *202 * Since this is shared memory with all clients and controller and controller203 * creates the shared memory space, all time values are absolute to controller204 * time. So first time client connects to shared memory mode it should take the205 * current_time value in shared memory and keep it internally as a diff to206 * shared memory times, and once shared memory is initialized, any interaction207 * with the controller must happen in the controller time domain, including any208 * messages (for clients that are not using shared memory, the controller will209 * handle an offset and make the clients think they start at time zero.)210 *211 * Along with the shared memory file descriptor is sent to the client a logging212 * file descriptor, to have all logs related to shared memory,213 * logged into one place. note: to have all logs synced into log file at write,214 * file should be flushed (fflush) after writing to it.215 *216 * To avoid memory corruption, we define below for each field who can write to217 * it at what time, defined in the structure fields.218 *219 * To avoid having to pack this struct, all fields in it must be naturally aligned220 * (i.e. aligned to their size).221 */222 223/**224 * union um_timetravel_schedshm_client - UM time travel client struct225 *226 * Every entity using the shared memory including the controller has a place in227 * the um_timetravel_schedshm clients array, that holds info related to the client228 * using the shared memory, and can be set only by the client after it gets the229 * fd memory.230 *231 * @capa: bit fields with client capabilities see232 * &enum um_timetravel_schedshm_cap, set by client once after getting the233 * shared memory file descriptor.234 * @flags: bit fields for flags see &enum um_timetravel_schedshm_flags for doc.235 * @req_time: request time to run, set by client on every request it needs.236 * @name: unique id sent to the controller by client with START message.237 */238union um_timetravel_schedshm_client {239 struct {240 __u32 capa;241 __u32 flags;242 __u64 req_time;243 __u64 name;244 };245 char reserve[128]; /* reserved for future usage */246};247 248/**249 * struct um_timetravel_schedshm - UM time travel shared memory struct250 *251 * @hdr: header fields:252 * @version: Current version struct UM_TIMETRAVEL_SCHEDSHM_VERSION,253 * set by controller once at init, clients must check this after mapping254 * and work without shared memory if they cannot handle the indicated255 * version.256 * @len: Length of all the memory including header (@hdr), clients should once257 * per connection first mmap the header and take the length (@len) to remap the entire size.258 * This is done in order to support dynamic struct size letting number of259 * clients be dynamic based on controller support.260 * @free_until: Stores the next request to run by any client, in order for the261 * current client to know how long it can still run. A client needs to (at262 * least) reload this value immediately after communicating with any other263 * client, since the controller will update this field when a new request264 * is made by any client. Clients also must update this value when they265 * insert/update an own request into the shared memory while not running266 * themselves, and the new request is before than the current value.267 * current_time: Current time, can only be set by the client in running state268 * (indicated by @running_id), though that client may only run until @free_until,269 * so it must remain smaller than @free_until.270 * @running_id: The current client in state running, set before a client is271 * notified that it's now running.272 * @max_clients: size of @clients array, set once at init by the controller.273 * @clients: clients array see &union um_timetravel_schedshm_client for doc,274 * set only by client.275 */276struct um_timetravel_schedshm {277 union {278 struct {279 __u32 version;280 __u32 len;281 __u64 free_until;282 __u64 current_time;283 __u16 running_id;284 __u16 max_clients;285 };286 char hdr[4096]; /* align to 4K page size */287 };288 union um_timetravel_schedshm_client clients[];289};290#endif /* _UAPI_LINUX_UM_TIMETRAVEL_H */291