Version 11 (Anthony Rowe, 06/08/2007 08:30 pm) → Version 12/45 (Anthony Rowe, 06/08/2007 08:31 pm)

= Signals =

A signal is a message that a task can use to wakeup one or more tasks waiting on an
event or events. When waiting on an event, a task is suspended and does not consume
CPU time. Nano-RK supports 32 unique signals. It is possible to wait on multiple
signals such that any one of them can wake a task from sleep. All signals must be
created using nrk_sig_create() before they can be used. Any task that wishes to wakeup on a signal
must register the signal using nrk_sig_register(). There are a few special case signals that are
generated by the kernel used to support event timeouts and notification of special actions. See the
'''Kernel Signals''' subsection for more information.

// This is a macro used to convert a signal into a bitmask for nrk_event_wait()
// See nrk_event_wait() for an example.
#define SIG(x) ((uint32_t)1)<<x

// These are typedefs used to represent signals and semaphores
typedef int8_t nrk_sig_t;
typedef uint32_t nrk_sig_mask_t;
typedef int8_t nrk_sem_t;

'''nrk_sig_mask_t nrk_get_active_signal_mask();'''

'''int8_t nrk_delete_signal(nrk_sig_t sig_id);'''

'''int8_t nrk_signal_unregister(nrk_sig_t sig_id);'''

'''int8_t nrk_signal_register(nrk_sig_t sig_id);'''

'''nrk_sig_t nrk_signal_create();'''

'''int8_t nrk_event_signal(nrk_sig_t sig_id);'''

This function is used to signal tasks that are waiting on events using nrk_event_wait().
See example below.

'''nrk_sig_mask_t nrk_event_wait(nrk_sig_mask_t event_mask);'''

This function will wait for a set events. nano-RK supports up to 31 signals. Each signal
represents a bit in a 32 bit number (bit 0 is reserved) so it is possible to logically
OR multiple signals together if you wish to wait on a combination of events. The 32
bit number returned by nrk_event_wait() corresponds to the signal that was returned.
When waiting on multiple signals, this should be used to determine which signal actually
triggered the wakeup. All signals should be defined in the nrk_cfg.h file for each

= Semaphores =

A semaphore is a protected variable and constitutes the classic method for restricting
access to shared resources (e.g. storage,actuators etc) in a multiprogramming environment.
Nano-RK implements semaphores and signals such that
tasks that are suspended on an event or waiting for access to a semaphore will not be
scheduled until the corresponding signal is sent or semaphore becomes available. For more information
on using semaphores please refer to the basic_sem project that comes with the Nano-RK distribution:

'''nrk_sem_t* nrk_sem_create(uint8_t count, uint8_t ceiling_priority);'''

This function creates a semaphore resource, with a priority ceiling value used by the task when accessing the resource. This facilitates the Priority Ceiling Protocol Emulation (PCPE) algorithm used in Nano-RK to avoid priority inversion. ''count'' specifies the number of entries allowed into the critical section. ''ceiling_priority'' sets the ceiling value for the task; Note if
using PCPE this should be the highest priority task accessing the critical section. Below is an example of declaring and creating a semaphore:

nrk_sem_t *my_semaphore;
my_semaphore = nrk_sem_create(1,4);
if(my_semaphore==NULL) nrk_kprintf( PSTR("Error creating Semaphore\r\n" ));

This created a semaphore with a count of 1 (also called a mutex or binary semaphore) with a priority ceiling value of 4.

'''int8_t nrk_sem_pend(nrk_sem_t *rsrc );'''

Semaphore pend takes the address of the created semaphore and attempts to access the resource. If the resource is available,
pend will decrement the resource counter and allow the program to continue, otherwise pend will suspend until the resource is
posted by another task. This can be used to protect critical sections of code. Below is an example of a task pending on a semaphore:

nrk_kprintf( PSTR("Task accessing semaphore\r\n"));
v = nrk_sem_pend(my_semaphore);
if(v==NRK_ERROR) nrk_kprintf( PSTR("Error calling pend\r\n"));
nrk_kprintf( PSTR("Task is now holding semaphore\r\n"));

'''int8_t nrk_sem_post(nrk_sem_t* rsrc);'''

Semaphore post takes the address of a created semaphore and releases access to the resource.
This should be called after exiting a critical section that was pended. Below is an example of a task posting a semaphore:

v = nrk_sem_post(my_semaphore);
if(v==NRK_ERROR) nrk_kprintf( PSTR("Error calling post\r\n"));
nrk_kprintf( PSTR("Task released semaphore\r\n"));

= Special Kernel Signals =

| [wiki:nrk-api Contents] | [wiki:nrk-api-device-drivers Device Drivers] |