Semaphores.
[RTAI FIFO module]

---

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
int	rtf_sem_wait (int fd)
int	rtf_sem_timed_wait (int fd, int ms_delay)
int	rtf_sem_init (unsigned int minor, int value)
int	rtf_sem_post (unsigned int minor)
int	rtf_sem_trywait (unsigned int minor)
int	rtf_sem_destroy (unsigned int minor)

---

Function Documentation

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 1305 of file fifos.c. References fifo, mbx_sem_delete(), TRACE_RTAI_FIFO, and VALID_FIFO. Here is the call graph for this function:

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 1221 of file fifos.c. References fifo, mbx_sem_init(), TRACE_RTAI_FIFO, and VALID_FIFO. Here is the call graph for this function:

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 1249 of file fifos.c. References fifo, mbx_sem_signal(), TRACE_RTAI_FIFO, and VALID_FIFO. Here is the call graph for this function:

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

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 686 of file rtai_fifos.h. References errno, and RTF_SEM_TIMED_WAIT.

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 1278 of file fifos.c. References fifo, mbx_sem_wait_if(), TRACE_RTAI_FIFO, and VALID_FIFO. Here is the call graph for this function:

int rtf_sem_wait (  int  fd  )  [inline]

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 648 of file rtai_fifos.h. References errno, and RTF_SEM_WAIT.

---