lib: sys: queued_operation: add API for managing a queue of operations

Full asynchronous support for APIs such as bus transactions generally
require managing operations from unrelated clients.  This API provides
a data structure and functions to manage those operations generically,
leaving the service to provide only the service-specific operation
description and implementation.

Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>

Author: pabigot

doc/reference/kernel/other/resource_mgmt.rst

@@ -10,19 +10,24 @@ complexity of properly managing multiple consumers of a device in a
 multithreaded system, especially when transitions may be asynchronous,
 suggests that a shared implementation is desirable.
 
+Zephyr provides managers for several coordination policies.  These
+managers are embedded into services that use them for specific
+functions.
+
 .. contents::
     :local:
     :depth: 2
 
+.. _resource_mgmt_onoff:
 
-On-Off Services
-***************
+On-Off Manager
+**************
 
-An on-off service supports an arbitrary number of clients of a service
+An on-off manager supports an arbitrary number of clients of a service
 which has a binary state.  Example applications are power rails, clocks,
 and binary device power management.
 
-The service has the following properties:
+The manager has the following properties:
 
 * The stable states are off, on, and error.  The service always begins
   in the off state.  The service may also be in a transition to a given
@@ -56,15 +61,15 @@ Requests are reference counted, but not tracked. That means clients are
 responsible for recording whether their requests were accepted, and for
 initiating a release only if they have previously successfully completed
 a request.  Improper use of the API can cause an active client to be
-shut out, and the service does not maintain a record of specific clients
+shut out, and the manager does not maintain a record of specific clients
 that have been granted a request.
 
 Failures in executing a transition are recorded and inhibit further
-requests or releases until the service is reset. Pending requests are
+requests or releases until the manager is reset. Pending requests are
 notified (and cancelled) when errors are discovered.
 
-Transition operation completion notifications are provided through any
-of the following mechanisms:
+Transition operation completion notifications are provided through the
+standard :ref:`async_notification`, supporting these methods:
 
 * Signal: A pointer to a :c:type:`struct k_poll_signal` is provided, and
   the signal is raised when the transition completes. The operation
@@ -79,5 +84,63 @@ Synchronous transition may be implemented by a caller based on its
 context, for example by using :cpp:func:`k_poll()` to wait until the
 completion is signalled.
 
-.. doxygengroup:: resource_mgmt_apis
+.. doxygengroup:: resource_mgmt_onoff_apis
+   :project: Zephyr
+
+.. _resource_mgmt_queued_operation:
+
+Queued Operation Manager
+************************
+
+While :ref:`resource_mgmt_onoff` supports a shared resource that must be
+available as long as any user still depends on it, the queued operation
+manager provides serialized exclusive access to a resource that executes
+operations asynchronously.  This can be used to support (for example)
+ADC sampling for different sensors, or groups of bus transactions.
+Clients submit a operation request that is processed when the device
+becomes available, with clients being notified of the completion of the
+operation though the standard :ref:`async_notification`.
+
+As with the on-off manager, the queued resource manager is a generic
+infrastructure tool that should be used by a extending service, such as
+an I2C bus controller or an ADC.  The manager has the following
+characteristics:
+
+* The stable states are idle and processing.  The manager always begins
+  in the idle state.
+* The core client operations are submit (add an operation) and cancel
+  (remove an operation before it starts).
+* Ownership of the operation object transitions from the client to the
+  manager when a queue request is accepted, and is returned to the
+  client when the manager notifies the client of operation completion.
+* The core client event is completion.  Manager state changes only as a
+  side effect from submitting or completing an operation.
+* The service transitions from idle to processing when an operation is
+  submitted.
+* The service transitions from processing to idle when notification of
+  the last operation has completed and there are no queued operations.
+* The manager selects the next operation to process when notification of
+  completion has itself completed.  In particular, changes to the set of
+  pending operations that are made during a completion callback affect
+  the next operation to execute.
+* Each submitted operation includes a priority that orders execution by
+  first-come-first-served within priority.
+* Operations are asynchronous, with completion notification through the
+  :ref:`async_notification`.  The operations and notifications are run
+  in a context that is service-specific.  This may be one or more
+  dedicated threads, or work queues.  Notifications may come from
+  interrupt handlers.  Note that for some services certain operations
+  may complete before the submit request has returned to its caller.
+
+The generic infrastructure holds the active operation and a queue of
+pending operations.  A service extension shall provide functions that:
+
+* check that a request is well-formed, i.e. can be added to the queue;
+* receive notification that a new operation is to be processed, or that
+  no operations are available (allowing the service to enter a
+  power-down mode);
+* translate a generic completion callback into a service-specific
+  callback.
+
+.. doxygengroup:: resource_mgmt_queued_operation_apis
    :project: Zephyr

include/sys/onoff.h

@@ -16,7 +16,7 @@ extern "C" {
 #endif
 
 /**
- * @defgroup resource_mgmt_apis Resource Management APIs
+ * @defgroup resource_mgmt_onoff_apis On-Off Service APIs
  * @ingroup kernel_apis
  * @{
  */

include/sys/queued_operation.h

@@ -0,0 +1,239 @@
+/*
+ * Copyright (c) 2019 Peter Bigot Consulting, LLC
+ * Copyright (c) 2020 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_SYS_QUEUED_OPERATION_H_
+#define ZEPHYR_INCLUDE_SYS_QUEUED_OPERATION_H_
+
+#include <kernel.h>
+#include <zephyr/types.h>
+#include <sys/async_notify.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Forward declaration */
+struct queued_operation;
+struct queued_operation_manager;
+
+/**
+ * @defgroup resource_mgmt_queued_operation_apis Queued Operation APIs
+ * @ingroup kernel_apis
+ * @{
+ */
+
+/** @internal */
+#define QUEUED_OPERATION_PRIORITY_POS ASYNC_NOTIFY_EXTENSION_POS
+/** @internal */
+#define QUEUED_OPERATION_PRIORITY_MASK 0xFF
+
+/**
+ * @brief Identify the region of async_notify flags available for
+ * containing services.
+ *
+ * Bits of the flags field of the async_notify structure contained
+ * within the queued_operation structure at and above this position
+ * may be used by extensions to the async_notify structure.
+ *
+ * These bits are intended for use by containing service
+ * implementations to record client-specific information.  The bits
+ * are cleared by async_notify_validate().  Use of these does not
+ * imply that the flags field becomes public API.
+ */
+#define QUEUED_OPERATION_EXTENSION_POS (8 + ASYNC_NOTIFY_EXTENSION_POS)
+
+/**
+ * @brief Base object providing state for an operation.
+ *
+ * Instances of this should be members of a service-specific structure
+ * that provides the operation parameters.
+ */
+struct queued_operation {
+	/* Links the operation into the operation queue. */
+	sys_snode_t node;
+
+	/* Notification configuration. */
+	struct async_notify notify;
+};
+
+/**
+ * @ brief Table of functions used by a queued operation manager.
+ */
+struct queued_operation_functions {
+	/**
+	 * @brief Function used to verify an operation is well-defined.
+	 *
+	 * When provided this function is invoked by
+	 * queued_operation_submit() to verify that the operation
+	 * definition meets the expectations of the service.  The
+	 * operation is acceptable only if a non-negative value is
+	 * returned.
+	 *
+	 * If not provided queued_operation_submit() will assume
+	 * service-specific expectations are trivially satisfied, and
+	 * will reject the operation only if the notification
+	 * configuration is unacceptable.
+	 *
+	 * @param mgr the service that supports queued operations.
+	 *
+	 * @param op the operation being considered for suitability.
+	 *
+	 * @return the value to be returned from queued_operation_submit().
+	 */
+	int (*validate)(struct queued_operation_manager *mgr,
+			struct queued_operation *op);
+
+	/**
+	 * @brief Function to transform a generic notification
+	 * callback to its service-specific form.
+	 *
+	 * The implementation should cast cb to the proper signature
+	 * for the service, and invoke the cast pointer with the
+	 * appropriate arguments.
+	 *
+	 * @param mgr the service that supports queued operations.
+	 *
+	 * @param op the operation that has been completed.
+	 *
+	 * @param cb the generic callback to invoke.
+	 */
+	void (*callback)(struct queued_operation_manager *mgr,
+			 struct queued_operation *op,
+			 async_notify_generic_callback cb);
+
+	/**
+	 * @brief Function used to inform the manager of a new operation.
+	 *
+	 * This is called as a side effect of
+	 * queued_operation_submit() or queued_operation_finalize() to
+	 * tell the service that a new operation needs to be
+	 * processed, or that there are no operations left to process.
+	 * The function will not be invoked while an operation is in
+	 * progress.
+	 *
+	 * @param mgr the service that supports queued operations.
+	 *
+	 * @param op the operation that should be initiated.  A null
+	 * pointer is passed if there are no pending operations.
+	 */
+	void (*process)(struct queued_operation_manager *mgr,
+			struct queued_operation *op);
+};
+
+/**
+ * @brief State associated with a manager instance.
+ */
+struct queued_operation_manager {
+	/* Links the operation into the operation queue. */
+	sys_slist_t operations;
+
+	/* Pointer to the functions that support the manager. */
+	const struct queued_operation_functions *vtable;
+
+	/* Lock controlling access to other fields. */
+	struct k_spinlock lock;
+
+	/* The operation that is being processed. */
+	struct queued_operation *current;
+
+	/* A flag indicating that the last operation has been
+	 * completed and the callback notification is being
+	 * executed.
+	 */
+	bool finalizing;
+};
+
+#define QUEUED_OPERATION_MANAGER_INITIALIZER(_vtable) {	\
+		.vtable = _vtable,			\
+}
+
+/**
+ * @brief Submit an operation to be processed when the service is
+ * available.
+ *
+ * During the call to this function the service process function will
+ * have been invoked at least once, either providing another operation
+ * or indicating that no operations are pending.
+ *
+ * @param mgr a generic pointer to the service instance
+ * @param op a generic pointer to an operation to be performed
+ * @param priority the priority of the operation relative to other
+ * operations.  Numerically lower values are higher priority.  Values
+ * outside the range of a signed 8-bit integer will be rejected.
+ *
+ * @retval -ENOTSUP if callback notification is requested and the
+ * service does not provide a callback translation.  This may also be
+ * returned due to service-specific validation.
+ *
+ * @retval -EINVAL if the passed priority is out of the range of
+ * supported priorities.  This may also be returned due to
+ * service-specific validation.
+ *
+ * @return A negative value if the operation was rejected by the
+ * service or due to other configuration errors.  A non-negative value
+ * indicates the operation has been accepted for processing and
+ * completion notification will be provided.
+ */
+int queued_operation_submit(struct queued_operation_manager *mgr,
+			    struct queued_operation *op,
+			    int priority);
+
+/**
+ * @brief Helper to extract the result from a queued operation.
+ *
+ * This forwards to :cpp:func:`async_notify_fetch_result()`.
+ */
+static inline int queued_operation_fetch_result(struct queued_operation *op,
+						int *result)
+{
+	return async_notify_fetch_result(&op->notify, result);
+}
+
+/**
+ * @brief Attempt to cancel a queued operation.
+ *
+ * Successful cancellation issues a completion notification with
+ * result -ECANCELED for the submitted operation before this function
+ * returns.
+ *
+ * @retval 0 if successfully cancelled.
+ * @retval -EINPROGRESS if op is currently being executed, so cannot
+ * be cancelled.
+ * @retval -EINVAL if op is neither being executed nor in the queue of
+ * pending operations
+ */
+int queued_operation_cancel(struct queued_operation_manager *mgr,
+			    struct queued_operation *op);
+
+/**
+ * @brief Send the completion notification for a queued operation.
+ *
+ * This function must be invoked by services that support queued
+ * operations when the operation provided to them through the process
+ * function have been completed.  It is not intended to be invoked by
+ * users of a service.
+ *
+ * During the call to this function the service process function will
+ * be invoked at least once, either providing another operation or
+ * indicating that no operations are pending.
+ *
+ * @param mgr a generic pointer to the service instance
+ * @param op a generic pointer to the now completed operation
+ * @param res the result of the operation, as with
+ * async_notify_finalize().
+ */
+void queued_operation_finalize(struct queued_operation_manager *mgr,
+			       struct queued_operation *op,
+			       int res);
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ZEPHYR_INCLUDE_SYS_ASYNCNOTIFY_H_ */

lib/os/CMakeLists.txt

@@ -14,6 +14,7 @@ zephyr_sources(
   mempool.c
   printk.c
   onoff.c
+  queued_operation.c
   rb.c
   sem.c
   thread_entry.c