From b2ead539bfad8d353208fa4cf0723d4581c6d60c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Hru=C5=A1ka?= Date: Wed, 24 Jan 2018 23:04:05 +0100 Subject: [PATCH] added more comments --- framework/rsc_enum.h | 54 +++++++++++++++++++++++++++++-------- framework/settings.c | 6 ++++- framework/settings.h | 2 ++ framework/system_settings.h | 6 +++++ framework/unit.h | 19 ++++++++++--- framework/unit_base.h | 3 +++ framework/unit_registry.c | 17 ++++++++++++ framework/unit_registry.h | 5 +++- 8 files changed, 96 insertions(+), 16 deletions(-) diff --git a/framework/rsc_enum.h b/framework/rsc_enum.h index 3b83e0c..3d4f3cf 100644 --- a/framework/rsc_enum.h +++ b/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)) diff --git a/framework/settings.c b/framework/settings.c index 744bbcf..246a74a 100644 --- a/framework/settings.c +++ b/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') { diff --git a/framework/settings.h b/framework/settings.h index 307129e..c08ad4d 100644 --- a/framework/settings.h +++ b/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 diff --git a/framework/system_settings.h b/framework/system_settings.h index 9953adc..b4b2c65 100644 --- a/framework/system_settings.h +++ b/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; /** diff --git a/framework/unit.h b/framework/unit.h index 961eb2e..8f8d48b 100644 --- a/framework/unit.h +++ b/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 * diff --git a/framework/unit_base.h b/framework/unit_base.h index e145236..5bf2a57 100644 --- a/framework/unit_base.h +++ b/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" diff --git a/framework/unit_registry.c b/framework/unit_registry.c index d6524ea..f0203fb 100644 --- a/framework/unit_registry.c +++ b/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; diff --git a/framework/unit_registry.h b/framework/unit_registry.h index 23ab198..47134e1 100644 --- a/framework/unit_registry.h +++ b/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 #include "platform.h" +#include #include "unit.h" /**