[kernel][magenta] Add slack options to timers
The long requested feature now exposed to user mode. Now
the timer slack and be early, center or late.
The default behavior of 0 is "center" which was the existing
behavior so there no effective change on the existing
build.
Tests included with the caveat that better tests
exist already via "k timer_tests".
Change-Id: If1787e30eda4c06be003dea715e92c3f240841ca
diff --git a/docs/syscalls/timer_create.md b/docs/syscalls/timer_create.md
index d2c69bc..c170087 100644
--- a/docs/syscalls/timer_create.md
+++ b/docs/syscalls/timer_create.md
@@ -17,8 +17,22 @@
**timer_create**() creates a timer, an object that can signal
when a specified point in time has been reached. The only valid
-value for *options* is zero and the only valid *clock_id* is
-MX_CLOCK_MONOTONIC
+*clock_id* is MX_CLOCK_MONOTONIC.
+
+The *options* value specifies the coalescing behavior which
+controls whether the system can fire the time earlier or later
+depending on other pending timers.
+
+The possible values are:
+
++ **MX_TIMER_SLACK_CENTER** coalescing is allowed with earlier and
+ later timers.
++ **MX_TIMER_SLACK_EARLY** coalescing is allowed only with earlier
+ timers.
++ **MX_TIMER_SLACK_LAYE** coalescing is allowed only with later
+ timers.
+
+Passing 0 in options is equivalent to MX_TIMER_SLACK_CENTER.
The returned handle has the MX_RIGHT_DUPLICATE, MX_RIGHT_TRANSFER,
MX_RIGHT_READ and MX_RIGHT_WRITE right.
@@ -31,7 +45,8 @@
## ERRORS
**MX_ERR_INVALID_ARGS** *out* is an invalid pointer or NULL or
-*options* or *clock_id* is any value other than MX_CLOCK_MONOTONIC.
+*options* is not one of the MX_TIMER_SLACK values or *clock_id* is
+any value other than MX_CLOCK_MONOTONIC.
**MX_ERR_NO_MEMORY** (Temporary) Failure due to lack of memory.
diff --git a/docs/syscalls/timer_set.md b/docs/syscalls/timer_set.md
index 1eee9f9..93becae 100644
--- a/docs/syscalls/timer_set.md
+++ b/docs/syscalls/timer_set.md
@@ -25,7 +25,7 @@
**MX_CLOCK_MONOTONIC**. To wait for a relative interval,
use **mx_deadline_after**() returned value in *deadline*.
-To fire the timer inmediately pass 0 to *deadline*.
+To fire the timer immediately pass 0 to *deadline*.
When the timer fires it asserts *MX_TIMER_SIGNALED*. To de-assert this
signal call **timer_cancel**() or **timer_set**() again.
@@ -34,6 +34,14 @@
*deadline* + *slack* during which the timer is allowed to fire. The system
uses this parameter as a hint to coalesce nearby timers.
+The precise coalescing behavior is controlled by the *options* parameter
+specified when the timer was created. **MX_TIMER_SLACK_EARLY** allows only
+firing in the *deadline* - *slack* interval and **MX_TIMER_SLACK_LATE**
+allows only firing in the *deadline* + *slack* interval. The default
+option value of 0 is **MX_TIMER_SLACK_CENTER** and allows both early and
+late firing with an effective interval of *deadline* - *slack* to
+*deadline* + *slack*
+
## RETURN VALUE
**mx_timer_set**() returns **MX_OK** on success.
