[Xenomai-core] tdm_event_timedwait documentation

[Bernhard Walle <bernhard.walle@domain.hid>]

[-- Attachment #1: Type: text/plain, Size: 2314 bytes --]

Hello,

IMO the documentation of tdm_event_timedwait is a bit unclear. There
are two timeout values: the timeout and the timeout sequence. After
reading the source code the behaviour is clear but from documentation
I would have expected following behaviour:

   - the sequence timeout is the sum of the timeouts over all calls
     (which is in case)

   - the timeout in the parameter is the maximum timeout of this call
     (which is not in case)

If I didn't get the source code totally wrong

        if (timeout < 0) {
            err = -EWOULDBLOCK;
            goto unlock_out;
        }

        if (timeout_seq && (timeout > 0)) {
            /* timeout sequence */
            timeout = *timeout_seq - xnpod_get_time();
            if (unlikely(timeout <= 0)) {
                err = -ETIMEDOUT;
                goto unlock_out;
            }
            xnsynch_sleep_on(&event->synch_base, timeout);
        } else {
            /* infinite or relative timeout */
            xnsynch_sleep_on(&event->synch_base, xnpod_ns2ticks(timeout));
        }

the timeout value is only interesting if RTDM_TIMEOUT_NONE or
RTDM_TIMEOUT_INFINITE otherwise it's not relevant because it's
overwritten by the value of the timeout sequence. That should be
expressed in the documentation.

Maybe

 * @param[in] timeout Relative timeout, see
 * @ref RTDM_TIMEOUT_xxx for special values (any positive value
 * means the timeout specified in the timeout sequence)

or something like that.


Regards,
  Bernhard

PS: As there are more and more RTDM-related questions (not only from
me :)) -- what do you think about a mailing list for real-time drivers
only? Which means a common list for RTAI and Xenomai. 

Because I'm using both systems for evaluation I'm always a bit unsure
to which list I should write (well, if it's not RTAI specified I wrote
to the Xenomai list because I know you're working on Xenomai and the
RTAI implementation is from Paolo Mantegazza ;)).
-- 
"Freedom is just another word for nothing left to lose,
Nothing don't mean nothing honey if it ain't free, now now.
And feeling good was easy, Lord, when Bobby sang the blues,
You know feeling good was good enough for me,
Good enough for me and my Bobby McGee."        -- Janis Joplin

[-- Attachment #2: Type: application/pgp-signature, Size: 307 bytes --]