[cdi-devel] [PATCH v2 3/5] cdi.h: Add cdi_provide_device_internal_drv()

[Kevin Wolf <kevin@xxxxxxxxxx>]

cdi_provide_device() hasn't been implemented so far because it raises
questions of inter-driver communication in microkernel environments that
aren't trivial to answer.

This patch adds an interface to provide a device that is guaranteed
to be handled by a CDI driver in the same binary, i.e. when passing
pointers works.

This is not meant as a general solution, but only to be used as a means
for the internal organisation of complex drivers where some kind of an
internal bus exists that can neither be exposed by a different driver
nor can its children be handled by a different driver.

Signed-off-by: Kevin Wolf <kevin@xxxxxxxxxx>
---
 include/cdi.h |   50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 50 insertions(+), 0 deletions(-)

diff --git a/include/cdi.h b/include/cdi.h
index cb87786..7c21836 100644
--- a/include/cdi.h
+++ b/include/cdi.h
@@ -358,6 +358,56 @@ void cdi_driver_register(struct cdi_driver* driver);
  */
 int cdi_provide_device(struct cdi_bus_data* device);
 
+/**
+ * \german
+ * Informiert das Betriebssystem, dass ein neues Gerät angeschlossen wurde und
+ * von einem internen Treiber (d.h. einem Treiber, der in dieselbe Binary
+ * gelinkt ist) angesteuert werden muss.
+ *
+ * Diese Funktion kann benutzt werden, um Treibern mit mehreren Komponenten
+ * eine klarere Struktur zu geben (z.B. SATA-Platten als vom AHCI-Controller
+ * getrennte CDI-Geräte zu modellieren).
+ *
+ * Vorsicht: Sie sollte nur benutzt werden, wenn eine enge Kopplung zwischen
+ * Gerät und Untergeräte unvermeidlich ist, da sie voraussetzt, dass beide
+ * Treiber in dieselbe Binary gelinkt sind. Dies mag für monolithische Kernel
+ * kein Problem darstellen, aber CDI wird auch in Betriebssystemen mit anderem
+ * Design benutzt.
+ *
+ * Falls der Treiber noch nicht initialisiert ist, wird er initialisiert, bevor
+ * das neue Gerät erstellt wird.
+ *
+ * @param device Adressinformation für den Treiber, um das Gerät zu finden
+ * @param driver Treiber, der für das Gerät benutzt werden soll
+ *
+ * @return 0 bei Erfolg, -1 im Fehlerfall
+ * \endgerman
+ * \english
+ * Informs the operating system that a new device has become available and
+ * is to be handled by an internal driver (i.e. a driver linked into the same
+ * binary).
+ *
+ * This function can be used to give drivers for devices with multiple
+ * components a clearer structure (e.g. model SATA disks as CDI devices
+ * separate from the AHCI controller).
+ *
+ * Be careful though: It should only be used if a tight coupling between device
+ * and subdevice is unvoidable, as it requires linking the code of both drivers
+ * into the same binary. This might not be a problem for monolithic kernels,
+ * but CDI is used in OSes of different designs.
+ *
+ * If the driver isn't initialised yet, it is initialised before creating the
+ * new device.
+ *
+ * @param device Addressing information for the driver to find the device
+ * @param driver Driver that must be used for this device
+ *
+ * @return 0 on success or -1 if an error was encountered.
+ * \endenglish
+ */
+int cdi_provide_device_internal_drv(struct cdi_bus_data* device,
+                                    struct cdi_driver* driver);
+
 #endif
 
 /*\@}*/
-- 
1.7.7