Add docstrings

src/ota.h

@@ -1,11 +1,34 @@
-// Copyright (c) 2023 Cesanta Software Limited
-// All rights reserved
+// Firmware OTA updates
+//
+// This is a low-level OTA API, not intended to be called directly by users.
+// Users are provided with a higher-level API:
+// - defining MG_OTA_URL enables HTTP pull-based updates
+// - mg_http_start_ota() enables push-based updates
+//
+// However, it is possible to use the mg_ota_* API directly. Below is the
+// example code of a function that is called repeatedly. It expects the
+// last chink of size 0, which marks the end of the OTA process
+//
+// ```c
+// static void ota(size_t total, size_t offset, void *buf, size_t len) {
+//   bool ok = false;
+//   if (ofs == 0 && (ok = mg_ota_begin(total)) == false) {
+//     mg_ota_end();
+//   } else if (len > 0 && (ok = mg_ota_write(buf, len)) == false) {
+//     mg_ota_end();
+//   } else if (len == 0) {}
+//     ok = mg_ota_end();
+//   }
+//   return ok;
+// }
+// ```
 
 #pragma once
 
 #include "arch.h"
 #include "net.h"
 
+// Supported OTA targets
 #define MG_OTA_NONE 0               // No OTA support
 #define MG_OTA_STM32H5 1            // STM32 H5
 #define MG_OTA_STM32H7 2            // STM32 H7
@@ -20,16 +43,18 @@
 #define MG_OTA_RT1170 304           // IMXRT1170
 #define MG_OTA_MCXN 310             // MCXN947
 #define MG_OTA_RW612 320            // FRDM-RW612
-#define MG_OTA_FLASH 900            // OTA via an internal flash
+#define MG_OTA_FLASH 900            // OTA via internal flash
 #define MG_OTA_ESP32 910            // ESP32 OTA implementation
 #define MG_OTA_PICOSDK 920          // RP2040/2350 using Pico-SDK hardware_flash
 #define MG_OTA_CUSTOM 1000          // Custom implementation
 
+// OTA target. Settable in mongoose_config.h
 #ifndef MG_OTA
 #define MG_OTA MG_OTA_NONE
 #else
 #ifndef MG_IRAM
 #if defined(__GNUC__)
+// Places code block in .iram ELF section. A linker script can place it in RAM
 #define MG_IRAM __attribute__((noinline, section(".iram")))
 #else
 #define MG_IRAM
@@ -37,12 +62,16 @@
 #endif  // IRAM
 #endif  // OTA
 
-// Firmware update API
-bool mg_ota_begin(size_t new_firmware_size);     // Start writing
-bool mg_ota_write(const void *buf, size_t len);  // Write chunk, aligned to 1k
-bool mg_ota_end(void);                           // Stop writing
+// Starts the OTA process. Called once at the beginning of a firmware update.
+bool mg_ota_begin(size_t new_firmware_size);
 
-// MG_OTA_ROLLBACK: swap firmware banks and reset. On flash-based OTA the
+// Writes the next firmware chunk. Called repeatedly until all data is written.
+bool mg_ota_write(const void *buf, size_t len);
+
+// Ends the OTA process and commits the written firmware.
+bool mg_ota_end(void);
+
+// MG_OTA_ROLLBACK: swap firmware banks and reset. On flash-based OTA, the
 // default calls swap_fn() (no-op on single-bank) then resets. Override in
 // mongoose_config.h for platforms without mg_flash (ESP32, PicoSDK, etc.).
 #ifndef MG_OTA_ROLLBACK
@@ -65,12 +94,10 @@ bool mg_ota_end(void);                           // Stop writing
 // MG_OTA_TESTING:   new firmware booted for the first time; IWDG is armed.
 //                   If the device reboots while in this state, it transitions
 //                   to MG_OTA_FAILED and rolls back on the next boot.
-// MG_OTA_FAILED:    previous boot did not commit in time; rollback on next
-// boot.
+// MG_OTA_FAILED:    previous boot did not commit in time; rollback on next boot.
 enum { MG_OTA_CONFIRMED = 0, MG_OTA_TESTING = 1, MG_OTA_FAILED = 2 };
 
-// Persistent OTA state storage. Define in mongoose_config.h to use a
-// location that survives resets
+// Persistent OTA state storage. Override in mongoose_config.h to persist state across resets.
 #ifndef MG_OTA_STATE_GET
 #define MG_OTA_STATE_GET() 0
 #endif
@@ -97,22 +124,31 @@ enum { MG_OTA_CONFIRMED = 0, MG_OTA_TESTING = 1, MG_OTA_FAILED = 2 };
     }                                                              \
   } while (0)
 
-// Pull based OTA over HTTP
+// Pull-based OTA over HTTP. Fetches the given URL, which should return a JSON
+// object like: { "version": "1.2.3", "url": "FIRMWARE_URL", "size": 324645 }
+// If the current firmware version differs from the JSON version, downloads
+// FIRMWARE_URL and performs the OTA update.
 void mg_ota_url_check(struct mg_mgr *mgr, const char *current_version,
                       const char *metadata_url, void (*fn)(const char *status));
 
+// Firmware info URL for mg_ota_poll() which calls mg_ota_url_check().
+// Example:  "http://mongoose.ws/ota/u/0/ota.json". See http://mongoose.ws/ota/
+// Settable in mongoose_config.h
 #ifndef MG_OTA_URL
 #define MG_OTA_URL NULL
 #endif
 
+// OTA status callback function for mg_ota_poll()
 #ifndef MG_OTA_STATUS_FN
 #define MG_OTA_STATUS_FN NULL
 #endif
 
+// Firmware version for mg_ota_poll(). Settable in mongoose_config.h
 #ifndef MG_OTA_FIRMWARE_VERSION
 #define MG_OTA_FIRMWARE_VERSION "1.0.0"
 #endif
 
+// Maximum version string length
 #ifndef MG_OTA_MAX_VERSION_LEN
 #define MG_OTA_MAX_VERSION_LEN 64
 #endif
@@ -123,14 +159,20 @@ void mg_ota_url_check(struct mg_mgr *mgr, const char *current_version,
 // -Wl,--gc-sections on builds that never poll for OTAs
 extern const char mg_fw_version[];
 
+// How often mg_ota_poll() checks for a firmware update, in seconds
 #ifndef MG_OTA_PULL_INTERVAL_SECONDS
 #define MG_OTA_PULL_INTERVAL_SECONDS 60
 #endif
 
+// Set to 1 to define a custom mg_ota_device_id(). Settable in mongoose_config.h
 #ifndef MG_ENABLE_CUSTOM_DEVICE_ID
 #define MG_ENABLE_CUSTOM_DEVICE_ID 0
 #endif
 
+// Populates buf with a unique device ID string.
+// E.g. on STM32, uses the 96-bit MCU UID converted to a hex string.
 void mg_ota_device_id(char *buf, size_t len);
 
+// Checks for a firmware update over HTTP. Called automatically by mg_mgr_poll()
+// when MG_OTA_URL is set in mongoose_config.h. Do not call directly.
 void mg_ota_poll(struct mg_mgr *);