everything is now documented

utils/avrlibc.h

@@ -1,14 +1,59 @@
 //
 // Created by MightyPork on 2017/11/26.
 //
+// Those are low memory footprint implementations of some stdlib functions
+// taken from the AVR libc. They are used instead of newlib versions.
+//
 
 #ifndef GEX_AVRLIBC_H_H
 #define GEX_AVRLIBC_H_H
 
+/**
+ * atoi() - parse decimal int from ASCII
+ *
+ * @param p - string
+ * @return int, 0 on failure
+ */
 int avr_atoi(const char *p);
-long avr_strtol(const char *nptr, char **endptr, register int base);
+
+/**
+ * atol() - parse decimal long int from ASCII
+ *
+ * @param p - string
+ * @return int, 0 on failure
+ */
 long avr_atol(const char *p);
+
+/**
+ * strtol() - parse integer number form string.
+ * this is internally called by atol and atoi
+ *
+ * 0x is allowed for bases 0 and 16
+ *
+ * @param nptr - string to parse
+ * @param endptr - NULL or pointer to string where the end will be stored (first bad char)
+ * @param base - base 2, 10, 16.... 0 for auto
+ * @return the number
+ */
+long avr_strtol(const char *nptr, char **endptr, register int base);
+
+/**
+ * Parse double from ASCII
+ *
+ * @param nptr - string to parse
+ * @param endptr - NULL or pointer to string where the end will be stored (first bad char)
+ * @return  the number
+ */
 double avr_strtod (const char * nptr, char ** endptr);
+
+/**
+ * like strtol(), but unsigned (and hence higher max value)
+ *
+ * @param nptr - string to parse
+ * @param endptr - NULL or pointer to string where the end will be stored (first bad char)
+ * @param base - base 2, 10, 16.... 0 for auto
+ * @return the number
+ */
 unsigned long avr_strtoul(const char *nptr, char **endptr, register int base);
 
 #endif //GEX_AVRLIBC_H_H

utils/circ_buf.h

@@ -1,3 +1,7 @@
+//
+// This is a circular buffer implementation borrowed from the DAPLink firmware
+//
+
 /**
  * @file    circ_buf.h
  * @brief   Implementation of a circular buffer

utils/cortex_utils.h

@@ -1,6 +1,8 @@
 //
 // Created by MightyPork on 2017/11/26.
 //
+// Cortex-M utilities (low level stuff missing from CMSIS)
+//
 
 #ifndef GEX_CORTEX_UTILS_H
 #define GEX_CORTEX_UTILS_H

utils/error.h

@@ -1,23 +1,6 @@
-/**
- * @file    error.h
- * @brief   collection of known errors and accessor for the friendly string
- *
- * DAPLink Interface Firmware
- * Copyright (c) 2009-2016, ARM Limited, All Rights Reserved
- * SPDX-License-Identifier: Apache-2.0
- *
- * Licensed under the Apache License, Version 2.0 (the "License"); you may
- * not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
+//
+// Error codes and labels. Loosely based on DAPLink, with more codes added.
+//
 
 #ifndef ERROR_H
 #define ERROR_H
@@ -59,7 +42,10 @@
     X(OUT_OF_MEM, "Not enough RAM") \
     X(RESOURCE_NOT_AVAILABLE, NULL)
 
-// Keep in sync with the list error_message
+
+/**
+ * The return value for all functions with error reporting.
+ */
 typedef enum {
 #define X(name, text) E_##name,
     X_ERROR_CODES
@@ -67,8 +53,6 @@ typedef enum {
     ERROR_COUNT
 } error_t;
 
-const char *error_get_message(error_t error) __attribute__((pure));
-const char *error_get_name(error_t error) __attribute__((pure));
 
 /** Check return value and return it if not E_SUCCESS */
 #define TRY(call) do { \
@@ -77,6 +61,24 @@ const char *error_get_name(error_t error) __attribute__((pure));
     if (E_SUCCESS != _rv) return _rv; \
 } while (0)
 
+
+/**
+ * Get a user-friendly message from a E_* enum value
+ *
+ * @param error - E_* value
+ * @return string, error name or description
+ */
+const char *error_get_message(error_t error) __attribute__((pure));
+
+
+/**
+ * Get error name from a E_* enum value
+ *
+ * @param error - E_* value
+ * @return string, error name
+ */
+const char *error_get_name(error_t error) __attribute__((pure));
+
 #ifdef __cplusplus
 }
 #endif

utils/hexdump.h

@@ -1,6 +1,9 @@
 //
 // Created by MightyPork on 2017/12/04.
 //
+// Memory dumping utility from: https://stackoverflow.com/a/7776146/2180189
+// Prints bytes in the usual hexdump format (as HEX and ASCII)
+//
 
 #ifndef GEX_HEXDUMP_H
 #define GEX_HEXDUMP_H

utils/ini_parser.h

@@ -1,8 +1,14 @@
+//
+// INI file parser with a FSM generated by Ragel. This was originally written for ESPTerm
+// Used to extract sections, keys and values from user-provided settings file
+//
+
 #ifndef INIPARSE_STREAM_H
 #define INIPARSE_STREAM_H
 
 #include "platform.h"
 
+// toggleable logging func
 #ifdef DEBUG_INI
 #define ini_error(fmt, ...) dbg("! INI err: "#fmt, ##__VA_ARGS__)
 #else

utils/ini_writer.h

@@ -1,12 +1,19 @@
 //
 // Created by MightyPork on 2017/12/01.
 //
+// Utility for generating a INI file with support for extracting individual sectors
+// and measuring total length without buffering. This is used to build the INI files
+// for the VFS and config.
+//
 
 #ifndef INIWRITER_H
 #define INIWRITER_H
 
 #include "platform.h"
 
+/**
+ * INI writer handle
+ */
 typedef struct iniwriter_ {
     char *ptr;
     uint32_t skip;
@@ -18,7 +25,7 @@ typedef struct iniwriter_ {
  *
  * This buffer is used internally by printf-like iw functions.
  * It can be used to prepare buffer for iw_buff or iw_string,
- * but must not be used for %s substitutions in iw_* functions.
+ * but must NOT be used for %s substitutions in iw_* functions.
  */
 extern char *iwbuffer;
 

utils/macro.h

@@ -1,3 +1,7 @@
+//
+// static assert and general purpose useful macros, borrowed in part from the DAPLink project
+//
+
 /**
  * @file    macro.h
  * @brief   useful things + Special asserts and macros

utils/malloc_safe.h

@@ -1,3 +1,9 @@
+//
+// Safe malloc with error file:line logging, using the FreeRTOS-provided malloc facility
+// The custom malloc implementation is safer than the poorly documented hacks provided by
+// newlib, written primarily for the desktop rather than embedded.
+//
+
 #ifndef MALLOC_SAFE_H
 #define MALLOC_SAFE_H
 

utils/snprintf.h

@@ -1,6 +1,8 @@
 //
 // Created by MightyPork on 2017/11/09.
 //
+// Small sprintf/snprintf implementation, used instead of the newlib one.
+//
 
 #ifndef GEX_SNPRINTF_H
 #define GEX_SNPRINTF_H
@@ -15,13 +17,6 @@ size_t fixup_vasprintf(char **ptr, const char *format, va_list ap);
 size_t fixup_asprintf(char **ptr, const char *format, ...);
 size_t fixup_sprintf(char *ptr, const char *format, ...);
 
-// Trap for using newlib functions
-//#define vsnprintf fuck1
-//#define snprintf fuck2
-//#define vasprintf fuck3
-//#define asprintf fuck4
-//#define sprintf fuck5
-
 #define VSNPRINTF(...) fixup_vsnprintf(__VA_ARGS__)
 #define SNPRINTF(...) fixup_snprintf(__VA_ARGS__)
 #define VASPRINTF(...) fixup_vasprintf(__VA_ARGS__)

utils/stacksmon.c

@@ -15,7 +15,6 @@ struct stackhandle {
     uint32_t len;
 };
 
-#define STACK_NUM 3
 static uint32_t nextidx = 0;
 static struct stackhandle stacks[STACK_NUM];
 

utils/stacksmon.h

@@ -1,6 +1,8 @@
 //
 // Created by MightyPork on 2017/12/04.
 //
+// Utility for monitoring usage levels of FreeRTOS stacks and printing it in a nice table
+//
 
 #ifndef GEX_STACKSMON_H
 #define GEX_STACKSMON_H
@@ -8,9 +10,29 @@
 #include "platform.h"
 
 #if USE_STACK_MONITOR
+
+/** Number of tracked stacks, max */
+#define STACK_NUM 3
+
+/**
+ * Check canaries and trap if they're dead
+ */
 void stackmon_check_canaries(void);
+
+/**
+ * Dump stacks usage table
+ */
 void stackmon_dump(void);
+
+/**
+ * Register a stack to be monitored
+ *
+ * @param description - stack name
+ * @param buffer - stack buffer
+ * @param len - stack size in bytes
+ */
 void stackmon_register(const char *description, void *buffer, uint32_t len);
+
 #else
 #define stackmon_check_canaries() do {} while(0)
 #define stackmon_dump() do {} while(0)

utils/str_utils.h

@@ -1,3 +1,8 @@
+//
+// Simple string testing / manipulation functions, mainly used when
+// building/parsing the config INI files
+//
+
 #ifndef PLATFORSTR_UTILS_H
 #define PLATFORSTR_UTILS_H
 
@@ -125,17 +130,20 @@ const char *str_4(uint32_t n,
                      uint32_t nc, const char *c,
                      uint32_t nd, const char *d);
 
+/** Convert string to one of two numeric options */
 uint32_t str_parse_2(const char *tpl,
                      const char *a, uint32_t na,
                      const char *b, uint32_t nb,
                      bool *suc);
 
+/** Convert string to one of three numeric options */
 uint32_t str_parse_3(const char *tpl,
                      const char *a, uint32_t na,
                      const char *b, uint32_t nb,
                      const char *c, uint32_t nc,
                      bool *suc);
 
+/** Convert string to one of four numeric options */
 uint32_t str_parse_4(const char *tpl,
                      const char *a, uint32_t na,
                      const char *b, uint32_t nb,
@@ -143,7 +151,7 @@ uint32_t str_parse_4(const char *tpl,
                      const char *d, uint32_t nd,
                      bool *suc);
 
-/** Convert bool to Y or N */
+/** Convert bool to a Y or N constant string */
 #define str_yn(cond) ((cond) ? ("Y") : ("N"))
 
 #endif