From 36d123e9c5a9ce0e29b9bc22ef87661bf479e299 Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Tue, 16 Nov 2021 05:21:09 +1100 Subject: [PATCH] Add support for deferred executors. (#14859) * Add support for deferred executors. * More docs. * Include from quantum.h * Cleanup. * Parameter checks * Comments. * qmk format-c * I accidentally a few words. * API name change. * Apply suggestions from code review Co-authored-by: Sergey Vlasov * Review comments. * qmk format-c * Review comments. Co-authored-by: Sergey Vlasov --- builddefs/generic_features.mk | 1 + docs/config_options.md | 2 + docs/custom_quantum_functions.md | 66 ++++++++ docs/getting_started_make_guide.md | 4 + quantum/deferred_exec.c | 152 +++++++++++++++++++ quantum/deferred_exec.h | 38 +++++ quantum/main.c | 10 ++ quantum/quantum.h | 4 + tmk_core/protocol/arm_atsam/main_arm_atsam.c | 9 ++ 9 files changed, 286 insertions(+) create mode 100644 quantum/deferred_exec.c create mode 100644 quantum/deferred_exec.h diff --git a/builddefs/generic_features.mk b/builddefs/generic_features.mk index 2281a82917e..e41ce6ac91d 100644 --- a/builddefs/generic_features.mk +++ b/builddefs/generic_features.mk @@ -19,6 +19,7 @@ GRAVE_ESC_ENABLE ?= yes GENERIC_FEATURES = \ COMBO \ COMMAND \ + DEFERRED_EXEC \ DIGITIZER \ DIP_SWITCH \ DYNAMIC_KEYMAP \ diff --git a/docs/config_options.md b/docs/config_options.md index ece7ab8ee35..9f2453b6986 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -446,6 +446,8 @@ Use these to enable or disable building certain features. The more you have enab * Forces the keyboard to wait for a USB connection to be established before it starts up * `NO_USB_STARTUP_CHECK` * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master. +* `DEFERRED_EXEC_ENABLE` + * Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions.md#deferred-execution) for more information. ## USB Endpoint Limitations diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 798c346e67a..dd1654bd298 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -405,3 +405,69 @@ And you're done. The RGB layer indication will only work if you want it to. And * Keymap: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` and `void eeconfig_update_user(uint32_t val)` The `val` is the value of the data that you want to write to EEPROM. And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM. + +### Deferred Execution :id=deferred-execution + +QMK has the ability to execute a callback after a specified period of time, rather than having to manually manage timers. + +#### Deferred executor callbacks + +All _deferred executor callbacks_ have a common function signature and look like: + +```c +uint32_t my_callback(uint32_t trigger_time, void *cb_arg) { + /* do something */ + bool repeat = my_deferred_functionality(); + return repeat ? 500 : 0; +} +``` + +The first argument `trigger_time` is the intended time of execution. If other delays prevent executing at the exact trigger time, this allows for "catch-up" or even skipping intervals, depending on the required behaviour. + +The second argument `cb_arg` is the same argument passed into `defer_exec()` below, and can be used to access state information from the original call context. + +The return value is the number of milliseconds to use if the function should be repeated -- if the callback returns `0` then it's automatically unregistered. In the example above, a hypothetical `my_deferred_functionality()` is invoked to determine if the callback needs to be repeated -- if it does, it reschedules for a `500` millisecond delay, otherwise it informs the deferred execution background task that it's done, by returning `0`. + +?> Note that the returned delay will be applied to the intended trigger time, not the time of callback invocation. This allows for generally consistent timing even in the face of occasional late execution. + +#### Deferred executor registration + +Once a callback has been defined, it can be scheduled using the following API: + +```c +deferred_token my_token = defer_exec(1500, my_callback, NULL); +``` + +The first argument is the number of milliseconds to wait until executing `my_callback` -- in the case above, `1500` milliseconds, or 1.5 seconds. + +The third parameter is the `cb_arg` that gets passed to the callback at the point of execution. This value needs to be valid at the time the callback is invoked -- a local function value will be destroyed before the callback is executed and should not be used. If this is not required, `NULL` should be used. + +The return value is a `deferred_token` that can consequently be used to cancel the deferred executor callback before it's invoked. If a failure occurs, the returned value will be `INVALID_DEFERRED_TOKEN`. Usually this will be as a result of supplying `0` to the delay, or a `NULL` for the callback. The other failure case is if there are too many deferred executions "in flight" -- this can be increased by changing the limit, described below. + +#### Extending a deferred execution + +The `deferred_token` returned by `defer_exec()` can be used to extend a the duration a pending execution waits before it gets invoked: +```c +// This will re-delay my_token's future execution such that it is invoked 800ms after the current time +extend_deferred_exec(my_token, 800); +``` + +#### Cancelling a deferred execution + +The `deferred_token` returned by `defer_exec()` can be used to cancel a pending execution before it gets invoked: +```c +// This will cancel my_token's future execution +cancel_deferred_exec(my_token); +``` + +Once a token has been canceled, it should be considered invalid. Reusing the same token is not supported. + +#### Deferred callback limits + +There are a maximum number of deferred callbacks that can be scheduled, controlled by the value of the define `MAX_DEFERRED_EXECUTORS`. + +If registrations fail, then you can increase this value in your keyboard or keymap `config.h` file, for example to 16 instead of the default 8: + +```c +#define MAX_DEFERRED_EXECUTORS 16 +``` diff --git a/docs/getting_started_make_guide.md b/docs/getting_started_make_guide.md index a514864353c..1a7e276098a 100644 --- a/docs/getting_started_make_guide.md +++ b/docs/getting_started_make_guide.md @@ -145,6 +145,10 @@ Lets you replace the default matrix scanning routine with your own code. For fur Lets you replace the default key debouncing routine with an alternative one. If `custom` you will need to provide your own implementation. +`DEFERRED_EXEC_ENABLE` + +Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions.md#deferred-execution) for more information. + ## Customizing Makefile Options on a Per-Keymap Basis If your keymap directory has a file called `rules.mk` any options you set in that file will take precedence over other `rules.mk` options for your particular keyboard. diff --git a/quantum/deferred_exec.c b/quantum/deferred_exec.c new file mode 100644 index 00000000000..5b0a5b14258 --- /dev/null +++ b/quantum/deferred_exec.c @@ -0,0 +1,152 @@ +// Copyright 2021 Nick Brassel (@tzarc) +// SPDX-License-Identifier: GPL-2.0-or-later + +#include +#include +#include + +#ifndef MAX_DEFERRED_EXECUTORS +# define MAX_DEFERRED_EXECUTORS 8 +#endif + +typedef struct deferred_executor_t { + deferred_token token; + uint32_t trigger_time; + deferred_exec_callback callback; + void * cb_arg; +} deferred_executor_t; + +static deferred_token current_token = 0; +static uint32_t last_deferred_exec_check = 0; +static deferred_executor_t executors[MAX_DEFERRED_EXECUTORS] = {0}; + +static inline bool token_can_be_used(deferred_token token) { + if (token == INVALID_DEFERRED_TOKEN) { + return false; + } + for (int i = 0; i < MAX_DEFERRED_EXECUTORS; ++i) { + if (executors[i].token == token) { + return false; + } + } + return true; +} + +static inline deferred_token allocate_token(void) { + deferred_token first = ++current_token; + while (!token_can_be_used(current_token)) { + ++current_token; + if (current_token == first) { + // If we've looped back around to the first, everything is already allocated (yikes!). Need to exit with a failure. + return INVALID_DEFERRED_TOKEN; + } + } + return current_token; +} + +deferred_token defer_exec(uint32_t delay_ms, deferred_exec_callback callback, void *cb_arg) { + // Ignore queueing if it's a zero-time delay, or invalid callback + if (delay_ms == 0 || !callback) { + return INVALID_DEFERRED_TOKEN; + } + + // Find an unused slot and claim it + for (int i = 0; i < MAX_DEFERRED_EXECUTORS; ++i) { + deferred_executor_t *entry = &executors[i]; + if (entry->token == INVALID_DEFERRED_TOKEN) { + // Work out the new token value, dropping out if none were available + deferred_token token = allocate_token(); + if (token == INVALID_DEFERRED_TOKEN) { + return false; + } + + // Set up the executor table entry + entry->token = current_token; + entry->trigger_time = timer_read32() + delay_ms; + entry->callback = callback; + entry->cb_arg = cb_arg; + return current_token; + } + } + + // None available + return INVALID_DEFERRED_TOKEN; +} + +bool extend_deferred_exec(deferred_token token, uint32_t delay_ms) { + // Ignore queueing if it's a zero-time delay, or the token is not valid + if (delay_ms == 0 || token == INVALID_DEFERRED_TOKEN) { + return false; + } + + // Find the entry corresponding to the token + for (int i = 0; i < MAX_DEFERRED_EXECUTORS; ++i) { + deferred_executor_t *entry = &executors[i]; + if (entry->token == token) { + // Found it, extend the delay + entry->trigger_time = timer_read32() + delay_ms; + return true; + } + } + + // Not found + return false; +} + +bool cancel_deferred_exec(deferred_token token) { + // Ignore request if the token is not valid + if (token == INVALID_DEFERRED_TOKEN) { + return false; + } + + // Find the entry corresponding to the token + for (int i = 0; i < MAX_DEFERRED_EXECUTORS; ++i) { + deferred_executor_t *entry = &executors[i]; + if (entry->token == token) { + // Found it, cancel and clear the table entry + entry->token = INVALID_DEFERRED_TOKEN; + entry->trigger_time = 0; + entry->callback = NULL; + entry->cb_arg = NULL; + return true; + } + } + + // Not found + return false; +} + +void deferred_exec_task(void) { + uint32_t now = timer_read32(); + + // Throttle only once per millisecond + if (((int32_t)TIMER_DIFF_32(now, last_deferred_exec_check)) > 0) { + last_deferred_exec_check = now; + + // Run through each of the executors + for (int i = 0; i < MAX_DEFERRED_EXECUTORS; ++i) { + deferred_executor_t *entry = &executors[i]; + + // Check if we're supposed to execute this entry + if (entry->token != INVALID_DEFERRED_TOKEN && ((int32_t)TIMER_DIFF_32(entry->trigger_time, now)) <= 0) { + // Invoke the callback and work work out if we should be requeued + uint32_t delay_ms = entry->callback(entry->trigger_time, entry->cb_arg); + + // Update the trigger time if we have to repeat, otherwise clear it out + if (delay_ms > 0) { + // Intentionally add just the delay to the existing trigger time -- this ensures the next + // invocation is with respect to the previous trigger, rather than when it got to execution. Under + // normal circumstances this won't cause issue, but if another executor is invoked that takes a + // considerable length of time, then this ensures best-effort timing between invocations. + entry->trigger_time += delay_ms; + } else { + // If it was zero, then the callback is cancelling repeated execution. Free up the slot. + entry->token = INVALID_DEFERRED_TOKEN; + entry->trigger_time = 0; + entry->callback = NULL; + entry->cb_arg = NULL; + } + } + } + } +} diff --git a/quantum/deferred_exec.h b/quantum/deferred_exec.h new file mode 100644 index 00000000000..f80d353169b --- /dev/null +++ b/quantum/deferred_exec.h @@ -0,0 +1,38 @@ +// Copyright 2021 Nick Brassel (@tzarc) +// SPDX-License-Identifier: GPL-2.0-or-later + +#pragma once + +#include +#include + +// A token that can be used to cancel an existing deferred execution. +typedef uint8_t deferred_token; +#define INVALID_DEFERRED_TOKEN 0 + +// Callback to execute. +// -- Parameter trigger_time: the intended trigger time to execute the callback -- equivalent time-space as timer_read32() +// cb_arg: the callback argument specified when enqueueing the deferred executor +// -- Return value: Non-zero re-queues the callback to execute after the returned number of milliseconds. Zero cancels repeated execution. +typedef uint32_t (*deferred_exec_callback)(uint32_t trigger_time, void *cb_arg); + +// Configures the supplied deferred executor to be executed after the required number of milliseconds. +// -- Parameter delay_ms: the number of milliseconds before executing the callback +// -- callback: the executor to invoke +// -- cb_arg: the argument to pass to the executor, may be NULL if unused by the executor +// -- Return value: a token usable for cancellation, or INVALID_DEFERRED_TOKEN if an error occurred +deferred_token defer_exec(uint32_t delay_ms, deferred_exec_callback callback, void *cb_arg); + +// Allows for extending the timeframe before an existing deferred execution is invoked. +// -- Parameter token: the returned value from defer_exec for the deferred execution you wish to extend. +// -- delay_ms: the new delay (with respect to the current time) +// -- Return value: if the token was found, and the delay was extended +bool extend_deferred_exec(deferred_token token, uint32_t delay_ms); + +// Allows for cancellation of an existing deferred execution. +// -- Parameter token: the returned value from defer_exec for the deferred execution you wish to cancel. +// -- Return value: if the token was found, and the executor was cancelled +bool cancel_deferred_exec(deferred_token token); + +// Forward declaration for the main loop in order to execute any deferred executors. Should not be invoked by keyboard/user code. +void deferred_exec_task(void); diff --git a/quantum/main.c b/quantum/main.c index 3814d371c12..6ed6b95741d 100644 --- a/quantum/main.c +++ b/quantum/main.c @@ -43,6 +43,10 @@ void protocol_task(void) { protocol_post_task(); } +#ifdef DEFERRED_EXEC_ENABLE +void deferred_exec_task(void); +#endif // DEFERRED_EXEC_ENABLE + /** \brief Main * * FIXME: Needs doc @@ -58,6 +62,12 @@ int main(void) { /* Main loop */ while (true) { protocol_task(); + +#ifdef DEFERRED_EXEC_ENABLE + // Run deferred executions + deferred_exec_task(); +#endif // DEFERRED_EXEC_ENABLE + housekeeping_task(); } } diff --git a/quantum/quantum.h b/quantum/quantum.h index e6015adbe9f..b34ff6ec51b 100644 --- a/quantum/quantum.h +++ b/quantum/quantum.h @@ -54,6 +54,10 @@ #include #include +#ifdef DEFERRED_EXEC_ENABLE +# include "deferred_exec.h" +#endif + extern layer_state_t default_layer_state; #ifndef NO_ACTION_LAYER diff --git a/tmk_core/protocol/arm_atsam/main_arm_atsam.c b/tmk_core/protocol/arm_atsam/main_arm_atsam.c index 1df5112ed8a..de12821a747 100644 --- a/tmk_core/protocol/arm_atsam/main_arm_atsam.c +++ b/tmk_core/protocol/arm_atsam/main_arm_atsam.c @@ -40,6 +40,10 @@ void send_mouse(report_mouse_t *report); void send_system(uint16_t data); void send_consumer(uint16_t data); +#ifdef DEFERRED_EXEC_ENABLE +void deferred_exec_task(void); +#endif // DEFERRED_EXEC_ENABLE + host_driver_t arm_atsam_driver = {keyboard_leds, send_keyboard, send_mouse, send_system, send_consumer}; uint8_t led_states; @@ -360,6 +364,11 @@ int main(void) { } #endif // CONSOLE_ENABLE +#ifdef DEFERRED_EXEC_ENABLE + // Run deferred executions + deferred_exec_task(); +#endif // DEFERRED_EXEC_ENABLE + // Run housekeeping housekeeping_task(); }