1 /* clock_control.h - public clock controller driver API */
6  * SPDX-License-Identifier: Apache-2.0
11  * @brief Public Clock Control APIs
18  * @brief Clock Control Interface
19  * @defgroup clock_control_interface Clock Control Interface
38 /* Clock control API */
40 /* Used to select all subsystem of a clock controller */
44  * @brief Current clock status.
54  * clock_control_subsys_t is a type to identify a clock controller sub-system.
55  * Such data pointed is opaque and relevant only to the clock controller
61  * clock_control_subsys_rate_t is a type to identify a clock
62  * controller sub-system rate.  Such data pointed is opaque and
63  * relevant only to set the clock controller rate of the driver
68 /** @brief Callback called on clock started.
70  * @param dev		Device structure whose driver controls the clock.
71  * @param subsys	Opaque data representing the clock.
83 				 uint32_t *rate);
96 				 clock_control_subsys_rate_t rate);
113  * @brief Enable a clock controlled by the device
115  * On success, the clock is enabled and ready when this function
119  * Use @ref clock_control_async_on() for non-blocking operation.
121  * @param dev Device structure whose driver controls the clock.
122  * @param sys Opaque data representing the clock.
129 		(const struct clock_control_driver_api *)dev->api;  in clock_control_on()
131 	return api->on(dev, sys);  in clock_control_on()
135  * @brief Disable a clock controlled by the device
137  * This function is non-blocking and can be called from any context.
138  * On success, the clock is disabled when this function returns.
140  * @param dev Device structure whose driver controls the clock
141  * @param sys Opaque data representing the clock
148 		(const struct clock_control_driver_api *)dev->api;  in clock_control_off()
150 	return api->off(dev, sys);  in clock_control_off()
154  * @brief Request clock to start with notification when clock has been started.
156  * Function is non-blocking and can be called from any context. User callback is
157  * called when clock is started.
160  * @param sys	    A pointer to an opaque data representing the sub-system.
165  * @retval -EALREADY if clock was already started and is starting or running.
166  * @retval -ENOTSUP If the requested mode of operation is not supported.
167  * @retval -ENOSYS if the interface is not implemented.
176 		(const struct clock_control_driver_api *)dev->api;  in clock_control_async_on()
178 	if (api->async_on == NULL) {  in clock_control_async_on()
179 		return -ENOSYS;  in clock_control_async_on()
182 	return api->async_on(dev, sys, cb, user_data);  in clock_control_async_on()
186  * @brief Get clock status.
189  * @param sys A pointer to an opaque data representing the sub-system.
197 		(const struct clock_control_driver_api *)dev->api;  in clock_control_get_status()
199 	if (!api->get_status) {  in clock_control_get_status()
203 	return api->get_status(dev, sys);  in clock_control_get_status()
207  * @brief Obtain the clock rate of given sub-system
208  * @param dev Pointer to the device structure for the clock controller driver
210  * @param sys A pointer to an opaque data representing the sub-system
211  * @param[out] rate Subsystem clock rate
212  * @retval 0 on successful rate reading.
213  * @retval -EAGAIN if rate cannot be read. Some drivers do not support returning the rate when the
214  *         clock is off.
215  * @retval -ENOTSUP if reading the clock rate is not supported for the given sub-system.
216  * @retval -ENOSYS if the interface is not implemented.
220 					 uint32_t *rate)  in clock_control_get_rate()  argument
223 		(const struct clock_control_driver_api *)dev->api;  in clock_control_get_rate()
225 	if (api->get_rate == NULL) {  in clock_control_get_rate()
226 		return -ENOSYS;  in clock_control_get_rate()
229 	return api->get_rate(dev, sys, rate);  in clock_control_get_rate()
233  * @brief Set the rate of the clock controlled by the device.
235  * On success, the new clock rate is set and ready when this function
239  * @param dev Device structure whose driver controls the clock.
240  * @param sys Opaque data representing the clock.
241  * @param rate Opaque data representing the clock rate to be used.
243  * @retval -EALREADY if clock was already in the given rate.
244  * @retval -ENOTSUP If the requested mode of operation is not supported.
245  * @retval -ENOSYS if the interface is not implemented.
250 		clock_control_subsys_rate_t rate)  in clock_control_set_rate()  argument
253 		(const struct clock_control_driver_api *)dev->api;  in clock_control_set_rate()
255 	if (api->set_rate == NULL) {  in clock_control_set_rate()
256 		return -ENOSYS;  in clock_control_set_rate()
259 	return api->set_rate(dev, sys, rate);  in clock_control_set_rate()
263  * @brief Configure a source clock
265  * This function is non-blocking and can be called from any context.
266  * On success, the selected clock is configured as per caller's request.
270  * the right action (such as using the right clock source on clock_control_get_rate
274  * supplementary information required for expected clock configuration.
276  * @param dev Device structure whose driver controls the clock
277  * @param sys Opaque data representing the clock
278  * @param data Opaque data providing additional input for clock configuration
281  * @retval -ENOSYS If the device driver does not implement this call
282  * @retval -errno Other negative errno on failure.
289 		(const struct clock_control_driver_api *)dev->api;  in clock_control_configure()
291 	if (api->configure == NULL) {  in clock_control_configure()
292 		return -ENOSYS;  in clock_control_configure()
295 	return api->configure(dev, sys, data);  in clock_control_configure()