Command: Pause a cog's execution until I/O pin(s) match designated state(s).

((PUB ┆ PRI))
  WAITPEQ (State, Mask, Port )

• State is the logic state(s) to compare the pin(s) against. It is a 32-bit value that indicates the high or low states of up to 32 I/O pins. State is compared against either (INA & Mask), or (INB & Mask), depending on Port.
• Mask is the desired pin(s) to monitor. Mask is a 32-bit value that contains high (1) bits for every I/O pin that should be monitored; low (0) bits indicate pins that should be ignored. Mask is bitwised-ANDed with the 32-bit port's input states and the resulting value is compared against the entire State value.
• Port is a 1-bit value indicating the I/O port to monitor; 0 = Port A, 1 = Port B. Only Port A exists on current (P8X32A) Propeller chips.

Explanation

WAITPEQ, "Wait for Pin(s) to Equal," is one of four wait commands (WAITCNT, WAITPEQ, WAITPNE, and WAITVID) used to pause execution of a cog until a condition is met. WAITPEQ pauses the cog until the value of Port's I/O pin states, bitwised-ANDed with Mask, matches that of State.

When executed, WAITPEQ activates special "wait" hardware in the cog that prevents the System Clock from causing further code execution within the cog until the moment the designated pin, or group of pins, equals the indicated state(s). The wait hardware checks the I/O pins every System Clock cycle and the cog's power consumption is reduced by approximately 7/8^ths during this time.

Using WAITPEQ

WAITPEQ is a great way to synchronize code to external events. For example:

waitpeq(%0100, %1100, 0)         'Wait for P3 & P2 to be low & high
outa[0] := 1                     'Set P0 high

The above code pauses the cog until I/O pin 3 is low and I/O pin 2 is high, then sets I/O pin 0 high.

Using Variable Pin Numbers

For Propeller objects, quite often it is necessary to monitor a single pin whose pin number is specified outside the object itself. An easy way to translate that pin number into the proper 32-bit State and Mask value is by using the Bitwise Decode operator "|<" (see Bitwise Decode '|<' for more information). For example, if the pin number was specified by the variable Pin, and we needed to wait until that pin is high, we could use the following code:

waitpeq(|< Pin, |< Pin, 0)       'Wait for Pin to go high

The Mask parameter, |< Pin, evaluates to a long value where only one bit is high; the bit that corresponds to the pin number given by Pin.

Waiting for Transitions

If we needed to wait for a transition from one state to another (high-to-low, for example) we could use the following code:

waitpeq(%100000, |< 5, 0)        'Wait for Pin 5 to go high
waitpeq(%000000, |< 5, 0)        'Then wait for Pin 5 to go low 

This example first waits for P5 to go high, then waits for it to go low; a high-to-low transition. If we had used the second line of code without the first, the cog would not have paused at all if P5 had been low to start with.