# LXRT module.

## Detailed Description

LXRT services (soft-hard real time in user space).

LXRT is a module that allows you to use all the services made available by RTAI and its schedulers in user space, both for soft and hard real time. At the moment it is a feature youll find nowhere but with RTAI. For an explanation of how it works see Pierre Cloutiers LXRT-INFORMED FAQs, and the explanation of the implementation of hard real time in user space (contributed by: Pierre Cloutier, Paolo Mantegazza, Steve Papacharalambous).

LXRT-INFORMED should be the production version of LXRT, the latter being the development version. So it can happen that LXRT-INFORMED could be lagging slightly behind LXRT. If you need to hurry to the services not yet ported to LXRT-INFORMED do it without pain. Even if you are likely to miss some useful services found only in LXRT-INFORMED, we release only when a feature is relatively stable.

From what said above there should be no need for anything specific as all the functions you can use in user space have been already documented in this manual. There are however a few exceptions that need to be explained.

Note also that, as already done for the shared memory services in user space, the function calls for Linux processes are inlined in the file rtai_lxrt.h. This approach has been preferred to a library since it is simpler, more effective, the calls are short and simple so that, even if it is likely that there can be more than just a few per process, they could never be charged of making codes too bigger. Also common to shared memory is the use of unsigned int to identify LXRT objects. If you want to use string identifiers the same support functions, i.e. nam2num() and num2nam(), can be used.

## Files

file | rtai_lxrt.h
| LXRT main header.

file | rtai_mbx.h
file | rtai_nam2num.h
| Conversion between characters strings and unsigned long identifiers.

file | rtai_registry.h
file | rtai_sem.h
file | api.c
| Common scheduling function.

## Defines

#define | rt_mbx_init(name, size) rt_typed_mbx_init(name, size, FIFO_Q)
#define | rt_sem_init(name, value) rt_typed_sem_init(name, value, CNT_SEM)
#define | rt_cond_init(name) rt_typed_sem_init(name, 0, BIN_SEM)

## Functions

void * | rt_get_adr (unsigned long name)
| Get an object address by its name.
unsigned long | rt_get_name (void *adr)
| Get an object name by its address.
RT_TASK * | rt_task_init (int name, int priority, int stack_size, int max_msg_size)
| Create a new real time task in user space.
void | rt_make_soft_real_time (void)
| Return a hard real time Linux process, or pthread to the standard Linux behavior.
void | rt_make_hard_real_time (void)
| Give a Linux process, or pthread, hard real time execution capabilities allowing full kernel preemption.
void | rt_allow_nonroot_hrt (void)
| Allows a non root user to use the Linux POSIX soft real time process management and memory lock functions, and allows it to do any input-output operation from user space.
int | rt_register (unsigned long name, void *adr, int type, struct task_struct *t)
int | rt_drg_on_name (unsigned long name)
int | rt_drg_on_adr (void *adr)

## Define Documentation

#define rt_cond_init | ( | name |  | ) | rt_typed_sem_init(name, 0, BIN_SEM)

Initialize a condition variable.

Allocates and initializes a condition variable to be referred by name.

Parameters:

  | name | name of the condition variable.

It is important to remark that the returned pointer cannot be used directly, it is for kernel space data, but just passed as arguments when needed.

Returns:
  a pointer to the condition variable to be used in related calls or 0 if an error has occured.

#define rt_mbx_init | ( | name,
|  | size |  | ) | rt_typed_mbx_init(name, size, FIFO_Q)

Initialize mailbox.

Initializes a mailbox referred to by name of size size.

It is important to remark that the returned task pointer cannot be used directly, they are for kernel space data, but just passed as arguments when needed.

Returns:
  On success a pointer to the mail box to be used in related calls.

  A 0 value is returned if it was not possible to setup the semaphore or something using the same name was found.

#define rt_sem_init | ( | name,
|  | value |  | ) | rt_typed_sem_init(name, value, CNT_SEM)

Initialize a counting semaphore.

Allocates and initializes a semaphore to be referred by name.

Parameters:

  | name | name of the semaphore.
  | value | is the initial value of the semaphore

It is important to remark that the returned task pointer cannot be used directly, they are for kernel space data, but just passed as arguments when needed.

Returns:
  a pointer to the semaphore to be used in related calls or 0 if an error has occured.

## Function Documentation

void rt_allow_nonroot_hrt | ( | void |  | ) | `[inline]`

| Allows a non root user to use the Linux POSIX soft real time process management and memory lock functions, and allows it to do any input-output operation from user space. Only the process itself can use this functions, it is not possible to impose the related transition from another process.

int rt_drg_on_adr | ( | void * | adr | ) |

Deregister an object by its address.

rt_drg_on_adr deregisters the object identified by its adr.

Returns:
  a positive number on success, 0 on failure.

int rt_drg_on_name | ( | unsigned long | name | ) |

Deregister an object by its name.

rt_drg_on_name deregisters the object identified by its name.

Returns:
  a positive number on success, 0 on failure.

void* rt_get_adr | ( | unsigned long | name | ) | `[inline]`

Get an object address by its name.

rt_get_adr returns the address associated to name.

Returns:
  the address associated to name on success, 0 on failure

unsigned long rt_get_name | ( | void * | adr | ) | `[inline]`

Get an object name by its address.

rt_get_name returns the name pointed by the address adr.

Returns:
  the identifier pointed by the address adr on success, 0 on failure.

void rt_make_hard_real_time | ( | void |  | ) | `[inline]`

Give a Linux process, or pthread, hard real time execution capabilities allowing full kernel preemption.

rt_make_hard_real_time makes the soft Linux POSIX real time process, from which it is called, a hard real time LXRT process. It is important to remark that this function must be used only with soft Linux POSIX processes having their memory locked in memory. See Linux man pages.

Only the process itself can use this functions, it is not possible to impose the related transition from another process.

Note that processes made hard real time should avoid making any Linux System call that can lead to a task switch as Linux cannot run anymore processes that are made hard real time. To interact with Linux you should couple the process that was made hard real time with a Linux buddy server, either standard or POSIX soft real time. To communicate and synchronize with the buddy you can use the wealth of available RTAI, and its schedulers, services.

After all it is pure nonsense to use a non hard real time Operating System, i.e. Linux, from within hard real time processes.

void rt_make_soft_real_time | ( | void |  | ) | `[inline]`

| Return a hard real time Linux process, or pthread to the standard Linux behavior. rt_make_soft_real_time returns to soft Linux POSIX real time a process, from which it is called, that was made hard real time by a call to rt_make_hard_real_time. Only the process itself can use this functions, it is not possible to impose the related transition from another process.

int rt_register | ( | unsigned long | name,
|  | void * | adr,
|  | int | type,
|  | struct task_struct * | t
| ) |

Register an object.

rt_register registers the object to be identified with name, which is pointed by adr.

Returns:
  a positive number on success, 0 on failure.

RT_TASK* rt_task_init | ( | int | name,
|  | int | priority,
|  | int | stack_size,
|  | int | max_msg_size
| ) | `[inline]`

Create a new real time task in user space.

rt_task_init provides a real time buddy, also called proxy, task to the Linux process that wants to access RTAI scheduler services. It needs no task function as none is used, but it does need to setup a task structure and initialize it appropriately as the provided services are carried out as if the Linux process has become an RTAI task. Because of that it requires less arguments and returns the pointer to the task that is to be used in related calls.

Parameters:

  | name | is a unique identifier that is possibly used by easing referencing the buddy RTAItask, and thus its peer Linux process.
  | priority | is the priority of the buddys priority.
  | stack_size | is just what is implied by such a name and refers to the stack size used by the buddy.
  | max_msg_size | is a hint for the size of the most lengthy message than is likely to be exchanged.

stack_size and max_msg_size can be zero, in which case the default internal values are used. The assignment of a different value should be required only if you want to use task signal functions. In such a case note that these signal functions are intended to catch asyncrounous events in kernel space and, as such, must be programmed into a companion module and interfaced to their parent Linux process through the available services.

Keep an eye on the default stack (512) and message (256) sizes as they seem to be acceptable, but this API has not been used extensively with complex interrupt service routines. Since the latter are served on the stack of any task being interrupted, and more than one can pile up on the same stack, it can be possible that a larger stack is required. In such a case either recompile lxrt.c with macros STACK_SIZE and MSG_SIZE set appropriately, or explicitly assign larger values at your buddy tasks inits. Note that while the stack size can be critical the message size will not. In fact the module reassigns it, appropriately sized, whenever it is needed. The cost is a kmalloc with GFP_KERNEL that can block, but within the Linux environment. Note also that max_msg_size is for a buffer to be used to copy whatever message, either mailbox or inter task, from user to kernel space, as messages are not necessarily copied immediately, and has nothing to do directly with what you are doing.

It is important to remark that the returned task pointers cannot be used directly, they are for kernel space data, but just passed as arguments when needed.

Returns:
  On success a pointer to the task structure initialized in kernel space.

  On failure a 0 value is returned if it was not possible to setup the buddy task or something using the same name was found.