[API-NEXT,07/21] drv: driver: add callback function for device destruction

Message ID 1487768164-43184-8-git-send-email-christophe.milard@linaro.org
State Superseded
Headers show
Series
  • driver items registration and probing
Related show

Commit Message

Christophe Milard Feb. 22, 2017, 12:55 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

Comments

Bill Fischofer Feb. 22, 2017, 10:20 p.m. | #1
On Wed, Feb 22, 2017 at 6:55 AM, Christophe Milard <
christophe.milard@linaro.org> wrote:

> 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(-)

>

> diff --git a/include/odp/drv/spec/driver.h b/include/odp/drv/spec/driver.h

> index a978d12..21a5fe1 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

>


Typo: termination


> +* 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 ee0a75c..f8844f5 100644

> --- a/platform/linux-generic/drv_driver.c

> +++ b/platform/linux-generic/drv_driver.c

> @@ -227,10 +227,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)

> --

> 2.7.4

>

>
Christophe Milard Feb. 27, 2017, 12:56 p.m. | #2
On 22 February 2017 at 23:20, Bill Fischofer <bill.fischofer@linaro.org> wrote:
>

>

> On Wed, Feb 22, 2017 at 6:55 AM, Christophe Milard

> <christophe.milard@linaro.org> wrote:

>>

>> 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(-)

>>

>> diff --git a/include/odp/drv/spec/driver.h b/include/odp/drv/spec/driver.h

>> index a978d12..21a5fe1 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

>

>

> Typo: termination


=> V2

Christophe

>

>>

>> +* 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 ee0a75c..f8844f5 100644

>> --- a/platform/linux-generic/drv_driver.c

>> +++ b/platform/linux-generic/drv_driver.c

>> @@ -227,10 +227,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)

>> --

>> 2.7.4

>>

>

Patch hide | download patch | download mbox

diff --git a/include/odp/drv/spec/driver.h b/include/odp/drv/spec/driver.h
index a978d12..21a5fe1 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 ee0a75c..f8844f5 100644
--- a/platform/linux-generic/drv_driver.c
+++ b/platform/linux-generic/drv_driver.c
@@ -227,10 +227,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)