e63b0bb3fe
With the incoming removal of kernel.h/types.h from init.h, lots of files start to show compile errors because they relied on indirect definitions, including errno.h. Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
305 lines
8.6 KiB
C
305 lines
8.6 KiB
C
/* clock_control.h - public clock controller driver API */
|
|
|
|
/*
|
|
* Copyright (c) 2015 Intel Corporation
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
/**
|
|
* @file
|
|
* @brief Public Clock Control APIs
|
|
*/
|
|
|
|
#ifndef ZEPHYR_INCLUDE_DRIVERS_CLOCK_CONTROL_H_
|
|
#define ZEPHYR_INCLUDE_DRIVERS_CLOCK_CONTROL_H_
|
|
|
|
/**
|
|
* @brief Clock Control Interface
|
|
* @defgroup clock_control_interface Clock Control Interface
|
|
* @ingroup io_interfaces
|
|
* @{
|
|
*/
|
|
|
|
#include <errno.h>
|
|
#include <stddef.h>
|
|
|
|
#include <zephyr/types.h>
|
|
#include <zephyr/device.h>
|
|
#include <zephyr/sys/__assert.h>
|
|
#include <zephyr/sys/slist.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* Clock control API */
|
|
|
|
/* Used to select all subsystem of a clock controller */
|
|
#define CLOCK_CONTROL_SUBSYS_ALL NULL
|
|
|
|
/**
|
|
* @brief Current clock status.
|
|
*/
|
|
enum clock_control_status {
|
|
CLOCK_CONTROL_STATUS_STARTING,
|
|
CLOCK_CONTROL_STATUS_OFF,
|
|
CLOCK_CONTROL_STATUS_ON,
|
|
CLOCK_CONTROL_STATUS_UNKNOWN
|
|
};
|
|
|
|
/**
|
|
* clock_control_subsys_t is a type to identify a clock controller sub-system.
|
|
* Such data pointed is opaque and relevant only to the clock controller
|
|
* driver instance being used.
|
|
*/
|
|
typedef void *clock_control_subsys_t;
|
|
|
|
/**
|
|
* clock_control_subsys_rate_t is a type to identify a clock
|
|
* controller sub-system rate. Such data pointed is opaque and
|
|
* relevant only to set the clock controller rate of the driver
|
|
* instance being used.
|
|
*/
|
|
typedef void *clock_control_subsys_rate_t;
|
|
|
|
/** @brief Callback called on clock started.
|
|
*
|
|
* @param dev Device structure whose driver controls the clock.
|
|
* @param subsys Opaque data representing the clock.
|
|
* @param user_data User data.
|
|
*/
|
|
typedef void (*clock_control_cb_t)(const struct device *dev,
|
|
clock_control_subsys_t subsys,
|
|
void *user_data);
|
|
|
|
typedef int (*clock_control)(const struct device *dev,
|
|
clock_control_subsys_t sys);
|
|
|
|
typedef int (*clock_control_get)(const struct device *dev,
|
|
clock_control_subsys_t sys,
|
|
uint32_t *rate);
|
|
|
|
typedef int (*clock_control_async_on_fn)(const struct device *dev,
|
|
clock_control_subsys_t sys,
|
|
clock_control_cb_t cb,
|
|
void *user_data);
|
|
|
|
typedef enum clock_control_status (*clock_control_get_status_fn)(
|
|
const struct device *dev,
|
|
clock_control_subsys_t sys);
|
|
|
|
typedef int (*clock_control_set)(const struct device *dev,
|
|
clock_control_subsys_t sys,
|
|
clock_control_subsys_rate_t rate);
|
|
|
|
typedef int (*clock_control_configure_fn)(const struct device *dev,
|
|
clock_control_subsys_t sys,
|
|
void *data);
|
|
|
|
struct clock_control_driver_api {
|
|
clock_control on;
|
|
clock_control off;
|
|
clock_control_async_on_fn async_on;
|
|
clock_control_get get_rate;
|
|
clock_control_get_status_fn get_status;
|
|
clock_control_set set_rate;
|
|
clock_control_configure_fn configure;
|
|
};
|
|
|
|
/**
|
|
* @brief Enable a clock controlled by the device
|
|
*
|
|
* On success, the clock is enabled and ready when this function
|
|
* returns. This function may sleep, and thus can only be called from
|
|
* thread context.
|
|
*
|
|
* Use @ref clock_control_async_on() for non-blocking operation.
|
|
*
|
|
* @param dev Device structure whose driver controls the clock.
|
|
* @param sys Opaque data representing the clock.
|
|
* @return 0 on success, negative errno on failure.
|
|
*/
|
|
static inline int clock_control_on(const struct device *dev,
|
|
clock_control_subsys_t sys)
|
|
{
|
|
const struct clock_control_driver_api *api =
|
|
(const struct clock_control_driver_api *)dev->api;
|
|
|
|
return api->on(dev, sys);
|
|
}
|
|
|
|
/**
|
|
* @brief Disable a clock controlled by the device
|
|
*
|
|
* This function is non-blocking and can be called from any context.
|
|
* On success, the clock is disabled when this function returns.
|
|
*
|
|
* @param dev Device structure whose driver controls the clock
|
|
* @param sys Opaque data representing the clock
|
|
* @return 0 on success, negative errno on failure.
|
|
*/
|
|
static inline int clock_control_off(const struct device *dev,
|
|
clock_control_subsys_t sys)
|
|
{
|
|
const struct clock_control_driver_api *api =
|
|
(const struct clock_control_driver_api *)dev->api;
|
|
|
|
return api->off(dev, sys);
|
|
}
|
|
|
|
/**
|
|
* @brief Request clock to start with notification when clock has been started.
|
|
*
|
|
* Function is non-blocking and can be called from any context. User callback is
|
|
* called when clock is started.
|
|
*
|
|
* @param dev Device.
|
|
* @param sys A pointer to an opaque data representing the sub-system.
|
|
* @param cb Callback.
|
|
* @param user_data User context passed to the callback.
|
|
*
|
|
* @retval 0 if start is successfully initiated.
|
|
* @retval -EALREADY if clock was already started and is starting or running.
|
|
* @retval -ENOTSUP If the requested mode of operation is not supported.
|
|
* @retval -ENOSYS if the interface is not implemented.
|
|
* @retval other negative errno on vendor specific error.
|
|
*/
|
|
static inline int clock_control_async_on(const struct device *dev,
|
|
clock_control_subsys_t sys,
|
|
clock_control_cb_t cb,
|
|
void *user_data)
|
|
{
|
|
const struct clock_control_driver_api *api =
|
|
(const struct clock_control_driver_api *)dev->api;
|
|
|
|
if (api->async_on == NULL) {
|
|
return -ENOSYS;
|
|
}
|
|
|
|
return api->async_on(dev, sys, cb, user_data);
|
|
}
|
|
|
|
/**
|
|
* @brief Get clock status.
|
|
*
|
|
* @param dev Device.
|
|
* @param sys A pointer to an opaque data representing the sub-system.
|
|
*
|
|
* @return Status.
|
|
*/
|
|
static inline enum clock_control_status clock_control_get_status(const struct device *dev,
|
|
clock_control_subsys_t sys)
|
|
{
|
|
const struct clock_control_driver_api *api =
|
|
(const struct clock_control_driver_api *)dev->api;
|
|
|
|
if (!api->get_status) {
|
|
return CLOCK_CONTROL_STATUS_UNKNOWN;
|
|
}
|
|
|
|
return api->get_status(dev, sys);
|
|
}
|
|
|
|
/**
|
|
* @brief Obtain the clock rate of given sub-system
|
|
* @param dev Pointer to the device structure for the clock controller driver
|
|
* instance
|
|
* @param sys A pointer to an opaque data representing the sub-system
|
|
* @param[out] rate Subsystem clock rate
|
|
* @retval 0 on successful rate reading.
|
|
* @retval -EAGAIN if rate cannot be read. Some drivers do not support returning the rate when the
|
|
* clock is off.
|
|
* @retval -ENOTSUP if reading the clock rate is not supported for the given sub-system.
|
|
* @retval -ENOSYS if the interface is not implemented.
|
|
*/
|
|
static inline int clock_control_get_rate(const struct device *dev,
|
|
clock_control_subsys_t sys,
|
|
uint32_t *rate)
|
|
{
|
|
const struct clock_control_driver_api *api =
|
|
(const struct clock_control_driver_api *)dev->api;
|
|
|
|
if (api->get_rate == NULL) {
|
|
return -ENOSYS;
|
|
}
|
|
|
|
return api->get_rate(dev, sys, rate);
|
|
}
|
|
|
|
/**
|
|
* @brief Set the rate of the clock controlled by the device.
|
|
*
|
|
* On success, the new clock rate is set and ready when this function
|
|
* returns. This function may sleep, and thus can only be called from
|
|
* thread context.
|
|
*
|
|
* @param dev Device structure whose driver controls the clock.
|
|
* @param sys Opaque data representing the clock.
|
|
* @param rate Opaque data representing the clock rate to be used.
|
|
*
|
|
* @retval -EALREADY if clock was already in the given rate.
|
|
* @retval -ENOTSUP If the requested mode of operation is not supported.
|
|
* @retval -ENOSYS if the interface is not implemented.
|
|
* @retval other negative errno on vendor specific error.
|
|
*/
|
|
static inline int clock_control_set_rate(const struct device *dev,
|
|
clock_control_subsys_t sys,
|
|
clock_control_subsys_rate_t rate)
|
|
{
|
|
const struct clock_control_driver_api *api =
|
|
(const struct clock_control_driver_api *)dev->api;
|
|
|
|
if (api->set_rate == NULL) {
|
|
return -ENOSYS;
|
|
}
|
|
|
|
return api->set_rate(dev, sys, rate);
|
|
}
|
|
|
|
/**
|
|
* @brief Configure a source clock
|
|
*
|
|
* This function is non-blocking and can be called from any context.
|
|
* On success, the selected clock is configured as per caller's request.
|
|
*
|
|
* It is caller's responsibility to ensure that subsequent calls to the API
|
|
* provide the right information to allows clock_control driver to perform
|
|
* the right action (such as using the right clock source on clock_control_get_rate
|
|
* call).
|
|
*
|
|
* @p data is implementation specific and could be used to convey
|
|
* supplementary information required for expected clock configuration.
|
|
*
|
|
* @param dev Device structure whose driver controls the clock
|
|
* @param sys Opaque data representing the clock
|
|
* @param data Opaque data providing additional input for clock configuration
|
|
*
|
|
* @retval 0 On success
|
|
* @retval -ENOSYS If the device driver does not implement this call
|
|
* @retval -errno Other negative errno on failure.
|
|
*/
|
|
static inline int clock_control_configure(const struct device *dev,
|
|
clock_control_subsys_t sys,
|
|
void *data)
|
|
{
|
|
const struct clock_control_driver_api *api =
|
|
(const struct clock_control_driver_api *)dev->api;
|
|
|
|
if (api->configure == NULL) {
|
|
return -ENOSYS;
|
|
}
|
|
|
|
return api->configure(dev, sys, data);
|
|
}
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
/**
|
|
* @}
|
|
*/
|
|
|
|
#endif /* ZEPHYR_INCLUDE_DRIVERS_CLOCK_CONTROL_H_ */
|