kernel: add user data API to timers

Similar to what was available with nano timers in the original kernel,
allow a user to associate opaque data with a timer.

Fix for ZEP-1558.

Change-Id: Ib8cf998b47988da27eba4ee5cd2658f90366b1e4
Signed-off-by: Benjamin Walsh <walsh.benj@gmail.com>

include/kernel.h

@@ -757,8 +757,8 @@ struct k_timer {
 	/* timer status */
 	uint32_t status;
 
-	/* used to support legacy timer APIs */
+	/* user-specific data, also used to support legacy features */
-	void *_legacy_data;
+	void *user_data;
 
 	_OBJECT_TRACING_NEXT_PTR(k_timer);
 };
@@ -773,7 +773,7 @@ struct k_timer {
 	.expiry_fn = expiry, \
 	.stop_fn = stop, \
 	.status = 0, \
-	._legacy_data = NULL, \
+	.user_data = 0, \
 	_OBJECT_TRACING_INIT \
 	}
 
@@ -929,6 +929,38 @@ static inline int32_t k_timer_remaining_get(struct k_timer *timer)
 	return _timeout_remaining_get(&timer->timeout);
 }
 
+/**
+ * @brief Associate user-specific data with a timer.
+ *
+ * This routine records the @a user_data with the @a timer, to be retrieved
+ * later.
+ *
+ * It can be used e.g. in a timer handler shared across multiple subsystems to
+ * retrieve data specific to the subsystem this timer is associated with.
+ *
+ * @param timer     Address of timer.
+ * @param user_data User data to associate with the timer.
+ *
+ * @return N/A
+ */
+static inline void k_timer_user_data_set(struct k_timer *timer,
+					 void *user_data)
+{
+	timer->user_data = user_data;
+}
+
+/**
+ * @brief Retrieve the user-specific data from a timer.
+ *
+ * @param timer     Address of timer.
+ *
+ * @return The user data.
+ */
+static inline void *k_timer_user_data_get(struct k_timer *timer)
+{
+	return timer->user_data;
+}
+
 /**
  * @} end defgroup timer_apis
  */

include/legacy.h

@@ -3076,7 +3076,7 @@ static inline __deprecated void
 nano_timer_init(struct k_timer *timer, void *data)
 {
 	k_timer_init(timer, NULL, NULL);
-	timer->_legacy_data = data;
+	timer->user_data = data;
 }
 
 /**

kernel/legacy_timer.c

@@ -46,7 +46,7 @@ static sys_dlist_t timer_pool;
 
 static void timer_sem_give(struct k_timer *timer)
 {
-	k_sem_give((ksem_t)timer->_legacy_data);
+	k_sem_give((ksem_t)timer->user_data);
 }
 
 static int init_dyamic_timers(struct device *dev)
@@ -97,7 +97,7 @@ void task_timer_start(ktimer_t timer, int32_t duration,
 		return;
 	}
 
-	timer->_legacy_data = (void *)sema;
+	timer->user_data = (void *)sema;
 
 	k_timer_start(timer, _ticks_to_ms(duration), _ticks_to_ms(period));
 }
@@ -123,5 +123,5 @@ void *nano_timer_test(struct nano_timer *timer, int32_t timeout_in_ticks)
 	} else {
 		test_fn = k_timer_status_sync;
 	}
-	return test_fn(timer) ? timer->_legacy_data : NULL;
+	return test_fn(timer) ? (void *)timer->user_data : NULL;
 }

kernel/timer.c

@@ -112,7 +112,7 @@ void k_timer_init(struct k_timer *timer,
 	_init_timeout(&timer->timeout, _timer_expiration_handler);
 	SYS_TRACING_OBJ_INIT(k_timer, timer);
 
-	timer->_legacy_data = NULL;
+	timer->user_data = 0;
 }