#include <nitro/os.h>void OS_WaitIrq( BOOL clear, OSIrqMask irqFlags );clear |
Whether check flags should be cleared. |
irqFlags |
The mask value of the interrupt generation for which the function is waiting. You can specify more than one by using a logical sum. |
None.
Waits for the generation of a specified IRQ interrupt cause.
Use irqFlags to specify multiple interrupt sources by logical OR-ing the mask values. Generation of any of the interrupts included here will cause a return from the function. Refer to the following information for the types of interrupts.
(Example) Waits for either VBLANK or TIMER0.
OS_WaitIrq( TRUE, OS_IE_V_BLANK | OS_IE_TIMER0 );
To determine if an interrupt occurred, examine whether the interrupt check flag has been set. To set this flag, the user must explicitly call the OS_SetIrqCheckFlag function from within the interrupt handler.
If clear is set to TRUE, the interrupt check flags specified in irqFlags will be reset before waiting for the interrupt to occur. If FALSE, they will not be reset. If they are not reset and the check flag you want to wait on is set when this function is reached, control will return from this function immediately.
The difference between the OS_WaitInterrupt and OS_WaitIrq functions is the following. While OS_WaitInterrupt is waiting for an interrupt cause, it uses OS_Halt to stop. While OS_WaitIrq is waiting for an interrupt cause, it switches processing to another thread. It restarts operation after an interrupt is generated. If no threads are used, both functions behave the same.
Care must be taken when multiple threads have the same interrupt. It is possible to have a situation in which only one thread is run, and the others are not.
For example, consider the following program.
void TwlMain(void)
{
:
OS_CreateThread( &thread1, proc1, ..., 10 );
OS_CreateThread( &thread2, proc2, ..., 11 );
:
}
//---- Thread1
void proc1(void* arg)
{
while(1)
{
OS_WaitIrq( TRUE, OS_IE_V_BLANK );
OS_Printf("proc1\n");
}
}
//---- Thread2
void proc2(void* arg)
{
while(1)
{
OS_WaitIrq( TRUE, OS_IE_V_BLANK );
OS_Printf("proc2\n");
}
}
//---- V-Blank interrupt handler
void VBlankHandler( void )
{
OS_SetIrqCheckFlag( OS_IE_V_BLANK );
}Thread 1 and thread 2 wait for VBLANK. Once a VBLANK occurs, the VBLANK interrupt check flag is set within the handler. Then thread 1 and thread 2 will enter the runnable state, but thread 1 will run first due to the order of thread priorities. Thread 1 will display "proc1" and then reenter the OS_WaitIrq function and wait for a VBLANK. Since at this time the first argument is TRUE, the thread will reset the VBLANK interrupt check flag and go to sleep. Next, thread 2 will be given the right to run, but because the VBLANK interrupt check flag has already been cleared, it will go back to sleep without returning from the OS_WaitIrq function. This cycle will also be repeated during the next VBLANK. In other words, this program will just keep displaying "proc1" without ever displaying "proc2".
That said, the first argument of the OS_WaitIrq function cannot be set to FALSE. If it is set to FALSE, no matter how many times the OS_WaitIrq function is called after a VBLANK occurs, control will return immediately.
OS_SetIrqCheckFlag
OS_WaitInterrupt
OS_WaitAnyIrq
2008/07/01 Added a note about invoking from multiple threads.
2005/03/08 Standardized the Japanese term for "interrupt."
2004/05/24 Clarified the differences from the OS_WaitInterrupt function.
2004/05/01 Initial version.
CONFIDENTIAL