commit 1304b12bd859603ad9f9b68493e1a3257f5e4595
Author: Thomas Schöpping <tschoepp@cit-ec.uni-bielefeld.de>
Date:   Wed Nov 13 13:33:36 2019 +0100

    Revised the realization of AMiRo-LLD interfaces (including periphAL):
     - The periphAL.h file is now part aof AMiRo-LLD and must no be implemented externally.
     - Type definitions, which were described in periphALtypes.h are now included in periphAL.h.
     - Several configuration macros were introduced in order to enable/disable individual modules of periphAL.
     - periphAL version increased to 1.2
     - AMiRo-LLD version increased to 1.1.0
     - README.txt has been updated

diff --git a/README.txt b/README.txt
index f9cf003..ac5b590 100644
--- a/README.txt
+++ b/README.txt
@@ -93,12 +93,17 @@ not present on the AMiRo platform, are highly appreciated.
 The files are structured as follows:
 ./
 │ The project root directory contains this file, a license.html file as well as
-│ a Makefile that allows to easily integrate the project. Furthermore, two
+│ a makefile that allows to easily integrate the project. Furthermore, two
 │ interface headers are provided: amiro-lld.h and periphALtypes.h. These are
 │ entry points for any utilizing superproject, so it is not required (and not
 │ recommended) to include each driver individually.
 │
-├── include/
+├── docs/
+│     UML graphs (using PlantUML; see plantuml.com for further information)
+│     visualize the structure of the AMiRo-LLD project. Doxygen related files
+│     can be used to gererate a documentation of the whole project (wip).
+│
+├── drivers/
 │     For each supported hardware device, there is exactly one directory in this
 │     folder. Further subfolders may contain various versions of a driver (e.g.
 │     'v1/', 'v2/', etc.). By convention the root directory of a driver is named
@@ -107,24 +112,16 @@ The files are structured as follows:
 │     <product_name> is a placeholder for the exact name of the according
 │     hardware, or the product familiy, if the driver is compatible with all
 │     parts.
-│     The root header consequently follows the naming scheme
-│     "alld_<product_name>.h"
-│     and header files within the version folders shall be named like
-│     "alld<product_name>_<driver_version>.h"
-│
-├── source/
-│     Any source files are placed in this directory. Naming conventions for
-│     folders and files are the same as described before for the include
-│     directory, as is the file structure. There is a dedicated folder for each
-│     device and further subfolders for multiple driver versions. Source files
-│     should only be put in these version folders.
+│     Each driver must provide a makefile script, which adds the required
+│     include folders to the AMIROLLD_INC variable and all C source files to the
+│     AMIROLLD_CSRC variable.
 │
 └── templates/
-      AMiRo-LLD requires an implementation of the defined interface and an
-      configuration header to be accessible in the include paths at compile
-      time. Template files for both can be found in this folder. It is
-      recommended to place according implementations of these templated not in
-      the AMiRo-LLD project, but the superproject which includes AMiRo-LLD.
+      AMiRo-LLD expects a configuration header "alldconf.h" to be found in the
+      include paths. An according template for such file can be found here.
+      There is no template for an implementation of periphAL, though. The
+      provided interface header in the root directory (periphAL.h) should give
+      you all required information for such an implementation anyway.
 
 
 
@@ -137,58 +134,67 @@ results, which are portable and maintainable for future use. Whereas the textual
 descriptions of the guides provide additional information about the underlying
 concepts and mechanisms, a short summary is provided at the end of each chapter.
 
+
 3.1  Adding a Device
 --------------------
 
 When adding new device to the project, the very first step is to create the
-according folders in the include/ and source/ directories. For this guide, we
-will add the fictional DEVICE1234. For this example the folders to be created
-are "include/DEVICE1234/" and "source/DEVICE1234/".
-
-The first file should be the root header: "include/DEVICE1234/alld_DEVICE1234.h"
-Have a look at existing drivers and use one of those as template. This header
-should introduce a new configuration to be set in the alldconf.h file and check
-it using the preprocessor. Eventually, another header is included, pointing to
-the selected driver version/implementation.
-
-Such implementations are to be put in further subfolders, e.g.
-"include/DEVICE1234/v1/" and "source/DEVICE1234/v1/". The header and C-source
-files in those folders do not follow a strict scheme, although there are some
-conventions to consider (i.e. naming conventions, cf. chapter 2).
+according folder in the drivers/ directory. For this guide, we will add the
+fictional DEVICE1234. For this example the folders to be created are
+"drivers/DEVICE1234/" and "drivers/DEVICE1234/v1/". In case there already exists
+a driver implementation for this device, but you want to implement another
+version from scratch (not just an update), the version subfolder must be named
+accordingly (e.g. "drivers/DEVICE1234/v42/").
+
+Most drivers will consist of exactly three files:
+ - alld_DEVICE1234.mk
+ - alld_DEVICE1234.h
+ - alld_DEVICE1234.c
+However, some drivers may feature multiple .h and/or .c files or even come with
+additional subfolders. In any case, all those required folders, including the
+driver root folder (i.e. "drivers/DEVICE1234/v1/"), as well as all C source
+files must be added to the according makefile variables AMIROLLD_INC and
+AMIROLLD_CSRC by the makefile script.
+It is highly recommended that files in the driver root directory (i.e.
+"drivers/DEVICE1234/v1/") use the prefix "alld_" in their names. This not only
+helps to achieve an easy to understand file structure, but also prevents
+compilation issues due to naming conflicts of header files.
 
 Summing up, you have to
-1) create device folders.
-2) add a root header.
-3) add further subfolders and implement the driver there.
+1) create device and version folders.
+2) add a makefile script.
+3) add header- and source files as well as subfulders, implementing the diver
 
 
 3.2  Implementing a Driver
 --------------------------
 
-Implementation of a new driver usually is very straight-forward. You most
+Implementation of a new driver usually is very straightforward. You most
 probably have a comprehensive datasheet of the device, or the manufacturer even
 provides a reference driver implementation.
 
 For the former case, you should first write a comprehensive header, containing
 all information like constants, register maps, etc. and according abstract
 access functions (e.g. for reading and writing registers, and convenient access
-to common functionalities). Only the you implement those functions, using
-periphAL to interface any hardware interfaces (e.g. I2C, SPI, etc.).
+to common functionalities). Only then you implement those functions, using
+periphAL to interface any hardware interfaces (e.g. I2C, SPI, etc.) in a
+separate C source file, or 'inline' in the header file itself.
 
 For the latter case, the reference implementation will specify some interface
 functions to interact with the hardware (e.g. I2C, SPI etc.). Even though all
 functionality should be covered by the reference driver, you still need to
-implement those interface functions.
+implement those interface functions and map them to periphAL.
 
 Since AMiRo-LLD does not rely on specific hardware or operating system, the only
 valid way to interact with both is through periphAL. Under no circumstances you
 must use any function of your operating system and directly or indirectly access
 the hardware of your platform. For your driver, there is no knowledge about the
 world beyond periphAL! If periphAL does not provide the function you need, you
-can do the following: 1) Think again if you really need that funcionality or
-whether it can be replicated by existing functions. 2) File a feature request
-to extend periphAL. 3) Write a custom patch that modifies periphAL to meet your
-requirements.
+can do one of the following:
+1) Think again if you really need that funcionality or whether it can be
+   replicated by the existing API.
+2) File a feature request to extend periphAL.
+3) Write a custom patch that modifies periphAL to meet your requirements.
 
 Summing up, you have to
 1) Get and read the datasheet of the device (A) or
