RTAI API ---RTAI service functions

rt_global_cli
rt_global_sti
rt_global_save_flags
rt_global_restore_flags
rt_global_save_flags_and_cli
send_ipi_shorthand
send_ipi_logical
rt_assign_irq_to_cpu
rt_reset_irq_to_sym_mode
rt_request_global_irq
rt_free_global_irq
request_RTirq
free_RTirq
rt_request_linux_irq
rt_free_linux_irq
rt_pend_linux_irq
rt_request_srq
rt_free_srq
rt_pend_linux_srq
rt_request_timer
rt_free_timer
rt_mount_rtai
rt_umount_rtai
rt_ack_irq
rt_mask_and_ack_irq
rt_unmask_irq
rt_startup_irq
rt_shutdown_irq
rt_enable_irq
rt_disable_irq
enable_RTirq
disable_RTirq

please refer to: https://www.rtai.org/userfiles/documentation/magma/html/api

******************************************************************************************************************************************************************

NAME

rt_global_cli, rt_global_sti - disable/enable interrupts

SYNOPSIS
#include "rtai.h"
void rt_global_cli (void);
void rt_global_sti (void);

DESCRIPTION
rt_global_cli hard disables interrupts (cli) on the requesting cpu and acquires the global spinlock to the calling cpu so that any other cpu synchronized by this method is blocked.
rt_global_sti hard enables interrupts (sti) on the calling cpu and releases the global lock.

NAME

rt_global_save_flags, rt_global_save_flags_and_cli, rt_global_restore_flags - save/restore CPU flags

SYNOPSIS
#include "rtai.h"
void rt_global_save_flags (unsigned long *flags);
int rt_global_save_flags_and_cli (void);
void rt_global_restore_flags (unsigned long flags);

DESCRIPTION
rt_global_save_flags saves the cpu interrupt flag (IF) and the global lock flag, in bits 9 and 0 of flags.
rt_global_save_flags_and_cli hard disables interrupts on the requesting CPU and returns old state of cpu interrupt flag (IF) and the global lock flag, in bits 9 and 0.
rt_global_restore_flags restores the cpu hard interrupt flag (IF) and the global lock flag as given by flags, freeing or acquiring the global lock according to the state of the global flag bit.
BUG
Types are inconsistent. Flags are stored in int as well as in unsigned long.
**************************************************************************************************************************************************************************
NAME

send_ipi_shorthand, send_ipi_logical - send interprocessor message

SYNOPSIS
#include "rtai.h"
void send_ipi_shorthand (unsigned int shorthand, int irq);
void send_ipi_logical (unsigned long dest, int irq);

DESCRIPTION
send_ipi_shorthand sends an interprocessor message of irq to
all CPUs if shorthand is equal to APIC_DEST_ALLINC;
all but itself if shorthand is equal to APIC_DEST_ALLBUT;
itself if shorthand is equal to APIC_DEST_SELF.
send_ipi_logical sends an interprocessor message of irq to all CPUs defined by dest. dest is given by an unsigned long corresponding to a bitmask of the CPUs to be sent. It is used for local apics programmed in flat logical mode, so the max number of allowed CPUs is 8, a constraint that is valid for all functions and data of RTAI. The flat logical mode is set when RTAI is installed by calling rt_mount_rtai.
*************************************************************************************************************************************************************************************
NAME

rt_assign_irq_to_cpu, rt_reset_irq_to_sym_mode - set/reset IRQ->CPU assignment

SYNOPSIS
#include "rtai.h"
int rt_assign_irq_to_cpu (int irq, int cpu);
int rt_reset_irq_to_sym_mode (int irq);

DESCRIPTION
rt_assign_irq_to_cpu forces the assignment of the external interrupt irq to the CPU cpu.
rt_reset_irq_to_sym_mode resets the interrupt irq to the symmetric interrupts management. The symmetric mode distributes the IRQs over all the CPUs.

Note: These functions have effect on multiprocessor systems only.

RETURN VALUE

If there is one CPU in the system, 1 returned.
If there is at least 2 CPU, on success 0 is returned. If cpu is refers to a non-existent CPU, the number of CPUs is returned. On other failures, a negative value is returned as desribed below.

ERRORS

-EINVAL
irq is not a valid IRQ number or some internal data incosistency is found.
BUGS

Incostent return values. In case of 1 CPU return value should be 0 (=success);
**************************************************************************************************************************************************************************
NAME

rt_request_global_irq, request_RTirq, rt_free_global_irq, free_RTirq - install/uninstall IT service routine

SYNOPSIS
#include "rtai.h"
int rt_request_global_irq (unsigned int irq, void (*handler)(void));
int rt_free_global_irq (unsigned int irq);
int request_RTirq (unsigned int irq, void (*handler)(void));
int free_RTirq (unsigned int irq);

DESCRIPTION
rt_request_global_irq installs function handler as an interrupt service routine for IRQ level irq. handler is then invoked whenever interrupt number irq occurs. 
The installed handler must take care of properly activating any Linux handler using the same irq number by calling rt_pend_linux_irq.
rt_free_global_irq uninstalls the interrupt service routine.

request_RTirq and free_RTirq are macros defined in rtai.h and is supported only for backwards compatibility with our variant of RT_linux for 2.0.35. They are fully equivalent of the other two functions above.

RETURN VALUE
On success 0 is returned. On failure a negative value is returned as described below.
ERRORS
-EINVAL
irq is not a valid IRQ number or handler is NULL.
-EBUSY
There is already a handler of interrupt irq.
************************************************************************************************************************************************************
NAME

rt_request_linux_irq, rt_free_linux_irq - install/uninstall shared Linux interrupt handler
SYNOPSIS

#include "rtai.h"
int rt_request_linux_irq (unsigned int irq, void (*handler)(int irq, void *dev_id, struct pt_regs *regs), char *linux_handler_id, void *dev_id);

int rt_free_linux_irq (unsigned int irq, void *dev_id);

DESCRIPTION
rt_request_linux_irq installs function handler as an interrupt service routine for IRQ level irq forcing Linux to share the IRQ with other interrupt handlers. The handler is appended to any already existing Linux handler for the same irq and run as a Linux irq handler. In this way a real time application can monitor Linux interrupts handling at is will. The handler appears in /proc/interrupts. 
linux_handler_id is a name for /proc/interrupts. The parameter dev_id is to pass to the interrupt handler, in the same way as the standard Linux irq request call.
The interrupt service routine can be uninstalled with rt_free_linux_irq.

RETURN VALUE
On success 0 is returned. On failure a negative value is returned as described below.
ERRORS

-EINVAL
irq is not a valid IRQ number or handler is NULL.
-EBUSY
There is already a handler of interrupt irq.
*******************************************************************************************************************************************************
NAME

rt_pend_linux_irq - make Linux service an interrupt

SYNOPSIS
#include "rtai.h"

void rt_pend_linux_irq (unsigned int irq);

DESCRIPTION

rt_pend_linux_irq appends a Linux interrupt irq for processing in Linux IRQ mode, i.e. with interrupts fully enabled..

BUGS

rt_pend_linux_irq does not perform any check on irq.

*************************************************************************************************************************************************************

NAME

rt_request_srq, rt_free_srq - ???

SYNOPSIS
#include "rtai.h"
int rt_request_srq (unsigned int label, void (*rtai_handler)(void), long long (*user_handler)(unsigned int whatever));

int rt_free_srq (unsigned int srq);

DESCRIPTION

rt_free_srq uninstalls the system call identified by srq.

RETURN VALUE
On success the number of the assigned system request is returned. On failure a negative value is returned as described below.
ERRORS

-EINVAL
rtai_handler is NULL or srq is invalid.
-EBUSY
No free srq slot is available.
*****************************************************************************************************************************************************************************
NAME

rt_pend_linux_srq 

SYNOPSIS
#include "rtai.h"
void rt_pend_linux_srq (unsigned int srq);

DESCRIPTION

rt_pend_linux_srq appends a system call request srq to be used as a service request to the Linux kernel. srq is the value returned by rt_request_srq.

BUGS
rt_pend_linux_srq does not perform any check on irq.
****************************************************************************************************************************************************************************
NAME

rt_request_timer, rt_free_timer - install a timer interrupt handler
SYNOPSIS

#include "rtai.h"
void rt_request_timer (void (*handler)(void), int tick, int apic);

void rt_free_timer (void);

DESCRIPTION
rt_request_timer requests a timer of period tick ticks, and installs the routine handler as a real time interrupt service routine for the timer. 
Set tick to 0 for oneshot mode. (???) 
If apic has a nonzero value the local APIC timer is used. Otherwise timing is based on the 8254.
rt_free_timer uninstalls the timer previously set by rt_request_timer.
**********************************************************************************************************************************************************************
NAME

rt_mount_rtai, rt_umount_rtai - initialize/uninitialize real time application interface

SYNOPSIS

#include "rtai.h"
void rt_mount_rtai (void);
void rt_umount_rtai (void);

DESCRIPTION
rt_mount_rtai initializes the real time application interface, i.e. grabs anything related to the hardware, data or service, pointed by at by the Real Time Hardware Abstraction Layer (struct rt_hal rthal;).
rt_umount_rtai unmounts the real time application interface resetting Linux to its normal state.