[cdi-devel] [PATCH] Add cdi_provide_device prototype to cdi.h

[Matthew Iselin <matthew@xxxxxxxxxxxxxx>]

Hi,

This patch provides a prototype and initial documentation for the
cdi_provide_device function.

Signed-off-by: Matthew Iselin <matthew@xxxxxxxxxxxxxx>
---
 include/cdi.h |   37 +++++++++++++++++++++++++++++++++++++
 1 files changed, 37 insertions(+), 0 deletions(-)

diff --git a/include/cdi.h b/include/cdi.h
index c77e071..5cbb4a6 100644
--- a/include/cdi.h
+++ b/include/cdi.h
@@ -290,6 +290,43 @@ void cdi_driver_destroy(struct cdi_driver* driver);
  */
 void cdi_driver_register(struct cdi_driver* driver);
 
+/**
+ * \english
+ * Allows a driver to inform the operating system that a new device has become
+ * available.
+ *
+ * The rationale behind cdi_provide_device is to allow controller interfaces
+ * to provide devices on their bus which may not be available through the
+ * conventional PCI bus (for example, a USB mass storage device). This also
+ * allows devices to inform the OS of the presence of other devices outside
+ * of the context of a controller interface, where necessary.
+ *
+ * The operating system should determine which driver to load (or inform of
+ * the new device) based on the cdi_bus_data struct passed. How the operating
+ * system decides which driver to load/inform is not defined by CDI. An example
+ * would be a simple list generated from a script which parses each driver in
+ * the source tree, finds relevant cdi_bus_data structs, and adds them to a
+ * list which maps the structs to a string. The OS can then use that string to
+ * load a driver somehow.
+ *
+ * Whilst CDI could provide a pre-defined list of mappings for operating
+ * systems to use when implementing cdi_provide_device, it was decided that
+ * this would make the interface too rigid. Whilst this method requires a
+ * little more effort from the CDI implementor, it also allows operating
+ * systems to load non-CDI drivers (eg, from a native driver interface) as
+ * defined by the OS-specific mapping list. This would be impossible if CDI
+ * rigidly enforced a specific method.
+ *
+ * Operating systems may also choose to implement cdi_provide_device and then
+ * use it when iterating over the PCI bus in order to load drivers dynamically
+ * (effectively treating coldplug devices as hotplugged before boot).
+ *
+ * @return 0 on success, -1 if an error was encountered, and -2 if no driver
+ * was found for the device.
+ * \endenglish
+ */
+int cdi_provide_device(struct cdi_bus_data* device);
+
 #endif
 
 /*\@}*/
-- 
1.6.4.msysgit.0