Signal Functions

A Signal function let you repeat operations, like signal inputs and pulses, in the background while µVision3 executes your target program. Signal functions help you simulate and test serial I/O, analog I/O, port communications, and other repetitive external events.

Signal functions execute in the background while µVision3 simulates your target program. Therefore, a signal function must call the twatch function at some point to delay and let µVision3 run your target program. µVision3 reports an error for signal functions that never call twatch.

Note

• µVision3 provides a number of system variables you may use in your signal functions. Refer to System Variables for more information.

Signal functions begin with the SIGNAL keyword and are defined as follows:

SIGNAL void fname (parameter_list) {
  statements
}

fname	is the name of the function.
parameter_list	is the list of arguments that are passed to the function. Each argument must have a type and a name. If no arguments are passed to the function, use void for the parameter_list. Multiple arguments are separated by commas.
statements	are instructions the function carries out.
{	is the open brace. The function definition is complete when the number of open braces is balanced with the number of the closing braces ("}").

Example

The following example shows a signal function that puts the character 'A' into the serial input buffer once every 1,000,000 CPU states. For more information refer to Creating Functions.

SIGNAL void StuffS0in (void) {
  while (1) {
    S0IN = 'A';
    twatch (1000000);
  }
}

To invoke this function, type the following in the command window.

StuffS0in()

When invoked, the StuffS0in signal function puts and ASCII character 'A' in the serial input buffer, delays for 1,000,000 CPU states, and repeats.

Restrictions

The following restrictions apply to signal functions:

• The return type of a signal function must be void.
• A signal function may have a maximum of eight function parameters.
• A signal function may invoke other predefined functions, user functions, or signal functions.
• A signal function may be invoked by a user function.
• A signal function must call the twatch function at least once. Signal functions that never call twatch do not allow the target program time to execute. Since you cannot use Ctrl+C to abort a signal function, µVision3 may enter an infinite loop.

Managing Signal Functions

µVision3 maintains a queue for active signal functions. A signal function may either be either idle or running. A signal function that is idle is delayed while it waits for the number of CPU states specified in a call to twatch to expire. A signal function that is running is executing statements inside the function.

When you invoke a signal function, µVision3 adds that function to the queue and marks it as running. Signal functions may only be activated once, if the function is already in the queue, a warning is displayed. View the state of active signal functions with the command SIGNAL STATE. Remove active signal functions form the queue with the command SIGNAL KILL.

When a signal function invokes the twatch function, it goes in the idle state for the number of CPU states passed to twatch. After the user program has executed the specified number of CPU states, the signal function becomes running. Execution continues at the statement after twatch.

If a signal function exits, because of a return statement, it is automatically removed from the queue of active signal functions.

Analog Example

The following example shows a signal function that varies the input to analog input 0 on a C167. The function increases and decreases the input voltage by 0.5 volts from 0V and an upper limit that is specified as the signal function's only argument. This signal function repeats indefinitely, delaying 200,000 states for each voltage step.

signal void analog0 (float limit) {
float volts;

printf ("Analog0 (%f) entered.\n", limit);
  while (1) {           /* forever */
    volts = 0;
    while (volts <= limit) {
      ain0 = volts;     /* analog input-0 */
      twatch (200000);  /* 200000 states Time-Break */
      volts += 0.1;     /* increase voltage */
    }
    volts = limit;
    while (volts >= 0.0) {
      ain0 = volts;
      twatch (200000);  /* 200000 states Time-Break */
      volts -= 0.1;     /* decrease voltage */
    }
  }
}

The signal function analog0 can then be invoked as follows:

>ANALOG0 (5.0)           /* Start of 'ANALOG()' */
ANALOG0 (5.000000) ENTERED

The SIGNAL STATE command to displays the current state of the analog0:

>SIGNAL STATE
 1  idle     Signal = ANALOG0 (line 8)

µVision3 lists the internal function number, the status of the signal function: idle or running, the function name and the line number that is executing.

Since the status of the signal function is idle, you can infer that analog0 executed the twatch function (on line 8 of analog0) and is waiting for the specified number of CPU states to elapse. When 200,000 states pass, analog0 continues execution until the next call to twatch in line 8 or line 14.

The following command removes the analog0 signal function from the queue of active signal functions.

>SIGNAL KILL ANALOG0