1. C++ and user-space inclusion
-------------------------------

RTAI system headers have been heavily reorganised and updated to be
C++ friendly. This allows to develop C++ support ontop of the RTAI
libraries and headers natively. The goal behind this overhaul is to
have a single interface header file for each functional module, that
can be included from kernel and user-space programs, using C and C++
languages.

Because some Linux kernel headers included by RTAI are not C++
friendly, the RTAI data types have been categorised into two distinct
parts:

o RTAI data types which depends on C++ unfriendly kernel-defined
types, for which non-conflicting placeholders have been defined.

o RTAI data types which do not depend on C++ unfriendly kernel-defined
types, which are immediately visible to C++ programs.

Additionally, some RTAI data types must remain opaque to user-space
programs and fully visible to kernel modules only, which leads to the
same solution used to work around C++ unfriendly data types.

Therefore, the basic structure of an RTAI system header is now (in its
most complex form):

#ifndef _inclusion_mark_h
#define _inclusion_mark_h

/*
 * Common definitions and values with neither language nor scope
 * restrictions.
 */

#define SOMETHING 1
#define NOTHING   (!SOMETHING)

/*
 * Forward reference tags of locally defined aggregate types.
 */

struct forward_struct_tag;

#ifdef __KERNEL__

#ifndef __cplusplus

#include <c++-unfriendly-header.h>

/*
 * Kernel-only data types which are C++ unfriendly.
 */

typedef struct forward_struct_tag {
	...
} struct_type;

#else /* __cplusplus */
extern "C" {
#endif /* !__cplusplus */

/*
 * Kernel-only function declarations allowed in C and C++ modules.
 */

void some_service(struct forward_struct_tag *p);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#else /* !__KERNEL__ */

#include <rtai_lxrt.h>

/* Inlined user-space LXRT definitions. */

__RTAI_INLINE__ void some_lxrt_service(struct forward_struct_tag *p) {
	...
}

#endif /* !__KERNEL__ */

#if !defined(__KERNEL__) || defined(__cplusplus)

/*
 * Type placeholders for inclusion from user-space and/or C++.
 */

typedef struct forward_struct_tag {
    int opaque;
} struct_type;

#endif /* !__KERNEL__ || __cplusplus */

#endif /* !_inclusion_mark_h */

2. LXRT inlining
----------------

LXRT service routines which can be inlined are defined by various RTAI
system headers, and have their respective definition prefixed by
__RTAI_INLINE__. The following settings combined with the adequate
compiler switches can be used to control the inlining:

a) #define __RTAI_INLINE__ "extern inline"

   This causes the routines to be either inlined if the optimization
   is turned on, or considered as extern if the optimization is off
   and/or -fno-inline has been passed for the compilation unit. In the
   latter case, the GNU linker will ensure that a single copy only of
   each routine is produced in the final executable, which is a very
   desirable feature when debugging (i.e. breakpoint setting).

b) #define __RTAI_INLINE__ "static inline"

   This causes the routines to be either inlined if the optimization
   is turned on, or considered as static if the optimization is off
   and/or -fno-inline has been passed for the compilation unit. In the
   latter case, a static copy of each referenced routine will be
   produced in each referencing compilation unit.

c) #define __RTAI_INLINE__

   This causes the routines to be incorporated "as-is" in the reader
   file. This mode is specifically used to produce the LXRT library
   (see base/sched/user/lxrt/lib/services.c).

In any case, the LXRT library is always produced appropriately.

--
April 23, 2003
Philippe Gerum
<rpm@xenomai.org>
