1 /*
2  * Permission to use, copy, modify, and/or distribute this software for any
3  * purpose with or without fee is hereby granted, provided that the above
4  * copyright notice and this permission notice appear in all copies.
5  *
6  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
7  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
8  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
9  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
10  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
11  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
12  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
13  *
14  * Copyright (C) 2019 Intel Corporation
15  */
16 #ifndef _UAPI_LINUX_UM_TIMETRAVEL_H
17 #define _UAPI_LINUX_UM_TIMETRAVEL_H
18 #include <linux/types.h>
19 
20 /**
21  * struct um_timetravel_msg - UM time travel message
22  *
23  * This is the basic message type, going in both directions.
24  *
25  * This is the message passed between the host (user-mode Linux instance)
26  * and the calendar (the application on the other side of the socket) in
27  * order to implement common scheduling.
28  *
29  * Whenever UML has an event it will request runtime for it from the
30  * calendar, and then wait for its turn until it can run, etc. Note
31  * that it will only ever request the single next runtime, i.e. multiple
32  * REQUEST messages override each other.
33  */
34 struct um_timetravel_msg {
35 	/**
36 	 * @op: operation value from &enum um_timetravel_ops
37 	 */
38 	__u32 op;
39 
40 	/**
41 	 * @seq: sequence number for the message - shall be reflected in
42 	 *	the ACK response, and should be checked while processing
43 	 *	the response to see if it matches
44 	 */
45 	__u32 seq;
46 
47 	/**
48 	 * @time: time in nanoseconds
49 	 */
50 	__u64 time;
51 };
52 
53 /**
54  * enum um_timetravel_ops - Operation codes
55  */
56 enum um_timetravel_ops {
57 	/**
58 	 * @UM_TIMETRAVEL_ACK: response (ACK) to any previous message,
59 	 *	this usually doesn't carry any data in the 'time' field
60 	 *	unless otherwise specified below
61 	 */
62 	UM_TIMETRAVEL_ACK		= 0,
63 
64 	/**
65 	 * @UM_TIMETRAVEL_START: initialize the connection, the time
66 	 *	field contains an (arbitrary) ID to possibly be able
67 	 *	to distinguish the connections.
68 	 */
69 	UM_TIMETRAVEL_START		= 1,
70 
71 	/**
72 	 * @UM_TIMETRAVEL_REQUEST: request to run at the given time
73 	 *	(host -> calendar)
74 	 */
75 	UM_TIMETRAVEL_REQUEST		= 2,
76 
77 	/**
78 	 * @UM_TIMETRAVEL_WAIT: Indicate waiting for the previously requested
79 	 *	runtime, new requests may be made while waiting (e.g. due to
80 	 *	interrupts); the time field is ignored. The calendar must process
81 	 *	this message and later	send a %UM_TIMETRAVEL_RUN message when
82 	 *	the host can run again.
83 	 *	(host -> calendar)
84 	 */
85 	UM_TIMETRAVEL_WAIT		= 3,
86 
87 	/**
88 	 * @UM_TIMETRAVEL_GET: return the current time from the calendar in the
89 	 *	ACK message, the time in the request message is ignored
90 	 *	(host -> calendar)
91 	 */
92 	UM_TIMETRAVEL_GET		= 4,
93 
94 	/**
95 	 * @UM_TIMETRAVEL_UPDATE: time update to the calendar, must be sent e.g.
96 	 *	before kicking an interrupt to another calendar
97 	 *	(host -> calendar)
98 	 */
99 	UM_TIMETRAVEL_UPDATE		= 5,
100 
101 	/**
102 	 * @UM_TIMETRAVEL_RUN: run time request granted, current time is in
103 	 *	the time field
104 	 *	(calendar -> host)
105 	 */
106 	UM_TIMETRAVEL_RUN		= 6,
107 
108 	/**
109 	 * @UM_TIMETRAVEL_FREE_UNTIL: Enable free-running until the given time,
110 	 *	this is a message from the calendar telling the host that it can
111 	 *	freely do its own scheduling for anything before the indicated
112 	 *	time.
113 	 *	Note that if a calendar sends this message once, the host may
114 	 *	assume that it will also do so in the future, if it implements
115 	 *	wraparound semantics for the time field.
116 	 *	(calendar -> host)
117 	 */
118 	UM_TIMETRAVEL_FREE_UNTIL	= 7,
119 
120 	/**
121 	 * @UM_TIMETRAVEL_GET_TOD: Return time of day, typically used once at
122 	 *	boot by the virtual machines to get a synchronized time from
123 	 *	the simulation.
124 	 */
125 	UM_TIMETRAVEL_GET_TOD		= 8,
126 };
127 
128 #endif /* _UAPI_LINUX_UM_TIMETRAVEL_H */
129