CF - restore docs folder from master_v1.x

docs/development/Configuration Format.md

@@ -0,0 +1,70 @@
+# Configuration Format
+
+The configuration format and external protocol use some of the same concepts
+as SAE J1939.  A parameter group (PG) is a set of parameters belonging
+to the same topic and are stored and sent together.  A parameter group
+instance has a unique parameter group number (PGN).  Each parameter
+also has a suspect parameter number (SPN) which can be used to get or
+set a parameter directly.
+
+When used as on-wire formats structures should be packed to give the
+same in storage, in memory, and on-wire format.  However care must be taken
+over memory alignment issues when packing structures.
+
+The PGs can be defined on a system-wide basis on a profile specific basis.
+profiles can be activated on the fly.
+
+The storage consists of a header, zero or more PGs, a footer and a checksum.
+To keep the RAM usage low, the parameters are written directly to flash
+which means that things that are only known at the end, such as the
+size are stored in the footer. The checksum is written after the footer.
+
+The header holds:
+
+* The format number.  This is bumped on incompatible changes.
+
+Each stored PG holds:
+
+* The size of this record
+* The PGN
+* Version number
+* Profile number
+* Flags
+* The record format.  This is bumped on incompatible changes.
+* The PG data
+
+The footer holds:
+
+* A zero to mark the end of data
+
+The checksum is based on the header, PGs, and footer.
+
+The PG registrations hold similar but not identical information (e.g. the profile
+number is not known until it is stored).
+
+## Initialiion function.
+
+All fields are reset to 0 upon initialisation and then if a reset function is
+defined for the group then initial settings can be defined by the system.
+
+## Upgrading
+
+Upgrades are done at the PG level and are detected by a difference in
+size or version.  New fields can be added to the end of the parameter group.
+The reset and initialisation function is called before upgrading so new
+fields will first be reset to 0 and then initialised by the system if defined.
+
+Note: Currently the code does not check the version field.
+ 
+## Downgrading
+
+Downgrades are done at the PG level.  Any trailing, unrecognised
+fields will be silently dropped on load.  Saving the config back to
+flash will discard these unrecognised fields.
+
+## Incompatible changes
+
+An incompatible change is where a field is inserted, deleted from the
+middle, reordered, resized (including changing the size of a contained array),
+or has the meaning changed.  Such changes should be handled by bumping the 
+PG version field or allocating a new PGN.