From 0b0435a96c1d7a726dc9ba3847d71cec00b2b29c Mon Sep 17 00:00:00 2001
From: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Date: Thu, 23 Dec 2021 17:25:34 +0100
Subject: [PATCH] device: deprecate (z_)device_usable_check

The functionality provided by device_usable_check is already provided by
device_is_ready. The (z_)device_usable_check APIs have been
re-implemented using the (z_)device_is_ready APIs and have been marked
as deprecated.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
---
 include/device.h | 65 ++++++++++++++++++++++++------------------------
 kernel/device.c  |  8 ------
 2 files changed, 33 insertions(+), 40 deletions(-)

diff --git a/include/device.h b/include/device.h
index 2c2276e699f..255848751ab 100644
--- a/include/device.h
+++ b/include/device.h
@@ -741,38 +741,6 @@ size_t z_device_get_all_static(const struct device * *devices);
  */
 bool z_device_is_ready(const struct device *dev);
 
-/** @brief Determine whether a device is ready for use
- *
- * This is the implementation underlying `device_usable_check()`, without the
- * overhead of a syscall wrapper.
- *
- * @param dev pointer to the device in question.
- *
- * @return a non-positive integer as documented in device_usable_check().
- */
-static inline int z_device_usable_check(const struct device *dev)
-{
-	return z_device_is_ready(dev) ? 0 : -ENODEV;
-}
-
-/** @brief Determine whether a device is ready for use.
- *
- * This checks whether a device can be used, returning 0 if it can, and
- * distinct error values that identify the reason if it cannot.
- *
- * @retval 0 if the device is usable.
- * @retval -ENODEV if the device has not been initialized, the device pointer
- * is NULL or the initialization failed.
- * @retval other negative error codes to indicate additional conditions that
- * make the device unusable.
- */
-__syscall int device_usable_check(const struct device *dev);
-
-static inline int z_impl_device_usable_check(const struct device *dev)
-{
-	return z_device_usable_check(dev);
-}
-
 /** @brief Verify that a device is ready for use.
  *
  * Indicates whether the provided device pointer is for a device known to be
@@ -796,6 +764,39 @@ static inline bool z_impl_device_is_ready(const struct device *dev)
 	return z_device_is_ready(dev);
 }
 
+/**
+ * @brief Determine whether a device is ready for use
+ *
+ * This is equivalent to device_usable_check(), without the overhead of a
+ * syscall wrapper.
+ *
+ * @deprecated Use z_device_is_ready() instead.
+ *
+ * @param dev Device instance.
+ *
+ * @retval 0 If device is usable.
+ * @retval -ENODEV If device is not usable.
+ */
+__deprecated static inline int z_device_usable_check(const struct device *dev)
+{
+	return z_device_is_ready(dev) ? 0 : -ENODEV;
+}
+
+/**
+ * @brief Determine whether a device is ready for use
+ *
+ * @deprecated Use device_is_ready() instead.
+ *
+ * @param dev Device instance.
+ *
+ * @retval 0 If device is usable.
+ * @retval -ENODEV If device is not usable.
+ */
+__deprecated static inline int device_usable_check(const struct device *dev)
+{
+	return device_is_ready(dev) ? 0 : -ENODEV;
+}
+
 /**
  * @}
  */
diff --git a/kernel/device.c b/kernel/device.c
index 7934113f2a0..1129a411974 100644
--- a/kernel/device.c
+++ b/kernel/device.c
@@ -134,14 +134,6 @@ static inline const struct device *z_vrfy_device_get_binding(const char *name)
 }
 #include <syscalls/device_get_binding_mrsh.c>
 
-static inline int z_vrfy_device_usable_check(const struct device *dev)
-{
-	Z_OOPS(Z_SYSCALL_OBJ_INIT(dev, K_OBJ_ANY));
-
-	return z_impl_device_usable_check(dev);
-}
-#include <syscalls/device_usable_check_mrsh.c>
-
 static inline bool z_vrfy_device_is_ready(const struct device *dev)
 {
 	Z_OOPS(Z_SYSCALL_OBJ_INIT(dev, K_OBJ_ANY));