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 */
34struct 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 */
56enum 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