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

move ipm.h to drivers/ipm.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/console/ipm_console_receiver.c

@@ -12,7 +12,7 @@
 #include <ring_buffer.h>
 #include <misc/printk.h>
 #include <stdio.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <console/ipm_console.h>
 #include <misc/__assert.h>
 

drivers/console/ipm_console_sender.c

@@ -10,7 +10,7 @@
 
 #include <kernel.h>
 #include <misc/printk.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <console/ipm_console.h>
 
 static struct device *ipm_console_device;

drivers/ipm/ipm_handlers.c

@@ -5,7 +5,7 @@
  */
 
 #include <syscall_handler.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 
 Z_SYSCALL_HANDLER(ipm_send, dev, wait, id, data, size)
 {

drivers/ipm/ipm_imx.c

@@ -8,7 +8,7 @@
 #include <string.h>
 #include <device.h>
 #include <soc.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <mu_imx.h>
 
 #define MU(config) ((MU_Type *)config->base)

drivers/ipm/ipm_mcux.c

@@ -6,7 +6,7 @@
 
 #include <errno.h>
 #include <device.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <fsl_mailbox.h>
 #include <fsl_clock.h>
 #include <soc.h>

drivers/ipm/ipm_mhu.h

@@ -8,7 +8,7 @@
 #define ZEPHYR_DRIVERS_IPM_IPM_MHU_H_
 
 #include <kernel.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <device.h>
 
 #ifdef __cplusplus

drivers/ipm/ipm_quark_se.c

@@ -11,7 +11,7 @@
 #include <string.h>
 #include <device.h>
 #include <init.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <arch/cpu.h>
 #include <misc/printk.h>
 #include <misc/__assert.h>

drivers/ipm/ipm_quark_se.h

@@ -12,7 +12,7 @@
 
 #include <kernel.h>
 #include <soc.h> /* for SCSS_REGISTER_BASE */
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <device.h>
 #include <init.h>
 

include/drivers/ipm.h

@@ -0,0 +1,225 @@
+/**
+ * @file
+ *
+ * @brief Generic low-level inter-processor mailbox communication API.
+ */
+
+/*
+ * Copyright (c) 2015 Intel Corporation
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_DRIVERS_IPM_H_
+#define ZEPHYR_INCLUDE_DRIVERS_IPM_H_
+
+/**
+ * @brief IPM Interface
+ * @defgroup ipm_interface IPM Interface
+ * @ingroup io_interfaces
+ * @{
+ */
+
+#include <kernel.h>
+#include <device.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @typedef ipm_callback_t
+ * @brief Callback API for incoming IPM messages
+ *
+ * These callbacks execute in interrupt context. Therefore, use only
+ * interrupt-safe APIS. Registration of callbacks is done via
+ * @a ipm_register_callback
+ *
+ * @param "void *context" Arbitrary context pointer provided at
+ *        registration time.
+ * @param "u32_t id" Message type identifier.
+ * @param "volatile void *data" Message data pointer. The correct
+ *        amount of data to read out
+ * must be inferred using the message id/upper level protocol.
+ */
+typedef void (*ipm_callback_t)(void *context, u32_t id, volatile void *data);
+
+/**
+ * @typedef ipm_send_t
+ * @brief Callback API to send IPM messages
+ *
+ * See @a ipm_send() for argument definitions.
+ */
+typedef int (*ipm_send_t)(struct device *ipmdev, int wait, u32_t id,
+			  const void *data, int size);
+/**
+ * @typedef ipm_max_data_size_get_t
+ * @brief Callback API to get maximum data size
+ *
+ * See @a ipm_max_data_size_get() for argument definitions.
+ */
+typedef int (*ipm_max_data_size_get_t)(struct device *ipmdev);
+
+/**
+ * @typedef ipm_max_id_val_get_t
+ * @brief Callback API to get the ID's maximum value
+ *
+ * See @a ipm_max_id_val_get() for argument definitions.
+ */
+typedef u32_t (*ipm_max_id_val_get_t)(struct device *ipmdev);
+
+/**
+ * @typedef ipm_register_callback_t
+ * @brief Callback API upon registration
+ *
+ * See @a ipm_register_callback() for argument definitions.
+ */
+typedef void (*ipm_register_callback_t)(struct device *port, ipm_callback_t cb,
+					void *cb_context);
+
+/**
+ * @typedef ipm_set_enabled_t
+ * @brief Callback API upon enablement of interrupts
+ *
+ * See @a ipm_set_enabled() for argument definitions.
+ */
+typedef int (*ipm_set_enabled_t)(struct device *ipmdev, int enable);
+
+struct ipm_driver_api {
+	ipm_send_t send;
+	ipm_register_callback_t register_callback;
+	ipm_max_data_size_get_t max_data_size_get;
+	ipm_max_id_val_get_t max_id_val_get;
+	ipm_set_enabled_t set_enabled;
+};
+
+/**
+ * @brief Try to send a message over the IPM device.
+ *
+ * A message is considered consumed once the remote interrupt handler
+ * finishes. If there is deferred processing on the remote side,
+ * or if outgoing messages must be queued and wait on an
+ * event/semaphore, a high-level driver can implement that.
+ *
+ * There are constraints on how much data can be sent or the maximum value
+ * of id. Use the @a ipm_max_data_size_get and @a ipm_max_id_val_get routines
+ * to determine them.
+ *
+ * The @a size parameter is used only on the sending side to determine
+ * the amount of data to put in the message registers. It is not passed along
+ * to the receiving side. The upper-level protocol dictates the amount of
+ * data read back.
+ *
+ * @param ipmdev Driver instance
+ * @param wait If nonzero, busy-wait for remote to consume the message. The
+ *	       message is considered consumed once the remote interrupt handler
+ *	       finishes. If there is deferred processing on the remote side,
+ *	       or you would like to queue outgoing messages and wait on an
+ *	       event/semaphore, you can implement that in a high-level driver
+ * @param id Message identifier. Values are constrained by
+ *        @a ipm_max_data_size_get since many boards only allow for a
+ *        subset of bits in a 32-bit register to store the ID.
+ * @param data Pointer to the data sent in the message.
+ * @param size Size of the data.
+ *
+ * @retval EBUSY    If the remote hasn't yet read the last data sent.
+ * @retval EMSGSIZE If the supplied data size is unsupported by the driver.
+ * @retval EINVAL   If there was a bad parameter, such as: too-large id value.
+ *                  or the device isn't an outbound IPM channel.
+ * @retval 0        On success.
+ */
+__syscall int ipm_send(struct device *ipmdev, int wait, u32_t id,
+		       const void *data, int size);
+
+static inline int z_impl_ipm_send(struct device *ipmdev, int wait, u32_t id,
+			   const void *data, int size)
+{
+	const struct ipm_driver_api *api = ipmdev->driver_api;
+
+	return api->send(ipmdev, wait, id, data, size);
+}
+
+/**
+ * @brief Register a callback function for incoming messages.
+ *
+ * @param ipmdev Driver instance pointer.
+ * @param cb Callback function to execute on incoming message interrupts.
+ * @param context Application-specific context pointer which will be passed
+ *        to the callback function when executed.
+ */
+static inline void ipm_register_callback(struct device *ipmdev,
+					 ipm_callback_t cb, void *context)
+{
+	const struct ipm_driver_api *api = ipmdev->driver_api;
+
+	api->register_callback(ipmdev, cb, context);
+}
+
+/**
+ * @brief Return the maximum number of bytes possible in an outbound message.
+ *
+ * IPM implementations vary on the amount of data that can be sent in a
+ * single message since the data payload is typically stored in registers.
+ *
+ * @param ipmdev Driver instance pointer.
+ *
+ * @return Maximum possible size of a message in bytes.
+ */
+__syscall int ipm_max_data_size_get(struct device *ipmdev);
+
+static inline int z_impl_ipm_max_data_size_get(struct device *ipmdev)
+{
+	const struct ipm_driver_api *api = ipmdev->driver_api;
+
+	return api->max_data_size_get(ipmdev);
+}
+
+
+/**
+ * @brief Return the maximum id value possible in an outbound message.
+ *
+ * Many IPM implementations store the message's ID in a register with
+ * some bits reserved for other uses.
+ *
+ * @param ipmdev Driver instance pointer.
+ *
+ * @return Maximum possible value of a message ID.
+ */
+__syscall u32_t ipm_max_id_val_get(struct device *ipmdev);
+
+static inline u32_t z_impl_ipm_max_id_val_get(struct device *ipmdev)
+{
+	const struct ipm_driver_api *api = ipmdev->driver_api;
+
+	return api->max_id_val_get(ipmdev);
+}
+
+/**
+ * @brief Enable interrupts and callbacks for inbound channels.
+ *
+ * @param ipmdev Driver instance pointer.
+ * @param enable Set to 0 to disable and to nonzero to enable.
+ *
+ * @retval 0      On success.
+ * @retval EINVAL If it isn't an inbound channel.
+ */
+__syscall int ipm_set_enabled(struct device *ipmdev, int enable);
+
+static inline int z_impl_ipm_set_enabled(struct device *ipmdev, int enable)
+{
+	const struct ipm_driver_api *api = ipmdev->driver_api;
+
+	return api->set_enabled(ipmdev, enable);
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+/**
+ * @}
+ */
+
+#include <syscalls/ipm.h>
+
+#endif /* ZEPHYR_INCLUDE_DRIVERS_IPM_H_ */

include/ipm.h

@@ -1,225 +1,15 @@
-/**
- * @file
- *
- * @brief Generic low-level inter-processor mailbox communication API.
- */
-
 /*
- * Copyright (c) 2015 Intel Corporation
+ * Copyright (c) 2019 Intel Corporation
  *
  * SPDX-License-Identifier: Apache-2.0
  */
-
 #ifndef ZEPHYR_INCLUDE_IPM_H_
 #define ZEPHYR_INCLUDE_IPM_H_
 
-/**
+#ifndef CONFIG_COMPAT_INCLUDES
- * @brief IPM Interface
+#warning "This header file has moved, include <drivers/ipm.h> instead."
- * @defgroup ipm_interface IPM Interface
- * @ingroup io_interfaces
- * @{
- */
-
-#include <kernel.h>
-#include <device.h>
-
-#ifdef __cplusplus
-extern "C" {
 #endif
 
-/**
+#include <drivers/ipm.h>
- * @typedef ipm_callback_t
- * @brief Callback API for incoming IPM messages
- *
- * These callbacks execute in interrupt context. Therefore, use only
- * interrupt-safe APIS. Registration of callbacks is done via
- * @a ipm_register_callback
- *
- * @param "void *context" Arbitrary context pointer provided at
- *        registration time.
- * @param "u32_t id" Message type identifier.
- * @param "volatile void *data" Message data pointer. The correct
- *        amount of data to read out
- * must be inferred using the message id/upper level protocol.
- */
-typedef void (*ipm_callback_t)(void *context, u32_t id, volatile void *data);
-
-/**
- * @typedef ipm_send_t
- * @brief Callback API to send IPM messages
- *
- * See @a ipm_send() for argument definitions.
- */
-typedef int (*ipm_send_t)(struct device *ipmdev, int wait, u32_t id,
-			  const void *data, int size);
-/**
- * @typedef ipm_max_data_size_get_t
- * @brief Callback API to get maximum data size
- *
- * See @a ipm_max_data_size_get() for argument definitions.
- */
-typedef int (*ipm_max_data_size_get_t)(struct device *ipmdev);
-
-/**
- * @typedef ipm_max_id_val_get_t
- * @brief Callback API to get the ID's maximum value
- *
- * See @a ipm_max_id_val_get() for argument definitions.
- */
-typedef u32_t (*ipm_max_id_val_get_t)(struct device *ipmdev);
-
-/**
- * @typedef ipm_register_callback_t
- * @brief Callback API upon registration
- *
- * See @a ipm_register_callback() for argument definitions.
- */
-typedef void (*ipm_register_callback_t)(struct device *port, ipm_callback_t cb,
-					void *cb_context);
-
-/**
- * @typedef ipm_set_enabled_t
- * @brief Callback API upon enablement of interrupts
- *
- * See @a ipm_set_enabled() for argument definitions.
- */
-typedef int (*ipm_set_enabled_t)(struct device *ipmdev, int enable);
-
-struct ipm_driver_api {
-	ipm_send_t send;
-	ipm_register_callback_t register_callback;
-	ipm_max_data_size_get_t max_data_size_get;
-	ipm_max_id_val_get_t max_id_val_get;
-	ipm_set_enabled_t set_enabled;
-};
-
-/**
- * @brief Try to send a message over the IPM device.
- *
- * A message is considered consumed once the remote interrupt handler
- * finishes. If there is deferred processing on the remote side,
- * or if outgoing messages must be queued and wait on an
- * event/semaphore, a high-level driver can implement that.
- *
- * There are constraints on how much data can be sent or the maximum value
- * of id. Use the @a ipm_max_data_size_get and @a ipm_max_id_val_get routines
- * to determine them.
- *
- * The @a size parameter is used only on the sending side to determine
- * the amount of data to put in the message registers. It is not passed along
- * to the receiving side. The upper-level protocol dictates the amount of
- * data read back.
- *
- * @param ipmdev Driver instance
- * @param wait If nonzero, busy-wait for remote to consume the message. The
- *	       message is considered consumed once the remote interrupt handler
- *	       finishes. If there is deferred processing on the remote side,
- *	       or you would like to queue outgoing messages and wait on an
- *	       event/semaphore, you can implement that in a high-level driver
- * @param id Message identifier. Values are constrained by
- *        @a ipm_max_data_size_get since many boards only allow for a
- *        subset of bits in a 32-bit register to store the ID.
- * @param data Pointer to the data sent in the message.
- * @param size Size of the data.
- *
- * @retval EBUSY    If the remote hasn't yet read the last data sent.
- * @retval EMSGSIZE If the supplied data size is unsupported by the driver.
- * @retval EINVAL   If there was a bad parameter, such as: too-large id value.
- *                  or the device isn't an outbound IPM channel.
- * @retval 0        On success.
- */
-__syscall int ipm_send(struct device *ipmdev, int wait, u32_t id,
-		       const void *data, int size);
-
-static inline int z_impl_ipm_send(struct device *ipmdev, int wait, u32_t id,
-			   const void *data, int size)
-{
-	const struct ipm_driver_api *api = ipmdev->driver_api;
-
-	return api->send(ipmdev, wait, id, data, size);
-}
-
-/**
- * @brief Register a callback function for incoming messages.
- *
- * @param ipmdev Driver instance pointer.
- * @param cb Callback function to execute on incoming message interrupts.
- * @param context Application-specific context pointer which will be passed
- *        to the callback function when executed.
- */
-static inline void ipm_register_callback(struct device *ipmdev,
-					 ipm_callback_t cb, void *context)
-{
-	const struct ipm_driver_api *api = ipmdev->driver_api;
-
-	api->register_callback(ipmdev, cb, context);
-}
-
-/**
- * @brief Return the maximum number of bytes possible in an outbound message.
- *
- * IPM implementations vary on the amount of data that can be sent in a
- * single message since the data payload is typically stored in registers.
- *
- * @param ipmdev Driver instance pointer.
- *
- * @return Maximum possible size of a message in bytes.
- */
-__syscall int ipm_max_data_size_get(struct device *ipmdev);
-
-static inline int z_impl_ipm_max_data_size_get(struct device *ipmdev)
-{
-	const struct ipm_driver_api *api = ipmdev->driver_api;
-
-	return api->max_data_size_get(ipmdev);
-}
-
-
-/**
- * @brief Return the maximum id value possible in an outbound message.
- *
- * Many IPM implementations store the message's ID in a register with
- * some bits reserved for other uses.
- *
- * @param ipmdev Driver instance pointer.
- *
- * @return Maximum possible value of a message ID.
- */
-__syscall u32_t ipm_max_id_val_get(struct device *ipmdev);
-
-static inline u32_t z_impl_ipm_max_id_val_get(struct device *ipmdev)
-{
-	const struct ipm_driver_api *api = ipmdev->driver_api;
-
-	return api->max_id_val_get(ipmdev);
-}
-
-/**
- * @brief Enable interrupts and callbacks for inbound channels.
- *
- * @param ipmdev Driver instance pointer.
- * @param enable Set to 0 to disable and to nonzero to enable.
- *
- * @retval 0      On success.
- * @retval EINVAL If it isn't an inbound channel.
- */
-__syscall int ipm_set_enabled(struct device *ipmdev, int enable);
-
-static inline int z_impl_ipm_set_enabled(struct device *ipmdev, int enable)
-{
-	const struct ipm_driver_api *api = ipmdev->driver_api;
-
-	return api->set_enabled(ipmdev, enable);
-}
-
-#ifdef __cplusplus
-}
-#endif
-
-/**
- * @}
- */
-
-#include <syscalls/ipm.h>
 
 #endif /* ZEPHYR_INCLUDE_IPM_H_ */

samples/boards/arduino_101/environmental_sensing/ap/src/main.c

@@ -9,7 +9,7 @@
 #include <bluetooth/uuid.h>
 #include <bluetooth/gatt.h>
 #include <device.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <ipm/ipm_quark_se.h>
 #include <misc/byteorder.h>
 #include <misc/printk.h>

samples/boards/arduino_101/environmental_sensing/sensor/src/main.c

@@ -5,7 +5,7 @@
  */
 
 #include <device.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <ipm/ipm_quark_se.h>
 #include <misc/printk.h>
 #include <misc/util.h>

samples/subsys/ipc/ipm_imx/src/main.c

@@ -7,7 +7,7 @@
 #include <zephyr.h>
 #include <misc/printk.h>
 #include <device.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 
 static struct device *ipm;
 

samples/subsys/ipc/ipm_mailbox/ap/src/hello.c

@@ -7,7 +7,7 @@
 
 #include <misc/printk.h>
 #include <zephyr.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <ipm/ipm_quark_se.h>
 
 QUARK_SE_IPM_DEFINE(ping_ipm, 0, QUARK_SE_IPM_OUTBOUND);

samples/subsys/ipc/ipm_mailbox/sensor/src/hello.c

@@ -6,7 +6,7 @@
  */
 #include <zephyr.h>
 
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <ipm/ipm_quark_se.h>
 #include <device.h>
 #include <init.h>

samples/subsys/ipc/ipm_mcux/remote/src/main_remote.c

@@ -7,7 +7,7 @@
 #include <zephyr.h>
 #include <misc/printk.h>
 #include <device.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 
 struct device *ipm;
 

samples/subsys/ipc/ipm_mcux/src/main_master.c

@@ -7,7 +7,7 @@
 #include <zephyr.h>
 #include <misc/printk.h>
 #include <device.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 
 struct device *ipm;
 int gcounter;

samples/subsys/ipc/ipm_mhu_dual_core/src/main.c

@@ -6,7 +6,7 @@
 
 #include <zephyr.h>
 #include <misc/printk.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 
 enum cpu_id_t {
 	MHU_CPU0 = 0,

samples/subsys/ipc/openamp/remote/src/main.c

@@ -7,7 +7,7 @@
  */
 
 #include <zephyr.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <misc/printk.h>
 #include <device.h>
 #include <stdio.h>

samples/subsys/ipc/openamp/src/main.c

@@ -7,7 +7,7 @@
  */
 
 #include <zephyr.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <misc/printk.h>
 #include <device.h>
 #include <stdio.h>

soc/arc/quark_se_c1000_ss/soc_config.c

@@ -9,7 +9,7 @@
 #include "soc.h"
 
 #if CONFIG_IPM_QUARK_SE
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <ipm/ipm_quark_se.h>
 
 static int arc_quark_se_ipm_init(void)

soc/x86/intel_quark/quark_se/soc_config.c

@@ -13,7 +13,7 @@
 #include <arch/cpu.h>
 
 #if CONFIG_IPM_QUARK_SE
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <ipm/ipm_quark_se.h>
 
 static int x86_quark_se_ipm_init(void)

tests/drivers/ipm/src/ipm_dummy.c

@@ -7,7 +7,7 @@
  */
 
 #include <zephyr.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <errno.h>
 #include <device.h>
 #include <init.h>

tests/drivers/ipm/src/ipm_dummy.h

@@ -10,7 +10,7 @@
 
 #include <zephyr.h>
 #include <device.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 
 /* Arbitrary */
 #define DUMMY_IPM_DATA_WORDS    4

tests/drivers/ipm/src/main.c

@@ -5,7 +5,7 @@
  */
 
 #include <zephyr.h>
-#include <ipm.h>
+#include <drivers/ipm.h>
 #include <drivers/console/ipm_console.h>
 #include <device.h>
 #include <init.h>