From ceb658e24602643cf5360d7ef5d6eee9cdabe7b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Hru=C5=A1ka?= Date: Thu, 25 Jan 2018 08:11:27 +0100 Subject: [PATCH] more doc comments --- framework/unit_registry.h | 6 +++--- platform/debug_uart.h | 16 +++++++++++++++ platform/hw_utils.h | 5 +++-- platform/irq_dispatcher.h | 2 ++ platform/lock_jumper.h | 2 ++ platform/plat_init.c | 2 ++ platform/platform.c | 1 - platform/platform.h | 2 +- platform/status_led.h | 2 ++ tasks/sched_queue.h | 43 +++++++++++++++++++++++++++++---------- tasks/task_main.h | 6 ++++++ tasks/task_msg.h | 24 ++++++++++++++++++++-- 12 files changed, 91 insertions(+), 20 deletions(-) diff --git a/framework/unit_registry.h b/framework/unit_registry.h index 47134e1..3146843 100644 --- a/framework/unit_registry.h +++ b/framework/unit_registry.h @@ -1,15 +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. +// Unit registry. This is a storage for a list of unit drivers and dynamically allocated user units. +// Provides handling of units init, deinit and message passing. // #ifndef GEX_UNIT_REGISTRY_H #define GEX_UNIT_REGISTRY_H #include "platform.h" -#include +#include #include "unit.h" /** diff --git a/platform/debug_uart.h b/platform/debug_uart.h index 7971d82..1fc6abb 100644 --- a/platform/debug_uart.h +++ b/platform/debug_uart.h @@ -1,13 +1,29 @@ // // Created by MightyPork on 2017/12/15. // +// Setup and routines for debug printing. +// The actual printf-like functions used for debug printing are in debug.h +// #ifndef GEX_DEBUG_UART_H #define GEX_DEBUG_UART_H +/** + * Pre-init the debug uart + * + * Set up the peripheral for printing, do not claim resources yet because the + * registry is not initialized + */ void DebugUart_PreInit(void); + +/** + * Finalize the init (claim resources) + */ void DebugUart_Init(void); +/** + * Write some bytes via the debug USART + */ void debug_write(const char *buf, uint16_t len); #endif //GEX_DEBUG_UART_H diff --git a/platform/hw_utils.h b/platform/hw_utils.h index abe091f..678ca14 100644 --- a/platform/hw_utils.h +++ b/platform/hw_utils.h @@ -1,8 +1,9 @@ // -// Utilities for parsing pins from settings to LL and resources -// // Created by MightyPork on 2017/12/08. // +// Utilities for parsing pins from settings to LL and resources, +// GPIO init, AF config and some LL driver extensions +// #ifndef GEX_PIN_UTILS_H #define GEX_PIN_UTILS_H diff --git a/platform/irq_dispatcher.h b/platform/irq_dispatcher.h index 76cb731..e278998 100644 --- a/platform/irq_dispatcher.h +++ b/platform/irq_dispatcher.h @@ -1,6 +1,8 @@ // // Created by MightyPork on 2018/01/14. // +// Provides a trampoline system for redirecting IRQ calls to assigned callbacks. +// #ifndef GEX_F072_IRQ_DISPATCHER_H #define GEX_F072_IRQ_DISPATCHER_H diff --git a/platform/lock_jumper.h b/platform/lock_jumper.h index 1f6c651..cc4b5c4 100644 --- a/platform/lock_jumper.h +++ b/platform/lock_jumper.h @@ -1,6 +1,8 @@ // // Created by MightyPork on 2017/12/15. // +// Handling the lock jumper or button (used to make the config filesystem visible to the PC OS) +// #ifndef GEX_LOCK_JUMPER_H #define GEX_LOCK_JUMPER_H diff --git a/platform/plat_init.c b/platform/plat_init.c index 12bf0cb..8b3660c 100644 --- a/platform/plat_init.c +++ b/platform/plat_init.c @@ -1,6 +1,8 @@ // // Created by MightyPork on 2017/11/26. // +// Initialize the platform. Belongs to platform.h +// #include "platform.h" #include "comm/messages.h" diff --git a/platform/platform.c b/platform/platform.c index 9ea3b0d..6579e39 100644 --- a/platform/platform.c +++ b/platform/platform.c @@ -2,7 +2,6 @@ // Created by MightyPork on 2017/11/26. // -#include #include "platform.h" #include "usbd_core.h" #include "USB/usb_device.h" diff --git a/platform/platform.h b/platform/platform.h index a4bbe58..f9199df 100644 --- a/platform/platform.h +++ b/platform/platform.h @@ -37,7 +37,7 @@ // --- /** - * Init the platform + * Init the platform (run before FreeRTOS starts) */ void plat_init(void); diff --git a/platform/status_led.h b/platform/status_led.h index 553f3fc..f61e3a9 100644 --- a/platform/status_led.h +++ b/platform/status_led.h @@ -1,6 +1,8 @@ // // Created by MightyPork on 2017/12/15. // +// Status LED blinking +// #ifndef GEX_INDICATORS_H #define GEX_INDICATORS_H diff --git a/tasks/sched_queue.h b/tasks/sched_queue.h index 8317cf0..e9aa118 100644 --- a/tasks/sched_queue.h +++ b/tasks/sched_queue.h @@ -1,6 +1,8 @@ // // Created by MightyPork on 2017/11/21. // +// Job and message scheduling queue structs and typedefs +// #ifndef GEX_SCHED_QUEUE_H #define GEX_SCHED_QUEUE_H @@ -8,36 +10,55 @@ #include "platform.h" #include +/** + * Queued job typedef + */ typedef struct sched_que_item Job; + +/** + * Queued job callback + */ typedef void (*ScheduledJobCb) (Job *job); +/** + * Queued job data struct + */ struct sched_que_item { + /** The callback */ ScheduledJobCb cb; + /** Data word 1 */ union { - TF_ID frame_id; - void *data1; + TF_ID frame_id; // typically used to pass frame id to the callback + void *data1; // arbitrary pointer or int }; + /** Data word 2 */ union { - uint32_t d32; - uint8_t *buf; - const uint8_t *cbuf; - const char *str; - void *data2; + uint32_t d32; // passing a number + uint8_t *buf; // uchar buffer + const uint8_t *cbuf; // const uchar buffer + const char *str; // string + void *data2; // arbitrary pointer }; + /** Data word 3 */ union { - uint32_t len; - void *data3; + uint32_t len; // typically length of the buffer + void *data3; // arbitrary pointer }; }; -// This que is used to stash frames received from TinyFrame for later evaluation on the application thread +/** + * Queued data chunk structure - used for buffering received messages for TinyFrame + */ struct rx_que_item { uint32_t len; uint8_t data[MSG_QUE_SLOT_SIZE]; }; +/** + * Combined struct - added when we merged the two separate queues + */ struct rx_sched_combined_que_item { - bool is_job; + bool is_job; // tag indicating whether the job or msg field is used union { struct rx_que_item msg; struct sched_que_item job; diff --git a/tasks/task_main.h b/tasks/task_main.h index 667b9b8..6d718bf 100644 --- a/tasks/task_main.h +++ b/tasks/task_main.h @@ -1,13 +1,19 @@ // // Created by MightyPork on 2017/11/09. // +// Main GEX thread. Handles USB communication, heartbeat LED blinking and VFS reconnect timeouts. +// The thread is notified via flag bits about events from the USB IRQs +// #ifndef GEX_TASK_MAIN_H #define GEX_TASK_MAIN_H #include "platform.h" +/** Main thread handle */ extern osThreadId tskMainHandle; + +/** Main thread entry point */ void TaskMain(const void *argument); // Notify flags: diff --git a/tasks/task_msg.h b/tasks/task_msg.h index 7084575..3b99d6a 100644 --- a/tasks/task_msg.h +++ b/tasks/task_msg.h @@ -1,6 +1,9 @@ // // Created by MightyPork on 2017/12/22. // +// Message and job combined queue, used for async job execution (dispatched form ISR) +// and TinyFrame message handling +// #ifndef GEX_F072_TASK_MSG_H #define GEX_F072_TASK_MSG_H @@ -8,15 +11,32 @@ #include "platform.h" #include "sched_queue.h" +/** Message queue handle */ extern osMessageQId queMsgJobHandle; + +/** Message/job thread handle */ extern osThreadId tskMsgJobHandle; + +/** Message/job thread entry point */ void TaskMsgJob(const void *argument); + +/** + * Add a job to the queue + * + * @param job + */ void scheduleJob(Job *job); +/** + * Add a message to the queue. This always takes the entire slot (64 bytes) or multiple + * + * @param buf - byte buffer + * @param len - number of bytes; can exceed 64 - then it will be split to multiple slots + */ +void rxQuePostMsg(uint8_t *buf, uint32_t len); + #if USE_STACK_MONITOR extern volatile uint32_t msgQueHighWaterMark; #endif -void rxQuePostMsg(uint8_t *buf, uint32_t len); - #endif //GEX_F072_TASK_MSG_H