Semaphore functions

Files
file	sem.c
	Semaphore functions.
Functions
	MODULE_LICENSE ("GPL")
void	rt_typed_sem_init (SEM *sem, int value, int type)
	Initialize a specifically typed (counting, binary, resource) semaphore.
void	rt_sem_init (SEM *sem, int value)
	Initialize a counting semaphore.
int	rt_sem_delete (SEM *sem)
	Delete a semaphore.
int	rt_sem_count (SEM *sem)
int	rt_sem_signal (SEM *sem)
	Signaling a semaphore.
int	rt_sem_broadcast (SEM *sem)
	Signaling a semaphore.
int	rt_sem_wait (SEM *sem)
	Take a semaphore.
int	rt_sem_wait_if (SEM *sem)
	Take a semaphore, only if the calling task is not blocked.
int	rt_sem_wait_until (SEM *sem, RTIME time)
	Wait a semaphore with timeout.
int	rt_sem_wait_timed (SEM *sem, RTIME delay)
	Wait a semaphore with timeout.
int	rt_sem_wait_barrier (SEM *sem)
	Wait on a semaphore barrier.
int	rt_cond_signal (CND *cnd)
	Wait for a signal to a conditional variable.
int	rt_cndmtx_signal (SEM *mtx, RT_TASK *rt_current)
int	rt_cond_wait (CND *cnd, SEM *mtx)
	Wait for a signal to a conditional variable.
int	rt_cond_wait_until (CND *cnd, SEM *mtx, RTIME time)
	Wait a semaphore with timeout.
int	rt_cond_wait_timed (CND *cnd, SEM *mtx, RTIME delay)
	Wait a semaphore with timeout.
int	rt_rwl_init (RWL *rwl)
	Initialize a multi readers single writer lock.
int	rt_rwl_delete (RWL *rwl)
	destroys a multi readers single writer lock.
int	rt_rwl_rdlock (RWL *rwl)
	acquires a multi readers single writer lock for reading.
int	rt_rwl_rdlock_if (RWL *rwl)
	try to acquire a multi readers single writer lock just for reading.
int	rt_rwl_rdlock_until (RWL *rwl, RTIME time)
	try to acquire a multi readers single writer lock for reading within an absolute deadline time.
int	rt_rwl_rdlock_timed (RWL *rwl, RTIME delay)
	try to acquire a multi readers single writer lock for reading within a relative deadline time.
int	rt_rwl_wrlock (RWL *rwl)
	acquires a multi readers single writer lock for wrtiting.
int	rt_rwl_wrlock_if (RWL *rwl)
	acquires a multi readers single writer lock for writing.
int	rt_rwl_wrlock_until (RWL *rwl, RTIME time)
	try to acquire a multi readers single writer lock for writing within an absolute deadline time.
int	rt_rwl_wrlock_timed (RWL *rwl, RTIME delay)
	try to acquire a multi readers single writer lock for writing within a relative deadline time.
int	rt_rwl_unlock (RWL *rwl)
	unlock an acquired multi readers single writer lock.
int	rt_spl_init (SPL *spl)
	Initialize a spinlock.
int	rt_spl_delete (SPL *spl)
	Initialize a spinlock.
int	rt_spl_lock (SPL *spl)
	Acquire a spinlock.
int	rt_spl_lock_if (SPL *spl)
	Acquire a spinlock without waiting.
int	rt_spl_lock_timed (SPL *spl, unsigned long ns)
	Acquire a spinlock with timeout.
int	rt_spl_unlock (SPL *spl)
	Release an owned spinlock.
SEM *	_rt_typed_named_sem_init (unsigned long sem_name, int value, int type)
	Initialize a specifically typed (counting, binary, resource) semaphore identified by a name.
int	rt_named_sem_delete (SEM *sem)
	Delete a semaphore initialized in named mode.
RWL *	_rt_named_rwl_init (unsigned long rwl_name)
	Initialize a multi readers single writer lock identified by a name.
int	rt_named_rwl_delete (RWL *rwl)
	Delete a multi readers single writer lock in named mode.
SPL *	_rt_named_spl_init (unsigned long spl_name)
	Initialize a spinlock identified by a name.
int	rt_named_spl_delete (SPL *spl)
	Delete a spinlock in named mode.
int	set_rt_fun_entries (struct rt_native_fun_entry *entry)
void	reset_rt_fun_entries (struct rt_native_fun_entry *entry)
int	__rtai_sem_init (void)
void	__rtai_sem_exit (void)
Variables
rt_native_fun_entry	rt_sem_entries []

---

Function Documentation

void __rtai_sem_exit (  void   )

Definition at line 1755 of file sem.c. References reset_rt_fun_entries(), and rt_sem_entries. Here is the call graph for this function:

int __rtai_sem_init (  void   )

Definition at line 1750 of file sem.c. References rt_sem_entries, and set_rt_fun_entries(). Here is the call graph for this function:

RWL* _rt_named_rwl_init (  unsigned long  rwl_name  )

Initialize a multi readers single writer lock identified by a name. _rt_named_rwl_init allocate and initializes a multi readers single writer lock (RWL) identified by name. Once the lock structure is allocated the initialization is as for rt_rwl_init. The function returns the handle pointing to the allocated multi readers single writer lock o structure, to be used as the usual lock address in all rwl based services. Named objects are useful for use among different processes, kernel/user space and in distributed applications, see netrpc. Parameters: rwl_name  is the identifier associated with the returned object. Since name can be a clumsy identifier, services are provided to convert 6 characters identifiers to unsigned long, and vice versa. See also: nam2num() and num2nam(). As for all the named initialization functions it must be remarked that only the very first call to initilize/create a named RTAI object does a real allocation of the object, any following call with the same name will just increase its usage count. In any case the function returns a pointer to the named object, or zero if in error. Returns: either a valid pointer or 0 if in error. Definition at line 1576 of file sem.c. References IS_RWL, rt_free(), rt_get_adr_cnt(), rt_malloc(), rt_register(), rt_rwl_delete(), rt_rwl_init(), and RWL. Here is the call graph for this function:

SPL* _rt_named_spl_init (  unsigned long  spl_name  )

Initialize a spinlock identified by a name. _rt_named_spl_init allocate and initializes a spinlock (SPL) identified by name. Once the spinlock structure is allocated the initialization is as for rt_spl_init. The function returns the handle pointing to the allocated spinlock structure, to be used as the usual spinlock address in all spinlock based services. Named objects are useful for use among different processes and kernel/user space. Parameters: spl_name  is the identifier associated with the returned object. Since name can be a clumsy identifier, services are provided to convert 6 characters identifiers to unsigned long, and vice versa. See also: nam2num() and num2nam(). As for all the named initialization functions it must be remarked that only the very first call to initilize/create a named RTAI object does a real allocation of the object, any following call with the same name will just increase its usage count. In any case the function returns a pointer to the named object, or zero if in error. Returns: either a valid pointer or 0 if in error. Definition at line 1656 of file sem.c. References IS_SPL, rt_free(), rt_get_adr_cnt(), rt_malloc(), rt_register(), rt_spl_delete(), rt_spl_init(), and SPL. Here is the call graph for this function:

SEM* _rt_typed_named_sem_init (  unsigned long  sem_name, int  value, int  type )

Initialize a specifically typed (counting, binary, resource) semaphore identified by a name. _rt_typed_named_sem_init allocate and initializes a semaphore identified by name of type type. Once the semaphore structure is allocated the initialization is as for rt_typed_sem_init. The function returns the handle pointing to the allocated semaphore structure, to be used as the usual semaphore address in all semaphore based services. Named objects are useful for use among different processes, kernel/user space and in distributed applications, see netrpc. Parameters: sem_name  is the identifier associated with the returned object. value  is the initial value of the semaphore, always set to 1 for a resource semaphore. type  is the semaphore type and queuing policy. It can be an OR a semaphore kind: CNT_SEM for counting semaphores, BIN_SEM for binary semaphores, RES_SEM for resource semaphores; and queuing policy: FIFO_Q, PRIO_Q for a fifo and priority queueing respectively. Resource semaphores will enforce a PRIO_Q policy anyhow. Since name can be a clumsy identifier, services are provided to convert 6 characters identifiers to unsigned long, and vice versa. See also: nam2num() and num2nam(). See rt_typed_sem_init for further clues. As for all the named initialization functions it must be remarked that only the very first call to initilize/create a named RTAI object does a real allocation of the object, any following call with the same name will just increase its usage count. In any case the function returns a pointer to the named object, or zero if in error. Returns: either a valid pointer or 0 if in error. Definition at line 1494 of file sem.c. References IS_SEM, rt_free(), rt_get_adr_cnt(), rt_malloc(), rt_register(), rt_sem_delete(), rt_typed_sem_init(), and SEM. Here is the call graph for this function:

MODULE_LICENSE (  "GPL"   )

void reset_rt_fun_entries (  struct rt_native_fun_entry *  entry  )

Definition at line 1543 of file sched.c.

int rt_cndmtx_signal (  SEM *  mtx, RT_TASK *  rt_current )  [inline, static]

Definition at line 736 of file sem.c. References dequeue_blocked(), RT_SCHED_DELAYED, RT_SCHED_READY, RT_SCHED_SEMAPHORE, rt_schedule(), RT_TASK, SEM, and task. Referenced by rt_cond_wait(), and rt_cond_wait_until(). Here is the call graph for this function:

int rt_cond_signal (  CND *  cnd  )

Wait for a signal to a conditional variable. rt_cond_signal resumes one of the tasks that are waiting on the condition semaphore cnd. Nothing happens if no task is waiting on cnd, while it resumed the first queued task blocked on cnd, according to the queueing method set at rt_cond_init. Parameters: cnd  points to the structure used in the call to rt_cond_init(). Returns: 0 Definition at line 715 of file sem.c. References CND, dequeue_blocked(), flags, RT_SCHED_DELAYED, RT_SCHED_READY, RT_SCHED_SEMAPHORE, RT_SEM_MAGIC, RT_TASK, SEM_ERR, and task. Here is the call graph for this function:

int rt_cond_wait (  CND *  cnd, SEM *  mtx )

Wait for a signal to a conditional variable. rt_cond_wait atomically unlocks mtx (as for using rt_sem_signal) and waits for the condition semaphore cnd to be signaled. The task execution is suspended until the condition semaphore is signalled. Mtx must be obtained by the calling task, before calling rt_cond_wait is called. Before returning to the calling task rt_cond_wait reacquires mtx by calling rt_sem_wait. Parameters: cnd  points to the structure used in the call to rt_cond_init(). mtx  points to the structure used in the call to rt_sem_init(). Returns: 0 on succes, SEM_ERR in case of error. Definition at line 791 of file sem.c. References CND, enqueue_blocked(), flags, rt_cndmtx_signal(), RT_SCHED_SEMAPHORE, RT_SEM_MAGIC, rt_sem_wait(), RT_TASK, SEM, and SEM_ERR. Here is the call graph for this function:

int rt_cond_wait_timed (  CND *  cnd, SEM *  mtx, RTIME  delay )

Wait a semaphore with timeout. rt_cond_wait_timed atomically unlocks mtx (as for using rt_sem_signal) and waits for the condition semaphore cnd to be signalled. The task execution is suspended until the condition semaphore is either signaled or a timeout expires. Mtx must be obtained by the calling task, before calling rt_cond_wait is called. Before returning to the calling task rt_cond_wait_until reacquires mtx by calling rt_sem_wait and returns a value to indicate if it has been signalled pr timedout. Parameters: cnd  points to the structure used in the call to rt_cond_init(). mtx  points to the structure used in the call to rt_sem_init(). delay  is a realtive time values with respect to the current time, in timer count unit. Returns: 0 if it was signaled, SEM_TIMOUT if a timeout occured, SEM_ERR if the task has been resumed because of any other action (likely cnd was deleted). Definition at line 903 of file sem.c. References CND, rt_cond_wait_until(), RTIME, and SEM. Here is the call graph for this function:

int rt_cond_wait_until (  CND *  cnd, SEM *  mtx, RTIME  time )

Wait a semaphore with timeout. rt_cond_wait_until atomically unlocks mtx (as for using rt_sem_signal) and waits for the condition semaphore cnd to be signalled. The task execution is suspended until the condition semaphore is either signaled or a timeout expires. Mtx must be obtained by the calling task, before calling rt_cond_wait is called. Before returning to the calling task rt_cond_wait_until reacquires mtx by calling rt_sem_wait and returns a value to indicate if it has been signalled pr timedout. Parameters: cnd  points to the structure used in the call to rt_cond_init(). mtx  points to the structure used in the call to rt_sem_init(). time  is an absolute value to the current time, in timer count unit. Returns: 0 if it was signaled, SEM_TIMOUT if a timeout occured, SEM_ERR if the task has been resumed because of any other action (likely cnd was deleted). Definition at line 840 of file sem.c. References CND, dequeue_blocked(), enqueue_blocked(), flags, rt_cndmtx_signal(), RT_SCHED_DELAYED, RT_SCHED_SEMAPHORE, RT_SEM_MAGIC, rt_sem_wait(), RTIME, SEM, SEM_ERR, and SEM_TIMOUT. Referenced by _mq_timedreceive(), _mq_timedsend(), and rt_cond_wait_timed(). Here is the call graph for this function:

int rt_named_rwl_delete (  RWL *  rwl  )

Delete a multi readers single writer lock in named mode. rt_named_rwl_delete deletes a multi readers single writer lock previously created with _rt_named_rwl_init(). Parameters: rwl  points to the structure pointer returned by a corresponding call to rt_named_rwl_init. As it is done by all the named allocation functions delete calls have just the effect of decrementing a usage count till the last is done, as that is the one the really frees the object. Returns: an int >=0 is returned upon success, SEM_ERR if it failed to delete the multi readers single writer lock, -EFAULT if the lock does not exist anymore. Definition at line 1614 of file sem.c. References rt_drg_on_adr_cnt(), rt_free(), rt_rwl_delete(), RWL, and SEM_ERR. Here is the call graph for this function:

int rt_named_sem_delete (  SEM *  sem  )

Delete a semaphore initialized in named mode. rt_named_sem_delete deletes a semaphore previously created with _rt_typed_named_sem_init(). Parameters: sem  points to the structure pointer returned by a corresponding call to _rt_typed_named_sem_init. Any tasks blocked on this semaphore is returned in error and allowed to run when semaphore is destroyed. As it is done by all the named allocation functions delete calls have just the effect of decrementing a usage count till the last is done, as that is the one the really frees the object. Returns: an int >=0 is returned upon success, SEM_ERR if it failed to delete the semafore, -EFAULT if the semaphore does not exist anymore. Definition at line 1533 of file sem.c. References rt_drg_on_adr_cnt(), rt_free(), rt_sem_delete(), SEM, and SEM_ERR. Referenced by RT_named_sem_delete(). Here is the call graph for this function:

int rt_named_spl_delete (  SPL *  spl  )

Delete a spinlock in named mode. rt_named_spl_delete deletes a spinlock previously created with _rt_named_spl_init(). Parameters: spl  points to the structure pointer returned by a corresponding call to rt_named_spl_init. As it is done by all the named allocation functions delete calls have just the effect of decrementing a usage count till the last is done, as that is the one the really frees the object. Returns: an int >=0 is returned upon success, -EFAULT if the spinlock does not exist anymore. Definition at line 1693 of file sem.c. References rt_drg_on_adr_cnt(), rt_free(), rt_spl_delete(), and SPL. Here is the call graph for this function:

int rt_rwl_delete (  RWL *  rwl  )

destroys a multi readers single writer lock. rt_rwl_init destroys a multi readers single writer lock rwl. Parameters: rwl  must point to an allocated RWL structure. Returns: 0 if OK, SEM_ERR if anything went wrong. Definition at line 949 of file sem.c. References rt_sem_delete(), RWL, and SEM_ERR. Referenced by _rt_named_rwl_init(), and rt_named_rwl_delete(). Here is the call graph for this function:

int rt_rwl_init (  RWL *  rwl  )

Initialize a multi readers single writer lock. rt_rwl_init initializes a multi readers single writer lock rwl. Parameters: rwl  must point to an allocated RWL structure. A multi readers single writer lock (RWL) is a synchronization mechanism that allows to have simultaneous read only access to an object, while only one task can have write access. A data set which is searched more frequently than it is changed can be usefully controlled by using an rwl. The lock acquisition policy is determined solely on the priority of tasks applying to own a lock. Returns: 0 if always. Definition at line 929 of file sem.c. References CNT_SEM, RES_SEM, rt_typed_sem_init(), and RWL. Referenced by _rt_named_rwl_init(). Here is the call graph for this function:

int rt_rwl_rdlock (  RWL *  rwl  )

acquires a multi readers single writer lock for reading. rt_rwl_rdlock acquires a multi readers single writer lock rwl for reading. The calling task will block only if any writer owns the lock already or there are writers with higher priority waiting to acquire write access. Parameters: rwl  must point to an allocated RWL structure. Returns: 0 if OK, SEM_ERR if anything went wrong after being blocked. Definition at line 974 of file sem.c. References flags, rt_sem_wait(), RT_TASK, RWL, SEM_ERR, and SEM_TIMOUT. Here is the call graph for this function:

int rt_rwl_rdlock_if (  RWL *  rwl  )

try to acquire a multi readers single writer lock just for reading. rt_rwl_rdlock_if tries to acquire a multi readers single writer lock rwl for reading immediately, i.e. without blocking if a writer owns the lock or there are writers with higher priority waiting to acquire write access. Parameters: rwl  must point to an allocated RWL structure. Returns: 0 if the lock was acquired, -1 if the lock was already owned. Definition at line 1011 of file sem.c. References flags, RT_TASK, and RWL.

int rt_rwl_rdlock_timed (  RWL *  rwl, RTIME  delay )

try to acquire a multi readers single writer lock for reading within a relative deadline time. rt_rwl_rdlock_timed tries to acquire a multi readers single writer lock rwl for reading, as for rt_rwl_rdlock, but timing out if the lock has not been acquired within an assigned deadline. Parameters: rwl  must point to an allocated RWL structure. delay  is the time delay within which the lock must be acquired, in internal count units. Returns: 0 if the lock was acquired, SEM_TIMOUT if the deadline expired without acquiring the lock, SEM_ERR in case something went wrong. Definition at line 1086 of file sem.c. References rt_rwl_rdlock_until(), RTIME, and RWL. Here is the call graph for this function:

int rt_rwl_rdlock_until (  RWL *  rwl, RTIME  time )

try to acquire a multi readers single writer lock for reading within an absolute deadline time. rt_rwl_rdlock_untill tries to acquire a multi readers single writer lock rwl for reading, as for rt_rwl_rdlock, but timing out if the lock has not been acquired within an assigned deadline. Parameters: rwl  must point to an allocated RWL structure. time  is the time deadline, in internal count units. Returns: 0 if the lock was acquired, SEM_TIMOUT if the deadline expired without acquiring the lock, SEM_ERR in case something went wrong. Definition at line 1044 of file sem.c. References flags, rt_sem_wait_until(), RT_TASK, RTIME, RWL, SEM_ERR, and SEM_TIMOUT. Referenced by rt_rwl_rdlock_timed(). Here is the call graph for this function:

int rt_rwl_unlock (  RWL *  rwl  )

unlock an acquired multi readers single writer lock. rt_rwl_unlock unlocks an acquired multi readers single writer lock rwl. After releasing the lock any task waiting to acquire it will own the lock according to its priority, whether it is a reader or a writer, otherwise the lock will be fully unlocked. Parameters: rwl  must point to an allocated RWL structure. Returns: 0 always. Definition at line 1228 of file sem.c. References flags, rt_sem_signal(), RT_TASK, and RWL. Here is the call graph for this function:

int rt_rwl_wrlock (  RWL *  rwl  )

acquires a multi readers single writer lock for wrtiting. rt_rwl_rwlock acquires a multi readers single writer lock rwl for writing. The calling task will block if any other task, reader or writer, owns the lock already. Parameters: rwl  must point to an allocated RWL structure. Returns: 0 if OK, SEM_ERR if anything went wrong after being blocked. Definition at line 1105 of file sem.c. References flags, rt_sem_wait(), RWL, and SEM_TIMOUT. Here is the call graph for this function:

int rt_rwl_wrlock_if (  RWL *  rwl  )

acquires a multi readers single writer lock for writing. rt_rwl_wrlock_if try to acquire a multi readers single writer lock rwl for writing immediately, i.e without blocking if the lock is owned already. Parameters: rwl  must point to an allocated RWL structure. Returns: 0 if the lock was acquired, -1 if the lock was already owned. Definition at line 1138 of file sem.c. References flags, rt_sem_wait_if(), and RWL. Here is the call graph for this function:

int rt_rwl_wrlock_timed (  RWL *  rwl, RTIME  delay )

try to acquire a multi readers single writer lock for writing within a relative deadline time. rt_rwl_wrlock_timed tries to acquire a multi readers single writer lock rwl for writing, as for rt_rwl_wrlock, timing out if the lock has not been acquired within an assigned deadline. Parameters: rwl  must point to an allocated RWL structure. delay  is the time delay within which the lock must be acquired, in internal count units. Returns: 0 if the lock was acquired, SEM_TIMOUT if the deadline expired without acquiring the lock, SEM_ERR in case something went wrong. Definition at line 1208 of file sem.c. References rt_rwl_wrlock_until(), RTIME, and RWL. Here is the call graph for this function:

int rt_rwl_wrlock_until (  RWL *  rwl, RTIME  time )

try to acquire a multi readers single writer lock for writing within an absolute deadline time. rt_rwl_rwlock_until tries to acquire a multi readers single writer lock rwl for writing, as for rt_rwl_rwlock, but timing out if the lock has not been acquired within an assigned deadline. Parameters: rwl  must point to an allocated RWL structure. time  is the time deadline, in internal count units. Returns: 0 if the lock was acquired, SEM_TIMOUT if the deadline expired without acquiring the lock, SEM_ERR in case something went wrong. Definition at line 1169 of file sem.c. References flags, rt_sem_wait_until(), RTIME, RWL, and SEM_TIMOUT. Referenced by rt_rwl_wrlock_timed(). Here is the call graph for this function:

int rt_sem_broadcast (  SEM *  sem  )

Signaling a semaphore. rt_sem_broadcast signals an event to a semaphore that unblocks all tasks waiting on it. It is used as a support for RTAI proper conditional variables but can be of help in many other instances. After the broadcast the semaphore counts is set to zero, thus all tasks waiting on it will blocked. Parameters: sem  points to the structure used in the call to rt_sem_init(). Returns: 0 always. Definition at line 355 of file sem.c. References dequeue_blocked(), flags, RT_SCHED_DELAYED, RT_SCHED_READY, RT_SCHED_SEMAPHORE, RT_SEM_MAGIC, RT_TASK, SEM, SEM_ERR, and task. Referenced by RT_sem_broadcast(), and rt_sem_wait_barrier(). Here is the call graph for this function:

int rt_sem_count (  SEM *  sem  )

Definition at line 232 of file sem.c. References SEM.

int rt_sem_delete (  SEM *  sem  )

Delete a semaphore. rt_sem_delete deletes a semaphore previously created with rt_sem_init(). Parameters: sem  points to the structure used in the corresponding call to rt_sem_init. Any tasks blocked on this semaphore is returned in error and allowed to run when semaphore is destroyed. Returns: 0 is returned upon success. A negative value is returned on failure as described below: 0xFFFF: sem does not refer to a valid semaphore. Note: In principle 0xFFFF could theoretically be a usable semaphores events count, so it could be returned also under normal circumstances. It is unlikely you are going to count up to such number of events, in any case avoid counting up to 0xFFFF. Definition at line 175 of file sem.c. References flags, RT_SCHED_DELAYED, RT_SCHED_READY, RT_SCHED_SEMAPHORE, RT_SCHED_SUSPENDED, rt_schedule(), RT_SEM_MAGIC, RT_TASK, rt_task_delete(), SEM, SEM_ERR, and task. Referenced by __rtai_netrpc_exit(), _rt_typed_named_sem_init(), rt_mbx_delete(), rt_msgq_delete(), rt_named_sem_delete(), and rt_rwl_delete(). Here is the call graph for this function:

void rt_sem_init (  SEM *  sem, int  value )

Initialize a counting semaphore. rt_sem_init initializes a counting fifo queueing semaphore sem. A semaphore can be used for communication and synchronization among real time tasks. Parameters: sem  must point to an allocated SEM structure. value  is the initial value of the semaphore. Positive values of the semaphore variable show how many tasks can do a rt_sem_wait() call without blocking. Negative value of a semaphore shows how many tasks are blocked on the semaphore queue, waiting to be awaken by calls to rt_sem_signal(). Note: RTAI counting semaphores assume that their counter will never exceed 0xFFFF, such a number being used to signal returns in error. Thus also the initial count value cannot be greater than 0xFFFF. This is an old legacy function. RTAI 24.1.xx has also rt_typed_sem_init(), allowing to choose among counting, binary and resource semaphores. Resource semaphores have priority inherithance. Definition at line 146 of file sem.c. References CNT_SEM, rt_typed_sem_init(), and SEM. Here is the call graph for this function:

int rt_sem_signal (  SEM *  sem  )

Signaling a semaphore. rt_sem_signal signals an event to a semaphore. It is typically called when the task leaves a critical region. The semaphore value is incremented and tested. If the value is not positive, the first task in semaphore's waiting queue is allowed to run. rt_sem_signal never blocks the caller task. Parameters: sem  points to the structure used in the call to rt_sem_init(). Returns: 0 is returned upon success. A negative value is returned on failure as described below: 0xFFFF: sem does not refer to a valid semaphore. Note: In principle 0xFFFF could theoretically be a usable semaphores events count, so it could be returned also under normal circumstances. It is unlikely you are going to count up to such number of events, in any case avoid counting up to 0xFFFF. See rt_sem_wait() notes for some curiosities. Definition at line 262 of file sem.c. References cpuid, dequeue_blocked(), flags, RT_SCHED_DELAYED, RT_SCHED_READY, RT_SCHED_SEMAPHORE, RT_SCHED_SUSPENDED, rt_schedule(), RT_SEM_MAGIC, RT_TASK, rt_task_delete(), SEM, SEM_ERR, and task. Referenced by _broadcast(), _receive(), _rt_mbx_ovrwr_send(), _rt_mbx_receive(), _rt_mbx_receive_if(), _rt_mbx_receive_until(), _rt_mbx_receive_wp(), _rt_mbx_send(), _rt_mbx_send_if(), _rt_mbx_send_until(), _rt_mbx_send_wp(), _rt_msg_broadcast(), _rt_msg_broadcast_if(), _rt_msg_broadcast_until(), _rt_msg_receive(), _rt_msg_receive_if(), _rt_msg_receive_until(), _rt_msg_send(), _rt_msg_send_if(), _rt_msg_send_until(), _send(), mbx_send_if(), net_resume_task(), rt_rwl_unlock(), RT_sem_signal(), and timer_fun(). Here is the call graph for this function:

int rt_sem_wait (  SEM *  sem  )

Take a semaphore. rt_sem_wait waits for a event to be signaled to a semaphore. It is typically called when a task enters a critical region. The semaphore value is decremented and tested. If it is still non-negative rt_sem_wait returns immediately. Otherwise the caller task is blocked and queued up. Queuing may happen in priority order or on FIFO base. This is determined by the compile time option SEM_PRIORD. In this case rt_sem_wait returns if: The caller task is in the first place of the waiting queue and another task issues a rt_sem_signal() call; An error occurs (e.g. the semaphore is destroyed); Parameters: sem  points to the structure used in the call to rt_sem_init(). Returns: the number of events already signaled upon success. A special value" as described below in case of a failure : 0xFFFF: sem does not refer to a valid semaphore. Note: In principle 0xFFFF could theoretically be a usable semaphores events count, so it could be returned also under normal circumstances. It is unlikely you are going to count up to such number of events, in any case avoid counting up to 0xFFFF. Just for curiosity: the original Dijkstra notation for rt_sem_wait was a "P" operation, and rt_sem_signal was a "V" operation. The name for P comes from the Dutch "prolagen", a combination of "proberen" (to probe) and "verlagen" (to decrement). Also from the word "passeren" (to pass). The name for V comes from the Dutch "verhogen" (to increase) or "vrygeven" (to release). (Source: Daniel Tabak - Multiprocessors, Prentice Hall, 1990). It should be also remarked that real time programming practitioners were using semaphores a long time before Dijkstra formalized P and V. "In Italian semaforo" means a traffic light, so that semaphores have an intuitive appeal and their use and meaning is easily understood. Definition at line 432 of file sem.c. References count, enqueue_blocked(), flags, RT_SCHED_SEMAPHORE, RT_SEM_MAGIC, RT_TASK, SEM, and SEM_ERR. Referenced by _rt_mbx_receive(), _rt_mbx_send(), _rt_msg_broadcast(), _rt_msg_receive(), _rt_msg_send(), hard_stub_fun(), rt_cond_wait(), rt_cond_wait_until(), rt_net_rpc(), rt_rwl_rdlock(), rt_rwl_wrlock(), RT_sem_wait(), rt_sem_wait_barrier(), and rt_send_req_rel_port(). Here is the call graph for this function:

int rt_sem_wait_barrier (  SEM *  sem  )

Wait on a semaphore barrier. rt_sem_wait_barrier is a gang waiting in that a task issuing such a request will be blocked till a number of tasks equal to the semaphore count set at rt_sem_init is reached. Returns: 0 always. Definition at line 675 of file sem.c. References flags, rt_sem_broadcast(), RT_SEM_MAGIC, rt_sem_wait(), SEM, and SEM_ERR. Referenced by _broadcast(), and _receive(). Here is the call graph for this function:

int rt_sem_wait_if (  SEM *  sem  )

Take a semaphore, only if the calling task is not blocked. rt_sem_wait_if is a version of the semaphore wait operation is similar to rt_sem_wait() but it is never blocks the caller. If the semaphore is not free, rt_sem_wait_if returns immediately and the semaphore value remains unchanged. Parameters: sem  points to the structure used in the call to rt_sem_init(). Returns: the number of events already signaled upon success. A special value as described below in case of a failure: 0xFFFF: sem does not refer to a valid semaphore. Note: In principle 0xFFFF could theoretically be a usable semaphores events count so it could be returned also under normal circumstances. It is unlikely you are going to count up to such number of events, in any case avoid counting up to 0xFFFF. Definition at line 501 of file sem.c. References count, flags, RT_SEM_MAGIC, SEM, and SEM_ERR. Referenced by _rt_msg_broadcast_if(), _rt_msg_receive_if(), _rt_msg_send_if(), rt_net_rpc(), rt_rwl_wrlock_if(), and RT_sem_wait_if().

int rt_sem_wait_timed (  SEM *  sem, RTIME  delay )

Wait a semaphore with timeout. rt_sem_wait_timed, like rt_sem_wait_until(), is a timed version of the standard semaphore wait call. The semaphore value is decremented and tested. If it is still non-negative these functions return immediately. Otherwise the caller task is blocked and queued up. Queuing may happen in priority order or on FIFO base. This is determined by the compile time option SEM_PRIORD. In this case the function returns if: The caller task is in the first place of the waiting queue and an other task issues a rt_sem_signal() call; a timeout occurs; an error occurs (e.g. the semaphore is destroyed); In case of a timeout, the semaphore value is incremented before return. Parameters: sem  points to the structure used in the call to rt_sem_init(). delay  is an absolute value to the current time. Returns: the number of events already signaled upon success. A special value as described below in case of a failure: 0xFFFF: sem does not refer to a valid semaphore. Note: In principle 0xFFFF could theoretically be a usable semaphores events count so it could be returned also under normal circumstances. It is unlikely you are going to count up to such number of events, in any case avoid counting up to 0xFFFF. Definition at line 657 of file sem.c. References rt_sem_wait_until(), RTIME, and SEM. Referenced by RT_sem_wait_timed(). Here is the call graph for this function:

int rt_sem_wait_until (  SEM *  sem, RTIME  time )

Wait a semaphore with timeout. rt_sem_wait_until, like rt_sem_wait_timed() is a timed version of the standard semaphore wait call. The semaphore value is decremented and tested. If it is still non-negative these functions return immediately. Otherwise the caller task is blocked and queued up. Queuing may happen in priority order or on FIFO base. This is determined by the compile time option SEM_PRIORD. In this case the function returns if: The caller task is in the first place of the waiting queue and an other task issues a rt_sem_signal call(); a timeout occurs; an error occurs (e.g. the semaphore is destroyed); In case of a timeout, the semaphore value is incremented before return. Parameters: sem  points to the structure used in the call to rt_sem_init(). time  is an absolute value to the current time. Returns: the number of events already signaled upon success. Aa special value" as described below in case of a failure: 0xFFFF: sem does not refer to a valid semaphore. Note: In principle 0xFFFF could theoretically be a usable semaphores events count so it could be returned also under normal circumstances. It is unlikely you are going to count up to such number of events, in any case avoid counting up to 0xFFFF. Definition at line 562 of file sem.c. References count, dequeue_blocked(), enqueue_blocked(), flags, RT_SCHED_DELAYED, RT_SCHED_SEMAPHORE, RT_SEM_MAGIC, RTIME, SEM, SEM_ERR, and SEM_TIMOUT. Referenced by _rt_mbx_receive_until(), _rt_mbx_send_until(), _rt_msg_broadcast_until(), _rt_msg_receive_until(), _rt_msg_send_until(), rt_rwl_rdlock_until(), rt_rwl_wrlock_until(), rt_sem_wait_timed(), and RT_sem_wait_until(). Here is the call graph for this function:

int rt_spl_delete (  SPL *  spl  )

Initialize a spinlock. rt_spl_delete destroies a spinlock spl. Parameters: spl  must point to an allocated SPL structure. Returns: 0 if always. Definition at line 1300 of file sem.c. References SPL. Referenced by _rt_named_spl_init(), and rt_named_spl_delete().

int rt_spl_init (  SPL *  spl  )

Initialize a spinlock. rt_spl_init initializes a spinlock spl. Parameters: spl  must point to an allocated SPL structure. A spinlock is an active wait synchronization mechanism useful for multi processors very short synchronization, when it is more efficient to wait at a meeting point instead of being suspended and the reactivated, as by using semaphores, to acquire ownership of any object. Spinlocks can be recursed once acquired, a recurring owner must care of unlocking as many times as he took the spinlock. Returns: 0 if always. Definition at line 1281 of file sem.c. References SPL. Referenced by _rt_named_spl_init().

int rt_spl_lock (  SPL *  spl  )

Acquire a spinlock. rt_spl_lock acquires a spinlock spl. Parameters: spl  must point to an allocated SPL structure. rt_spl_lock spins on lock till it can be acquired. If a tasks asks for lock it owns already it will acquire it immediately but will have to care to unlock it as many times as it recursed the spinlock ownership. Returns: 0 if always. Definition at line 1321 of file sem.c. References atomic_cmpxchg, flags, RT_TASK, rtai_save_flags_and_cli, and SPL.

int rt_spl_lock_if (  SPL *  spl  )

Acquire a spinlock without waiting. rt_spl_lock_if acquires a spinlock spl without waiting. Parameters: spl  must point to an allocated SPL structure. rt_spl_lock_if tries to acquire a spinlock but will not spin on it if it is owned already. Returns: 0 if it succeeded, -1 if the lock was owned already. Definition at line 1351 of file sem.c. References atomic_cmpxchg, flags, RT_TASK, rtai_restore_flags, rtai_save_flags_and_cli, and SPL.

int rt_spl_lock_timed (  SPL *  spl, unsigned long  ns )

Acquire a spinlock with timeout. rt_spl_lock_timed acquires a spinlock spl, but waiting spinning only for an allowed time. Parameters: spl  must point to an allocated SPL structure. ns  timeout rt_spl_lock spins on lock till it can be acquired, as for rt_spl_lock, but only for an allowed time. If the spinlock cannot be acquired in time the functions returns in error. This function can be usefull either in itself or as a diagnosis toll during code development. Returns: 0 if the spinlock was acquired, -1 if a timeout occured. Definition at line 1390 of file sem.c. References atomic_cmpxchg, flags, imuldiv(), locked, rdtsc, RT_TASK, rtai_restore_flags, rtai_save_flags_and_cli, RTIME, SPL, and tuned. Here is the call graph for this function:

int rt_spl_unlock (  SPL *  spl  )

Release an owned spinlock. rt_spl_lock releases an owned spinlock spl. Parameters: spl  must point to an allocated SPL structure. rt_spl_unlock releases an owned lock. The spinlock can remain locked and its ownership can remain with the task is the spinlock acquisition was recursed. Returns: 0 if the function was used legally, -1 if a tasks tries to unlock a spinlock it does not own. Definition at line 1429 of file sem.c. References flags, RT_TASK, rtai_restore_flags, rtai_save_flags_and_cli, and SPL.

void rt_typed_sem_init (  SEM *  sem, int  value, int  type )

Initialize a specifically typed (counting, binary, resource) semaphore. rt_typed_sem_init initializes a semaphore sem of type type. A semaphore can be used for communication and synchronization among real time tasks. Negative value of a semaphore shows how many tasks are blocked on the semaphore queue, waiting to be awaken by calls to rt_sem_signal. Parameters: sem  must point to an allocated SEM structure. value  is the initial value of the semaphore, always set to 1 for a resource semaphore. type  is the semaphore type and queuing policy. It can be an OR a semaphore kind: CNT_SEM for counting semaphores, BIN_SEM for binary semaphores, RES_SEM for resource semaphores; and queuing policy: FIFO_Q, PRIO_Q for a fifo and priority queueing respectively. Resource semaphores will enforce a PRIO_Q policy anyhow. Counting semaphores can register up to 0xFFFE events. Binary semaphores do not count signalled events, their count will never exceed 1 whatever number of events is signaled to them. Resource semaphores are special binary semaphores suitable for managing resources. The task that acquires a resource semaphore becomes its owner, also called resource owner, since it is the only one capable of manipulating the resource the semaphore is protecting. The owner has its priority increased to that of any task blocking on a wait to the semaphore. Such a feature, called priority inheritance, ensures that a high priority task is never slaved to a lower priority one, thus allowing to avoid any deadlock due to priority inversion. Resource semaphores can be recursed, i.e. their task owner is not blocked by nested waits placed on an owned resource. The owner must insure that it will signal the semaphore, in reversed order, as many times as he waited on it. Note that that full priority inheritance is supported both for resource semaphores and inter task messages, for a singly owned resource. Instead it becomes an adaptive priority ceiling when a task owns multiple resources, including messages sent to him. In such a case in fact its priority is returned to its base one only when all such resources are released and no message is waiting for being received. This is a compromise design choice aimed at avoiding extensive searches for the new priority to be inherited across multiply owned resources and blocked tasks sending messages to him. Such a solution will be implemented only if it proves necessary. Note also that, to avoid deadlocks, a task owning a resource semaphore cannot be suspended. Any rt_task_suspend() posed on it is just registered. An owner task will go into suspend state only when it releases all the owned resources. Note: RTAI counting semaphores assume that their counter will never exceed 0xFFFF, such a number being used to signal returns in error. Thus also the initial count value cannot be greater than 0xFFFF. To be used only with RTAI24.x.xx (FIXME). Definition at line 98 of file sem.c. References FIFO_Q, RES_SEM, RT_SEM_MAGIC, and SEM. Referenced by __rtai_netrpc_init(), _broadcast(), _rt_typed_named_sem_init(), rt_msgq_init(), rt_rwl_init(), rt_sem_init(), and rt_typed_mbx_init().

int set_rt_fun_entries (  struct rt_native_fun_entry *  entry  )

Definition at line 1555 of file sched.c.

---

Variable Documentation

struct rt_native_fun_entry rt_sem_entries[]

Definition at line 1706 of file sem.c. Referenced by __rtai_sem_exit(), and __rtai_sem_init().

---