Allocates signals.

int32 AllocSignal( uint32 sigMask )

One of the ways tasks communicate is by sending signals to each other. Signals are 1-bit flags that indicate that a particular event has occurred.

Tasks that send and receive signals must agree on which signal bits to use and the meanings of the signals. Except for system signals, there are no conventions for the meanings of individual signal bits; it is up to software developers to define their meanings.

You allocate bits for new signals by calling AllocSignal(). To define one signal at a time - by far the most common case - call AllocSignal() with 0 as the argument:

theSignal = AllocSignal( 0 )

This allocates the next unused bit in the signal word. In the return value, the bit that was allocated is set. If the allocation fails (which happens if all the non-reserved bits in the signal word are already allocated), the procedure returns 0.

In rare cases, you may need to define more than one signal with a single call. You do this by creating a uint32 value and setting any bits you want to allocate for new signals, then calling AllocSignal() with this value as the argument. If all the signals are successfully allocated, the bits set in the return value are the same as the bits that were set in the argument.

Signals are implemented as follows:

• Each task has a 32-bit signal mask that specifies the signals it understands. Tasks allocate bits for new signals by calling AllocSignal(). The bits are numbered from 0 (the least-significant bit) to 31 (the most-significant bit). Bits 0 through 7 are reserved for system signals (signals sent by the kernel to all tasks); remaining bits can be allocated for other signals. Note: Bit 31 is also reserved for the system. It is set when the kernel returns an error code to a task instead of signals. For example, trying to allocate a system signal or signal number 31.
• A task calls SendSignal() to send one or more signals to another task. Each bit set in the signalWord argument specifies a signal to send. Normally, only one signal is sent at a time.
• When SendSignal() is called, the kernel gets the incoming signal word and ORs it into the received signal mask of the target task. If the task was in the wait queue, it compares the received signals with the WaitSignalMask. If there are any bits set in the target, the task is moved from the wait queue to the ready queue.
• If the SIGF_ABORT system signal is sent to the task, the corresponding bit in the task's signal word is automatically set. This signal cannot be masked.
• A task gets incoming signals by calling WaitSignal(). If any bits are set in the task's signal word , WaitSignal() returns immediately. If no bits are set in the task's signal word, the task remains in wait state until a signal arrives that matches one of the signals the task is waiting for.

The following system signals are currently defined:

• SIGF_ABORT Informs the task that the current operation has been aborted.

• SIGF_IODONE Informs the task that an asynchronous I/O request is complete.

• SIGF_DEADTASK Informs the task that one of its child tasks or threads has been deleted. Note: This signal does not specify which task was deleted. To find this out, the parent task must check to see which of its child tasks still exist.

• SIGF_SEMAPHORE Informs a task waiting to lock a semaphore that it can do so. Note: This signal is for system internal use only.

• signalMask An uint32 value in which the bits to be allocated are set, or 0 to allocate the next available bit. You should use 0 whenever possible (see Notes).

The procedure returns a int32 value with bits set for any bits that were allocated or 0 if not all of the requested bits could be allocated. It returns ILLEGALSIGNAL if the signalMask specified a reserved signal.

SWI implemented in kernel folio V20.

• task.h ARM C Prototype

Use FreeSignal() to deallocate signals.

Future versions of Portfolio may define additional system signals. To help ensure that the signal bits you allocate in current applications do not conflict with future system signals, you should always use 0 as the value of the signalMask argument when allocating signals. If you must allocate specific signal bits (which is discouraged), use bits 17-31.

FreeSignal(), GetCurrentSignals(), SendSignal(), WaitSignal()