Module: xenomai-forge
Branch: master
Commit: 2506fcd585600e66640beaa5de757eac118212e0
URL:    
http://git.xenomai.org/?p=xenomai-forge.git;a=commit;h=2506fcd585600e66640beaa5de757eac118212e0

Author: Philippe Gerum <r...@xenomai.org>
Date:   Sat Oct 26 17:53:39 2013 +0200

alchemy/timer: add documentation

---

 lib/alchemy/timer.c |   90 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)

diff --git a/lib/alchemy/timer.c b/lib/alchemy/timer.c
index f19bf98..616fdba 100644
--- a/lib/alchemy/timer.c
+++ b/lib/alchemy/timer.c
@@ -21,6 +21,23 @@
 
 struct clockobj alchemy_clock;
 
+/**
+ * @fn RTIME rt_timer_read(void)
+ * @brief Return the current system time.
+ *
+ * Return the current time maintained by the Xenomai core clock.
+ *
+ * @return The current time expressed in clock ticks (see note).
+ *
+ * Valid calling context:
+ *
+ * - Regular POSIX threads
+ * - Xenomai threads
+ *
+ * @note The @a time value is a multiple of the Alchemy clock
+ * resolution (see --alchemy-clock-resolution option, defaults to 1
+ * nanosecond).
+ */
 RTIME rt_timer_read(void)
 {
        ticks_t ticks;
@@ -30,16 +47,72 @@ RTIME rt_timer_read(void)
        return ticks;
 }
 
+/**
+ * @fn RTIME rt_timer_ns2ticks(SRTIME ns)
+ * @brief Convert nanoseconds to Alchemy clock ticks.
+ *
+ * Convert a count of nanoseconds to Alchemy clock ticks.  This
+ * routine operates on signed nanosecond values. This is the converse
+ * call to rt_timer_ticks2ns().
+ *
+ * @param ns The count of nanoseconds to convert.
+ *
+ * @return The corresponding value expressed in clock ticks of the
+ * Alchemy clock. The resolution of the Alchemy clock can be set using
+ * the --alchemy-clock-resolution option when starting the application
+ * process (defaults to 1 nanosecond).
+ *
+ * Valid calling context:
+ *
+ * - Regular POSIX threads
+ * - Xenomai threads
+ */
 SRTIME rt_timer_ns2ticks(SRTIME ns)
 {
        return clockobj_ns_to_ticks(&alchemy_clock, ns);
 }
 
+/**
+ * @fn RTIME rt_timer_ticks2ns(SRTIME ns)
+ * @brief Convert Alchemy clock ticks to nanoseconds.
+ *
+ * Convert a count of Alchemy clock ticks to nanoseconds.  This
+ * routine operates on signed nanosecond values. This is the converse
+ * call to rt_timer_ns2ticks().
+ *
+ * @param ns The count of nanoseconds to convert.
+ *
+ * @return The corresponding value expressed in nanoseconds.  The
+ * resolution of the Alchemy clock can be set using the
+ * --alchemy-clock-resolution option when starting the application
+ * process (defaults to 1 nanosecond).
+ *
+ * Valid calling context:
+ *
+ * - Regular POSIX threads
+ * - Xenomai threads
+ */
 SRTIME rt_timer_ticks2ns(SRTIME ticks)
 {
        return clockobj_ticks_to_ns(&alchemy_clock, ticks);
 }
 
+/**
+ * @fn int rt_timer_inquire(RT_TIMER_INFO *info)
+ * @brief Inquire about the Xenomai core timer.
+ *
+ * Return status information of the Xenomai core timer.
+ *
+ * @param info The address of a structure the status data will be
+ * written to.
+ *
+ * @return This service always returns 0.
+ *
+ * Valid calling context:
+ *
+ * - Regular POSIX threads
+ * - Xenomai threads
+ */
 int rt_timer_inquire(RT_TIMER_INFO *info)
 {
        info->period = clockobj_get_resolution(&alchemy_clock);
@@ -48,6 +121,23 @@ int rt_timer_inquire(RT_TIMER_INFO *info)
        return 0;
 }
 
+/**
+ * @fn void rt_timer_spin(RTIME ns)
+ * @brief Busy wait burning CPU cycles.
+ *
+ * Enter a busy waiting loop for a count of nanoseconds.
+ *
+ * Since this service is always called with interrupts enabled, the
+ * caller might be preempted by other real-time activities, therefore
+ * the actual delay might be longer than specified.
+ *
+ * @param ns The time to wait expressed in nanoseconds.
+ *
+ * Valid calling context:
+ *
+ * - Regular POSIX threads
+ * - Xenomai threads
+ */
 void rt_timer_spin(RTIME ns)
 {
        threadobj_spin(ns);


_______________________________________________
Xenomai-git mailing list
Xenomai-git@xenomai.org
http://www.xenomai.org/mailman/listinfo/xenomai-git

Reply via email to