Improvents for library documentation

- Renamed header file reg.h to register.h
- Added unified header comments for files
- [doc] flash_loader.h: // Static functions

CMakeLists.txt

@@ -180,7 +180,7 @@ set(STLINK_HEADERS
         src/stlink-lib/map_file.h
         src/stlink-lib/md5.h
         src/stlink-lib/option_bytes.h
-        src/stlink-lib/reg.h
+        src/stlink-lib/register.h
         src/stlink-lib/sg.h
         src/stlink-lib/usb.h
         )

inc/stlink.h

@@ -1,9 +1,7 @@
-
 /*
  * File: stlink.h
  *
- * This should contain all the common top level stlink interfaces,
+ * All common top level stlink interfaces, regardless of how the backend does the work....
- * regardless of how the backend does the work....
  */
 
 #ifndef STLINK_H
@@ -300,7 +298,7 @@ int32_t stlink_target_connect(stlink_t *sl, enum connect_type connect);
 
 #include <sg.h>
 #include <usb.h>
-#include <reg.h>
+#include <register.h>
 #include <commands.h>
 #include <chipid.h>
 #include <flash_loader.h>

src/st-trace/trace.c

@@ -11,7 +11,7 @@
 #include <unistd.h>
 
 #include <logging.h>
-#include <reg.h>
+#include <register.h>
 #include <stlink.h>
 
 #define DEFAULT_LOGGING_LEVEL 50

src/stlink-lib/calculate.c

@@ -1,3 +1,9 @@
+/*
+ * File: calculate.c
+ *
+ * Calculation of sector numbers and pages
+ */
+
 #include <stdint.h>
 
 #include <stlink.h>

src/stlink-lib/chipid.c

@@ -1,3 +1,9 @@
+/*
+ * File: chipid.c
+ *
+ * Chip-ID parametres
+ */
+
 #include <ctype.h>
 #include <errno.h>
 #include <stdio.h>

src/stlink-lib/chipid.h

@@ -1,3 +1,9 @@
+/*
+ * File: chipid.h
+ *
+ * Chip-ID parametres
+ */
+
 #ifndef CHIPID_H
 #define CHIPID_H
 

src/stlink-lib/commands.h

@@ -1,3 +1,9 @@
+/*
+ * File: commands.h
+ *
+ * stlink commands
+ */
+
 #ifndef COMMANDS_H
 #define COMMANDS_H
 

src/stlink-lib/common_flash.c

@@ -1,3 +1,9 @@
+/*
+ * File: common_flash.c
+ *
+ * Flash operations
+ */
+
 #include <stdint.h>
 #include <stdio.h>
 #include <unistd.h>

src/stlink-lib/flash_loader.c

@@ -1,3 +1,9 @@
+/*
+ * File: flash_loader.c
+ *
+ * Flash loaders
+ */
+
 #include <stdint.h>
 #include <stdio.h>
 #include <string.h>

src/stlink-lib/flash_loader.h

@@ -1,7 +1,7 @@
 /*
  * File: flash_loader.h
  *
- * Flash loader
+ * Flash loaders
  */
  
 #ifndef FLASH_LOADER_H
@@ -14,10 +14,10 @@
 #include <stlink.h>
 
 int32_t stlink_flash_loader_init(stlink_t *sl, flash_loader_t* fl);
-static int32_t loader_v_dependent_assignment(stlink_t *sl,
+// static int32_t loader_v_dependent_assignment(stlink_t *sl,
-                                            const uint8_t **loader_code, size_t *loader_size,
+//                                             const uint8_t **loader_code, size_t *loader_size,
-                                            const uint8_t *high_v_loader, size_t high_v_loader_size,
+//                                             const uint8_t *high_v_loader, size_t high_v_loader_size,
-                                            const uint8_t *low_v_loader, size_t low_v_loader_size);
+//                                             const uint8_t *low_v_loader, size_t low_v_loader_size);
 int32_t stlink_flash_loader_write_to_sram(stlink_t *sl, stm32_addr_t* addr, size_t* size);
 int32_t stlink_flash_loader_run(stlink_t *sl, flash_loader_t* fl, stm32_addr_t target, const uint8_t* buf, size_t size);
 
@@ -25,8 +25,8 @@ int32_t stlink_flash_loader_run(stlink_t *sl, flash_loader_t* fl, stm32_addr_t t
 /* === Functions from old header file flashloader.h === */
 
 int32_t stm32l1_write_half_pages(stlink_t *sl, stm32_addr_t addr, uint8_t *base, uint32_t len, uint32_t pagesize);
-static void set_flash_cr_pg(stlink_t *sl, uint32_t bank);
+// static void set_flash_cr_pg(stlink_t *sl, uint32_t bank);
-static void set_dma_state(stlink_t *sl, flash_loader_t *fl, int32_t bckpRstr);
+// static void set_dma_state(stlink_t *sl, flash_loader_t *fl, int32_t bckpRstr);
 int32_t stlink_flashloader_start(stlink_t *sl, flash_loader_t *fl);
 int32_t stlink_flashloader_write(stlink_t *sl, flash_loader_t *fl, stm32_addr_t addr, uint8_t *base, uint32_t len);
 int32_t stlink_flashloader_stop(stlink_t *sl, flash_loader_t *fl);

src/stlink-lib/helper.c

@@ -1,3 +1,9 @@
+/*
+ * File: helper.c
+ *
+ * General helper functions
+ */
+
 #include <stddef.h>
 #include <stdint.h>
 #include <stdlib.h>

src/stlink-lib/helper.h

@@ -1,3 +1,9 @@
+/*
+ * File: helper.h
+ *
+ * General helper functions
+ */
+
 #ifndef HELPER_H
 #define HELPER_H
 

src/stlink-lib/libusb_settings.h

@@ -1,3 +1,9 @@
+/*
+ * File: libusb_settings.h
+ *
+ * Settings for libusb library
+ */
+
 #ifndef LIBUSB_SETTINGS_H
 #define LIBUSB_SETTINGS_H
 

src/stlink-lib/logging.c

@@ -1,8 +1,7 @@
 /*
  * UglyLogging
  *
- * Slow, yet another wheel reinvented, but enough to make the rest of our code
+ * Slow, yet another wheel reinvented, but enough to make the rest of our code pretty enough.
- * pretty enough.
  */
 
 #include <stdarg.h>

src/stlink-lib/map_file.c

@@ -1,3 +1,9 @@
+/*
+ * File: map_file.c
+ *
+ * File mapping
+ */
+
 #include <fcntl.h>
 #include <stdint.h>
 #include <unistd.h>

src/stlink-lib/md5.c

@@ -5,6 +5,12 @@
  * This is free and unencumbered software released into the public domain - June 2013 - waterjuice.org
  */
 
+/*
+ * File: md5.c
+ *
+ * MD5 hash function
+ */
+
 #include <stdint.h>
 #include <memory.h>
 

src/stlink-lib/option_bytes.c

@@ -1,3 +1,9 @@
+/*
+ * File: option_bytes.c
+ *
+ * Read and write option bytes and option control registers
+ */
+
 #include <stdint.h>
 #include <stdio.h>
 #include <string.h>

src/stlink-lib/register.h

@@ -1,5 +1,11 @@
-#ifndef REG_H
+/*
-#define REG_H
+ * File: register.h
+ *
+ * Common STM32 registers
+ */
+
+#ifndef REGISTER_H
+#define REGISTER_H
 
 #define STLINK_REG_CM3_CPUID                0xE000ED00
 

src/stlink-lib/sg.c

@@ -74,6 +74,12 @@
  *         part to an existing options line for usb-storage).
  */
 
+/*
+ * File: sg.c
+ *
+ *
+ */
+
 #define __USE_GNU
 
 #include <assert.h>

src/stlink-lib/sg.h

@@ -1,6 +1,7 @@
 /*
  * File: sg.h
- * Author: karl
+ *
+ *
  */
 
 #ifndef SG_H

src/stlink-lib/usb.c

@@ -1,3 +1,9 @@
+/*
+ * File: usb.c
+ *
+ * 
+ */
+
 #include <limits.h>
 #include <stdint.h>
 #include <stdio.h>

src/stlink-lib/usb.h

@@ -1,6 +1,7 @@
 /*
  * File: usb.h
- * Author: karl
+ *
+ * 
  */
 
 #ifndef USB_H