include/uapi/linux/um_timetravel.h

   1 /* SPDX-License-Identifier: BSD-3-Clause */
   2 /*
   3  * Copyright (C) 2019 - 2023 Intel Corporation
   4  */
   5 #ifndef _UAPI_LINUX_UM_TIMETRAVEL_H
   6 #define _UAPI_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  */
  23 struct 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  */
  48 enum 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         UM_TIMETRAVEL_SHARED_MAX_FDS,
  60 };
  61
  62 /**
  63  * enum um_timetravel_start_ack - ack-time mask for start message
  64  */
  65 enum 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 codes
  74  */
  75 enum 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' field
  79          *      unless otherwise specified below, note: while using shared
  80          *      memory no ACK for WAIT and RUN messages, for more info see
  81          *      &struct um_timetravel_schedshm.
  82          */
  83         UM_TIMETRAVEL_ACK               = 0,
  84
  85         /**
  86          * @UM_TIMETRAVEL_START: initialize the connection, the time
  87          *      field contains an (arbitrary) ID to possibly be able
  88          *      to distinguish the connections.
  89          */
  90         UM_TIMETRAVEL_START             = 1,
  91
  92         /**
  93          * @UM_TIMETRAVEL_REQUEST: request to run at the given time
  94          *      (host -> calendar)
  95          */
  96         UM_TIMETRAVEL_REQUEST           = 2,
  97
  98         /**
  99          * @UM_TIMETRAVEL_WAIT: Indicate waiting for the previously requested
 100          *      runtime, new requests may be made while waiting (e.g. due to
 101          *      interrupts); the time field is ignored. The calendar must process
 102          *      this message and later  send a %UM_TIMETRAVEL_RUN message when
 103          *      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 the
 110          *      ACK message, the time in the request message is ignored
 111          *      (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 calendar
 118          *      (host -> calendar)
 119          */
 120         UM_TIMETRAVEL_UPDATE            = 5,
 121
 122         /**
 123          * @UM_TIMETRAVEL_RUN: run time request granted, current time is in
 124          *      the time field
 125          *      (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 can
 132          *      freely do its own scheduling for anything before the indicated
 133          *      time.
 134          *      Note that if a calendar sends this message once, the host may
 135          *      assume that it will also do so in the future, if it implements
 136          *      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 at
 143          *      boot by the virtual machines to get a synchronized time from
 144          *      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 system
 151          *      with a single message, if the calender gets the message, the
 152          *      calender broadcast the message to all components, and if a
 153          *      component receives it it should act based on it e.g print a
 154          *      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 2
 162
 163 /**
 164  * enum um_timetravel_schedshm_cap - time travel capabilities of every client
 165  *
 166  * These flags must be set immediately after processing the ACK to
 167  * the START message, before sending any message to the controller.
 168  */
 169 enum um_timetravel_schedshm_cap {
 170         /**
 171          * @UM_TIMETRAVEL_SCHEDSHM_CAP_TIME_SHARE: client can read current time
 172          *      update internal time request to shared memory and read
 173          *      free until and send no Ack on RUN and doesn't expect ACK on
 174          *      WAIT.
 175          */
 176         UM_TIMETRAVEL_SCHEDSHM_CAP_TIME_SHARE = 0x1,
 177 };
 178
 179 /**
 180  * enum um_timetravel_schedshm_flags - time travel flags of every client
 181  */
 182 enum 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 only
 186          *      if) the @running_id points to a client that is able to use
 187          *      shared memory, i.e. has %UM_TIMETRAVEL_SCHEDSHM_CAP_TIME_SHARE
 188          *      (this includes the client itself). Otherwise, a message must
 189          *      be used.
 190          */
 191         UM_TIMETRAVEL_SCHEDSHM_FLAGS_REQ_RUN = 0x1,
 192 };
 193
 194 /**
 195  * DOC: Time travel shared memory overview
 196  *
 197  * The main purpose of the shared memory is to avoid all time travel message
 198  * that don't need any action, for example current time can be held in shared
 199  * memory without the need of any client to send a message UM_TIMETRAVEL_GET
 200  * in order to know what's the time.
 201  *
 202  * Since this is shared memory with all clients and controller and controller
 203  * creates the shared memory space, all time values are absolute to controller
 204  * time. So first time client connects to shared memory mode it should take the
 205  * current_time value in shared memory and keep it internally as a diff to
 206  * shared memory times, and once shared memory is initialized, any interaction
 207  * with the controller must happen in the controller time domain, including any
 208  * messages (for clients that are not using shared memory, the controller will
 209  * 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 logging
 212  * 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 to
 217  * 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 aligned
 220  * (i.e. aligned to their size).
 221  */
 222
 223 /**
 224  * union um_timetravel_schedshm_client - UM time travel client struct
 225  *
 226  * Every entity using the shared memory including the controller has a place in
 227  * the um_timetravel_schedshm clients array, that holds info related to the client
 228  * using the shared memory, and can be set only by the client after it gets the
 229  * fd memory.
 230  *
 231  * @capa: bit fields with client capabilities see
 232  *      &enum um_timetravel_schedshm_cap, set by client once after getting the
 233  *      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  */
 238 union 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 struct
 250  *
 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 mapping
 254  *      and work without shared memory if they cannot handle the indicated
 255  *      version.
 256  * @len: Length of all the memory including header (@hdr), clients should once
 257  *      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 of
 259  *      clients be dynamic based on controller support.
 260  * @free_until: Stores the next request to run by any client, in order for the
 261  *      current client to know how long it can still run. A client needs to (at
 262  *      least) reload this value immediately after communicating with any other
 263  *      client, since the controller will update this field when a new request
 264  *      is made by any client. Clients also must update this value when they
 265  *      insert/update an own request into the shared memory while not running
 266  *      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 state
 268  *      (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 is
 271  *      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  */
 276 struct 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 */