everything is now documented

vfs/file_stream.h

@@ -1,3 +1,8 @@
+//
+// File streams, this was used in DAPLink to capture and flash the firmware update image.
+// Here we detect only the settings INI files, which start by two hash symbols.
+//
+
 /**
  * @file    file_stream.h
  * @brief   Different file stream parsers that are supported
@@ -42,16 +47,19 @@ typedef enum {
     STREAM_TYPE_NONE
 } stream_type_t;
 
-// Stateless function to identify a filestream by its contents
+/** Stateless function to identify a filestream by its contents */
 stream_type_t stream_start_identify(const uint8_t *data, uint32_t size);
 
-// Stateless function to identify a filestream by its name
+/** Stateless function to identify a filestream by its name */
 stream_type_t stream_type_from_name(const vfs_filename_t filename);
 
+/** Open a stream (only one can be open at all times) */
 error_t stream_open(stream_type_t stream_type);
 
+/** Write some data to an open stream */
 error_t stream_write(const uint8_t *data, uint32_t size);
 
+/** Close the open stream */
 error_t stream_close(void);
 
 #ifdef __cplusplus

vfs/vfs_manager.c

@@ -328,7 +328,7 @@ void vfs_if_usbd_msc_read_sect(uint32_t sector, uint8_t *buf, uint32_t num_of_se
     vfs_read(sector, buf, num_of_sectors);
 }
 
-void vfs_if_usbd_msc_write_sect(uint32_t sector, uint8_t *buf, uint32_t num_of_sectors)
+void vfs_if_usbd_msc_write_sect(uint32_t sector, const uint8_t *buf, uint32_t num_of_sectors)
 {
     sync_assert_usb_thread();
     vfs_printf("\033[32mWRITE @ %d, len %d\033[0m", (int)sector, (int)num_of_sectors);

vfs/vfs_manager.h

@@ -1,3 +1,10 @@
+//
+// The main VFS state machine, mostly based on DAPLink
+//
+// TODO many errors were originally written to a FAIL.TXT file for the user to see,
+//      those are now caught by assert_param(0) and crash the whole system. This is not ideal.
+//
+
 /**
  * @file    vfs_manager.h
  * @brief   Methods that build and manipulate a virtual file system
@@ -29,61 +36,114 @@
 extern "C" {
 #endif
 
+/**
+ * Flag that we're plugged into Windows.
+ * This is detected by characteristic writes of some system metadata store (which we discard)
+ */
 extern bool vfs_is_windows;
 
 /* Callable from anywhere */
 
-// Enable or disable the virtual filesystem
+/** Enable or disable the virtual filesystem */
 void vfs_mngr_fs_enable(bool enabled);
 
-// Remount the virtual filesystem
+/**
+ * Remount the virtual filesystem
+ *
+ * @param force_full - use media ready toggle instead of just notifying of modified data
+ *                     (this should be more reliable, but can also be more intrusive)
+ */
 void vfs_mngr_fs_remount(bool force_full);
 
 
 /* Callable only from the thread running the virtual fs */
 
-// Initialize the VFS manager
-// Must be called after USB has been initialized (usbd_init())
-// Notes: Must only be called from the thread runnning USB
+/**
+ * Initialize the VFS manager
+ * Must be called after USB has been initialized (usbd_init())
+ *
+ * @note Must only be called from the thread runnning USB
+ * @param enabled
+ */
 void vfs_mngr_init(bool enabled);
 
-// Run the vfs manager state machine
-// Notes: Must only be called from the thread runnning USB
+
+/**
+ * Run the vfs manager state machine
+ *
+ * @note Must only be called from the thread runnning USB
+ * @param elapsed_ms
+ */
 void vfs_mngr_periodic(uint32_t elapsed_ms);
 
-// Return the status of the last transfer or E_SUCCESS
-// if none have been performed yet
+/**
+ * Return the status of the last transfer or E_SUCCESS
+ * if none have been performed yet
+ *
+ * @return success
+ */
 error_t vfs_mngr_get_transfer_status(void);
 
 
 /* Use functions */
 
-// Build the filesystem by calling vfs_init and then adding files with vfs_create_file
+/**
+ * Build the filesystem by calling vfs_init and then adding files with vfs_create_file
+ */
 void vfs_user_build_filesystem(void);
 
-// Called when a file on the filesystem changes
-void vfs_user_file_change_handler(const vfs_filename_t filename, vfs_file_change_t change, vfs_file_t file, vfs_file_t new_file_data);
+/**
+ * Called when a file on the filesystem changes
+ *
+ * @param filename - name of the changed file
+ * @param change - type of change
+ * @param file - data pointer (?)
+ * @param new_file_data - new data pointer (?)
+ */
+void vfs_user_file_change_handler(const vfs_filename_t filename,
+                                  vfs_file_change_t change,
+                                  vfs_file_t file, vfs_file_t new_file_data);
 
-// Called when VFS is disconnecting
+/**
+ * Called when VFS is disconnecting
+ */
 void vfs_user_disconnecting(void);
 
-
-
 // --- interface ---
+
+/**
+ * Initialize, call form the MSC init callback
+ */
 void vfs_if_usbd_msc_init(void);
+
+/**
+ * MSC wants to read a sector
+ *
+ * @param sector - first sector number
+ * @param buf - destination
+ * @param num_of_sectors - length
+ */
 void vfs_if_usbd_msc_read_sect(uint32_t sector, uint8_t *buf, uint32_t num_of_sectors);
-void vfs_if_usbd_msc_write_sect(uint32_t sector, uint8_t *buf, uint32_t num_of_sectors);
+
+/**
+ * MSC wants to write a sector
+ *
+ * @param sector - first sector number
+ * @param buf - data
+ * @param num_of_sectors - length
+ */
+void vfs_if_usbd_msc_write_sect(uint32_t sector, const uint8_t *buf, uint32_t num_of_sectors);
 
 typedef struct {
     uint32_t MemorySize;
     uint16_t BlockSize;
-    uint32_t BlockGroup; // LUN?
+    uint32_t BlockGroup; // LUN
     uint32_t BlockCount;
-//    uint8_t *BlockBuf; // apparently unused :thaenkin:
     bool MediaReady;
     bool MediaChanged;
 } vfs_info_t;
 
+/** VFS info struct - some are used by SCSI/MSC */
 extern volatile vfs_info_t vfs_info;
 
 #ifdef __cplusplus

vfs/vfs_user.c

@@ -1,3 +1,7 @@
+//
+// Here are defined the files and handlers
+//
+
 /**
  * @file    vfs_user.c
  * @brief   Implementation of vfs_user.h
@@ -27,6 +31,7 @@
 
 const vfs_filename_t daplink_drive_name = VFS_DRIVE_NAME;
 
+
 static uint32_t read_iw_sector(uint32_t sector_offset, uint8_t *data, uint32_t num_sectors, void (*handler)(IniWriter *))
 {
     const uint32_t avail = num_sectors*VFS_SECTOR_SIZE;
@@ -38,6 +43,7 @@ static uint32_t read_iw_sector(uint32_t sector_offset, uint8_t *data, uint32_t n
     return avail - iw.count;
 }
 
+
 // File callback to be used with vfs_add_file to return file contents
 static uint32_t read_file_units_ini(uint32_t sector_offset, uint8_t *data, uint32_t num_sectors)
 {
@@ -45,18 +51,21 @@ static uint32_t read_file_units_ini(uint32_t sector_offset, uint8_t *data, uint3
     return read_iw_sector(sector_offset, data, num_sectors, settings_build_units_ini);
 }
 
+
 static uint32_t read_file_system_ini(uint32_t sector_offset, uint8_t *data, uint32_t num_sectors)
 {
     vfs_printf("Read SYSTEM.INI");
     return read_iw_sector(sector_offset, data, num_sectors, settings_build_system_ini);
 }
 
+
 static uint32_t read_file_pinout_txt(uint32_t sector_offset, uint8_t *data, uint32_t num_sectors)
 {
     vfs_printf("Read PINOUT.TXT");
     return read_iw_sector(sector_offset, data, num_sectors, settings_build_pinout_txt);
 }
 
+
 void vfs_user_build_filesystem(void)
 {
     dbg("Rebuilding VFS...");
@@ -69,6 +78,7 @@ void vfs_user_build_filesystem(void)
     vfs_create_file("PINOUT  TXT", read_file_pinout_txt, NULL, iw_measure_total(settings_build_pinout_txt));
 }
 
+
 // Callback to handle changes to the root directory.  Should be used with vfs_set_file_change_callback
 void vfs_user_file_change_handler(const vfs_filename_t filename,
                                   vfs_file_change_t change,
@@ -98,6 +108,7 @@ void vfs_user_file_change_handler(const vfs_filename_t filename,
     }
 }
 
+
 void vfs_user_disconnecting(void)
 {
     // maybe reset...

vfs/virtual_fs.h

@@ -1,3 +1,8 @@
+//
+// The guts of the virtual FAT16 are implemented here.
+// This is taken from DAPLink and some memory-wasting bits are commented out or removed.
+//
+
 /**
  * @file    virtual_fs.h
  * @brief   FAT 12/16 filesystem handling
@@ -28,6 +33,7 @@
 extern "C" {
 #endif
 
+// Toggleable debug funcs
 #if DEBUG_VFS
 #define vfs_printf(...)  do { dbg(__VA_ARGS__); } while(0)
 #define vfs_printf_nonl(...)  do { PRINTF(__VA_ARGS__); } while(0)
@@ -48,6 +54,7 @@ extern "C" {
 #define VFS_MAX_FILES           16
 #define VFS_DISK_SIZE MB(32)
 
+/** Filename typedef */
 typedef char vfs_filename_t[11];
 
 typedef enum {
@@ -69,51 +76,116 @@ typedef enum {
                                   notification will also occur*/
 } vfs_file_change_t;
 
+/** File typedef */
 typedef void *vfs_file_t;
+
+/** Sector struct typedef */
 typedef uint32_t vfs_sector_t;
 
-// Callback for when data is written to a file on the virtual filesystem
+/**
+ * Callback for when data is written to a file on the virtual filesystem
+ */
 typedef void (*vfs_write_cb_t)(uint32_t sector_offset, const uint8_t *data, uint32_t num_sectors);
-// Callback for when data is ready from the virtual filesystem
+
+/**
+ * Callback for when data is ready from the virtual filesystem
+ */
 typedef uint32_t (*vfs_read_cb_t)(uint32_t sector_offset, uint8_t *data, uint32_t num_sectors);
-// Callback for when a file's attributes are changed on the virtual filesystem.  Note that the 'file' parameter
-// can be saved and compared to other files to see if they are referencing the same object.  The
-// same cannot be done with new_file_data since it points to a temporary buffer.
+
+/**
+ * Callback for when a file's attributes are changed on the virtual filesystem.
+ * Note that the 'file' parameter can be saved and compared to other files to see if
+ * they are referencing the same object. The same cannot be done with new_file_data
+ * since it points to a temporary buffer.
+ */
 typedef void (*vfs_file_change_cb_t)(const vfs_filename_t filename, vfs_file_change_t change,
                                      vfs_file_t file, vfs_file_t new_file_data);
 
-// Initialize the filesystem with the given size and name
+/**
+ * Initialize the filesystem with the given size and name
+ *
+ * @param drive_name
+ * @param disk_size
+ */
 void vfs_init(const vfs_filename_t drive_name, uint32_t disk_size);
 
-// Get the total size of the virtual filesystem
+/**
+ * Get the total size of the virtual filesystem
+ */
 uint32_t vfs_get_total_size(void);
 
-// Add a file to the virtual FS and return a handle to this file.
-// This must be called before vfs_read or vfs_write are called.
-// Adding a new file after vfs_read or vfs_write have been called results in undefined behavior.
-vfs_file_t vfs_create_file(const vfs_filename_t filename, vfs_read_cb_t read_cb, vfs_write_cb_t write_cb, uint32_t len);
+/**
+ * Add a file to the virtual FS and return a handle to this file.
+ * This must be called before vfs_read or vfs_write are called.
+ * Adding a new file after vfs_read or vfs_write have been called results in undefined behavior.
+ *
+ * @param filename
+ * @param read_cb
+ * @param write_cb
+ * @param len
+ * @return
+ */
+vfs_file_t vfs_create_file(const vfs_filename_t filename,
+                           vfs_read_cb_t read_cb, vfs_write_cb_t write_cb,
+                           uint32_t len);
 
-// Set the attributes of a file
+/**
+ * Set the attributes of a file
+ *
+ * @param file
+ * @param attr
+ */
 void vfs_file_set_attr(vfs_file_t file, vfs_file_attr_bit_t attr);
 
-// Get the starting sector of this file.
-// NOTE - If the file size is 0 there is no starting
-// sector so VFS_INVALID_SECTOR will be returned.
+/**
+ * Get the starting sector of this file.
+ * NOTE - If the file size is 0 there is no starting
+ * sector so VFS_INVALID_SECTOR will be returned.
+ *
+ * @param file
+ * @return
+ */
 vfs_sector_t vfs_file_get_start_sector(vfs_file_t file);
 
-// Get the size of the file.
+/**
+ * Get the size of the file.
+ *
+ * @param file
+ * @return
+ */
 uint32_t vfs_file_get_size(vfs_file_t file);
 
-// Get the attributes of a file
+/**
+ * Get the attributes of a file
+ *
+ * @param file
+ * @return
+ */
 vfs_file_attr_bit_t vfs_file_get_attr(vfs_file_t file);
 
-// Set the callback when a file is created, deleted or has atributes changed.
+/**
+ * Set the callback when a file is created, deleted or has atributes changed.
+ *
+ * @param cb
+ */
 void vfs_set_file_change_callback(vfs_file_change_cb_t cb);
 
-// Read one or more sectors from the virtual filesystem
+/**
+ * Read one or more sectors from the virtual filesystem
+ *
+ * @param sector
+ * @param buf
+ * @param num_of_sectors
+ */
 void vfs_read(uint32_t sector, uint8_t *buf, uint32_t num_of_sectors);
 
-// Write one or more sectors to the virtual filesystem
+/**
+ * Write one or more sectors to the virtual filesystem
+ *
+ * @param sector
+ * @param buf
+ * @param num_of_sectors
+ */
 void vfs_write(uint32_t sector, const uint8_t *buf, uint32_t num_of_sectors);
 
 bool vfs_find_file(uint32_t start_sector, vfs_filename_t *destFilename, vfs_file_t **destFile);