hal: document flash protect API contract

Author: danielinux

hal/skeleton.c

@@ -35,9 +35,11 @@ void hal_init(void)
 void hal_prepare_boot(void)
 {
     /* wolfBoot calls hal_flash_protect() before this hook.
-     * Override hal_flash_protect() to lock the bootloader region on
-     * targets that support runtime write protection, and use this hook
-     * only for any remaining platform-specific handoff work. */
+     * Override int hal_flash_protect(haladdr_t address, int len) to lock
+     * the bootloader region on targets that support runtime write
+     * protection. Return 0 on success or a negative value on failure, and
+     * use this hook only for any remaining platform-specific handoff work.
+     */
 }
 
 #endif

include/hal.h

@@ -87,6 +87,10 @@ uint64_t hal_get_timer_us(void);
 #endif
 void hal_flash_unlock(void);
 void hal_flash_lock(void);
+/*
+ * Lock the flash region [address, address + len) against writes.
+ * Return 0 on success, or a negative value on failure.
+ */
 int hal_flash_protect(haladdr_t address, int len);
 void hal_prepare_boot(void);