Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 1 | /* |
| 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 DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 19 | #include <functional> |
Ady Abraham | b5d3afa | 2021-05-07 11:22:23 -0700 | [diff] [blame] | 20 | #include <optional> |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 21 | #include <string> |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 22 | |
Dominik Laskowski | 43baf90 | 2023-11-17 18:13:11 -0500 | [diff] [blame] | 23 | #include <ftl/mixins.h> |
ramindani | 32a88b1 | 2024-01-31 18:45:30 -0800 | [diff] [blame] | 24 | #include <scheduler/Time.h> |
Dominik Laskowski | 4e0d20d | 2021-12-06 11:31:02 -0800 | [diff] [blame] | 25 | #include <utils/Timers.h> |
| 26 | |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 27 | namespace android::scheduler { |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 28 | |
ramindani | 32a88b1 | 2024-01-31 18:45:30 -0800 | [diff] [blame] | 29 | struct ScheduleResult { |
| 30 | TimePoint callbackTime; |
| 31 | TimePoint vsyncTime; |
| 32 | }; |
Ady Abraham | b5d3afa | 2021-05-07 11:22:23 -0700 | [diff] [blame] | 33 | |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 34 | enum class CancelResult { Cancelled, TooLate, Error }; |
| 35 | |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 36 | /* |
| 37 | * VSyncDispatch is a class that will dispatch callbacks relative to system vsync events. |
| 38 | */ |
| 39 | class VSyncDispatch { |
| 40 | public: |
Dominik Laskowski | 43baf90 | 2023-11-17 18:13:11 -0500 | [diff] [blame] | 41 | struct CallbackToken : ftl::DefaultConstructible<CallbackToken, size_t>, |
| 42 | ftl::Equatable<CallbackToken>, |
| 43 | ftl::Incrementable<CallbackToken> { |
| 44 | using DefaultConstructible::DefaultConstructible; |
| 45 | }; |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 46 | |
Kevin DuBois | e4f27a8 | 2019-11-12 11:41:41 -0800 | [diff] [blame] | 47 | virtual ~VSyncDispatch(); |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 48 | |
| 49 | /* |
Kevin DuBois | 2968afc | 2020-01-14 09:48:50 -0800 | [diff] [blame] | 50 | * A callback that can be registered to be awoken at a given time relative to a vsync event. |
Ady Abraham | 9c53ee7 | 2020-07-22 21:16:18 -0700 | [diff] [blame] | 51 | * \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 DuBois | 2968afc | 2020-01-14 09:48:50 -0800 | [diff] [blame] | 55 | */ |
Ady Abraham | 9c53ee7 | 2020-07-22 21:16:18 -0700 | [diff] [blame] | 56 | using Callback = |
| 57 | std::function<void(nsecs_t vsyncTime, nsecs_t targetWakeupTime, nsecs_t readyTime)>; |
Kevin DuBois | 2968afc | 2020-01-14 09:48:50 -0800 | [diff] [blame] | 58 | |
| 59 | /* |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 60 | * 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 Laskowski | 4e0d20d | 2021-12-06 11:31:02 -0800 | [diff] [blame] | 72 | virtual CallbackToken registerCallback(Callback, std::string callbackName) = 0; |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 73 | |
| 74 | /* |
| 75 | * Unregisters a callback. |
| 76 | * |
| 77 | * \param [in] token The callback to unregister. |
| 78 | * |
| 79 | */ |
Kevin DuBois | e4f27a8 | 2019-11-12 11:41:41 -0800 | [diff] [blame] | 80 | virtual void unregisterCallback(CallbackToken token) = 0; |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 81 | |
| 82 | /* |
Ady Abraham | 9c53ee7 | 2020-07-22 21:16:18 -0700 | [diff] [blame] | 83 | * 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 Abraham | 4335afd | 2023-12-18 19:10:47 -0800 | [diff] [blame] | 94 | * @lastVsync: The targeted display time. This will be snapped to the closest |
| 95 | * predicted vsync time after lastVsync. |
Ady Abraham | 9c53ee7 | 2020-07-22 21:16:18 -0700 | [diff] [blame] | 96 | * |
| 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 Abraham | 4335afd | 2023-12-18 19:10:47 -0800 | [diff] [blame] | 103 | nsecs_t lastVsync = 0; |
Ady Abraham | 55fa727 | 2020-09-30 19:19:27 -0700 | [diff] [blame] | 104 | |
| 105 | bool operator==(const ScheduleTiming& other) const { |
| 106 | return workDuration == other.workDuration && readyDuration == other.readyDuration && |
Ady Abraham | 4335afd | 2023-12-18 19:10:47 -0800 | [diff] [blame] | 107 | lastVsync == other.lastVsync; |
Ady Abraham | 55fa727 | 2020-09-30 19:19:27 -0700 | [diff] [blame] | 108 | } |
| 109 | |
| 110 | bool operator!=(const ScheduleTiming& other) const { return !(*this == other); } |
Ady Abraham | 9c53ee7 | 2020-07-22 21:16:18 -0700 | [diff] [blame] | 111 | }; |
| 112 | |
| 113 | /* |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 114 | * Schedules the registered callback to be dispatched. |
| 115 | * |
Ady Abraham | 9c53ee7 | 2020-07-22 21:16:18 -0700 | [diff] [blame] | 116 | * The callback will be dispatched at 'workDuration + readyDuration' nanoseconds before a vsync |
| 117 | * event. |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 118 | * |
Ady Abraham | 4335afd | 2023-12-18 19:10:47 -0800 | [diff] [blame] | 119 | * The caller designates the earliest vsync event that should be targeted by the lastVsync |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 120 | * parameter. |
Ady Abraham | 9c53ee7 | 2020-07-22 21:16:18 -0700 | [diff] [blame] | 121 | * The callback will be scheduled at (workDuration + readyDuration - predictedVsync), where |
Ady Abraham | 4335afd | 2023-12-18 19:10:47 -0800 | [diff] [blame] | 122 | * predictedVsync is the first vsync event time where ( predictedVsync >= lastVsync ). |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 123 | * |
Ady Abraham | 4335afd | 2023-12-18 19:10:47 -0800 | [diff] [blame] | 124 | * If (workDuration + readyDuration - lastVsync) is in the past, or if a callback has |
Ady Abraham | 9c53ee7 | 2020-07-22 21:16:18 -0700 | [diff] [blame] | 125 | * already been dispatched for the predictedVsync, an error will be returned. |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 126 | * |
| 127 | * It is valid to reschedule a callback to a different time. |
| 128 | * |
| 129 | * \param [in] token The callback to schedule. |
Ady Abraham | 9c53ee7 | 2020-07-22 21:16:18 -0700 | [diff] [blame] | 130 | * \param [in] scheduleTiming The timing information for this schedule call |
ramindani | 32a88b1 | 2024-01-31 18:45:30 -0800 | [diff] [blame] | 131 | * \return The expected callback time if a callback was scheduled, |
| 132 | * along with VSYNC time for the callback scheduled. |
Ady Abraham | b5d3afa | 2021-05-07 11:22:23 -0700 | [diff] [blame] | 133 | * std::nullopt if the callback is not registered. |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 134 | */ |
ramindani | 32a88b1 | 2024-01-31 18:45:30 -0800 | [diff] [blame] | 135 | virtual std::optional<ScheduleResult> schedule(CallbackToken token, |
| 136 | ScheduleTiming scheduleTiming) = 0; |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 137 | |
Ady Abraham | 011f8ba | 2022-11-22 15:09:07 -0800 | [diff] [blame] | 138 | /* |
| 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 |
ramindani | 32a88b1 | 2024-01-31 18:45:30 -0800 | [diff] [blame] | 144 | * \return The expected callback time if a callback was scheduled, |
| 145 | * along with VSYNC time for the callback scheduled. |
Ady Abraham | 011f8ba | 2022-11-22 15:09:07 -0800 | [diff] [blame] | 146 | * std::nullopt if the callback is not registered. |
| 147 | */ |
ramindani | 32a88b1 | 2024-01-31 18:45:30 -0800 | [diff] [blame] | 148 | virtual std::optional<ScheduleResult> update(CallbackToken token, |
| 149 | ScheduleTiming scheduleTiming) = 0; |
Ady Abraham | 011f8ba | 2022-11-22 15:09:07 -0800 | [diff] [blame] | 150 | |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 151 | /* 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 DuBois | e4f27a8 | 2019-11-12 11:41:41 -0800 | [diff] [blame] | 158 | virtual CancelResult cancel(CallbackToken token) = 0; |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 159 | |
Ady Abraham | 5e7371c | 2020-03-24 14:47:24 -0700 | [diff] [blame] | 160 | virtual void dump(std::string& result) const = 0; |
| 161 | |
Kevin DuBois | e4f27a8 | 2019-11-12 11:41:41 -0800 | [diff] [blame] | 162 | protected: |
| 163 | VSyncDispatch() = default; |
Dominik Laskowski | 4e0d20d | 2021-12-06 11:31:02 -0800 | [diff] [blame] | 164 | |
| 165 | VSyncDispatch(const VSyncDispatch&) = delete; |
| 166 | VSyncDispatch& operator=(const VSyncDispatch&) = delete; |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 167 | }; |
| 168 | |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 169 | class VSyncCallbackRegistration { |
| 170 | public: |
Leon Scroggins III | 6738862 | 2023-02-06 20:36:20 -0500 | [diff] [blame] | 171 | VSyncCallbackRegistration(std::shared_ptr<VSyncDispatch>, VSyncDispatch::Callback, |
| 172 | std::string callbackName); |
Dominik Laskowski | 4e0d20d | 2021-12-06 11:31:02 -0800 | [diff] [blame] | 173 | ~VSyncCallbackRegistration(); |
| 174 | |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 175 | VSyncCallbackRegistration(VSyncCallbackRegistration&&); |
| 176 | VSyncCallbackRegistration& operator=(VSyncCallbackRegistration&&); |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 177 | |
| 178 | // See documentation for VSyncDispatch::schedule. |
ramindani | 32a88b1 | 2024-01-31 18:45:30 -0800 | [diff] [blame] | 179 | std::optional<ScheduleResult> schedule(VSyncDispatch::ScheduleTiming scheduleTiming); |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 180 | |
Ady Abraham | 011f8ba | 2022-11-22 15:09:07 -0800 | [diff] [blame] | 181 | // See documentation for VSyncDispatch::update. |
ramindani | 32a88b1 | 2024-01-31 18:45:30 -0800 | [diff] [blame] | 182 | std::optional<ScheduleResult> update(VSyncDispatch::ScheduleTiming scheduleTiming); |
Ady Abraham | 011f8ba | 2022-11-22 15:09:07 -0800 | [diff] [blame] | 183 | |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 184 | // See documentation for VSyncDispatch::cancel. |
| 185 | CancelResult cancel(); |
| 186 | |
| 187 | private: |
Leon Scroggins III | 6c440ae | 2023-04-21 15:01:03 -0400 | [diff] [blame] | 188 | friend class VSyncCallbackRegistrationTest; |
| 189 | |
Leon Scroggins III | 6738862 | 2023-02-06 20:36:20 -0500 | [diff] [blame] | 190 | std::shared_ptr<VSyncDispatch> mDispatch; |
Leon Scroggins III | 6c440ae | 2023-04-21 15:01:03 -0400 | [diff] [blame] | 191 | std::optional<VSyncDispatch::CallbackToken> mToken; |
Kevin DuBois | 305bef1 | 2019-10-09 13:23:27 -0700 | [diff] [blame] | 192 | }; |
| 193 | |
| 194 | } // namespace android::scheduler |