[API-NEXT,PATCHv2,09/23] drv: driver: add callback function for device destruction

Message ID 1490194110-40168-10-git-send-email-christophe.milard@linaro.org
State New
Headers show
Series
  • driver items registration and probing
Related show

Commit Message

Christophe Milard March 22, 2017, 2:48 p.m.
When a device is destroyed by an enumerator, odpdrv_device_destroy() is
called.
However, the complete device destruction may require waiting for IO to be
completed: the device destruction is therefore divided in 2 steps:
odpdrv_device_destroy() starts the device destruction, and the provided
callback function is called when the device can be fully removed, i.e.
when it no longer has any driver bound to it.
An extra flag is also added to select the destruction type:
The default is a graceful destruction, letting the time for any attached
driver to terminate. This may imply that the callback function is called
from another ODP thread, later on.
ODPDRV_DEV_DESTROY_IMMEDIATE forces an immediate device destruction,
possibly terminating things abrubtly, but it guarantees that the
callback is performed by the same ODP thread. This is to be used at ODP
terminaison time.

Signed-off-by: Christophe Milard <christophe.milard@linaro.org>

---
 include/odp/drv/spec/driver.h       | 31 +++++++++++++++++++++++++++----
 platform/linux-generic/drv_driver.c |  9 ++++++++-
 2 files changed, 35 insertions(+), 5 deletions(-)

-- 
2.7.4

Patch

diff --git a/include/odp/drv/spec/driver.h b/include/odp/drv/spec/driver.h
index 8ff856c..9643268 100644
--- a/include/odp/drv/spec/driver.h
+++ b/include/odp/drv/spec/driver.h
@@ -357,12 +357,35 @@  odpdrv_device_t odpdrv_device_create(odpdrv_device_param_t *param);
 
 /**
 * Destroy a device
-* Called by each enumerator at probe time, or anytime later, for each
-* destroyed created device
+* Called by each enumerator after probe time, for each device to be
+* destroyed.
+* Destroying a device may require tearing down a driver and waiting for some IO
+* to terminate: The device destruction is therefore done in 2 steps:
+* Calling this function starts the device destruction: when the device has
+* no driver attached any longer, ODP calls the provided callback()
+* function  which should free the enumerator-allocated resources for
+* this device.
+* If the flag ODPDRV_DEV_DESTROY_IMMEDIATE is given, the device destruction
+* is immediate, i.e. the callback function is guaranteed to be called by the
+* same ODP thread: This might however not let the time for the bound driver
+* (if any) to terminate gracefully. This would typically be used at ODP
+* terminaison. By default, the callback may be called later, when the driver
+* has gracefully terminated, hence possibly from another ODP thread.
 * @param dev A odpdrv device handle as returned by odpdrv_device_create.
-* @return 0 on success or a negative value on error.
+* @param callback a pointer to a function to be called when the device is
+*        freed (no more driver). The parameter to the callback function is
+*	 the pointer to the enumerator specific part of the device as provided
+*	 at device creation time (void *enum_dev). The callback function
+*	 should release these resources.
+* @param flags 0 or ODPDRV_DEV_DESTROY_IMMEDIATE for immediate shut down
+* @return 0 on success or a negative value on error. On error, the callback
+* function is not called.
 */
-void odpdrv_device_destroy(odpdrv_device_t dev);
+int odpdrv_device_destroy(odpdrv_device_t dev,
+			  void (*callback)(void *enum_dev), uint32_t flags);
+
+/** The callback function must be called by the current ODP thread */
+#define ODPDRV_DEV_DESTROY_IMMEDIATE	0x00000001
 
 /**
 * Register an devio.
diff --git a/platform/linux-generic/drv_driver.c b/platform/linux-generic/drv_driver.c
index 35473bd..4ade3c3 100644
--- a/platform/linux-generic/drv_driver.c
+++ b/platform/linux-generic/drv_driver.c
@@ -232,10 +232,17 @@  odpdrv_device_t odpdrv_device_create(odpdrv_device_param_t *param)
 	return ODPDRV_DEVICE_INVALID;
 }
 
-void odpdrv_device_destroy(odpdrv_device_t dev)
+int odpdrv_device_destroy(odpdrv_device_t dev,
+			  void (*callback)(void *enum_dev), uint32_t flags)
 {
 	if (dev == ODPDRV_DEVICE_INVALID)
 		ODP_ERR("Invalid device\n");
+	if (callback != NULL)
+		ODP_ERR("Callback not supported yet\n");
+	if (flags != 0)
+		ODP_ERR("flags not supported yet\n");
+
+	return 0;
 }
 
 odpdrv_devio_t odpdrv_devio_register(odpdrv_devio_param_t *param)