ChorusOS man pages section 9DKI: Driver to Kernel Interface

svTimeoutSet(9DKI)

NAME

svTimeoutSet, svTimeoutCancel, svTimeoutGetRes- timeout operations

SYNOPSIS

#include <dki/dki.h>

timeout

handler

waitLimit

flag

timeout

resolution

FEATURES

DKI

DESCRIPTION

Provides timeout operations services.

EXTENDED DESCRIPTION

Device drivers may need Timeout services to check whether there is any activity on a device, or to verify that a started action will terminate before a given time limit is reached. The svTimeout API is used for DKI purposes. Note that as these services should be implemented using drivers, they are not available and must not be used by drivers at initialization time.

svTimeoutSet sets a timeout request. When the interval of time specified by waitLimit has expired, the handler is invoked with timeout passed as its only argument. Fields within the KnTimeout structure are initialized and modified solely within the nucleus and are inaccessible to an application.

The handler argument points to a timeout handler routine. A timeout handler is a special kind of interrupt handler which is executed solely in supervisor execution mode, its code and accessed data must be within the locked-in-memory regions of the supervisor space. The set of kernel calls that can be used in a timeout handler are limited, as for any interrupt handler.

The waitLimit pointer argument refers to a KnTimeVal structure whose members are defined in sysTime(2K).

svTimeoutSet expects the KnTimeVal structure parameter to be set to a relative interval of time after which the handler is invoked. The flag argument is unused and should therefore be set to 0 .

On success, svTimeoutSet returns K_OK .

Otherwise, K_EINVAL is returned specifying that the waitLimit value is invalid or that no handler was specified.

svTimeoutSet must not be called using a KnTimeout which has an existing timeout pending (use svTimeoutCancel to cancel the request first).

svTimeoutCancel attempts to cancel a timeout request. It takes as an argument the address of the KnTimeout object used in the call to svTimeoutSet . If the timeout request is still pending, it is immediately cancelled and TRUE is returned signifying that the timer had not yet expired. Otherwise, the timeout interval had already passed and the timeout handler was called, in which case nothing occurs and FALSE is returned.

svTimeoutGetRes returns in resolution the smallest possible difference between two distinct waitLimit values. Note that Timeout resolution usually corresponds to the microkernel tick period (usually 10 milli-seconds).

Allowed Calling Contexts

The following table specifies the contexts in which a caller is allowed to invoke each service.

Services	Base level	DKI thread	Interrupt	Blocking
svTimeoutSet	+	+	+	-
svTimeoutCancel	+	+	+	-
svTimeoutGetRes	+	+	-	-

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving