cleanup: include/: move clock_control.h to drivers/clock_control.h

move clock_control.h to drivers/clock_control.h and
create a shim for backward-compatibility.

No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.

Related to #16539

Signed-off-by: Anas Nashif <anas.nashif@intel.com>

drivers/can/can_mcux_flexcan.c

@@ -7,7 +7,7 @@
 #include <zephyr.h>
 #include <sys/atomic.h>
 #include <drivers/can.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <device.h>
 #include <misc/byteorder.h>
 #include <fsl_flexcan.h>

drivers/can/can_stm32.c

@@ -5,7 +5,7 @@
  */
 
 #include <clock_control/stm32_clock_control.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 #include <string.h>
 #include <kernel.h>

drivers/clock_control/beetle_clock_control.c

@@ -13,7 +13,7 @@
  */
 
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 #include <clock_control/arm_clock_control.h>
 

drivers/clock_control/clock_control_mcux_ccm.c

@@ -5,7 +5,7 @@
  */
 #include <errno.h>
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <dt-bindings/clock/imx_ccm.h>
 #include <fsl_clock.h>
 

drivers/clock_control/clock_control_mcux_pcc.c

@@ -9,7 +9,7 @@
 
 #include <errno.h>
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <fsl_clock.h>
 
 #define LOG_LEVEL CONFIG_CLOCK_CONTROL_LOG_LEVEL

drivers/clock_control/clock_control_mcux_scg.c

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <dt-bindings/clock/kinetis_scg.h>
 #include <soc.h>
 #include <fsl_clock.h>

drivers/clock_control/clock_control_mcux_sim.c

@@ -5,7 +5,7 @@
  */
 #include <errno.h>
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <dt-bindings/clock/kinetis_sim.h>
 #include <fsl_clock.h>
 

drivers/clock_control/clock_control_rv32m1_pcc.c

@@ -5,7 +5,7 @@
  */
 #include <errno.h>
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <fsl_clock.h>
 
 #define LOG_LEVEL CONFIG_CLOCK_CONTROL_LOG_LEVEL

drivers/clock_control/clock_stm32_ll_common.c

@@ -7,7 +7,7 @@
  */
 
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 #include <clock_control/stm32_clock_control.h>
 #include "clock_stm32_ll_common.h"

drivers/clock_control/clock_stm32_ll_mp1.c

@@ -5,7 +5,7 @@
  */
 
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 #include <clock_control/stm32_clock_control.h>
 

drivers/clock_control/clock_stm32f0_f3.c

@@ -7,7 +7,7 @@
 
 
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 #include <clock_control/stm32_clock_control.h>
 #include "clock_stm32_ll_common.h"

drivers/clock_control/clock_stm32f1.c

@@ -7,7 +7,7 @@
 
 
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 #include <clock_control/stm32_clock_control.h>
 #include "clock_stm32_ll_common.h"

drivers/clock_control/clock_stm32f2_f4_f7.c

@@ -7,7 +7,7 @@
 
 
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 #include <clock_control/stm32_clock_control.h>
 #include "clock_stm32_ll_common.h"

drivers/clock_control/clock_stm32l0_l1.c

@@ -7,7 +7,7 @@
 
 
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 #include <clock_control/stm32_clock_control.h>
 #include "clock_stm32_ll_common.h"

drivers/clock_control/clock_stm32l4_wb.c

@@ -7,7 +7,7 @@
 
 
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 #include <clock_control/stm32_clock_control.h>
 #include "clock_stm32_ll_common.h"

drivers/clock_control/nrf_power_clock.c

@@ -9,7 +9,7 @@
 #include <errno.h>
 #include <sys/atomic.h>
 #include <device.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/__assert.h>
 #include <nrf_clock.h>
 #if defined(CONFIG_USB) && defined(CONFIG_SOC_NRF52840)

drivers/clock_control/quark_se_clock_control.c

@@ -16,7 +16,7 @@
 
 #include <sys/sys_io.h>
 
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <clock_control/quark_se_clock_control.h>
 
 #define LOG_LEVEL CONFIG_CLOCK_CONTROL_LOG_LEVEL

drivers/counter/counter_ll_stm32_rtc.c

@@ -12,7 +12,7 @@
 #include <time.h>
 
 #include <clock_control/stm32_clock_control.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 #include <kernel.h>
 #include <soc.h>

drivers/counter/counter_nrfx_rtc.c

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 #include <counter.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <drivers/clock_control/nrf_clock_control.h>
 #include <nrfx_rtc.h>
 #ifdef DPPI_PRESENT

drivers/entropy/entropy_stm32.c

@@ -14,7 +14,7 @@
 #include <errno.h>
 #include <soc.h>
 #include <misc/printk.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <clock_control/stm32_clock_control.h>
 
 #if !defined(CONFIG_SOC_SERIES_STM32L4X) && !defined(CONFIG_SOC_SERIES_STM32F4X) && !defined(CONFIG_SOC_SERIES_STM32F7X)

drivers/ethernet/eth_stm32_hal.c

@@ -21,7 +21,7 @@ LOG_MODULE_REGISTER(LOG_MODULE_NAME);
 #include <ethernet/eth_stats.h>
 #include <soc.h>
 #include <misc/printk.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <clock_control/stm32_clock_control.h>
 
 #include "eth_stm32_hal_priv.h"

drivers/flash/flash_stm32.h

@@ -13,7 +13,7 @@
 #if defined(CONFIG_SOC_SERIES_STM32L4X) || \
 	defined(CONFIG_SOC_SERIES_STM32F0X) || \
 	defined(CONFIG_SOC_SERIES_STM32F3X)
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <clock_control/stm32_clock_control.h>
 #endif
 

drivers/gpio/gpio_dw.c

@@ -16,7 +16,7 @@
 #include <init.h>
 #include <misc/util.h>
 #include <misc/__assert.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 
 #ifdef CONFIG_SHARED_IRQ
 #include <shared_irq.h>

drivers/gpio/gpio_rv32m1.c

@@ -12,7 +12,7 @@
 #include <soc.h>
 #include <fsl_common.h>
 #include <fsl_port.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 
 #include "gpio_utils.h"
 

drivers/i2c/i2c_ll_stm32.c

@@ -6,7 +6,7 @@
  */
 
 #include <clock_control/stm32_clock_control.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 #include <kernel.h>
 #include <soc.h>

drivers/i2c/i2c_ll_stm32_v1.c

@@ -9,7 +9,7 @@
  */
 
 #include <clock_control/stm32_clock_control.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 #include <kernel.h>
 #include <soc.h>

drivers/i2c/i2c_ll_stm32_v2.c

@@ -9,7 +9,7 @@
  */
 
 #include <clock_control/stm32_clock_control.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 #include <kernel.h>
 #include <soc.h>

drivers/i2c/i2c_mchp_xec.c

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <kernel.h>
 #include <soc.h>
 #include <errno.h>

drivers/i2c/i2c_mcux_lpi2c.c

@@ -7,7 +7,7 @@
 
 #include <errno.h>
 #include <i2c.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <fsl_lpi2c.h>
 
 #include <logging/log.h>

drivers/i2c/i2c_rv32m1_lpi2c.c

@@ -9,7 +9,7 @@
  */
 
 #include <i2c.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <fsl_lpi2c.h>
 #include <logging/log.h>
 LOG_MODULE_REGISTER(rv32m1_lpi2c);

drivers/i2s/i2s_ll_stm32.c

@@ -9,7 +9,7 @@
 #include <i2s.h>
 #include <soc.h>
 #include <clock_control/stm32_clock_control.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 
 #include "i2s_ll_stm32.h"
 #include <logging/log.h>

drivers/interrupt_controller/rv32m1_intmux.c

@@ -21,7 +21,7 @@
  */
 
 #include <kernel.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <init.h>
 #include <irq.h>
 #include <irq_nextlevel.h>

drivers/led_strip/ws2812b_sw.c

@@ -16,7 +16,7 @@ LOG_MODULE_REGISTER(ws2812b_sw);
 #include <soc.h>
 #include <gpio.h>
 #include <device.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 
 #define BLOCKING ((void *)1)
 

drivers/pinmux/stm32/pinmux_stm32.h

@@ -13,7 +13,7 @@
 
 #include <zephyr/types.h>
 #include <stddef.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #ifdef CONFIG_SOC_SERIES_STM32F1X
 #include <dt-bindings/pinctrl/stm32-pinctrlf1.h>
 #else

drivers/rtc/rtc_ll_stm32.c

@@ -11,7 +11,7 @@
 #include <time.h>
 
 #include <clock_control/stm32_clock_control.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 #include <kernel.h>
 #include <soc.h>

drivers/sensor/nrf5/temp_nrf5.c

@@ -6,7 +6,7 @@
 
 #include <device.h>
 #include <sensor.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <logging/log.h>
 
 #define LOG_LEVEL CONFIG_SENSOR_LOG_LEVEL

drivers/serial/uart_mcux.c

@@ -7,7 +7,7 @@
 #include <errno.h>
 #include <device.h>
 #include <uart.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <fsl_uart.h>
 #include <soc.h>
 

drivers/serial/uart_mcux_lpsci.c

@@ -7,7 +7,7 @@
 #include <errno.h>
 #include <device.h>
 #include <uart.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <fsl_lpsci.h>
 #include <soc.h>
 

drivers/serial/uart_mcux_lpuart.c

@@ -7,7 +7,7 @@
 #include <errno.h>
 #include <device.h>
 #include <uart.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <fsl_lpuart.h>
 #include <soc.h>
 

drivers/serial/uart_rv32m1_lpuart.c

@@ -8,7 +8,7 @@
 #include <errno.h>
 #include <device.h>
 #include <uart.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <fsl_lpuart.h>
 #include <soc.h>
 

drivers/serial/uart_stm32.c

@@ -18,7 +18,7 @@
 #include <soc.h>
 #include <init.h>
 #include <uart.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 
 #include <linker/sections.h>
 #include <clock_control/stm32_clock_control.h>

drivers/spi/spi_dw.c

@@ -33,7 +33,7 @@ LOG_MODULE_REGISTER(spi_dw);
 #include <init.h>
 
 #include <sys/sys_io.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 
 #ifdef CONFIG_IOAPIC

drivers/spi/spi_ll_stm32.c

@@ -16,7 +16,7 @@ LOG_MODULE_REGISTER(spi_ll_stm32);
 #include <toolchain.h>
 
 #include <clock_control/stm32_clock_control.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 
 #include "spi_ll_stm32.h"
 

drivers/spi/spi_mcux_dspi.c

@@ -7,7 +7,7 @@
 
 #include <errno.h>
 #include <spi.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <fsl_dspi.h>
 
 #define LOG_LEVEL CONFIG_SPI_LOG_LEVEL

drivers/spi/spi_mcux_lpspi.c

@@ -6,7 +6,7 @@
 
 #include <errno.h>
 #include <spi.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <fsl_lpspi.h>
 
 #define LOG_LEVEL CONFIG_SPI_LOG_LEVEL

drivers/timer/nrf_rtc_timer.c

@@ -6,7 +6,7 @@
  */
 
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <drivers/clock_control/nrf_clock_control.h>
 #include <drivers/timer/system_timer.h>
 #include <sys_clock.h>

drivers/timer/sam0_rtc_timer.c

@@ -15,7 +15,7 @@
  */
 
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <drivers/timer/system_timer.h>
 #include <sys_clock.h>
 

drivers/usb/device/usb_dc_nrfx.c

@@ -19,7 +19,7 @@
 #include <kernel.h>
 #include <usb/usb_dc.h>
 #include <usb/usb_device.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <hal/nrf_power.h>
 #include <drivers/clock_control/nrf_clock_control.h>
 #include <nrfx_usbd.h>

drivers/watchdog/wdt_mcux_wdog.c

@@ -6,7 +6,7 @@
  */
 
 #include <drivers/watchdog.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <fsl_wdog.h>
 
 #define LOG_LEVEL CONFIG_WDT_LOG_LEVEL

ext/hal/nordic/drivers/nrf_radio_802154/platform/clock/nrf_802154_clock_zephyr.c

@@ -41,7 +41,7 @@
 
 #include <compiler_abstraction.h>
 #include <drivers/clock_control/nrf_clock_control.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 
 static bool hfclk_is_running;
 static bool lfclk_is_running;

include/clock_control.h

@@ -1,214 +1,15 @@
-/* clock_control.h - public clock controller driver API */
-
 /*
- * Copyright (c) 2015 Intel Corporation
+ * Copyright (c) 2019 Intel Corporation
  *
  * SPDX-License-Identifier: Apache-2.0
  */
-
 #ifndef ZEPHYR_INCLUDE_CLOCK_CONTROL_H_
 #define ZEPHYR_INCLUDE_CLOCK_CONTROL_H_
 
-#include <zephyr/types.h>
-#include <stddef.h>
-#include <device.h>
-#include <misc/__assert.h>
-#include <misc/slist.h>
-
-#ifdef __cplusplus
-extern "C" {
+#ifndef CONFIG_COMPAT_INCLUDES
+#warning "This header file has moved, include <drivers/clock_control.h> instead."
 #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
-};
-
-typedef void (*clock_control_cb_t)(struct device *dev, void *user_data);
-
-/**
- * @cond INTERNAL_HIDDEN
- */
-#define Z_CLOCK_CONTROL_ASYNC_DATA_INITIALIZER(_cb, _user_data) \
-	{ \
-		.cb = cb, \
-		.user_data = _user_data \
-	}
-/**
- * INTERNAL_HIDDEN @endcond
- */
-
-/**
- * Define and initialize clock_control async data.
- *
- * @param name		Name of the data.
- * @param cb		Callback.
- * @param user_data	User data
- */
-#define CLOCK_CONTROL_ASYNC_DATA_DEFINE(name, cb, user_data) \
-	struct clock_control_async_data name = \
-		Z_CLOCK_CONTROL_ASYNC_DATA_INITIALIZER(cb, user_data)
-
-/**
- * @brief Clock control data used for asynchronous clock enabling.
- *
- * @param node		Used internally for linking asynchronous requests.
- * @param cb		Callback called when clock is started.
- * @param user_data	User data passed as an argument in the callback.
- */
-struct clock_control_async_data {
-	sys_snode_t node;
-	clock_control_cb_t cb;
-	void *user_data;
-};
-
-/**
- * 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;
-
-typedef int (*clock_control)(struct device *dev, clock_control_subsys_t sys);
-
-typedef int (*clock_control_get)(struct device *dev,
-				 clock_control_subsys_t sys,
-				 u32_t *rate);
-
-typedef int (*clock_control_async_on_fn)(struct device *dev,
-				   clock_control_subsys_t sys,
-				   struct clock_control_async_data *data);
-
-typedef enum clock_control_status (*clock_control_get_status_fn)(
-						struct device *dev,
-						clock_control_subsys_t sys);
-
-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;
-};
-
-/**
- * @brief Enable the clock of a sub-system controlled by the device
- * @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
- */
-static inline int clock_control_on(struct device *dev,
-				   clock_control_subsys_t sys)
-{
-	const struct clock_control_driver_api *api =
-		(const struct clock_control_driver_api *)dev->driver_api;
-
-	return api->on(dev, sys);
-}
-
-/**
- * @brief Disable the clock of a sub-system controlled by the device
- * @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
- */
-static inline int clock_control_off(struct device *dev,
-				    clock_control_subsys_t sys)
-{
-	const struct clock_control_driver_api *api =
-		(const struct clock_control_driver_api *)dev->driver_api;
-
-	return api->off(dev, sys);
-}
-
-/**
- * @brief Request clock to start with notification when clock has been started.
- *
- * User can request delayed start by providing exact information when clock
- * should be ready. Driver ensures that clock is ready before requested time.
- * It is the driver responsibility to take into account clock startup time.
- * When clock is already running user callback will be called from the context
- * of the function call else it is called from other context (e.g. clock
- * interrupt).
- *
- * @param dev 	   Device.
- * @param sys	   A pointer to an opaque data representing the sub-system.
- * @param data	   Data structure containing a callback that is called when
- *		   action is performed. Structure content must be valid until
- *		   clock is started and user callback is called. Can be NULL.
- *
- * @retval 0 if clock is started or already running.
- * @retval -EBUSY if same request already scheduled and not yet completed.
- * @retval -ENOTSUP if not supported.
- */
-static inline int clock_control_async_on(struct device *dev,
-					 clock_control_subsys_t sys,
-					 struct clock_control_async_data *data)
-{
-	const struct clock_control_driver_api *api =
-		(const struct clock_control_driver_api *)dev->driver_api;
-
-	if (!api->async_on) {
-		return -ENOTSUP;
-	}
-
-	return api->async_on(dev, sys, 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(
-						struct device *dev,
-						clock_control_subsys_t sys)
-{
-	const struct clock_control_driver_api *api =
-		(const struct clock_control_driver_api *)dev->driver_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
- */
-static inline int clock_control_get_rate(struct device *dev,
-					 clock_control_subsys_t sys,
-					 u32_t *rate)
-{
-	const struct clock_control_driver_api *api =
-		(const struct clock_control_driver_api *)dev->driver_api;
-
-	__ASSERT(api->get_rate != NULL, "%s not implemented for device %s",
-		__func__, dev->config->name);
-
-	return api->get_rate(dev, sys, rate);
-}
-
-#ifdef __cplusplus
-}
-#endif
+#include <drivers/clock_control.h>
 
 #endif /* ZEPHYR_INCLUDE_CLOCK_CONTROL_H_ */

include/drivers/clock_control.h

@@ -0,0 +1,214 @@
+/* clock_control.h - public clock controller driver API */
+
+/*
+ * Copyright (c) 2015 Intel Corporation
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_DRIVERS_CLOCK_CONTROL_H_
+#define ZEPHYR_INCLUDE_DRIVERS_CLOCK_CONTROL_H_
+
+#include <zephyr/types.h>
+#include <stddef.h>
+#include <device.h>
+#include <misc/__assert.h>
+#include <misc/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
+};
+
+typedef void (*clock_control_cb_t)(struct device *dev, void *user_data);
+
+/**
+ * @cond INTERNAL_HIDDEN
+ */
+#define Z_CLOCK_CONTROL_ASYNC_DATA_INITIALIZER(_cb, _user_data) \
+	{ \
+		.cb = cb, \
+		.user_data = _user_data \
+	}
+/**
+ * INTERNAL_HIDDEN @endcond
+ */
+
+/**
+ * Define and initialize clock_control async data.
+ *
+ * @param name		Name of the data.
+ * @param cb		Callback.
+ * @param user_data	User data
+ */
+#define CLOCK_CONTROL_ASYNC_DATA_DEFINE(name, cb, user_data) \
+	struct clock_control_async_data name = \
+		Z_CLOCK_CONTROL_ASYNC_DATA_INITIALIZER(cb, user_data)
+
+/**
+ * @brief Clock control data used for asynchronous clock enabling.
+ *
+ * @param node		Used internally for linking asynchronous requests.
+ * @param cb		Callback called when clock is started.
+ * @param user_data	User data passed as an argument in the callback.
+ */
+struct clock_control_async_data {
+	sys_snode_t node;
+	clock_control_cb_t cb;
+	void *user_data;
+};
+
+/**
+ * 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;
+
+typedef int (*clock_control)(struct device *dev, clock_control_subsys_t sys);
+
+typedef int (*clock_control_get)(struct device *dev,
+				 clock_control_subsys_t sys,
+				 u32_t *rate);
+
+typedef int (*clock_control_async_on_fn)(struct device *dev,
+				   clock_control_subsys_t sys,
+				   struct clock_control_async_data *data);
+
+typedef enum clock_control_status (*clock_control_get_status_fn)(
+						struct device *dev,
+						clock_control_subsys_t sys);
+
+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;
+};
+
+/**
+ * @brief Enable the clock of a sub-system controlled by the device
+ * @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
+ */
+static inline int clock_control_on(struct device *dev,
+				   clock_control_subsys_t sys)
+{
+	const struct clock_control_driver_api *api =
+		(const struct clock_control_driver_api *)dev->driver_api;
+
+	return api->on(dev, sys);
+}
+
+/**
+ * @brief Disable the clock of a sub-system controlled by the device
+ * @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
+ */
+static inline int clock_control_off(struct device *dev,
+				    clock_control_subsys_t sys)
+{
+	const struct clock_control_driver_api *api =
+		(const struct clock_control_driver_api *)dev->driver_api;
+
+	return api->off(dev, sys);
+}
+
+/**
+ * @brief Request clock to start with notification when clock has been started.
+ *
+ * User can request delayed start by providing exact information when clock
+ * should be ready. Driver ensures that clock is ready before requested time.
+ * It is the driver responsibility to take into account clock startup time.
+ * When clock is already running user callback will be called from the context
+ * of the function call else it is called from other context (e.g. clock
+ * interrupt).
+ *
+ * @param dev 	   Device.
+ * @param sys	   A pointer to an opaque data representing the sub-system.
+ * @param data	   Data structure containing a callback that is called when
+ *		   action is performed. Structure content must be valid until
+ *		   clock is started and user callback is called. Can be NULL.
+ *
+ * @retval 0 if clock is started or already running.
+ * @retval -EBUSY if same request already scheduled and not yet completed.
+ * @retval -ENOTSUP if not supported.
+ */
+static inline int clock_control_async_on(struct device *dev,
+					 clock_control_subsys_t sys,
+					 struct clock_control_async_data *data)
+{
+	const struct clock_control_driver_api *api =
+		(const struct clock_control_driver_api *)dev->driver_api;
+
+	if (!api->async_on) {
+		return -ENOTSUP;
+	}
+
+	return api->async_on(dev, sys, 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(
+						struct device *dev,
+						clock_control_subsys_t sys)
+{
+	const struct clock_control_driver_api *api =
+		(const struct clock_control_driver_api *)dev->driver_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
+ */
+static inline int clock_control_get_rate(struct device *dev,
+					 clock_control_subsys_t sys,
+					 u32_t *rate)
+{
+	const struct clock_control_driver_api *api =
+		(const struct clock_control_driver_api *)dev->driver_api;
+
+	__ASSERT(api->get_rate != NULL, "%s not implemented for device %s",
+		__func__, dev->config->name);
+
+	return api->get_rate(dev, sys, rate);
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ZEPHYR_INCLUDE_DRIVERS_CLOCK_CONTROL_H_ */

include/drivers/clock_control/arm_clock_control.h

@@ -7,7 +7,7 @@
 #ifndef ZEPHYR_INCLUDE_DRIVERS_CLOCK_CONTROL_ARM_CLOCK_CONTROL_H_
 #define ZEPHYR_INCLUDE_DRIVERS_CLOCK_CONTROL_ARM_CLOCK_CONTROL_H_
 
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 
 /**
  * @file

include/drivers/clock_control/stm32_clock_control.h

@@ -9,7 +9,7 @@
 #ifndef ZEPHYR_INCLUDE_DRIVERS_CLOCK_CONTROL_STM32_CLOCK_CONTROL_H_
 #define ZEPHYR_INCLUDE_DRIVERS_CLOCK_CONTROL_STM32_CLOCK_CONTROL_H_
 
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <dt-bindings/clock/stm32_clock.h>
 
 /* common clock control device name for all STM32 chips */

subsys/bluetooth/controller/hci/hci_driver.c

@@ -13,7 +13,7 @@
 #include <soc.h>
 #include <init.h>
 #include <device.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <sys/atomic.h>
 
 #include <misc/util.h>

subsys/bluetooth/controller/ll_sw/ctrl.c

@@ -12,7 +12,7 @@
 #include <soc.h>
 #include <device.h>
 #include <entropy.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <bluetooth/hci.h>
 #include <misc/util.h>
 #include <misc/byteorder.h>

subsys/bluetooth/controller/ll_sw/ll.c

@@ -10,7 +10,7 @@
 
 #include <soc.h>
 #include <device.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #ifdef CONFIG_CLOCK_CONTROL_NRF
 #include <drivers/clock_control/nrf_clock_control.h>
 #endif

subsys/bluetooth/controller/ll_sw/ll_test.c

@@ -10,7 +10,7 @@
 #include <toolchain.h>
 #include <zephyr/types.h>
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 
 #include "hal/cpu.h"
 #include "hal/cntr.h"

subsys/bluetooth/controller/ll_sw/nordic/lll/lll.c

@@ -8,7 +8,7 @@
 #include <zephyr/types.h>
 #include <device.h>
 #include <entropy.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <drivers/clock_control/nrf_clock_control.h>
 
 #include "hal/ccm.h"

subsys/bluetooth/controller/ll_sw/nordic/lll/lll_clock.c

@@ -7,7 +7,7 @@
 #include <zephyr/types.h>
 #include <soc.h>
 #include <device.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <drivers/clock_control/nrf_clock_control.h>
 
 #define LOG_MODULE_NAME bt_ctlr_llsw_nordic_lll_clock

subsys/bluetooth/controller/ll_sw/nordic/lll/lll_test.c

@@ -10,7 +10,7 @@
 #include <toolchain.h>
 #include <zephyr/types.h>
 #include <soc.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 
 #include "hal/cpu.h"
 #include "hal/cntr.h"

tests/drivers/i2c/i2c_slave_api/common/i2c_virtual.c

@@ -5,7 +5,7 @@
  */
 
 #include <clock_control/stm32_clock_control.h>
-#include <clock_control.h>
+#include <drivers/clock_control.h>
 #include <misc/util.h>
 #include <kernel.h>
 #include <errno.h>