# 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.

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.

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.

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.

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.

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.