more doc comments

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 <TinyFrame/TinyFrame.h>
+#include <TinyFrame.h>
 #include "unit.h"
 
 /**

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

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

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

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

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"

platform/platform.c

@@ -2,7 +2,6 @@
 // Created by MightyPork on 2017/11/26.
 //
 
-#include <stm32f072xb.h>
 #include "platform.h"
 #include "usbd_core.h"
 #include "USB/usb_device.h"

platform/platform.h

@@ -37,7 +37,7 @@
 // ---
 
 /**
- * Init the platform
+ * Init the platform (run before FreeRTOS starts)
  */
 void plat_init(void);
 

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

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 <TinyFrame.h>
 
+/**
+ * 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;

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:

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