[cdi-devel] [PATCH] doc.h: English translation

[Kevin Wolf <kevin@xxxxxxxxxx>]

Added English translation of the general interface description.

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

diff --git a/doc/doc.h b/doc/doc.h
index d1f60e5..94c4ccc 100644
--- a/doc/doc.h
+++ b/doc/doc.h
@@ -4,6 +4,7 @@
  */
 
 /**
+ * \german
  * \page general_interface Allgemeine Schnittstellenbeschreibung
  *
  * Diese Seite beschreibt allgemeine Regeln für das Zusammenspiel von Treibern
@@ -53,4 +54,58 @@
  *   (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.
+ * \endgerman
+ */
+
+/**
+ * \english
+ * \page general_interface General interface description
+ *
+ * This page describes general rules for the interaction between drivers and
+ * the operating system which are not related to just one specific module or
+ * data structure.
+ *
+ * The two major parts of it are conditions that the operating systems needs to
+ * guarantee on the source code level (e.g. availability of certain functions)
+ * and runtime conditions.
+ *
+ * \section gi_source Source code
+ * \subsection gi_source_naming Naming
+ * In order to avoid name space conflicts, the following rules should be
+ * applied:
+ * - Public names of the CDI implementation (i.e. globally visible symbol names
+ *   and names used in CDI header files) start with cdi_ or CDI_.
+ * - Public names of a CDI driver start with the driver name followed by an
+ *   underscore (e.g. e1000_send_packet)
+ *
+ * \subsection gi_source_libc Functions of the C standard library
+ * The CDI implementation doesn't have to provide a complete C standard
+ * library. Drivers are limited to following parts of the library, which the
+ * CDI implementation must provide:
+ * - Everything in stddef.h
+ * - Everything in stdint.h
+ * - Everything in string.h
+ * - Memory management functions in stdlib.h: malloc, calloc, realloc, free
+ * - printf family in stdio.h, without fprintf and vfprintf. Additionally
+ *   asprintf.
+ *   \todo Further restrictions for stdio.h
+ *
+ * \section gi_runtime Runtime
+ * \subsection gi_runtime_intr Concurrency and interruptions
+ * Concurrency means (seemingly) parallel execution of code (e.g.
+ * multithreading). An interruption means that running code is stopped in order
+ * to execute different code, and only afterwards the stopped code is continued
+ * (e.g. Unix signals).
+ *
+ * Both concepts require that source code is protected against unwanted effects
+ * like race conditions, e.g. by locks. The respective method is OS dependent,
+ * and to keep drivers simple, for CDI the following restrictions are made:
+ *
+ * - Driver code is never interrupted. The only exception is the function
+ *   cdi_wait_irq: While it is running, IRQ handler may be executed.
+ * - The use of threading is allowed if the CDI implementation ensures that for
+ *   each device only one function is executed at the same time (e.g. by
+ *   putting a lock in cdi_device). Drivers may not assume that threading is
+ *   used, it is optional for the CDI implementation.
+ * \endenglish
  */
-- 
1.6.0.2