Readme update

README.md

@@ -3,21 +3,47 @@ Ada bindings for STM32 internals
 
 ## Design directions
 
+Main design goal is a type safety. Specific enumerations and records are used
+in hardware definitions. Common structure of a peripherial module
+is a record with all its registers and
+every register is a record with all its fields. That is every field is
+addressed using scheme `Unit.Register.Field`
+
+While it is generally preferred to have entities same identifiers as in STM's
+user manuals, it is not always possible. So some of them have originel or
+a bit changed name.
+- The identifier clashes with Ada keyword. E. g. `ABORT` bit-field is renamed to `ABRT`.
+- Identifier is not given by UM. This is common case for bit-field values.
+They taken descriptive names based on original UM text.
+- Identifier decomposition and generalization. Bitfield identifiers are
+shortened if they have common part. Also if two or more registers have same or
+analogous fields they commonly share the same record type, thus having same
+field names. Thus RCC's xxxRST, xxxEN and xxxLPEN registers a defined the same
+with RST/EN/LPEN part removed from their bit fields.
+
 ### Compiler implication
 
 `System.Address` should be standard 32 bit byte address as in CPU registers
 and peripherals (DMA etc.).
 
+### Development boards supported
+
+stm32f429disco (stm32f429disc1) -- board available from STM.
+429disco in examples.
+
+STM32F407Z-based board from PiSwords. Widely available from chinese suppliers.
+407z_piswords in examples.
+
 ## Hardware quirks and workarounds
 
 ### APB
 
-APB does not support writes of parts of 32-bit registers.
-The library provides acess to register fields as records.
+APB does not support partial writes to 32-bit registers.
+The library provides access to register fields as records.
 This could lead compiler to emit byte and half-word writes
 to APB registers causing erroneous effects.
 As a workaround those registers should be read to local variable,
-this variable altered, and then written back to hardware.
+this variable altered, and then written back to the hardware.
 GNAT users may not need the workaround, because of its pragma
 `Volatile_Full_Access` used in this library.
 
@@ -33,4 +59,4 @@ as byte- and half-wide writes are not supported by APB. Read STM docs on
 what those accesses actually do.
 
 Currently GPR cannot manage aggregate projects for different targets.
-GNU Make script is used to build whole set of libraries instead.
+GNU Make script is used to build whole set of libraries instead.