logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

um_timetravel.h (10032B)


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