added more comments

framework/rsc_enum.h

@@ -1,6 +1,8 @@
 //
 // Created by MightyPork on 2018/01/06.
 //
+// Enum of all defined resources
+//
 
 #ifndef GEX_F072_RSC_ENUM_H
 #define GEX_F072_RSC_ENUM_H
@@ -31,6 +33,7 @@
 // X(HDMI_CEC)
 // X(COMP1) X(COMP2) X(COMP3) X(COMP4) X(COMP5) X(COMP6) X(COMP7)
 
+// GPIO resources have names generated dynamically to save ROM
 #define XX_RESOURCES_GPIO \
     X(PA0) X(PA1) X(PA2) X(PA3) X(PA4) X(PA5) X(PA6) X(PA7) \
     X(PA8) X(PA9) X(PA10) X(PA11) X(PA12) X(PA13) X(PA14) X(PA15) \
@@ -45,13 +48,15 @@
     X(PF0) X(PF1) X(PF2) X(PF3) X(PF4) X(PF5) X(PF6) X(PF7) \
     X(PF8) X(PF9) X(PF10) X(PF11) X(PF12) X(PF13) X(PF14) X(PF15) \
 
+// EXTI resources have names generated dynamically to save ROM
 #define XX_RESOURCES_EXTI \
     X(EXTI0) X(EXTI1) X(EXTI2) X(EXTI3) X(EXTI4) X(EXTI5) X(EXTI6) X(EXTI7) \
     X(EXTI8) X(EXTI9) X(EXTI10) X(EXTI11) X(EXTI12) X(EXTI13) X(EXTI14) X(EXTI15)
 
-
+/** Resource typedef for cleaner code */
 typedef enum hw_resource Resource;
 
+/** Enum of all resources */
 enum hw_resource {
 #define X(res_name) R_##res_name,
     XX_RESOURCES
@@ -62,35 +67,62 @@ enum hw_resource {
     RESOURCE_COUNT = R_NONE,
 };
 
+/** Length of the resource map */
 #define RSCMAP_LEN ((RESOURCE_COUNT/8)+1)
 
+/**
+ * Resource map is a bitfield byte array located in all component instances.
+ * Each bit corresponds to one resource claimed by the unit.
+ */
 typedef uint8_t ResourceMap[RSCMAP_LEN];
 
-static inline bool rscmap_is_free(ResourceMap *rscmap, Resource rsc)
+/**
+ * Check if a resource is free
+ *
+ * @param rscmap - resource map to look into
+ * @param rsc - tested resource
+ * @return is free
+ */
+static inline bool rscmap_is_free(const ResourceMap *rscmap, Resource rsc)
 {
-    return (0 == ((*rscmap)[((rsc)>>3)&0xFF] & (1<<((rsc)&0x7))));
+    return (0 == ((*rscmap)[(rsc >> 3) & 0xFF] & (1 << (rsc & 0x7))));
 }
 
-static inline bool rscmap_is_held(ResourceMap *rscmap, Resource rsc)
+/**
+ * Check if a resource is held
+ *
+ * @param rscmap - resource map to look into
+ * @param rsc - tested resource
+ * @return is not free
+ */
+static inline bool rscmap_is_held(const ResourceMap *rscmap, Resource rsc)
 {
     return !rscmap_is_free(rscmap, rsc);
 }
 
+/**
+ * Claim a resource in a resource map
+ *
+ * @param rscmap - resource map to modify
+ * @param rsc - resource to claim
+ */
 static inline void rscmap_claim(ResourceMap *rscmap, Resource rsc)
 {
-    (*rscmap)[((rsc)>>3)&0xFF] |= (1<<((rsc)&0x7));
+    (*rscmap)[(rsc >> 3) & 0xFF] |= (1 << (rsc & 0x7));
 }
 
+/**
+ * Release a resource in a resource map
+ *
+ * @param rscmap - resource map to modify
+ * @param rsc - resource to release
+ */
 static inline void rscmap_free(ResourceMap *rscmap, Resource rsc)
 {
-    (*rscmap)[((rsc)>>3)&0xFF] &= ~(1<<((rsc)&0x7));
+    (*rscmap)[(rsc >> 3) & 0xFF] &= ~(1 << (rsc & 0x7));
 }
 
-//#define RSC_IS_FREE(rscmap, rsc) (0 == (rscmap[((rsc)>>3)&0xFF] & (1<<((rsc)&0x7))))
-//#define RSC_IS_HELD(rscmap, rsc) (!RSC_IS_FREE(rscmap, rsc))
-//#define RSC_CLAIM(rscmap, rsc)   do { rscmap[((rsc)>>3)&0xFF] |= (1<<((rsc)&0x7)); } while(0)
-//#define RSC_FREE(rscmap, rsc)   do { rscmap[((rsc)>>3)&0xFF] &= ~(1<<((rsc)&0x7)); } while(0)
-
+// helper macros
 #define RSC_IS_FREE(rscmap, rsc) rscmap_is_free(&rscmap, (rsc))
 #define RSC_IS_HELD(rscmap, rsc) rscmap_is_held(&rscmap, (rsc))
 #define RSC_CLAIM(rscmap, rsc)   rscmap_claim(&rscmap, (rsc))

framework/settings.c

@@ -83,7 +83,7 @@ static bool savebuf_ovhandler(PayloadBuilder *pb, uint32_t more)
     return true;
 }
 
-/** Save settings to flash */
+// Save settings to flash
 void settings_save(void)
 {
     HAL_StatusTypeDef hst;
@@ -222,6 +222,7 @@ static void savebuf_flush(PayloadBuilder *pb, bool final)
 
 // ---------------------------------------------------------------
 
+/** Generate a file header */
 static void gex_file_preamble(IniWriter *iw, const char *filename)
 {
 // File header
@@ -231,6 +232,7 @@ static void gex_file_preamble(IniWriter *iw, const char *filename)
     iw_cmt_newline(iw);
 }
 
+/** Generate a config file header (write instructions) */
 static void ini_preamble(IniWriter *iw, const char *filename)
 {
     gex_file_preamble(iw, filename);
@@ -296,6 +298,7 @@ void settings_load_ini_begin(void)
     SystemSettings.loading_inifile = 0;
 }
 
+
 void settings_load_ini_key(const char *restrict section, const char *restrict key, const char *restrict value)
 {
 //    dbg("[%s] %s = %s", section, key, value);
@@ -344,6 +347,7 @@ void settings_load_ini_key(const char *restrict section, const char *restrict ke
     }
 }
 
+
 void settings_load_ini_end(void)
 {
     if (SystemSettings.loading_inifile == 'U') {

framework/settings.h

@@ -1,6 +1,8 @@
 //
 // Created by MightyPork on 2017/11/26.
 //
+// This module manages the INI and binary settings storage.
+//
 
 #ifndef GEX_SETTINGS_H
 #define GEX_SETTINGS_H

framework/system_settings.h

@@ -1,6 +1,8 @@
 //
 // Created by MightyPork on 2017/12/02.
 //
+// SYSTEM.INI system settings
+//
 
 #ifndef GEX_SYSTEM_SETTINGS_H
 #define GEX_SYSTEM_SETTINGS_H
@@ -10,6 +12,9 @@
 #include "utils/payload_parser.h"
 #include "utils/payload_builder.h"
 
+/**
+ * Struct of the global system settings storage
+ */
 struct system_settings {
     bool visible_vcom;
     bool ini_comments;
@@ -20,6 +25,7 @@ struct system_settings {
     volatile char loading_inifile; // S-system, U-units
 };
 
+/** Global system settings storage */
 extern struct system_settings SystemSettings;
 
 /**

framework/unit.h

@@ -1,6 +1,8 @@
 //
 // Created by MightyPork on 2017/11/24.
 //
+// Structures and basic scaffolding for defining unit drivers
+//
 
 #ifndef GEX_UNIT_H
 #define GEX_UNIT_H
@@ -12,18 +14,27 @@
 #include "utils/payload_parser.h"
 #include "rsc_enum.h"
 
+/** Helper macro that returns E_BAD_UNIT_TYPE if unit is not of the given type */
 #define CHECK_TYPE(_unit, _driver) do { \
-    if ((_unit->driver) != (_driver)) \
+    if (((_unit)->driver) != (_driver)) \
         return E_BAD_UNIT_TYPE; \
 } while (0)
 
+/** Shared unit scratch buffer */
 extern char unit_tmp512[UNIT_TMP_LEN]; // temporary static buffer - not expected to be accessed asynchronously
 // TODO add mutex?
 
+/** Unit typedef - a instance */
 typedef struct unit Unit;
+
+/** Unit driver typedef - type handlers / props object */
 typedef struct unit_driver UnitDriver;
 
+/**
+ * Unit instance structure
+ */
 struct unit {
+    /** Reference to the used driver */
     const UnitDriver *driver;
 
     /** Unit name (used in error messages) */
@@ -46,7 +57,10 @@ struct unit {
     /** Bit-map of held resources */
     ResourceMap resources;
 
+    /** Tick interval to run the updateTick() function, if defined */
     uint16_t tick_interval;
+
+    /** Current number of ticks since last interval completion */
     uint16_t _tick_cnt;
 };
 
@@ -125,8 +139,7 @@ struct unit_driver {
 
 /**
  * De-init a partially initialized unit (before 'init' succeeds)
- * This releases all held resources and frees the *data,
- * if it looks like it has been dynamically allocated.
+ * This releases all held resources and frees *data and *name.
  *
  * Does NOT free the unit struct itself
  *

framework/unit_base.h

@@ -1,6 +1,9 @@
 //
 // Created by MightyPork on 2017/12/09.
 //
+// This is a common include file used in unit drivers to avoid repeating all the
+// needed includes everywhere.
+//
 
 #include "platform.h"
 #include "unit.h"

framework/unit_registry.c

@@ -40,6 +40,7 @@ static int32_t unit_count = -1;
 
 // ---
 
+
 void ureg_add_type(const UnitDriver *driver)
 {
     bool suc = true;
@@ -72,6 +73,7 @@ void ureg_add_type(const UnitDriver *driver)
     ureg_tail = re;
 }
 
+
 /** Free unit in a list entry (do not free the list entry itself!) */
 static void free_le_unit(UlistEntry *le)
 {
@@ -84,6 +86,7 @@ static void free_le_unit(UlistEntry *le)
     free_ck(pUnit->name);
 }
 
+
 /** Add unit to the list, updating references as needed */
 static void add_unit_to_list(UlistEntry *le)
 {
@@ -96,6 +99,7 @@ static void add_unit_to_list(UlistEntry *le)
     ulist_tail = le;
 }
 
+
 // create a unit instance (not yet loading or initing - just pre-init)
 Unit *ureg_instantiate(const char *driver_name)
 {
@@ -141,6 +145,7 @@ Unit *ureg_instantiate(const char *driver_name)
     return NULL;
 }
 
+
 void ureg_save_units(PayloadBuilder *pb)
 {
     assert_param(pb->ok);
@@ -171,6 +176,7 @@ void ureg_save_units(PayloadBuilder *pb)
     } // end units list
 }
 
+
 bool ureg_load_units(PayloadParser *pp)
 {
     bool suc;
@@ -251,6 +257,7 @@ void ureg_remove_all_units(void)
     unit_count = -1;
 }
 
+
 /** Create unit instances from the [UNITS] overview section */
 bool ureg_instantiate_by_ini(const char *restrict driver_name, const char *restrict names)
 {
@@ -297,6 +304,7 @@ bool ureg_instantiate_by_ini(const char *restrict driver_name, const char *restr
     return false;
 }
 
+
 /** Load unit key-value */
 error_t ureg_load_unit_ini_key(const char *restrict name,
                             const char *restrict key,
@@ -316,6 +324,7 @@ error_t ureg_load_unit_ini_key(const char *restrict name,
     return E_NO_SUCH_UNIT;
 }
 
+
 /** Finalize units init. Returns true if all inited OK. */
 bool ureg_finalize_all_init(void)
 {
@@ -353,6 +362,7 @@ bool ureg_finalize_all_init(void)
     return suc;
 }
 
+/** helper foir ureg_build_ini() */
 static void export_unit_do(UlistEntry *li, IniWriter *iw)
 {
     Unit *const pUnit = &li->unit;
@@ -379,6 +389,7 @@ static void export_unit_do(UlistEntry *li, IniWriter *iw)
     pUnit->driver->cfgWriteIni(pUnit, iw);
 }
 
+
 // unit to INI
 void ureg_build_ini(IniWriter *iw)
 {
@@ -433,6 +444,7 @@ void ureg_build_ini(IniWriter *iw)
     }
 }
 
+
 // count units
 uint32_t ureg_get_num_units(void)
 {
@@ -450,6 +462,7 @@ uint32_t ureg_get_num_units(void)
     return (uint32_t) unit_count;
 }
 
+
 extern osMutexId mutScratchBufferHandle;
 
 /** Deliver message to it's destination unit */
@@ -497,6 +510,7 @@ void ureg_deliver_unit_request(TF_Msg *msg)
     assert_param(osOK == osMutexRelease(mutScratchBufferHandle));
 }
 
+
 /** Send a response for a unit-list request */
 void ureg_report_active_units(TF_ID frame_id)
 {
@@ -542,6 +556,7 @@ void ureg_report_active_units(TF_ID frame_id)
     free_ck(buff);
 }
 
+
 Unit *ureg_get_rsc_owner(Resource resource)
 {
     UlistEntry *li = ulist_head;
@@ -558,6 +573,7 @@ Unit *ureg_get_rsc_owner(Resource resource)
     return NULL;
 }
 
+
 void ureg_print_unit_resources(IniWriter *iw)
 {
     if (iw->count == 0) return;
@@ -584,6 +600,7 @@ void ureg_print_unit_resources(IniWriter *iw)
     iw_newline(iw);
 }
 
+
 void ureg_tick_units(void)
 {
     UlistEntry *li = ulist_head;

framework/unit_registry.h

@@ -1,12 +1,15 @@
 //
 // Created by MightyPork on 2017/11/26.
 //
+// Unit registry. This is a storage for dynamically allocated user units,
+// handling units init, deinit and message passing.
+//
 
 #ifndef GEX_UNIT_REGISTRY_H
 #define GEX_UNIT_REGISTRY_H
 
-#include <TinyFrame/TinyFrame.h>
 #include "platform.h"
+#include <TinyFrame/TinyFrame.h>
 #include "unit.h"
 
 /**