Counting semaphore services.
[Native Xenomai API.]

Collaboration diagram for Counting semaphore services.:

---

Detailed Description

A counting semaphore is a synchronization object granting Xenomai tasks a concurrent access to a given number of resources maintained in an internal counter variable. The semaphore is used through the P ("Proberen", from the Dutch "test and decrement") and V ("Verhogen", increment) operations. The P operation waits for a unit to become available from the count, and the V operation releases a resource by incrementing the unit count by one.

If no more than a single resource is made available at any point in time, the semaphore enforces mutual exclusion and thus can be used to serialize access to a critical section. However, mutexes should be used instead in order to prevent priority inversions.

Files
file	sem.c
	This file is part of the Xenomai project.
Functions
int	rt_sem_create (RT_SEM *sem, const char *name, unsigned long icount, int mode)
int	rt_sem_delete (RT_SEM *sem)
int	rt_sem_p (RT_SEM *sem, RTIME timeout)
int	rt_sem_v (RT_SEM *sem)
int	rt_sem_broadcast (RT_SEM *sem)
int	rt_sem_inquire (RT_SEM *sem, RT_SEM_INFO *info)
int	rt_sem_bind (RT_SEM *sem, const char *name, RTIME timeout)
static int	rt_sem_unbind (RT_SEM *sem)

---

Function Documentation

int rt_sem_bind	(	RT_SEM *	sem,
		const char *	name,
		RTIME	timeout
	)

Bind to a semaphore.

This user-space only service retrieves the uniform descriptor of a given Xenomai semaphore identified by its symbolic name. If the semaphore does not exist on entry, this service blocks the caller until a semaphore of the given name is created.

Parameters:

	name	A valid NULL-terminated name which identifies the semaphore to bind to.
	sem	The address of a semaphore descriptor retrieved by the operation. Contents of this memory is undefined upon failure.
	timeout	The number of clock ticks to wait for the registration to occur (see note). Passing TM_INFINITE causes the caller to block indefinitely until the object is registered. Passing TM_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry.

Returns:

0 is returned upon success. Otherwise:

• -EFAULT is returned if sem or name is referencing invalid memory.

• -EINTR is returned if rt_task_unblock() has been called for the waiting task before the retrieval has completed.

• -EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the searched object is not registered on entry.

• -ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time.

• -EPERM is returned if this service should block, but was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked).

Environments:

This service can be called from:

• User-space task (switches to primary mode)

Rescheduling: always unless the request is immediately satisfied or timeout specifies a non-blocking operation.

Note:

The timeout value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.

int rt_sem_broadcast

(

RT_SEM *

sem

)

Broadcast a semaphore.

Unblock all tasks waiting on a semaphore. Awaken tasks return from rt_sem_p() as if the semaphore has been signaled. The semaphore count is zeroed as a result of the operation.

Parameters:

sem

The descriptor address of the affected semaphore.

Returns:

0 is returned upon success. Otherwise:

• -EINVAL is returned if sem is not a semaphore descriptor.

• -EIDRM is returned if sem is a deleted semaphore descriptor.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Interrupt service routine
• Kernel-based task
• User-space task

Rescheduling: possible.

int rt_sem_create	(	RT_SEM *	sem,
		const char *	name,
		unsigned long	icount,
		int	mode
	)

Create a counting semaphore.

Parameters:

	sem	The address of a semaphore descriptor Xenomai will use to store the semaphore-related data. This descriptor must always be valid while the semaphore is active therefore it must be allocated in permanent memory.
	name	An ASCII string standing for the symbolic name of the semaphore. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created semaphore.
	icount	The initial value of the semaphore count.
	mode	The semaphore creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new semaphore:

• S_FIFO makes tasks pend in FIFO order on the semaphore.

• S_PRIO makes tasks pend in priority order on the semaphore.

• S_PULSE causes the semaphore to behave in "pulse" mode. In this mode, the V (signal) operation attempts to release a single waiter each time it is called, but without incrementing the semaphore count if no waiter is pending. For this reason, the semaphore count in pulse mode remains zero.

Returns:

0 is returned upon success. Otherwise:

• -ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to register the semaphore.

• -EEXIST is returned if the name is already in use by some registered object.

• -EINVAL is returned if the icount is non-zero and mode specifies a pulse semaphore.

• -EPERM is returned if this service was called from an asynchronous context.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Kernel-based task
• User-space task

Rescheduling: possible.

int rt_sem_delete

(

RT_SEM *

sem

)

Delete a semaphore.

Destroy a semaphore and release all the tasks currently pending on it. A semaphore exists in the system since rt_sem_create() has been called to create it, so this service must be called in order to destroy it afterwards.

Parameters:

sem

The descriptor address of the affected semaphore.

Returns:

0 is returned upon success. Otherwise:

• -EINVAL is returned if sem is not a semaphore descriptor.

• -EIDRM is returned if sem is a deleted semaphore descriptor.

• -EPERM is returned if this service was called from an asynchronous context.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Kernel-based task
• User-space task

Rescheduling: possible.

int rt_sem_inquire	(	RT_SEM *	sem,
		RT_SEM_INFO *	info
	)

Inquire about a semaphore.

Return various information about the status of a given semaphore.

Parameters:

	sem	The descriptor address of the inquired semaphore.
	info	The address of a structure the semaphore information will be written to.

Returns:

0 is returned and status information is written to the structure pointed at by info upon success. Otherwise:

• -EINVAL is returned if sem is not a semaphore descriptor.

• -EIDRM is returned if sem is a deleted semaphore descriptor.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Interrupt service routine
• Kernel-based task
• User-space task

Rescheduling: never.

int rt_sem_p	(	RT_SEM *	sem,
		RTIME	timeout
	)

Pend on a semaphore.

Acquire a semaphore unit. If the semaphore value is greater than zero, it is decremented by one and the service immediately returns to the caller. Otherwise, the caller is blocked until the semaphore is either signaled or destroyed, unless a non-blocking operation has been required.

Parameters:

	sem	The descriptor address of the affected semaphore.
	timeout	The number of clock ticks to wait for a semaphore unit to be available (see note). Passing TM_INFINITE causes the caller to block indefinitely until a unit is available. Passing TM_NONBLOCK causes the service to return immediately without waiting if no unit is available.

Returns:

0 is returned upon success. Otherwise:

• -EINVAL is returned if sem is not a semaphore descriptor.

• -EIDRM is returned if sem is a deleted semaphore descriptor, including if the deletion occurred while the caller was sleeping on it for a unit to become available.

• -EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the semaphore value is zero.

• -EINTR is returned if rt_task_unblock() has been called for the waiting task before a semaphore unit has become available.

• -ETIMEDOUT is returned if no unit is available within the specified amount of time.

• -EPERM is returned if this service should block, but was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked).

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Interrupt service routine only if timeout is equal to TM_NONBLOCK.

• Kernel-based task
• User-space task (switches to primary mode)

Rescheduling: always unless the request is immediately satisfied or timeout specifies a non-blocking operation.

Note:

The timeout value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.

int rt_sem_unbind

(

RT_SEM *

sem

)

[inline, static]

Unbind from a semaphore.

This user-space only service unbinds the calling task from the semaphore object previously retrieved by a call to rt_sem_bind().

Parameters:

sem

The address of a semaphore descriptor to unbind from.

Returns:

0 is always returned.

This service can be called from:

• User-space task.

Rescheduling: never.

int rt_sem_v

(

RT_SEM *

sem

)

Signal a semaphore.

Release a semaphore unit. If the semaphore is pended, the first waiting task (by queuing order) is immediately unblocked; otherwise, the semaphore value is incremented by one.

Parameters:

sem

The descriptor address of the affected semaphore.

Returns:

0 is returned upon success. Otherwise:

• -EINVAL is returned if sem is not a semaphore descriptor.

• -EIDRM is returned if sem is a deleted semaphore descriptor.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Interrupt service routine
• Kernel-based task
• User-space task

Rescheduling: possible.

---