From 8e9c653090c33ca04af04620fee52bd0c54b5005 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Hru=C5=A1ka?= Date: Wed, 24 Jan 2018 22:09:42 +0100 Subject: [PATCH] Doc comments and explanations --- comm/messages.h | 9 ++++- comm/msg_bulkread.c | 2 +- comm/msg_bulkread.h | 2 + comm/msg_bulkwrite.c | 2 +- comm/msg_bulkwrite.h | 6 +++ comm/msg_responses.c | 2 + comm/msg_responses.h | 2 + framework/resources.c | 51 ++++++------------------- framework/resources.h | 88 +++++++++++++++++++++++++++++++++++++++---- 9 files changed, 115 insertions(+), 49 deletions(-) diff --git a/comm/messages.h b/comm/messages.h index c75acf5..5331baa 100644 --- a/comm/messages.h +++ b/comm/messages.h @@ -1,6 +1,12 @@ // // Created by MightyPork on 2017/11/21. // +// This is the only file to include from the comm/ folder directly. +// Provides TinyFrame message types, utilities for forming payloads, +// bulk read and write routines. +// +// See the other headers in the folder for prototypes. +// #ifndef GEX_MESSAGES_H #define GEX_MESSAGES_H @@ -36,9 +42,10 @@ enum Message_Types_ { MSG_PERSIST_CFG = 0x23, //!< Write current settings to Flash (the equivalent of replacing the lock jumper) }; +/** The shared USB-serial TinyFrame instance */ extern TinyFrame *comm; -// Must be after the enum because it's used in the header file. +// those must be after the enum because it's used in the header files #include "msg_responses.h" #include "msg_bulkread.h" #include "msg_bulkwrite.h" diff --git a/comm/msg_bulkread.c b/comm/msg_bulkread.c index 15dfd0f..a0b4ea7 100644 --- a/comm/msg_bulkread.c +++ b/comm/msg_bulkread.c @@ -68,7 +68,7 @@ close: return TF_CLOSE; } -/** Start the bulk read flow */ + void bulkread_start(TinyFrame *tf, BulkRead *bulk) { assert_param(bulk); diff --git a/comm/msg_bulkread.h b/comm/msg_bulkread.h index eb9fefe..d8ca9ee 100644 --- a/comm/msg_bulkread.h +++ b/comm/msg_bulkread.h @@ -1,6 +1,8 @@ // // Created by MightyPork on 2017/12/23. // +// Bulk read (providing data for bulk read by the PC) +// #ifndef GEX_F072_MSG_BULKREAD_H #define GEX_F072_MSG_BULKREAD_H diff --git a/comm/msg_bulkwrite.c b/comm/msg_bulkwrite.c index 1ef4f9f..f2453d9 100644 --- a/comm/msg_bulkwrite.c +++ b/comm/msg_bulkwrite.c @@ -62,7 +62,7 @@ close: return TF_CLOSE; } -/** Start the bulk write flow */ + void bulkwrite_start(TinyFrame *tf, BulkWrite *bulk) { assert_param(bulk); diff --git a/comm/msg_bulkwrite.h b/comm/msg_bulkwrite.h index b1c2121..3e5715e 100644 --- a/comm/msg_bulkwrite.h +++ b/comm/msg_bulkwrite.h @@ -1,10 +1,16 @@ // // Created by MightyPork on 2017/12/23. // +// Bulk write (receiving bulk write from the PC) +// #ifndef GEX_F072_MSG_BULKWRITE_H #define GEX_F072_MSG_BULKWRITE_H +#ifndef GEX_MESSAGES_H +#error "Include messages.h instead!" +#endif + #include typedef struct bulk_write BulkWrite; diff --git a/comm/msg_responses.c b/comm/msg_responses.c index a59b0d8..ed03d32 100644 --- a/comm/msg_responses.c +++ b/comm/msg_responses.c @@ -38,6 +38,7 @@ void com_respond_ok(TF_ID frame_id) com_respond_buf(frame_id, MSG_SUCCESS, NULL, 0); } + void com_send_pb(TF_TYPE type, PayloadBuilder *pb) { uint32_t len; @@ -45,6 +46,7 @@ void com_send_pb(TF_TYPE type, PayloadBuilder *pb) com_send_buf(type, buf, len); } + void com_send_buf(TF_TYPE type, const uint8_t *buf, uint32_t len) { TF_Msg msg; diff --git a/comm/msg_responses.h b/comm/msg_responses.h index f91f2c9..2a70521 100644 --- a/comm/msg_responses.h +++ b/comm/msg_responses.h @@ -1,6 +1,8 @@ // // Created by MightyPork on 2017/12/22. // +// Routines for sending TinyFrame responses. +// #ifndef GEX_F072_MSG_RESPONSES_H #define GEX_F072_MSG_RESPONSES_H diff --git a/framework/resources.c b/framework/resources.c index 96c2181..7ab418e 100644 --- a/framework/resources.c +++ b/framework/resources.c @@ -25,7 +25,7 @@ const char *const rsc_names[] = { // (determines the logic in the name generation code below) COMPILER_ASSERT(R_EXTI0 > R_PA0); -/** Get rsc name */ + const char * rsc_get_name(Resource rsc) { assert_param(rsc < RESOURCE_COUNT); @@ -51,7 +51,7 @@ const char * rsc_get_name(Resource rsc) return rsc_names[rsc]; } -/** Get rsc owner name */ + const char * rsc_get_owner_name(Resource rsc) { assert_param(rsc < RESOURCE_COUNT); @@ -61,9 +61,7 @@ const char * rsc_get_owner_name(Resource rsc) return pUnit->name; } -/** - * Initialize the resources registry - */ + void rsc_init_registry(void) { for(uint32_t i = 0; i < RSCMAP_LEN; i++) { @@ -73,13 +71,7 @@ void rsc_init_registry(void) rsc_initialized = true; } -/** - * Claim a resource for a unit - * - * @param unit - claiming unit - * @param rsc - resource to claim - * @return true on successful claim - */ + error_t rsc_claim(Unit *unit, Resource rsc) { assert_param(rsc_initialized); @@ -113,14 +105,7 @@ error_t rsc_claim(Unit *unit, Resource rsc) return E_SUCCESS; } -/** - * Claim a range of resources for a unit (useful for GPIO) - * - * @param unit - claiming unit - * @param rsc0 - first resource to claim - * @param rsc1 - last resource to claim - * @return true on complete claim, false if any failed (none are claimed in that case) - */ + error_t rsc_claim_range(Unit *unit, Resource rsc0, Resource rsc1) { assert_param(rsc_initialized); @@ -136,6 +121,7 @@ error_t rsc_claim_range(Unit *unit, Resource rsc0, Resource rsc1) return E_SUCCESS; } + error_t rsc_claim_gpios(Unit *unit, char port_name, uint16_t pins) { bool suc = true; @@ -151,6 +137,7 @@ error_t rsc_claim_gpios(Unit *unit, char port_name, uint16_t pins) return E_SUCCESS; } + error_t rsc_claim_pin(Unit *unit, char port_name, uint8_t pin) { bool suc = true; @@ -160,12 +147,7 @@ error_t rsc_claim_pin(Unit *unit, char port_name, uint8_t pin) return E_SUCCESS; } -/** - * Free a resource for other use - * - * @param unit - owning unit; if not null, free only resources claimed by this unit - * @param rsc - resource to free - */ + void rsc_free(Unit *unit, Resource rsc) { assert_param(rsc_initialized); @@ -196,13 +178,7 @@ void rsc_free(Unit *unit, Resource rsc) RSC_FREE(global_rscmap, rsc); } -/** - * Free a range of resources (useful for GPIO) - * - * @param unit - owning unit; if not null, free only resources claimed by this unit - * @param rsc0 - first resource to free - * @param rsc1 - last resource to free - */ + void rsc_free_range(Unit *unit, Resource rsc0, Resource rsc1) { assert_param(rsc_initialized); @@ -215,12 +191,7 @@ void rsc_free_range(Unit *unit, Resource rsc0, Resource rsc1) } } -/** - * Tear down a unit - release all resources owned by the unit. - * Also de-init all GPIOs - * - * @param unit - unit to tear down; free only resources claimed by this unit - */ + void rsc_teardown(Unit *unit) { assert_param(rsc_initialized); @@ -235,6 +206,8 @@ void rsc_teardown(Unit *unit) } } + +// build the pins part of the PINOUT.TXT file void rsc_print_all_available(IniWriter *iw) { if (iw->count == 0) return; diff --git a/framework/resources.h b/framework/resources.h index 3e3e5b5..2fec7a3 100644 --- a/framework/resources.h +++ b/framework/resources.h @@ -1,6 +1,16 @@ // // Created by MightyPork on 2017/11/24. // +// Resource repository. Provides routines for claiming and releasing resources, +// resource listing, owner look-up etc. +// +// Resource is a peripheral or a software facility with exclusive access. +// +// Resources are assigned to: +// - PLATFORM if they're not available +// - SYSTEM if they're claimed internally (e.g. status LED pin) +// - individual user-defined units +// #ifndef GEX_RESOURCES_H #define GEX_RESOURCES_H @@ -10,18 +20,45 @@ #include "rsc_enum.h" #if DEBUG_RSC -#define rsc_dbg(fmt, ...) dbg("[RSC] "fmt, ##__VA_ARGS__) + #define rsc_dbg(fmt, ...) dbg("[RSC] "fmt, ##__VA_ARGS__) #else -#define rsc_dbg(fmt, ...) + #define rsc_dbg(fmt, ...) #endif -#define CHECK_SUC() do { if (!suc) return false; } while (0) - +/** + * Initialize the repository. Mark all resources as claimed by PLATFORM. + */ void rsc_init_registry(void); +/** + * Claim a GPIO using port name and pin number. + * + * @param unit - claiming unit + * @param port_name - port (eg. 'A') + * @param pin - pin number 0-15 + * @return success + */ error_t rsc_claim_pin(Unit *unit, char port_name, uint8_t pin); + +/** + * Claim a resource by the Resource enum + * + * @param unit - claiming unit + * @param rsc - resource to claim + * @return success + */ error_t rsc_claim(Unit *unit, Resource rsc); + +/** + * Claim a range of resources (use for resources of the same type, e.g. USART1-5) + * + * @param unit - claiming unit + * @param rsc0 - first resource to claim + * @param rsc1 - last resource to claim + * @return success (E_SUCCESS = complete claim) + */ error_t rsc_claim_range(Unit *unit, Resource rsc0, Resource rsc1); + /** * Claim GPIOs by bitmask and port name, atomically. * Tear down the unit on failure. @@ -29,20 +66,57 @@ error_t rsc_claim_range(Unit *unit, Resource rsc0, Resource rsc1); * @param unit - claiming unit * @param port_name - port (eg. 'A') * @param pins - pins, bitmask - * @return success + * @return success (E_SUCCESS = complete claim) */ error_t rsc_claim_gpios(Unit *unit, char port_name, uint16_t pins); +/** + * Release all resources held by a unit, de-init held GPIOs + * + * @param unit - unit to tear down + */ void rsc_teardown(Unit *unit); + +/** + * Release a resource by the Resource enum + * + * @param unit - holding unit, NULL to ignore + * @param rsc - resource to release + */ void rsc_free(Unit *unit, Resource rsc); + +/** + * Release a range of resources (use for resources of the same type, e.g. USART1-5) + * + * @param unit - releasing unit + * @param rsc0 - first resource to release + * @param rsc1 - last resource to release + */ void rsc_free_range(Unit *unit, Resource rsc0, Resource rsc1); +/** + * Get name of a resource by the Resource enum. + * Uses a static buffer, DO NOT store the returned pointer. + * + * @param rsc - resource to inspect + * @return resource name (eg. PA1) + */ const char * rsc_get_name(Resource rsc); -/** Get rsc owner name */ +/** + * Get rsc owner name + * + * @param rsc - resource to inspect + * @return name of the holding unit, or "NULL" (string) + */ const char * rsc_get_owner_name(Resource rsc); -/** Print all available resource names */ +/** + * Print all available resource names + * (this is the pins part of the PINOUT.TXT file) + * + * @param iw - writer to use + */ void rsc_print_all_available(IniWriter *iw); #endif //GEX_RESOURCES_H