diff --git a/drivers/include/periph/flashpage.h b/drivers/include/periph/flashpage.h
index ce78273f03..2ae1a62eec 100644
--- a/drivers/include/periph/flashpage.h
+++ b/drivers/include/periph/flashpage.h
@@ -213,11 +213,17 @@ void flashpage_erase(unsigned page);
 
 /**
  * @brief Get number of first free flashpage
+ *
+ * If riotboot is used in two slot mode, this number will change across
+ * firmware updates as the firmware slots alternate.
  */
 unsigned flashpage_first_free(void);
 
 /**
  * @brief Get number of last free flashpage
+ *
+ * If riotboot is used in two slot mode, this number will change across
+ * firmware updates as the firmware slots alternate.
  */
 unsigned flashpage_last_free(void);