GNU Linux-libre 6.9.2-gnu
[releases.git] / include / uapi / linux / um_timetravel.h
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 */