tstop Kernel Service

Purpose

Cancels a pending timer request.

Syntax

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/timer.h>

int tstop ( t)
struct trb *t;

Parameter

Table 1. Parameter
Item	Description
`t`	Specifies the pending timer request to cancel.

Description

The tstop kernel service cancels a pending timer request. The tstop kernel service must be called before a timer request block can be freed with the tfree kernel service.

In a multiprocessor environment, the timer function associated with a timer request block may be active on another processor when the tstop kernel service is called. In this case, the timer request cannot be canceled. A multiprocessor-safe driver must therefore check the return code and take appropriate action if the cancel request failed.

In a uniprocessor environment, the call always succeeds. This is untrue in a multiprocessor environment, where the call fails if the timer is being handled by another processor. Therefore, the function now has a return value, which is set to 0 if successful, or -1 otherwise. Funnelled device drivers do not need to check the return value since they run in a logical uniprocessor environment. Multiprocessor-safe and multiprocessor-efficient device drivers need to check the return value in a loop. In addition, if a driver uses locking, it must release and reacquire its lock within this loop. A delay should be used between the release and reacquiring the lock as shown below:

while (tstop(&trp)) {
       release_any_lock;
       delay_some_time;
       reacquire_the_lock;
} /* null while loop if locks not used */

Execution Environment

The tstop kernel service can be called from either the process or interrupt environment.

Return Values

Table 2. Return Values
Item	Description
0	Indicates that the request was successfully canceled.
-1	Indicates that the request might not be canceled.