Doc comments and explanations

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"

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);

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

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);

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 <TinyFrame.h>
 
 typedef struct bulk_write BulkWrite;

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;

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

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;

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