[cdi-devel] [PATCH] Documentation: Add general interface description (German)

[Kevin Wolf <kevin@xxxxxxxxxx>]

Start documentation on general subjects that cannot be associated with
any module or data structure. The page is linked from the Doxygen main
page.

Signed-off-by: Kevin Wolf <kevin@xxxxxxxxxx>
---
 doc/doc.h       |   56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/doxyfile.in |    2 +-
 2 files changed, 57 insertions(+), 1 deletions(-)
 create mode 100644 doc/doc.h

diff --git a/doc/doc.h b/doc/doc.h
new file mode 100644
index 0000000..d1f60e5
--- /dev/null
+++ b/doc/doc.h
@@ -0,0 +1,56 @@
+/**
+ * \mainpage
+ * - \ref general_interface
+ */
+
+/**
+ * \page general_interface Allgemeine Schnittstellenbeschreibung
+ *
+ * Diese Seite beschreibt allgemeine Regeln für das Zusammenspiel von Treibern
+ * und Betriebssystem, die nicht einem bestimmtem Modul oder einer bestimmten
+ * Datenstruktur zugeordnet werden können.
+ *
+ * Die zwei wesentlichen Teile sind Bedingungen, die das Betriebssystem auf
+ * Quellcode-Ebene garantieren muss (z.B. Bereitstellung von bestimmten
+ * Funktionen) und Bedingungen, die zur Laufzeit gelten.
+ *
+ * \section gi_source Quellcode-Ebene
+ * \subsection gi_source_naming Namensregeln
+ * Um Namenskonflikte zu vermeiden, sind folgende Regeln zu beachten:
+ * - Ã?ffentliche Namen der CDI-Implementierung (d.h. global sichtbare Namen
+ *   und in CDI-Headerdateien verwendete Namen) beginnen mit cdi_ oder CDI_.
+ * - Ã?ffentliche Namen eines CDI-Treibers beginnen mit dem Treibernamen
+ *   gefolgt von einem Unterstrich (z.B. e1000_send_packet)
+ *
+ * \subsection gi_source_libc Funktionen der C-Standardbibliothek
+ * Die CDI-Implementierung muss keine vollständige C-Standardbibliothek zur
+ * Verfügung stellen. Treiber müssen sich auf folgende Teile beschränken
+ * (oder die Benutzung weiterer Funktionen durch \#ifdef optional machen):
+ * - Alles aus stddef.h
+ * - Alles aus stdint.h
+ * - Alles aus string.h
+ * - Speicherverwaltungsfunktionen aus stdlib.h: malloc, calloc, realloc, free
+ * - printf-Familie aus stdio.h, ohne fprintf und vfprintf. AuÃ?erdem asprintf.
+ *   \todo Gebrauch von stdio.h einschränken
+ *
+ * \section gi_runtime Laufzeit
+ * \subsection gi_runtime_intr Nebenläufigkeit und Unterbrechungen
+ * Nebenläufigkeit ist das gleichzeitige oder quasi-gleichzeitige Ablaufen von
+ * Code (z.B. Multithreading). Eine Unterbrechung bedeutet, dass ausgeführter
+ * Code angehalten wird, um anderen Code auszuführen, und erst anschlie�end
+ * der angehaltene Code wieder fortgesetzt wird (z.B. Unix-Signale).
+ *
+ * Die Nutzung beider Konzepte erfordert es, dass der Quellcode sich gegen
+ * unerwünschte Effekt wie Race Conditions schützt, z.B. durch Locks. Da die
+ * jeweiligen Methoden OS-abhängig sind und um Treiber einfach zu halten,
+ * gelten für CDI die folgenden Einschränkungen:
+ *
+ * - Treibercode wird niemals unterbrochen. Die einzige Ausnahme ist die
+ *   Funktion cdi_wait_irq, während der IRQ-Handler ausgeführt werden
+ *   dürfen.
+ * - Nebenläufigkeit ist erlaubt, sofern die CDI-Implementierung sicherstellt,
+ *   dass für jedes Gerät gleichzeitig nur eine Funktion ausgeführt wird
+ *   (z.B. durch ein Lock auf das cdi_device). Treiber dürfen nicht davon
+ *   ausgehen, dass irgendwelche Funktionen nebenläufig ausgeführt werden.
+ *   Nebenläufigkeit ist für die Implementierung optional.
+ */
diff --git a/doc/doxyfile.in b/doc/doxyfile.in
index bf51713..af4fad1 100644
--- a/doc/doxyfile.in
+++ b/doc/doxyfile.in
@@ -80,7 +80,7 @@ WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = include
+INPUT                  = include doc/doc.h
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = 
 RECURSIVE              = YES
-- 
1.6.0.2