Changes between Version 15 and Version 16 of DeviceDrivers

Timestamp:

2011-11-14T21:10:04Z (13 years ago)

Author:

Jiri Svoboda

Comment:

dev_add, dev_remove, dev_gone

DeviceDrivers

@@ -68 +68 @@
  * driver_t
  * driver_ops_t
-   * add_device (rename to dev_add)
+   * dev_add
    * dev_remove
    * dev_gone
@@ -74 +74 @@
    * fun_offline
  * ddf_dev_ops_t
+
+Every driver must define a ''driver_t'' structure which links to a ''driver_ops_t'' structure.
+''driver_ops_t'' fields point to various driver entry points. ''dev_add'' is necessary in order
+for the driver to work. ''dev_remove'', ''dev_gone'', ''fun_online'', ''fun_offline'' are required
+in order for the driver to support hot unplug (all drivers should support hot unplug).
+
+=== Driver Entry Points (driver_opts_t) ===
+==== dev_add ====
+{{{
+int (*dev_add)(ddf_dev_t *dev)
+}}}
+This entry point is called by DDF to ask the driver to take ownership of a new device. The driver
+should probe the device to verify that it is there and operational. If not, it should return failure.
+If the device is operational, the driver should take ownership and return EOK. The driver should 
+also allocate soft state and create functions to expose functionality of the device (in case of bus driver
+some of these will correspond to devices currently connected to the bus).
+
+It is up to the driver to which extent it wants to perform these initialization steps
+before or after returning from ''dev_add''. This entry point is mandatory, it must always be implemented.
+
+==== dev_remove ====
+{{{
+int (*dev_remove)(ddf_dev_t *dev)
+}}}
+This entry point is called by DDF to ask the driver to gracefully give up ownership of a device. The driver
+should gracefully terminate any pending operations on the device, quiesce the device and return it
+to some suitable, clean state (from which it could be picked up by ''dev_add'', for example).
+
+The driver must unbind all functions belonging to this device and it should also clean up any
+software state associated with the device. If this entry point is not implemented, it should
+be either set to NULL or it should always return ENOTSUP.
+
+==== dev_gone ====
+{{{
+int (*dev_gone)(ddf_dev_t *dev)
+}}}
+This entry point is called by DDF to inform the driver that connectivity to a device has been lost
+(e.g. because the device has been physically unplugged). The driver must coordinate with its parent
+to terminate any pending operations on the device. The parent will normally not allow any new operations
+to be started and, possibly, it will abort all outstanding operations (or wait for the driver to
+abort them).
+
+The driver must unbind all functions belonging to this device and it should also clean up any
+software state associated with the device. If this entry point is not implemented, it should
+be either set to NULL or it should always return ENOTSUP.
 
 == Device and Function Life Cycle ==