[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[cdi-devel] [PATCH] Documentation: Document and translate cdi.h
+ Add module documentation for Core module
+ Add some more doxygen commits in cdi.h
+ Add English translations for comments in cdi.h
Signed-off-by: Kevin Wolf <kevin@xxxxxxxxxx>
---
include/cdi.h | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
1 files changed, 196 insertions(+), 8 deletions(-)
diff --git a/include/cdi.h b/include/cdi.h
index d7cd210..629bbd1 100644
--- a/include/cdi.h
+++ b/include/cdi.h
@@ -2,13 +2,99 @@
* Copyright (c) 2007 Kevin Wolf
*
* This program is free software. It comes without any warranty, to
- * the extent permitted by applicable law. You can redistribute it
- * and/or modify it under the terms of the Do What The Fuck You Want
+ * the extent permitted by applicable law. You can redistribute it
+ * and/or modify it under the terms of the Do What The Fuck You Want
* To Public License, Version 2, as published by Sam Hocevar. See
* http://sam.zoy.org/projects/COPYING.WTFPL for more details.
- */
+ */
-/** \addtogroup core */
+/**
+ * \german
+ * Core ist das Basismodul von CDI. Es stellt die grundlegenden Datenstrukturen
+ * und Funktionen bereit, auf die andere Module aufbauen.
+ *
+ * \section Datenstrukturen
+ * CDI basiert auf drei grundlegenden Datenstrukturen. Die einzelnen Module
+ * erweitern diese Strukturen in einer kompatiblen Weise: cdi_net_driver ist
+ * beispielsweise eine Struktur, die cdi_driver als erstes Element enthält, so
+ * dass sie auf cdi_driver gecastet werden kann. Bei den Strukturen handelt es
+ * sich um:
+ *
+ * - cdi_device beschreibt ein allgemeines Gerät. Es hat insbesondere einen
+ * zugehörigen Treiber und eine Adresse, die es in seinem Bus eindeutig
+ * beschreibt.
+ * - cdi_driver beschreibt einen allgemeinen Treiber. Jeder Treiber hat einen
+ * Typ, der beschreibt, zu welchem Modul er gehört und damit auch, in
+ * welchen Datentyp sowohl der Treiber als auch seine Geräte gecastet werden
+ * können. Jeder Treiber hat au�erdem eine Reihe von Funktionspointern, die
+ * es der CDI-Bibliothek erlauben, Funktionen im Treiber aufzurufen (z.B. ein
+ * Netzwerkpaket zu versenden)
+ * - cdi_bus_data enthält busspezifische Informationen zu einem Gerät wie die
+ * Adresse des Geräts auf dem Bus (z.B. bus.dev.func für PCI-Geräte) oder
+ * andere busbezogene Felder enthalten (z.B. Vendor/Device ID). Diese
+ * Struktur wird zur Initialisierung von Geräten benutzt, d.h. wenn das
+ * Gerät noch nicht existiert.
+ *
+ * \section core_init Initialisierung
+ *
+ * Die Initialisierung der Treiber läuft in folgenden Schritten ab:
+ *
+ * -# Initialisierung der Treiber: Es wird der init-Callback jedes Treibers
+ * aufgerufen. AnschlieÃ?end wird der Treiber bei CDI und dem Betriebssystem
+ * registriert, so dass er vor und während der Ausführung von init keine
+ * Anfragen entgegennehmen muss, aber direkt anschlie�end dafür bereit
+ * sein muss.
+ * -# Suche und Initialisierung der Geräte: Für jedes verfügbare Gerät wird
+ * init_device nacheinander für alle Treiber aufgerufen, bis ein Treiber
+ * das Gerät akzeptiert (oder alle Treiber erfolglos versucht wurden).
+ * \n
+ * @todo Für jedes Gerät scan_bus aufrufen und die dabei gefundenen
+ * Geräte wiederum initialisieren.
+ *\endgerman
+ *
+ * \english
+ * The Core module contains the fundamental CDI data structures and functions
+ * on which the other modules are based.
+ *
+ * \section Data structures
+ * CDI is based on three basic structures. The other modules extend these
+ * structures in a compatible way: For example, cdi_net_driver is a structure
+ * that contains a cdi_driver as its first element so that it can be cast to
+ * cdi_device. The structures are:
+ *
+ * - cdi_device describes a device. Amongst others, it contains fields that
+ * reference the corresponding driver and an address that identifies the
+ * device uniquely on its bus.
+ * - cdi_driver describes a driver. It has a type which determines to which
+ * CDI module the driver belongs (and thus which type the struct may be cast
+ * to). Moreover, each driver has some function points which can be used by
+ * the CDI library to call driver functions (e.g. for sending a network
+ * packet)
+ * - cdi_bus_data contains bus specific information on a device, like the
+ * address of the device on the bus (e.g. bus.dev.func for PCI) or other
+ * bus related information (e.g. device/vendor ID). This structure is used
+ * for initialisation of devices, i.e. when the device itself doesn't exist
+ * yet.
+ *
+ * \section core_init Initialisation
+ *
+ * Drivers are initialised in the following steps:
+ *
+ * -# Initialisation of drivers: The init() callback of each driver is called.
+ * After the driver has returned from there, it is registered with CDI and
+ * the operating system. The driver needs not to be able to handle requests
+ * before it has completed its init() call, but it must be prepared for them
+ * immediately afterwards.
+ * -# Search for and initialisation of devices: For each device init_device is
+ * called in the available drivers until a driver accepts the device (or all
+ * of the drivers reject it).
+ * \n
+ * @todo Call scan_bus for each device and initialise possible child devices
+ * \endenglish
+ *
+ *
+ * \defgroup core
+ */
/*\@{*/
#ifndef _CDI_H_
@@ -35,25 +121,102 @@ typedef enum {
struct cdi_driver;
+/**
+ * \german
+ * Beschreibt ein Gerät in Bezug auf den Bus, an dem es hängt. Diese
+ * Informationen enthalten in der Regel eine Busadresse und zusätzliche Daten
+ * wie Device/Vendor ID
+ * \endgerman
+ *
+ * \english
+ * Describes a device in relation to its bus. This information usually contains
+ * a bus address and some additional data like device/vendor ID.
+ * \endenglish
+ *
+ */
struct cdi_bus_data {
cdi_device_type_t bus_type;
};
+/**
+ * \if german
+ * Beschreibt ein Gerät
+ * \elseif english
+ * Describes a device
+ * \endif
+ */
struct cdi_device {
+ /**
+ * \if german
+ * Name des Geräts (eindeutig unter den Geräten desselben Treibers)
+ * \elseif english
+ * Name of the device (must be unique among the devices of the same driver)
+ * \endif
+ */
const char* name;
+
+ /**
+ * \if german
+ * Treiber, der für das Gerät benutzt wird
+ * \elseif english
+ * Driver used for the device
+ * \endif
+ */
struct cdi_driver* driver;
+
+ /**
+ * \if german
+ * Busspezifische Daten zum Gerät
+ * \elseif english
+ * Bus specific data for the device
+ * \endif
+ */
struct cdi_bus_data* bus_data;
// tyndur-spezifisch
void* backdev;
};
+/**
+ * \if german
+ * Beschreibt einen CDI-Treiber
+ * \elseif english
+ * Describes a CDI driver
+ * \endif
+ */
struct cdi_driver {
cdi_device_type_t type;
cdi_device_type_t bus;
const char* name;
+
+ /**
+ * \if german
+ * Enthält alle Geräte (cdi_device), die den Treiber benutzen
+ * \elseif english
+ * Contains all devices (cdi_device) which use this driver
+ * \endif
+ */
cdi_list_t devices;
+ /**
+ * \german
+ * Versucht ein Gerät zu initialisieren. Die Funktion darf von der
+ * CDI-Bibliothek nur aufgerufen werden, wenn bus_data->type dem Typ des
+ * Treibers entspricht
+ *
+ * @return Ein per malloc() erzeugtes neues cdi_device, wenn der Treiber
+ * das Gerät akzeptiert. Wenn er das Gerät nicht unterstützt, gibt er
+ * NULL zurück.
+ * \endgerman
+ *
+ * \english
+ * Tries to initialise a device. The function may only be called by the CDI
+ * library if bus_data->type matches the type of the driver.
+ *
+ * @return A new cdi_device created by malloc() if the driver accepts the
+ * device. NULL if the device is not supported by this driver.
+ * \endenglish
+ */
struct cdi_device* (*init_device)(struct cdi_bus_data* bus_data);
void (*remove_device)(struct cdi_device* device);
@@ -62,30 +225,55 @@ struct cdi_driver {
};
/**
- * Muss vor dem ersten Aufruf einer anderen CDI-Funktion aufgerufen werden.
+ * \german
+ * Treiber, die ihre eigene main-Funktion implemenieren, müssen diese Funktoin
+ * vor dem ersten Aufruf einer anderen CDI-Funktion aufrufen.
* Initialisiert interne Datenstruktur der Implementierung fuer das jeweilige
* Betriebssystem und startet anschliessend alle Treiber.
*
- * Ein wiederholter Aufruf bleibt ohne Effekt.
+ * Ein wiederholter Aufruf bleibt ohne Effekt. Es ist nicht definiert, ob diese
+ * Funktion zurückkehrt.
+ * \endgerman
+ *
+ * \english
+ * Drivers which implement their own main() function must call this function
+ * before they call any other CDI function. It initialises internal data
+ * structures of the CDI implementation and starts all drivers.
+ *
+ * This function takes effect only once, any other calls remain without effect.
+ * It is not defined if this function returns.
+ * \endenglish
*/
void cdi_init(void);
/**
- * Initialisiert die Datenstrukturen fuer einen Treiber
+ * \if german
+ * Initialisiert die Datenstrukturen für einen Treiber
* (erzeugt die devices-Liste)
+ * \elseif english
+ * Initialises the data structures for a driver
+ * \endif
*/
void cdi_driver_init(struct cdi_driver* driver);
/**
- * Deinitialisiert die Datenstrukturen fuer einen Treiber
+ * \if german
+ * Deinitialisiert die Datenstrukturen für einen Treiber
* (gibt die devices-Liste frei)
+ * \elseif english
+ * Deinitialises the data structures for a driver
+ * \endif
*/
void cdi_driver_destroy(struct cdi_driver* driver);
/**
+ * \if german
* Registriert den Treiber fuer ein neues Geraet
*
* @param driver Zu registierender Treiber
+ * \elseif english
+ * Registers a new driver with CDI
+ * \endif
*/
void cdi_driver_register(struct cdi_driver* driver);
--
1.6.0.2