blob: 0c43ffbc0418a346c462bb072f7cc7e546a24db4 [file] [log] [blame]
Kevin DuBois305bef12019-10-09 13:23:27 -07001/*
2 * Copyright 2019 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#pragma once
18
Kevin DuBois305bef12019-10-09 13:23:27 -070019#include <functional>
Ady Abrahamb5d3afa2021-05-07 11:22:23 -070020#include <optional>
Kevin DuBois305bef12019-10-09 13:23:27 -070021#include <string>
Kevin DuBois305bef12019-10-09 13:23:27 -070022
Dominik Laskowski43baf902023-11-17 18:13:11 -050023#include <ftl/mixins.h>
ramindani32a88b12024-01-31 18:45:30 -080024#include <scheduler/Time.h>
Dominik Laskowski4e0d20d2021-12-06 11:31:02 -080025#include <utils/Timers.h>
26
Kevin DuBois305bef12019-10-09 13:23:27 -070027namespace android::scheduler {
Kevin DuBois305bef12019-10-09 13:23:27 -070028
ramindani32a88b12024-01-31 18:45:30 -080029struct ScheduleResult {
30 TimePoint callbackTime;
31 TimePoint vsyncTime;
32};
Ady Abrahamb5d3afa2021-05-07 11:22:23 -070033
Kevin DuBois305bef12019-10-09 13:23:27 -070034enum class CancelResult { Cancelled, TooLate, Error };
35
Kevin DuBois305bef12019-10-09 13:23:27 -070036/*
37 * VSyncDispatch is a class that will dispatch callbacks relative to system vsync events.
38 */
39class VSyncDispatch {
40public:
Dominik Laskowski43baf902023-11-17 18:13:11 -050041 struct CallbackToken : ftl::DefaultConstructible<CallbackToken, size_t>,
42 ftl::Equatable<CallbackToken>,
43 ftl::Incrementable<CallbackToken> {
44 using DefaultConstructible::DefaultConstructible;
45 };
Kevin DuBois305bef12019-10-09 13:23:27 -070046
Kevin DuBoise4f27a82019-11-12 11:41:41 -080047 virtual ~VSyncDispatch();
Kevin DuBois305bef12019-10-09 13:23:27 -070048
49 /*
Kevin DuBois2968afc2020-01-14 09:48:50 -080050 * A callback that can be registered to be awoken at a given time relative to a vsync event.
Ady Abraham9c53ee72020-07-22 21:16:18 -070051 * \param [in] vsyncTime: The timestamp of the vsync the callback is for.
52 * \param [in] targetWakeupTime: The timestamp of intended wakeup time of the cb.
53 * \param [in] readyTime: The timestamp of intended time where client needs to finish
54 * its work by.
Kevin DuBois2968afc2020-01-14 09:48:50 -080055 */
Ady Abraham9c53ee72020-07-22 21:16:18 -070056 using Callback =
57 std::function<void(nsecs_t vsyncTime, nsecs_t targetWakeupTime, nsecs_t readyTime)>;
Kevin DuBois2968afc2020-01-14 09:48:50 -080058
59 /*
Kevin DuBois305bef12019-10-09 13:23:27 -070060 * Registers a callback that will be called at designated points on the vsync timeline.
61 * The callback can be scheduled, rescheduled targeting vsync times, or cancelled.
62 * The token returned must be cleaned up via unregisterCallback.
63 *
64 * \param [in] callbackFn A function to schedule for callback. The resources needed to invoke
65 * callbackFn must have lifetimes encompassing the lifetime of the
66 * CallbackToken returned.
67 * \param [in] callbackName A human-readable, unique name to identify the callback.
68 * \return A token that can be used to schedule, reschedule, or cancel the
69 * invocation of callbackFn.
70 *
71 */
Dominik Laskowski4e0d20d2021-12-06 11:31:02 -080072 virtual CallbackToken registerCallback(Callback, std::string callbackName) = 0;
Kevin DuBois305bef12019-10-09 13:23:27 -070073
74 /*
75 * Unregisters a callback.
76 *
77 * \param [in] token The callback to unregister.
78 *
79 */
Kevin DuBoise4f27a82019-11-12 11:41:41 -080080 virtual void unregisterCallback(CallbackToken token) = 0;
Kevin DuBois305bef12019-10-09 13:23:27 -070081
82 /*
Ady Abraham9c53ee72020-07-22 21:16:18 -070083 * Timing information about a scheduled callback
84 *
85 * @workDuration: The time needed for the client to perform its work
86 * @readyDuration: The time needed for the client to be ready before a vsync event.
87 * For external (non-SF) clients, not only do we need to account for their
88 * workDuration, but we also need to account for the time SF will take to
89 * process their buffer/transaction. In this case, readyDuration will be set
90 * to the SF duration in order to provide enough end-to-end time, and to be
91 * able to provide the ready-by time (deadline) on the callback.
92 * For internal clients, we don't need to add additional padding, so
93 * readyDuration will typically be 0.
Ady Abraham4335afd2023-12-18 19:10:47 -080094 * @lastVsync: The targeted display time. This will be snapped to the closest
95 * predicted vsync time after lastVsync.
Ady Abraham9c53ee72020-07-22 21:16:18 -070096 *
97 * callback will be dispatched at 'workDuration + readyDuration' nanoseconds before a vsync
98 * event.
99 */
100 struct ScheduleTiming {
101 nsecs_t workDuration = 0;
102 nsecs_t readyDuration = 0;
Ady Abraham4335afd2023-12-18 19:10:47 -0800103 nsecs_t lastVsync = 0;
Ady Abraham55fa7272020-09-30 19:19:27 -0700104
105 bool operator==(const ScheduleTiming& other) const {
106 return workDuration == other.workDuration && readyDuration == other.readyDuration &&
Ady Abraham4335afd2023-12-18 19:10:47 -0800107 lastVsync == other.lastVsync;
Ady Abraham55fa7272020-09-30 19:19:27 -0700108 }
109
110 bool operator!=(const ScheduleTiming& other) const { return !(*this == other); }
Ady Abraham9c53ee72020-07-22 21:16:18 -0700111 };
112
113 /*
Kevin DuBois305bef12019-10-09 13:23:27 -0700114 * Schedules the registered callback to be dispatched.
115 *
Ady Abraham9c53ee72020-07-22 21:16:18 -0700116 * The callback will be dispatched at 'workDuration + readyDuration' nanoseconds before a vsync
117 * event.
Kevin DuBois305bef12019-10-09 13:23:27 -0700118 *
Ady Abraham4335afd2023-12-18 19:10:47 -0800119 * The caller designates the earliest vsync event that should be targeted by the lastVsync
Kevin DuBois305bef12019-10-09 13:23:27 -0700120 * parameter.
Ady Abraham9c53ee72020-07-22 21:16:18 -0700121 * The callback will be scheduled at (workDuration + readyDuration - predictedVsync), where
Ady Abraham4335afd2023-12-18 19:10:47 -0800122 * predictedVsync is the first vsync event time where ( predictedVsync >= lastVsync ).
Kevin DuBois305bef12019-10-09 13:23:27 -0700123 *
Ady Abraham4335afd2023-12-18 19:10:47 -0800124 * If (workDuration + readyDuration - lastVsync) is in the past, or if a callback has
Ady Abraham9c53ee72020-07-22 21:16:18 -0700125 * already been dispatched for the predictedVsync, an error will be returned.
Kevin DuBois305bef12019-10-09 13:23:27 -0700126 *
127 * It is valid to reschedule a callback to a different time.
128 *
129 * \param [in] token The callback to schedule.
Ady Abraham9c53ee72020-07-22 21:16:18 -0700130 * \param [in] scheduleTiming The timing information for this schedule call
ramindani32a88b12024-01-31 18:45:30 -0800131 * \return The expected callback time if a callback was scheduled,
132 * along with VSYNC time for the callback scheduled.
Ady Abrahamb5d3afa2021-05-07 11:22:23 -0700133 * std::nullopt if the callback is not registered.
Kevin DuBois305bef12019-10-09 13:23:27 -0700134 */
ramindani32a88b12024-01-31 18:45:30 -0800135 virtual std::optional<ScheduleResult> schedule(CallbackToken token,
136 ScheduleTiming scheduleTiming) = 0;
Kevin DuBois305bef12019-10-09 13:23:27 -0700137
Ady Abraham011f8ba2022-11-22 15:09:07 -0800138 /*
139 * Update the timing information for a scheduled callback.
140 * If the callback is not scheduled, then this function does nothing.
141 *
142 * \param [in] token The callback to schedule.
143 * \param [in] scheduleTiming The timing information for this schedule call
ramindani32a88b12024-01-31 18:45:30 -0800144 * \return The expected callback time if a callback was scheduled,
145 * along with VSYNC time for the callback scheduled.
Ady Abraham011f8ba2022-11-22 15:09:07 -0800146 * std::nullopt if the callback is not registered.
147 */
ramindani32a88b12024-01-31 18:45:30 -0800148 virtual std::optional<ScheduleResult> update(CallbackToken token,
149 ScheduleTiming scheduleTiming) = 0;
Ady Abraham011f8ba2022-11-22 15:09:07 -0800150
Kevin DuBois305bef12019-10-09 13:23:27 -0700151 /* Cancels a scheduled callback, if possible.
152 *
153 * \param [in] token The callback to cancel.
154 * \return A CancelResult::TooLate if the callback was already dispatched.
155 * A CancelResult::Cancelled if the callback was successfully cancelled.
156 * A CancelResult::Error if there was an pre-condition violation.
157 */
Kevin DuBoise4f27a82019-11-12 11:41:41 -0800158 virtual CancelResult cancel(CallbackToken token) = 0;
Kevin DuBois305bef12019-10-09 13:23:27 -0700159
Ady Abraham5e7371c2020-03-24 14:47:24 -0700160 virtual void dump(std::string& result) const = 0;
161
Kevin DuBoise4f27a82019-11-12 11:41:41 -0800162protected:
163 VSyncDispatch() = default;
Dominik Laskowski4e0d20d2021-12-06 11:31:02 -0800164
165 VSyncDispatch(const VSyncDispatch&) = delete;
166 VSyncDispatch& operator=(const VSyncDispatch&) = delete;
Kevin DuBois305bef12019-10-09 13:23:27 -0700167};
168
Kevin DuBois305bef12019-10-09 13:23:27 -0700169class VSyncCallbackRegistration {
170public:
Leon Scroggins III67388622023-02-06 20:36:20 -0500171 VSyncCallbackRegistration(std::shared_ptr<VSyncDispatch>, VSyncDispatch::Callback,
172 std::string callbackName);
Dominik Laskowski4e0d20d2021-12-06 11:31:02 -0800173 ~VSyncCallbackRegistration();
174
Kevin DuBois305bef12019-10-09 13:23:27 -0700175 VSyncCallbackRegistration(VSyncCallbackRegistration&&);
176 VSyncCallbackRegistration& operator=(VSyncCallbackRegistration&&);
Kevin DuBois305bef12019-10-09 13:23:27 -0700177
178 // See documentation for VSyncDispatch::schedule.
ramindani32a88b12024-01-31 18:45:30 -0800179 std::optional<ScheduleResult> schedule(VSyncDispatch::ScheduleTiming scheduleTiming);
Kevin DuBois305bef12019-10-09 13:23:27 -0700180
Ady Abraham011f8ba2022-11-22 15:09:07 -0800181 // See documentation for VSyncDispatch::update.
ramindani32a88b12024-01-31 18:45:30 -0800182 std::optional<ScheduleResult> update(VSyncDispatch::ScheduleTiming scheduleTiming);
Ady Abraham011f8ba2022-11-22 15:09:07 -0800183
Kevin DuBois305bef12019-10-09 13:23:27 -0700184 // See documentation for VSyncDispatch::cancel.
185 CancelResult cancel();
186
187private:
Leon Scroggins III6c440ae2023-04-21 15:01:03 -0400188 friend class VSyncCallbackRegistrationTest;
189
Leon Scroggins III67388622023-02-06 20:36:20 -0500190 std::shared_ptr<VSyncDispatch> mDispatch;
Leon Scroggins III6c440ae2023-04-21 15:01:03 -0400191 std::optional<VSyncDispatch::CallbackToken> mToken;
Kevin DuBois305bef12019-10-09 13:23:27 -0700192};
193
194} // namespace android::scheduler