Semaphores.
[RTAI FIFO module]

Collaboration diagram for Semaphores.:

---

Detailed Description

RTAI FIFO semaphore functions.

Fifos have an embedded synchronization capability, however using them only for such a purpose can be clumsy. So RTAI fifos have binary semaphores for that purpose. Note that, as for put and get fifos functions, only nonblocking functions are available in kernel space.

Called from RT task	Called from Linux process
rtf_sem_init	rtf_sem_init
rtf_sem_post	rtf_sem_post
rtf_sem_trywait	rtf_sem_wait rtf_sem_trywait rtf_sem_timed_wait
rtf_sem_destroy	rtf_sem_destroy

To add a bit of confusion (J), with respect to RTAI schedulers semaphore functions, fifos semaphore functions names follow the POSIX mnemonics.

It should be noted that semaphores are associated to a fifo for identification purposes. So it is once more important to remember is that in the user space side you address fifos through the file descriptor you get at fifo device opening while in kernel space you directly address them by their minor number. So you will mate the fd you get in user space by

open(/dev/rtfxx,) 

to the integer xx youll use in kernel space.

Files
file	rtai_fifos.h
	Interface of the RTAI FIFO module.
file	fifos.c
	Implementation of the RTAI FIFO module.
Functions
static int	rtf_sem_wait (int fd)
	Take a semaphore.
static int	rtf_sem_timed_wait (int fd, int ms_delay)
	Wait a semaphore with timeout.
RTAI_SYSCALL_MODE int	rtf_sem_init (unsigned int minor, int value)
	Initialize a binary semaphore.
RTAI_SYSCALL_MODE int	rtf_sem_post (unsigned int minor)
	Posting (signaling) a semaphore.
RTAI_SYSCALL_MODE int	rtf_sem_trywait (unsigned int minor)
	Take a semaphore, only if the calling task is not blocked.
RTAI_SYSCALL_MODE int	rtf_sem_destroy (unsigned int minor)
	Delete a semaphore.

---

Function Documentation

RTAI_SYSCALL_MODE int rtf_sem_destroy

(

unsigned int

minor

)

Delete a semaphore.

rtf_sem_destroy deletes a semaphore previously created with rtf_sem_init().

Parameters:

minor

is a file descriptor returned by standard UNIX open in user space while it is directly the chosen fifo number in kernel space. In fact fifos semaphores must be associated to a fifo for identification purposes.

Any tasks blocked on this semaphore is returned in error and allowed to run when semaphore is destroyed.

rtf_sem_destroy can be used both in kernel and user space.

Return values:

	0	on sucess.
	EINVAL	if fd_fifo refers to an invalid file descriptor or fifo.

Definition at line 1313 of file fifos.c.

References fifo, mbx_sem_delete(), TRACE_RTAI_FIFO, and VALID_FIFO.

Here is the call graph for this function:

RTAI_SYSCALL_MODE int rtf_sem_init	(	unsigned int	minor,
		int	value
	)

Initialize a binary semaphore.

rtf_sem_init initializes a semaphore identified by the file descriptor or fifo number fd_fifo.

A fifo semaphore can be used for communication and synchronization between kernel and user space.

Parameters:

	minor	is a file descriptor returned by standard UNIX open in user space while it is directly the chosen fifo number in kernel space. In fact fifos semaphores must be associated to a fifo for identification purposes.
	value	is the initial value of the semaphore, it must be either 0 or 1.

rt_sem_init can be used both in kernel and user space.

Return values:

	0	on success.
	EINVAL	if fd_fifo refers to an invalid file descriptor or fifo.

Definition at line 1229 of file fifos.c.

References fifo, mbx_sem_init(), TRACE_RTAI_FIFO, and VALID_FIFO.

Here is the call graph for this function:

RTAI_SYSCALL_MODE int rtf_sem_post

(

unsigned int

minor

)

Posting (signaling) a semaphore.

rtf_sem_post signal an event to a semaphore. The semaphore value is set to one and the first process, if any, in semaphore's waiting queue is allowed to run.

Parameters:

minor

is a file descriptor returned by standard UNIX open in user space while it is directly the chosen fifo number in kernel space. In fact fifos semaphores must be associated to a fifo for identification purposes.

Since it is not blocking rtf_sem_post can be used both in kernel and user space.

Return values:

	0	on success.
	EINVAL	if fd_fifo refers to an invalid file descriptor or fifo.

Definition at line 1257 of file fifos.c.

References fifo, mbx_sem_signal(), TRACE_RTAI_FIFO, and VALID_FIFO.

Here is the call graph for this function:

static int rtf_sem_timed_wait	(	int	fd,
		int	ms_delay
	)			[inline, static]

Wait a semaphore with timeout.

rtf_sem_timed_wait is a timed version of the standard semaphore wait call. The semaphore value is tested and set to zero. If it was one rtf_sem_timed_wait returns immediately. Otherwise the caller process is blocked and queued up in a priority order based on is POSIX real time priority.

A process blocked on a semaphore returns when:

• the caller task is in the first place of the waiting queue and somebody issues a rtf_sem_post;
• timeout occurs;
• an error occurs (e.g. the semaphore is destroyed).

Parameters:

	fd	is the file descriptor returned by standard UNIX open in user space. In case of timeout the semaphore value is set to one before return.
	ms_delay	is in milliseconds and is relative to the Linux current time.

Since it is blocking rtf_sem_timed_wait cannot be used both in kernel and user space.

Return values:

	0	on success.
	-EINVAL	if fd_fifo refers to an invalid file descriptor or fifo.

Definition at line 712 of file rtai_fifos.h.

References errno, and RTF_SEM_TIMED_WAIT.

RTAI_SYSCALL_MODE int rtf_sem_trywait

(

unsigned int

minor

)

Take a semaphore, only if the calling task is not blocked.

rtf_sem_trywait is a version of the semaphore wait operation is similar to rtf_sem_wait() but it is never blocks the caller. If the semaphore is not free, rtf_sem_trywait returns immediately and the semaphore value remains unchanged.

Parameters:

minor

is a file descriptor returned by standard UNIX open in user space while it is directly the chosen fifo number in kernel space. In fact fifos semaphores must be associated to a fifo for identification purposes.

Since it is not blocking rtf_sem_trywait can be used both in kernel and user space.

Return values:

	0	on success.
	EINVAL	if fd_fifo refers to an invalid file descriptor or fifo.

Definition at line 1286 of file fifos.c.

References fifo, mbx_sem_wait_if(), TRACE_RTAI_FIFO, and VALID_FIFO.

Here is the call graph for this function:

static int rtf_sem_wait

(

int

fd

)

[inline, static]

Take a semaphore.

rtf_sem_wait waits for a event to be posted (signaled) to a semaphore. The semaphore value is set to tested and set to zero. If it was one rtf_sem_wait returns immediately. Otherwise the caller process is blocked and queued up in a priority order based on is POSIX real time priority.

A process blocked on a semaphore returns when:

• the caller task is in the first place of the waiting queue and somebody issues a rtf_sem_post;
• an error occurs (e.g. the semaphore is destroyed).

Parameters:

fd

is the file descriptor returned by standard UNIX open in user space

Since it is blocking rtf_sem_waitcannot be used both in kernel and user space.

Return values:

	0	on success.
	-EINVAL	if fd_fifo refers to an invalid file descriptor or fifo.

Definition at line 674 of file rtai_fifos.h.

References errno, and RTF_SEM_WAIT.

---