Lines Matching +full:force +full:- +full:off
5 * SPDX-License-Identifier: Apache-2.0
20 * @defgroup resource_mgmt_onoff_apis On-Off Service APIs
50 * @brief Value exposed by ONOFF_STATE_MASK when service is off.
73 * transitioning to off.
88 * @brief Signature used to notify an on-off manager that a transition
91 * Functions of this type are passed to service-specific transition
98 * non-negative on success, or a negative error code. If an error is
112 * The start function will be called only from the off state.
119 * @note All transitions functions must be isr-ok.
132 /** @brief On-off service transition functions. */
137 /** Function to invoke to transition the service to off. */
140 /** Function to force the service state to reset, where
147 * @brief State associated with an on-off manager.
183 * @param _start a function used to transition from off to on state.
185 * @param _stop a function used to transition from on to off state.
187 * @param _reset a function used to clear errors and force the service
188 * to an off state. Can be null.
203 * @brief Initialize an on-off service to off state.
207 * on-off service API is invoked on the service.
209 * This function should never be invoked by clients of an on-off
219 * @retval -EINVAL if start, stop, or flags are invalid
228 * @brief Signature used to notify an on-off service client of the
232 * pre-kernel, ISR, or cooperative or pre-emptible threads.
233 * Compatible functions must be isr-ok and not sleep.
236 * null if the on-off service uses synchronous transitions.
247 * service-specific, but the value shall be non-negative if the
250 * non-negative ONOFF_FLAG_ERROR may still be set in state.
258 * @brief State associated with a client of an on-off service.
261 * responsible for zero-initializing the node field and invoking the
265 * when a pointer to the object is passed to any on-off manager
278 * Applications must ensure this field is zero-initialized
297 * implementations to record client-specific information and are
303 * @brief Test whether an on-off service has recorded an error.
311 * transitions the service between an error and non-error state.
317 return (mgr->flags & ONOFF_FLAG_ERROR) != 0; in onoff_has_error()
321 * @brief Request a reservation to use an on-off service.
335 * @param cli a non-null pointer to client state providing
341 * @retval non-negative the observed state of the machine at the time
343 * @retval -EIO if service has recorded an error.
344 * @retval -EINVAL if the parameters are invalid.
345 * @retval -EAGAIN if the reference count would overflow.
351 * @brief Release a reserved use of an on-off service.
355 * off, which can be observed by registering an onoff_monitor.
362 * @retval non-negative the observed state (ONOFF_STATE_ON) of the
364 * @retval -EIO if service has recorded an error.
365 * @retval -ENOTSUP if the machine is not in a state that permits
371 * @brief Attempt to cancel an in-progress client operation.
383 * transition to off.
392 * @retval non-negative the observed state of the machine at the time
395 * @retval -EINVAL if the parameters are invalid.
396 * @retval -EALREADY if cli was not a record of an uncompleted
410 * cannot precisely determine that an in-progress request is still
431 * @retval -EINVAL if the parameters are invalid.
440 if (rv == -EALREADY) { in onoff_cancel_or_release()
447 * @brief Clear errors on an on-off service and reset it to its off
475 * @retval non-negative the observed state of the machine at the time
477 * @retval -ENOTSUP if reset is not supported by the service.
478 * @retval -EINVAL if the parameters are invalid.
479 * @retval -EALREADY if the service does not have a recorded error.
494 * pre-kernel, ISR, or cooperative or pre-emptible threads.
495 * Compatible functions must be isr-ok and not sleep.
509 * service- and state-specific, but the value shall be non-negative if
527 * This must be zero-initialized.
543 * @param mon a linkable node providing a non-null callback to be
546 * @return non-negative on successful addition, or a negative error
560 * @return non-negative on successful removal, or a negative error
567 * @brief State used when a driver uses the on-off service API for synchronous
570 * This is useful when a subsystem API uses the on-off API to support
572 * particular driver are isr-ok and not sleep. It serves as a
580 /** Negative is error, non-negative is reference count. */
589 * the error (finalize with a non-error result).
611 * If the service was in an error state when locked, and @p res is non-negative
623 * turning off devices).
626 * into an error state. A non-negative value increments or decrements the
629 * @param on Only when @p res is non-negative, the service reference count will