From 09e61d97a9c46c764236178636e31791ce9d5097 Mon Sep 17 00:00:00 2001
From: schneider <schneider@blinkenlichts.net>
Date: Thu, 16 Sep 2021 23:49:17 +0200
Subject: [PATCH] doc(sleep): Add docs for epic_sleep()

---
 epicardium/epicardium.h | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/epicardium/epicardium.h b/epicardium/epicardium.h
index a4615364e..bc32e5cab 100644
--- a/epicardium/epicardium.h
+++ b/epicardium/epicardium.h
@@ -336,7 +336,24 @@ API(API_SYSTEM_EXEC, int __epic_exec(char *name));
  */
 API(API_SYSTEM_RESET, void epic_system_reset(void));
 
-API(API_SLEEP, void epic_sleep(uint32_t ms));
+/**
+ * Sleep for the specified amount of time.
+ *
+ * This call will block for at most the specified amount of time. It allows epicardium to
+ * reduce clock speed of the system until this call is finished.
+ *
+ * This call returns early if an interrupt is signaled from epicardium.
+ *
+ * The clock source of epicardium has a limited amount of accuracy. Tolerances
+ * of +- 10% have been observed. This means that the sleep time also has a
+ * tolarance of at least +- 10%. The exact amount varies from device to device and
+ * also with temperature. You should take this into consideration when selecting
+ * the time you want to sleep.
+ *
+ * :param ms:  Time to wait in milliseconds
+ * :returns: 0 if no interrupt happened, ``INT_MAX`` if an interrupt happened and the sleep ended early.
+ */
+API(API_SLEEP, int epic_sleep(uint32_t ms));
 
 /**
  * PMIC API
-- 
GitLab